Detections object

Detections is the unified object for computer vision that lets you iterate, index, and serialize detection results from any ML framework.
Powered by PixelFlow.

pip install pixelflow

❌ Before

# Can't iterate naturally
instances = detectron_output['instances']
for i in range(len(instances)):
    box = instances.pred_boxes[i]
    score = instances.scores[i]

✅ After

# Natural iteration
for detection in detections:
    print(detection.bbox)
first = detections[0]
count = len(detections)

ML frameworks don't give you standard Python containers

Every ML framework outputs detections in incompatible custom types that break the Python developer experience.

Detectron2 - Tensors Everywhere

# Must call .cpu(), .numpy()
boxes = output['instances'].pred_boxes.tensor.cpu().numpy()
scores = output['instances'].scores.cpu().numpy()

# Can't iterate: for detection in instances ❌
# Can't index: first = instances[0] ❌

YOLO - Different Structure

# Same problems, different names
boxes = output[0].boxes.xyxy.cpu().numpy()
scores = output[0].boxes.conf.cpu().numpy()

# pred_boxes vs boxes.xyxy
# scores vs boxes.conf

The Core Problems:

  • No standard Python container protocol (can't iterate naturally)
  • Framework-specific tensor/array handling (.cpu(), .numpy())
  • Different attribute names for same data
  • No unified serialization (custom JSON encoding needed)
  • Can't swap frameworks without rewriting integration code

One Object. Standard Python. Any Framework.

Layer 1: Detections Object

What it is: A standard Python container for detection data with unified attributes.

import pixelflow as pf

# Convert ANY framework
detections = pf.detections.from_ultralytics(yolo_output)

# ✅ Natural iteration
for detection in detections:
    print(detection.bbox)

# ✅ Direct indexing
first = detections[0]
count = len(detections)

# ✅ Built-in serialization
json_str = detection.to_json()

Layer 2: PixelFlow Toolkit

What it adds: Production-ready tools that operate on Detections objects.

# Method chaining filters
filtered = (detections
    .filter_by_confidence(0.8)
    .filter_by_class_id([0, 2]))

# Spatial transforms
img, dets = pf.transform.rotate_detections(img, dets, 45)

# Zone analytics
zones.update(detections)

# Object tracking
tracker.update(detections)

Key Benefits

Python Container Protocol

Iterate, index, and slice naturally. Works with all Python tools like list comprehensions.

for det in detections:
    print(det.bbox)

Unified Field Access

Same attribute names across all frameworks. No more framework gymnastics.

bbox = det.bbox
confidence = det.confidence
class_id = det.class_id

Framework Converters

The bridge from framework chaos to unified objects. Supports YOLO, Detectron2, OCR, and more.

from_ultralytics()
from_detectron2()
from_easyocr()

Built-in Serialization

JSON export with automatic base64 encoding for masks. Ready for APIs and databases.

json_str = det.to_json()
data_dict = det.to_dict()

Immutability Support

Safe copying for functional programming patterns and parallel processing.

new_dets = dets.copy()
# No side effects

Direct List Access

It's just a Python list under the hood. Use all standard list methods.

dets.detections.append(new)
dets.detections.pop(0)

PixelFlow Toolkit Features

Method Chaining Filters

Readable, composable filtering that eliminates nested loops.

filtered = (detections
    .filter_by_confidence(0.8)
    .filter_by_class_id([0, 2])
    .filter_by_size(min_area=1000))

Spatial Transforms

Geometric operations with automatic coordinate history tracking.

img, dets = pf.transform.rotate_detections(img, dets, 45)
original = pf.transform.inverse_transforms(dets)

Getting Started

Installation

pip install pixelflow

Quick Start

import pixelflow as pf
import cv2
from ultralytics import YOLO

# Load image and run inference
image = cv2.imread("image.jpg")
model = YOLO("yolo11n.pt")
outputs = model.predict(image)

# Convert to Detections object
detections = pf.detections.from_ultralytics(outputs)

# ✅ Use standard Python
for detection in detections:
    print(f"Class: {detection.class_name}")

first = detections[0]
count = len(detections)

With PixelFlow Features

# Method chaining filters
filtered = (detections
    .filter_by_confidence(0.7)
    .filter_by_class_id([0]))  # person class

# Transforms
img, dets = pf.transform.rotate_detections(
    image, detections, 45
)

# Zone analytics
zones = pf.Zones()
zones.add_zone(polygon, zone_id="checkout")
detections = zones.update(detections)

# Filter by zone
checkout_dets = detections.filter_by_zones(['checkout'])

# Annotate
annotated = pf.annotate.box(image, filtered)
annotated = pf.annotate.label(annotated, filtered)