🚀 acmenra-cv

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

# Install core library (lightweight, no heavy ML dependencies)
pip install acmenra-cv

# OR install with YOLO support (includes ultralytics, torch, etc.)
pip install "acmenra-cv[yolo]"

📦 Overview

acmenra-cv is a high-performance, type-safe computer vision library engineered for real-time applications on resource-constrained embedded systems (Raspberry Pi, Jetson, NPU, etc.). Built following Clean Architecture principles, it provides a strict, domain-agnostic interface for spatial reasoning and tracking, while delegating specific model inference to optional plugin packages (like acmenra-yolo).

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

✨ Key Features

🔹 Unified & Backend-Agnostic Architecture

• Strict type & range validation ([0.0, 1.0] with safe() clamping factory)
• Seamless plugin integration (e.g., acmenra-yolo for Ultralytics, future OpenVINO/TensorRT plugins)
• Immutable geometric transformations (scale, translate, smooth)
• Full type safety with IDE autocomplete and consistent API across all primitives

🔹 Robust Result Handling

• 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 and analytics

🔹 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) incremental average calculation
• Grid-sampled utilities delivering 10-50× speedup on resource-constrained devices

🔹 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 & Contracts

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

🔷 utils — Foundational Helpers

High-performance, resource-aware operations

💡 Quick Start

from enum import Enum
import numpy as np

# 1. Import core components
from acmenra_cv.instance import DeviceType, TaskType
from acmenra_cv.inference import Result, Timing
from acmenra_cv.tracker import Tracker
from acmenra_cv.render import Drawer, Style, Font, Stroke, Fill

# 2. Import YOLO plugin (requires: pip install "acmenra-cv[yolo]")
from acmenra_yolo import YOLOBackend
from ultralytics import YOLO

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

# 4. Initialize components
model = YOLO("yolov8n.pt")

# Backend-agnostic inference engine (provided by acmenra-yolo plugin)
backend = YOLOBackend(
    model=model,
    device=DeviceType.CPU,
    category=CocoClass,          # Enum CLASS
    task_type=TaskType.DETECT,
    threshold=0.5,
    iou=0.7,
    imgsz=640,
    half=False,
    refined=False
)

# Visualization styling
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 receives the backend, decoupling inference from tracking logic
tracker = Tracker(id=0, backend=backend, max_length=50)
drawer = Drawer(style=style)

# 5. Process a frame
frame = np.zeros((1080, 1920, 3), dtype=np.uint8)  # Replace with your BGR frame
tracked_objects = tracker.track(frame, enable_tracking=True)

# 6. Create Result container (optional, for serialization/analytics)
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
)

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

# 8. Use Result collection-like API
print(f"Detected {len(result)} objects")
for instance in result:
    # Note: use instance.label (Enum member), not instance.category
    print(f"  - {instance.label.name}: {instance.conf:.2f}")

# 9. Serialize for Outbox/Analytics
result_dict = result.to_dict()

# 10. Use spatial data for business logic
for obj in tracked_objects:
    if obj.trajectory.count >= 5:
        if obj.instance.label == CocoClass.CAR:
            pass # trigger_alert(obj)

📋 Requirements

Core dependencies (installed with pip install acmenra-cv):

numpy>=1.21.0
opencv-python>=4.5.0

Optional dependencies (installed with pip install "acmenra-cv[yolo]"):

acmenra-yolo>=0.1.0.0
ultralytics>=8.0.0
torch>=1.8.0

Development dependencies:

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

This project is licensed under the GNU Affero General Public License v3 or later (AGPL-3.0-or-later).
See the LICENSE file for details.

🌐 Links

• PyPI: https://pypi.org/project/acmenra-cv/
• YOLO Plugin: https://pypi.org/project/acmenra-yolo/
• 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. 🚀