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_api - 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_api

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(
    api_response: Dict[str, Any]
) -> Detections

​
Parameters

​
api_response
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

​
result
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

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

​
detectron2_results
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

​
result
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

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

​
ultralytics_results
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

​
result
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

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

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

​
Returns

​
result
Detections
Empty Detections object. Full implementation pending.

​
Example

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

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

​
Returns

​
result
Detections
Empty Detections object. Full implementation pending.

​
Example

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

​
group
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].
​
height
int
required
Image height in pixels for coordinate denormalization. Must be positive integer representing actual image height.
​
width
int
required
Image width in pixels for coordinate denormalization. Must be positive integer representing actual image width.

​
Returns

​
result
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

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: