Перейти к содержанию

📚 Модули acmenra-ds

Config

Типобезопасный контейнер для конфигурации YOLO-датасета из YAML-файла.

Ключевые особенности

  • Автодетект Layout: Автоматически определяет DIRECT (train/images) или REVERSE (images/train) на основе пути в YAML.
  • Валидация путей: Запрещает абсолютные пути, .. и пустые строки на этапе инициализации.
  • Защита от мутаций: Любая попытка изменить конфигурацию после __init__ логируется как WARNING.

Основные свойства

  • root, train, val, test: Разрешенные абсолютные пути (Path).
  • names, nc: Список классов и их количество.
  • task, layout: TaskType и DatasetLayout enum'ы.
  • *_leaf: Имена папок (например, images_leaf="frames").

Dataset

Верховный контейнер для всего датасета, оркестрирующий общие ресурсы.

Методы

  • health() → Dict: Агрегирует отчеты о здоровье всех активных сплитов. Возвращает количество отсутствующих файлов и список первых 30 ошибок.
  • visualize(sample, style) → np.ndarray: Универсальный метод отрисовки. Автоматически определяет task (DETECT/SEGMENT/OBB) и включает нужные флаги для Drawer.
  • split(name) → Optional[Split]: Безопасный доступ к конкретному сплиту по имени или Enum.

Split

Представляет один сплит (Train, Val или Test) с атомарным парсингом и опциональным кэшированием.

Методы

  • __iter__() / __getitem__(idx): Позволяет использовать сплит как итерируемый объект или список для PyTorch DataLoader.
  • get_instances(idx) → List[Instance]: Абстрагирует логику кэша. Если is_cache=True, возвращает данные из RAM, иначе парсит .txt на лету.
  • get_random_sample() → Sample: Возвращает случайный сэмпл для быстрого дебага без накладных расходов на парсинг.
  • visualize(idx, style) → np.ndarray: Отрисовывает сэмпл по индексу.

Sample

Типизированное представление пары "изображение + опциональная разметка". Заменяет хрупкие кортежи (Path, Path).

Свойства

  • stem: Уникальный ключ для кэширования (имя файла без расширения).
  • image_path: Абсолютный путь к изображению.
  • label_path: Абсолютный путь к .txt файлу (или None, если разметки нет).
  • is_labeled(): Быстрая проверка наличия разметки.

LabelCache

In-memory кэш для распарсенных инстансов, оптимизированный для циклов обучения.

Особенности

  • Хранит List[Instance], ключом является stem.
  • Поддерживает max_size для предотвращения Out-Of-Memory (OOM) ошибок.
  • Предоставляет Pythonic API: __getitem__, __contains__, __len__.

Augmentation

In-memory пайплайн поверх acmenra-cv.Instance. Не ходит на диск — это делает Split + LabelWriter.

Класс Роль
Transform ABC. p крутится в __call__, подклассы пишут только apply().
Compose Последовательность шагов. Пустой список запрещён. Getter возвращает копию.
Geometric HorizontalFlip, VerticalFlip, Resize — пиксели + геометрия.
Photometric Brightness, ChannelBrightness, Blur, Noise, Pixelate, Gray, Normalize — только пиксели. 
from acmenra_ds.augmentation import Compose, HorizontalFlip, Brightness

pipeline = Compose([
    HorizontalFlip(p=0.5),
    Brightness(p=0.8),
])
aug_image, aug_labels = pipeline(image, labels)

Полный контракт, список шагов и ограничения (Normalize, OBB + anisotropic Resize) — на странице Аугментация.

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

Вернуться к обзору | Аугментация | Документация плагина acmenra-yolo