Core

3.3 `docs/core.md` — Обзор acmenra-core¶

# 🧱 acmenra-core

**Базовая библиотека компьютерного зрения** для создания production-ready решений.

[![PyPI](https://img.shields.io/pypi/v/acmenra-core.svg)](https://pypi.org/project/acmenra-core/)
[![Python](https://img.shields.io/pypi/pyversions/acmenra-core.svg)](https://pypi.org/project/acmenra-core/)
[![License](https://img.shields.io/pypi/l/acmenra-core.svg)](license.md)

```bash
pip install acmenra-core

Обзор¶

acmenra-core — это высокопроизводительная, типобезопасная библиотека компьютерного зрения, спроектированная для real-time приложений на embedded-системах (Raspberry Pi 5, Jetson, NPU и др.).

Построена по принципам Clean Architecture и включает пять связанных модулей:

Модуль	Назначение	Ключевые возможности
Instance	Пространственные примитивы	Point, Box, Polygon, OBB, Instance
Inference	Backend-agnostic inference	YOLO, PyTorch, ONNX backends
Tracker	Multi-object tracking	Persistent IDs, траектории
Render	Визуализация	Alpha-blending, embedded-оптимизации
Utils	Утилиты	Illumination, geometry helpers

Ключевые возможности¶

🔹 Типобезопасность¶

Строгая валидация типов и диапазонов ([0.0, 1.0] с safe()-фабрикой)
Неизменяемые трансформации (scale, translate, smooth)
Полная типобезопасность с автодополнением в IDE

🔹 Backend-agnostic¶

Универсальный интерфейс для разных inference engines
Поддержка YOLO (через YOLOBackend)
Поддержка PyTorch (через PyTorchBackend)
Расширяемость — легко добавить свой backend

🔹 Embedded-ready¶

Zero-crash OpenCV с @validate_frame-декоратором
Глобальный toggle show=False для headless-режима
Memory-efficient очереди траекторий с O(1) вычислением
Grid-sampled утилиты с ускорением 10-50×

Модули¶

Instance (пространственные примитивы)¶

Типобезопасные контейнеры для геометрических объектов:

Point — валидированная 3D точка с координатами [0.0, 1.0]
Box — axis-aligned 3D bounding box
Polygon — vertex collection для масок сегментации
Obb — oriented (rotated) bounding box
Instance — детектированный объект с классификацией

from acmenra_core.instance import Point, Box, Instance
from enum import Enum

class CocoClass(Enum):
    PERSON = 0
    CAR = 2

# Создание точки
p = Point(X=0.5, Y=0.3, Z=0.0)

# Создание bounding box
box = Box(left=0.1, right=0.5, top=0.2, bottom=0.8, front=0.5, back=0.5)

# Создание instance
instance = Instance(
    id=42,
    class_id=2,
    label=CocoClass.CAR,
    conf=0.95,
    box=box,
)

Inference (backend-agnostic inference)¶

Универсальный интерфейс для разных inference engines:

from acmenra_core.inference import YOLOBackend, Result
from acmenra_core.instance import DeviceType, TaskType
from ultralytics import YOLO

# Загрузка модели
model = YOLO("yolov8n.pt")

# Создание backend
backend = YOLOBackend(
    model=model,
    device=DeviceType.CPU,
    category=CocoClass,
    task_type=TaskType.DETECT,
    threshold=0.5,
)

# Инференс
result = backend.predict(frame)

# Обработка результатов
for instance in result:
    print(f"{instance.label.name}: {instance.conf:.2f}")

Tracker (multi-object tracking)¶

Отслеживание объектов с persistent IDs и траекториями:

from acmenra_core.tracker import Tracker

# Создание трекера
tracker = Tracker(
    id=0,
    backend=backend,
    max_length=50,  # Длина истории траектории
)

# Отслеживание
tracked_objects = tracker.track(frame, enable_tracking=True)

# Доступ к траекториям
for obj in tracked_objects:
    print(f"ID: {obj.id}, Trajectory length: {len(obj.trajectory)}")

Render (визуализация)¶

Типобезопасная визуализация с alpha-blending:

from acmenra_core.render import Drawer, Style, Stroke, Fill

# Настройка стиля
style = Style(
    palette=[(255, 0, 0), (0, 255, 0), (0, 0, 255)],
    stroke=Stroke(thickness=2, segment=0.1, alpha=0.8),
    fill=Fill(alpha=0.3),
    show=True,
)

# Создание drawer
drawer = Drawer(style=style)

# Визуализация
output = drawer.draw_instances(
    frame=frame,
    tracked_objects=tracked_objects,
    is_box=True,
    is_trajectory=True,
)

Utils (утилиты)¶

Вспомогательные функции для CV:

from acmenra_core.utils import get_frame_illumination

# Оценка освещённости кадра
illumination = get_frame_illumination(
    frame=frame,
    grid_size=10,
    method="BGR",
)

print(f"Illumination: {illumination:.2f}")

Требования¶

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

Совместимость¶

ОС	Статус
Astra Linux SE 1.7+	✅ Полная совместимость
РЕД ОС 7.3+	✅ Полная совместимость
ROSA Chrome / Fresh	✅ Поддерживается
Ubuntu / Debian	✅ Поддерживается

Подробнее

Лицензия¶

Продукт включён в Реестр отечественного ПО РФ.

Лицензионное соглашение

Ссылки¶

PyPI: https://pypi.org/project/acmenra-core/
GitHub: https://github.com/acmenra/acmenra-core
Документация: https://docs.acmenra.studio/core
Issues: https://github.com/acmenra/acmenra-core/issues ```