🚀 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:

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

🔷 inference — Result Container

Backend-agnostic output format with collection-like API

🔷 tracker — Multi-Object Tracking

Persistent IDs, trajectory management, ADAS integration

🔷 render — Visualization Layer

Type-safe drawing operations for embedded systems

💡 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: contact@acmenra.studio

🌐 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. 🚀