Converters

Provides standardized conversion utilities to transform detection outputs from various machine learning frameworks (Detectron2, Ultralytics YOLO, Datamarkin API, Transformers) into PixelFlow’s unified Detections format. This module enables seamless integration with different ML backends while maintaining consistent data structures for downstream processing, visualization, and analysis workflows.

Functions

from_datamarkin - Convert Datamarkin API response to a unified Detections object.
from_detectron2 - Convert Detectron2 inference results to a unified Detections object.
from_ultralytics - Convert Ultralytics YOLO results to a unified Detections object.
from_transformers - Convert Transformers library results to a unified Detections object.
from_sam - Convert Segment Anything Model (SAM) results to a unified Detections object.
from_datamarkin_csv - Convert CSV data from Datamarkin format to a unified Detections object.

from_datamarkin

Convert Datamarkin API response to a unified Detections object. Processes detection results from Datamarkin’s cloud-based object detection API, extracting bounding boxes, segmentation masks, keypoints, class labels, and confidence scores into PixelFlow’s standardized format for further processing.

Function Signature

from_datamarkin(
    api_response: Dict[str, Any]
) -> Detections

Parameters

Dict[str, Any]

required

Datamarkin API response dictionary containing nested ‘predictions’ -> ‘objects’ structure with detection data. Each object should have ‘bbox’, ‘mask’, ‘keypoints’, ‘class’, and ‘bbox_score’ fields.

Returns

Detections

Unified Detections object containing all detected objects with standardized XYXY bounding boxes, polygon masks, keypoint data, and confidence scores. Empty Detections object if no predictions.

Example

import pixelflow as pf
import requests

# Call Datamarkin API for object detection
response = requests.post(

from_detectron2

Convert Detectron2 inference results to a unified Detections object. Extracts bounding boxes, confidence scores, class IDs, segmentation masks, and keypoints from Detectron2’s instances format and standardizes them into PixelFlow’s Detection objects. Handles automatic tensor-to-numpy conversion and CPU transfer for efficient processing.

Function Signature

from_detectron2(
    detectron2_results: Dict[str, Any]
) -> Detections

Parameters

Dict[str, Any]

required

Detectron2 inference results dictionary containing ‘instances’ key with prediction data including pred_boxes, scores, pred_classes, pred_masks, and pred_keypoints. Results should be from DefaultPredictor output.

Returns

Detections

Unified Detections object with all detected instances converted to standardized format. Contains XYXY bounding boxes as lists, boolean numpy array masks, integer class IDs, and float confidences. Returns empty Detections if no instances found.

Example

import cv2
import pixelflow as pf
from detectron2 import model_zoo
from detectron2.engine import DefaultPredictor
from detectron2.config import get_cfg

# Setup Detectron2 object detection model
cfg = get_cfg()
cfg.merge_from_file(model_zoo.get_config_file("COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml"))
cfg.MODEL.WEIGHTS = model_zoo.get_checkpoint_url("COCO-Detection/faster_rcnn_R_50_FPN_3x.yaml")
predictor = DefaultPredictor(cfg)
image = cv2.imread("path/to/image.jpg")
outputs = predictor(image)  # Raw Detectron2 output
detections = pf.detections.from_detectron2(outputs)  # Convert to PixelFlow format

# Basic usage - access detection data
for detection in detections.detections:

from_ultralytics

Convert Ultralytics YOLO results to a unified Detections object. Supports both detection and segmentation models, handling bounding boxes, confidence scores, class IDs, segmentation masks, and tracker IDs. Automatically processes letterbox padding removal and mask resizing to original image dimensions with precise coordinate transformation.

Function Signature

from_ultralytics(
    ultralytics_results: Union[Any, List[Any]]
) -> Detections

Parameters

Union[Any, List[Any]]

required

YOLO results from Ultralytics library prediction or tracking. Can be single Result object or list containing one Result object. Must have boxes attribute with detection data.

Returns

Detections

Unified Detections object containing all detected objects with standardized XYXY bounding boxes, boolean binary masks resized to original image dimensions, polygon segments as integer coordinates, and tracker IDs if available. Empty Detections if no boxes found.

Example

import cv2
import pixelflow as pf
from ultralytics import YOLO

# Basic object detection
model = YOLO("yolo11n.pt")
image = cv2.imread("path/to/image.jpg")
outputs = model.predict(image)  # Raw YOLO output
detections = pf.detections.from_ultralytics(outputs)  # Convert to PixelFlow format

# Access detection data with class names
for detection in detections.detections:

from_transformers

Convert Transformers library results to a unified Detections object. Placeholder function for future integration with Hugging Face Transformers object detection and segmentation models. Will support DETR, RT-DETR, and other transformer-based detection architectures.

Function Signature

from_transformers(
    transformers_results: Any
) -> Detections

Parameters

Any

required

Results from Transformers library object detection models. Expected format includes boxes, labels, and scores tensors.

Returns

Detections

Empty Detections object. Full implementation pending.

Example

import pixelflow as pf
# Future usage with Transformers models
# from transformers import AutoImageProcessor, AutoModelForObjectDetection
# processor = AutoImageProcessor.from_pretrained("facebook/detr-resnet-50")
# model = AutoModelForObjectDetection.from_pretrained("facebook/detr-resnet-50")
# outputs = model(**processor(image, return_tensors="pt"))  # Raw output
# detections = pf.detections.from_transformers(outputs)  # Convert to PixelFlow
print("Function not yet implemented")

from_sam

Convert Segment Anything Model (SAM) results to a unified Detections object. Placeholder function for integration with Meta’s Segment Anything Model (SAM) for interactive and automatic segmentation tasks. Will support prompt-based segmentation with point, box, and text prompts.

Function Signature

from_sam(
    sam_results: Any
) -> Detections

Parameters

Any

required

Results from SAM model inference including masks, iou_predictions, and low_res_logits from SamPredictor or SamAutomaticMaskGenerator output.

Returns

Detections

Empty Detections object. Full implementation pending.

Example

import pixelflow as pf
# Future usage with SAM models
# from segment_anything import SamPredictor, sam_model_registry
# sam = sam_model_registry["vit_h"](checkpoint="sam_vit_h.pth")
# predictor = SamPredictor(sam)
# predictor.set_image(image)
# masks, scores, logits = predictor.predict(point_coords=input_point)  # Raw output
# detections = pf.detections.from_sam({"masks": masks, "scores": scores})  # Convert to PixelFlow
print("Function not yet implemented")

from_datamarkin_csv

Convert CSV data from Datamarkin format to a unified Detections object. Processes normalized coordinates from CSV annotation format and converts them to pixel coordinates using the provided image dimensions. Handles both bounding box rectangles and segmentation polygon data with automatic coordinate denormalization and validation.

Function Signature

from_datamarkin_csv(
    group: Any,
    height: int,
    width: int
) -> Detections

Parameters

Any

required

Pandas DataFrame or DataFrame group containing CSV rows with required columns ‘xmin’, ‘ymin’, ‘xmax’, ‘ymax’, ‘segmentation’, ‘class’, and optional ‘confidence’. All coordinate values must be normalized floats in range [0.0, 1.0].

int

required

Image height in pixels for coordinate denormalization. Must be positive integer representing actual image height.

int

required

Image width in pixels for coordinate denormalization. Must be positive integer representing actual image width.

Returns

Detections

Unified Detections object with pixel coordinates converted from normalized values. Contains XYXY bounding boxes as integers, polygon masks as lists of (x, y) tuples, and preserved class labels. Empty Detections if group contains no rows.

Example

import pandas as pd
import pixelflow as pf

# Load CSV annotations with normalized coordinates
df = pd.read_csv("datamarkin_annotations.csv")
# CSV format: image,xmin,ymin,xmax,ymax,segmentation,class,confidence
# Example row: img1.jpg,0.1,0.2,0.8,0.9,"[0.1,0.2,0.8,0.2,0.8,0.9,0.1,0.9]",person,0.95
detections = pf.detections.from_datamarkin_csv(df, height=480, width=640)  # Convert to PixelFlow format

# Basic usage - process single image annotations
for detection in detections.detections:

Getting Started

Detections

Annotators

Zones

Object Tracking

Processing Tools

Analytics

Functions

from_datamarkin

Function Signature

Parameters

Returns

Example

from_detectron2

Function Signature

Parameters

Returns

Example

from_ultralytics

Function Signature

Parameters

Returns

Example

from_transformers

Function Signature

Parameters

Returns

Example

from_sam

Function Signature

Parameters

Returns

Example

from_datamarkin_csv

Function Signature

Parameters

Returns

Example

​Functions

​from_datamarkin

​Function Signature

​Parameters

​Returns

​Example

​from_detectron2

​Function Signature

​Parameters

​Returns

​Example

​from_ultralytics

​Function Signature

​Parameters

​Returns

​Example

​from_transformers

​Function Signature

​Parameters

​Returns

​Example

​from_sam

​Function Signature

​Parameters

​Returns

​Example

​from_datamarkin_csv

​Function Signature

​Parameters

​Returns

​Example

Functions

from_datamarkin

Function Signature

Parameters

Returns

Example

from_detectron2

Function Signature

Parameters

Returns

Example

from_ultralytics

Function Signature

Parameters

Returns

Example

from_transformers

Function Signature

Parameters

Returns

Example

from_sam

Function Signature

Parameters

Returns

Example

from_datamarkin_csv

Function Signature

Parameters

Returns

Example