Быстрый старт с acmenra-ds

В этих примерах показано, как использовать acmenra-ds для загрузки, проверки, визуализации и аугментации YOLO-датасетов.

Пример 1: Загрузка конфигурации и проверка здоровья (Health Check)

Самый надежный способ начать работу — проверить целостность датасета перед обучением.

from acmenra_ds import Config
from acmenra_ds.data import Dataset

# 1. Парсим YAML (автоматически определит DIRECT или REVERSE layout)
config = Config.from_yaml(yaml_path="/path/to/your/dataset/data.yaml")
print(f"Загружено классов: {config.nc}, Layout: {config.layout.value}")

# 2. Инициализируем Dataset
dataset = Dataset(config=config)

# 3. Проверяем здоровье всего датасета
report = dataset.health()

if report["is_healthy"]:
    print(f"✅ Датасет здоров! Всего сэмплов: {report['total_samples']}")
else:
    print(f"❌ Найдены проблемы:")
    for error in report["errors"]:
        print(f"  - {error}")

Пример 2: Итерация и визуализация сплита

Используйте встроенный .visualize() для мгновенной отрисовки разметки поверх изображения.

import cv2
import numpy as np
from enum import IntEnum
from acmenra_cv import Style, Stroke, Fill
from acmenra_ds import Config
from acmenra_ds.data import Dataset

# 1. Определяем категории (IntEnum критически важен для маппинга class_id)
class IndustrialClass(IntEnum):
    inclusion = 0
    scratch = 1
    crack = 2

# 2. Инициализация
config = Config.from_yaml(yaml_path="/path/to/your/dataset/data.yaml")
dataset = Dataset(config=config, category=IndustrialClass)

# 3. Настройка стиля отрисовки
style = Style(
    palette=np.random.randint(0, 255, (80, 3)).tolist(),
    stroke=Stroke(thickness=2, alpha=0.8),
    fill=Fill(alpha=0.2),
    show=True,
)

# 4. Визуализация первых 5 изображений из тренировочного сплита
for i, sample in enumerate(dataset.train):
    if i >= 5:
        break

    # dataset.visualize автоматически парсит лейблы и рисует Box/Polygon/Obb
    drawn_frame = dataset.visualize(sample=sample, style=style)

    cv2.imshow("Acmenra Dataset Sample", drawn_frame)
    if cv2.waitKey(1000) & 0xFF == ord("q"):
        break

cv2.destroyAllWindows()

Пример 3: Работа с кэшем и сырыми инстансами

Если вам нужен доступ к распарсенным объектам Instance (например, для кастомной аугментации), используйте get_instances.

# Включаем RAM-кэширование при инициализации
dataset = Dataset(config=config, category=IndustrialClass, is_cache=True)

for idx in range(10):
    # Мгновенное получение List[Instance] из кэша (O(1))
    instances = dataset.train.get_instances(idx)

    for inst in instances:
        print(f"Class: {inst.label.name}, Conf: {inst.conf:.2f}")
        if inst.box:
            print(f"  Box center: ({inst.box.center.X:.2f}, {inst.box.center.Y:.2f})")

Пример 4: Онлайн-аугментация через Compose

Единый контракт: (image, List[Instance]) → (image, List[Instance]). Каждый шаг крутит свой p независимо. Источники Instance не мутируются.

import cv2
from acmenra_cv import Style, Stroke, Fill, Drawer, TaskType
from acmenra_ds import Config
from acmenra_ds.data import Dataset
from acmenra_ds.augmentation import (
    Compose,
    HorizontalFlip,
    VerticalFlip,
    Brightness,
    Blur,
    Noise,
)

config = Config.from_yaml(yaml_path="/path/to/your/dataset/data.yaml")
dataset = Dataset(config=config, category=IndustrialClass, is_cache=True)

pipeline = Compose([
    HorizontalFlip(p=0.5),
    VerticalFlip(p=0.5),
    Brightness(min_factor=0.6, max_factor=1.4, p=0.8),
    Blur(max_ksize=5, p=0.4),
    Noise(max_ratio=0.03, p=0.4),
])

style = Style(
    stroke=Stroke(thickness=2, alpha=0.8),
    fill=Fill(alpha=0.2),
    show=True,
)
drawer = Drawer(style=style)

for idx, sample in enumerate(dataset.train):
    image = dataset.train.image_parser.parse(sample.image_path, is_strict=False)
    labels = dataset.train.get_instances(idx)
    if image is None:
        continue

    aug_image, aug_labels = pipeline(image, labels)

    vis = drawer.draw_instances(
        frame=aug_image.copy(),
        instances=aug_labels,
        is_box=dataset.task == TaskType.DETECT,
        is_obb=dataset.task == TaskType.OBB,
        is_polygon=dataset.task == TaskType.SEGMENT,
    )
    cv2.imshow("Augmented", vis)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cv2.destroyAllWindows()

Normalize не для imshow / JPEG

Normalize переводит uint8 [0, 255] в float32 [0.0, 1.0]. Ставьте его последним шагом только в training-loop. Не кладите в пайплайн визуализации и не пишите float как JPEG.

Геометрия не отстаёт от пикселей

HorizontalFlip / VerticalFlip зеркалят Box, Polygon и OBB через map_instance. Resize пиксели меняет, нормализованные координаты [0, 1] оставляет как есть. Фотометрия (Brightness, Blur, Noise, …) список лейблов не трогает.

Полный список шагов и контракт p — на странице Аугментация.

---

Следующие шаги

Изучить модули | Аугментация