acmenra-cv 0.2.0.0

Production-ready computer vision utilities for multi-object tracking

🚀 acmenra-cv

Production-ready computer vision utilities for ADAS, multi-object tracking, and embedded vision systems

pip install acmenra-cv

---

📦 Overview

acmenra-cv is a high-performance, type-safe computer vision library engineered for real-time applications on resource-constrained embedded systems (Raspberry Pi 5, Jetson, NPU, etc.). Built following Clean Architecture principles, it provides four cohesive modules:

Module	Purpose	Key Features
instance	Spatial primitives for detection outputs	Normalized coordinates, strict validation, immutable transformations
tracker	Multi-object tracking with trajectories	Persistent IDs, configurable history, BoT-SORT integration
render	Type-safe visualization layer	Alpha-blended overlays, embedded optimizations, graceful degradation
inference	Backend-agnostic result container	Collection-like API, timing metrics, JSON serialization

All spatial components operate in normalized coordinate space [0.0, 1.0] by default, ensuring resolution independence across varying camera inputs and inference resolutions. The inference module stores absolute integer dimensions to serve as the ground truth for coordinate denormalization.

---

✨ Key Features

🔹 Unified Architecture

• Strict type & range validation ([0.0, 1.0] with safe() clamping factory)
• Seamless YOLO integration (boxes, masks.xyn, obb.xyxyxyxyn)
• Immutable geometric transformations (scale, translate, smooth)
• Full type safety with IDE autocomplete and consistent API across all primitives

🔹 Backend-Agnostic Results

• Universal Result container with collection-like API (len(), iteration, indexing)
• Execution timing metrics with partial measurement support (None for unprofiled stages)
• Absolute pixel dimensions (width, height, depth as int) for accurate denormalization
• Full JSON serialization (to_dict/from_dict) optimized for Outbox persistence

🔹 Embedded-Ready Performance

• Zero-crash OpenCV integration with @validate_frame decorator
• Global show=False toggle to bypass all rendering for headless/embedded deployments
• Memory-efficient trajectory queues with O(1) average calculation
• Alpha-blended compositing (cv2.addWeighted) and anti-aliased geometry (LINE_AA)

🔹 ADAS & Safety-Critical Design

• Trajectory history management for zone crossing and collision detection
• Temporal metadata (TimedPoint) for velocity/direction estimation
• Configurable thresholds (conf, iou, max_length) for dynamic adaptation
• Graceful degradation on invalid inputs — no exceptions, just safe fallbacks

---

🧩 Module Documentation

🔷 instance — Spatial Primitives

Validated geometric containers for detection outputs

Classes

Point — Validated 3D normalized coordinates

• __init__(): Initializes with X, Y, Z. Validates float type and [0.0, 1.0] range.
• X, Y, Z: Properties with strict type and range validation.
• get_distance(): Euclidean distance to another point (includes Z).
• scale(), translate(): Immutable transformations returning new instances.
• safe(): Class method factory with coordinate clamping — no exceptions.

Box — Axis-aligned 3D bounding box

• __init__(): Six boundaries (left, right, top, bottom, front, back).
• center, bottom_center: Computed properties for tracking.
• width, height, depth: Dimension properties.
• get_area(), get_volume(): Geometric calculations.
• to_absolute_array(): Converts to pixel corners for OpenCV.
• YOLO format conversions: to_xyxyn(), to_xywhn(), to_xyzxyzn(), to_xyzwhdn().

Polygon — Segmentation mask container

• from_xyn(): Static factory from YOLO masks.xyn.
• smooth(): Vertex smoothing via moving average.
• get_area(): Shoelace formula for normalized area.
• __getitem__(): Supports slicing — returns new Polygon.
• __len__(), __iter__(): Collection-like behavior.

Obb — Oriented (rotated) bounding box

• from_xywhrn(): Static factory from YOLO OBB format.
• yaw, pitch, roll: Rotation angles with tolerance-based equality.
• width, height, depth: Dimension properties.
• Full 3D support with canonical state management.

Instance — Unified detection container

• Combines id, class_id, category, conf, box, polygon, obb.
• Strict validation on all properties.
• Designed for safe pipeline integration.

---

🔷 inference — Result Container

Backend-agnostic output format with collection-like API

Classes

Timing — Pipeline stage duration tracking

• __init__(): Initializes with preprocess, prediction, postprocess (all Optional[float]).
• total: Computed property returning sum of non-None stages.
• to_dict(), from_dict(): Full JSON serialization with None support.
• Gracefully handles partial profiling data.

Result — Universal result container

• __init__(): Accepts instances, timing, width, height, depth, device, category.
• __len__(): Returns number of detected instances.
• __iter__(): Enables for instance in result: iteration.
• __getitem__(): Supports result[0] and result[-1] indexing.
• width, height, depth: Absolute pixel dimensions (int, strictly > 0).
• device: Hardware backend (DeviceType enum).
• category: Semantic category enumeration (Optional[EnumType]).
• to_dict(), from_dict(): JSON serialization (instances omitted, metadata only).

---

🔷 tracker — Multi-Object Tracking

Persistent IDs, trajectory management, ADAS integration

Classes

Tracker — Main tracking engine

• __init__(): Configurable with YOLO model, device, thresholds, max_length.
• track(): Main entry point — returns List[TrackedObject] with persistent IDs.
• predict(): Detection mode with optional tracking.
• Properties: model, device, conf, iou, max_length — all validated.

TrackedObject — Single tracked entity

• id: Tracking identifier (Optional[int]).
• instance: Latest Instance detection data.
• trajectory: TimedPointQueue with historical positions.

TimedPointQueue — Fixed-length trajectory history

• enqueue(), dequeue(): FIFO with auto-eviction.
• average_x/y/z: O(1) incremental centroid calculation.
• get_values(): Deep-copy snapshot for safe external access.
• __len__(), __iter__(), __getitem__(): Collection-like behavior.

TimedPoint — Time-stamped spatial point

• Extends Point with timestamp: Optional[datetime].
• to_point(): Discards temporal metadata for geometry-only ops.
• safe(), _from_raw(): Factory methods with clamping.

---

🔷 render — Visualization Layer

Type-safe drawing operations for embedded systems

Classes

Drawer — Main rendering engine

• draw_instances(): Renders multiple objects with alpha-blended overlays 🔥
• draw_box_fill(), draw_box_stroke(): Axis-aligned boxes with firmware-style corners.
• draw_obb_fill(), draw_obb_stroke(): Oriented boxes with rotated corners.
• draw_polygon_fill(), draw_polygon_stroke(): Segmentation masks with smoothing.
• draw_trajectory(): Movement paths with None filtering.
• draw_text(): Absolute pixel coordinate text rendering.
• @validate_frame decorator on all public methods — zero-crash guarantee.

Style — Centralized visualization config

• palette: Unique RGB tuples with [0, 255] validation.
• stroke: Stroke configuration (thickness, segment, alpha).
• fill: Fill configuration (alpha).
• font: Font configuration (color, font face, scale, thickness).
• rounding, smooth, alpha: All range-validated.
• label: LabelPosition enum for badge placement.
• show: Global toggle — False bypasses all rendering.
• to_dict(), from_dict(): Full JSON serialization.

Stroke — Outline styling

• thickness: Line thickness in pixels (int ≥ 0).
• segment: Corner segment factor [0.0, 0.5].
• alpha: Stroke opacity [0.0, 1.0].

Fill — Interior fill styling

• alpha: Fill opacity [0.0, 1.0].

Font — OpenCV typography config

• color: 3-element RGB tuple validation.
• font: OpenCV font identifier [0, 7].
• font_scale, thickness: Positive integer validation.

LabelPosition — Badge positioning enum

• TOP, BOTTOM, LEFT, RIGHT, CENTER, OFF.

---

💡 Quick Start

from acmenra_cv.instance import Point, Box, Instance
from acmenra_cv.inference import Result, Timing
from acmenra_cv.tracker import Tracker, TimedPointQueue
from acmenra_cv.render import Drawer, Style, Font, Stroke, Fill
from acmenra_cv.instance import DeviceType
from ultralytics import YOLO
from enum import Enum

# Define your categories
class CocoClass(Enum):
    PERSON = 0
    CAR = 2
    # ... other classes

# 1. Initialize components
model = YOLO("yolov8n.pt")
style = Style(
    palette=[(255, 0, 0), (0, 255, 0), (0, 0, 255)],
    font=Font(color=(255, 255, 255)),
    stroke=Stroke(thickness=2, segment=0.1, alpha=0.8),
    fill=Fill(alpha=0.3),
    show=True
)
tracker = Tracker(
    id=0,
    model=model,
    category=CocoClass,
    device=DeviceType.CPU,
    max_length=50
)
drawer = Drawer(style=style)

# 2. Process a frame
frame = ...  # Your BGR frame (numpy array)
tracked_objects = tracker.track(frame, enable_tracking=True)

# 3. Create Result container (optional, for serialization)
timing = Timing(preprocess=1.5, prediction=15.2, postprocess=2.1)
result = Result(
    instances=[obj.instance for obj in tracked_objects],
    timing=timing,
    width=frame.shape[1],
    height=frame.shape[0],
    depth=1,
    device=DeviceType.CPU,
    category=CocoClass
)

# 4. Render results
output = drawer.draw_instances(
    frame=frame,
    tracked_objects=tracked_objects,
    is_box=True,
    is_trajectory=True
)

# 5. Use Result collection-like API
print(f"Detected {len(result)} objects")
for instance in result:
    print(f"  - {instance.category.name}: {instance.conf:.2f}")

# 6. Serialize for Outbox/Analytics
result_dict = result.to_dict()
# ... send to backend or save to disk

# 7. Use spatial data for business logic
for obj in tracked_objects:
    if obj.trajectory.count >= 5:
        speed = estimate_speed(obj.trajectory)  # Your logic
        if obj.instance.category == CocoClass.CAR and speed > threshold:
            trigger_alert(obj)

---

📋 Requirements

numpy>=1.21.0
opencv-python>=4.5.0
ultralytics>=8.0.0

Optional for development:

pytest>=7.0.0
ddt>=1.6.0
black>=23.0.0
mypy>=1.0.0

---

🧪 Testing

The library includes comprehensive test suites with DDT (Data-Driven Testing) and extensive mocks:

# Run all tests
pytest tests/

# Run specific module tests
pytest tests/inference/
pytest tests/instance/
pytest tests/tracker/
pytest tests/render/

Test coverage includes:

• ✅ Type validation (positive and negative paths)
• ✅ Range validation (boundary conditions)
• ✅ Serialization round-trips (to_dict ↔ from_dict)
• ✅ Edge cases (empty collections, None values, extreme values)
• ✅ Collection-like behavior (__len__, __iter__, __getitem__)

---

🔐 License

© 2026 acmenra.studio. All rights reserved.

This software is proprietary and confidential. Unauthorized copying, distribution, or use is strictly prohibited.

For commercial licensing inquiries: [e-mail]

---

🌐 Links

• PyPI: https://pypi.org/project/acmenra-cv/
• Source: https://github.com/acmenra/acmenra-cv
• Documentation: https://github.com/acmenra/acmenra-cv#readme
• Issues: https://github.com/acmenra/acmenra-cv/issues

---

acmenra.studio — Building reliable vision systems for the edge.
Every millisecond and frame buffer counts. 🚀