Датасеты

Указание датасета для обучения

data= принимает путь к YAML или имя конфига, который поставляется вместе с пакетом.

from libreyolo import LibreYOLO model = LibreYOLO("LibreYOLO9s.pt") # Подойдёт встроенное имя, относительный путь или абсолютный путь.model.train(data="coco8.yaml", epochs=10)

libreyolo train model=LibreYOLO9s.pt data=coco8.yaml epochs=10

Имя разрешается в фиксированном порядке: существующий абсолютный путь, затем имя как есть относительно рабочего каталога, затем то же имя с добавленным .yaml, затем каталог встроенных конфигов. Если ничего не совпало, в ошибке перечисляются все просмотренные каталоги и все встроенные конфиги.

Встроенные конфиги

Вместе с пакетом поставляются тринадцать конфигов датасетов — они лежат в libreyolo/config/datasets/.

Обычный URL для скачивания есть только у coco8.yaml и coco128.yaml. Остальные либо содержат Python-блок скачивания, для которого нужно явное разрешение (описано ниже), либо ожидают, что данные уже лежат на диске.

Где датасет лежит на диске

Ключ path в YAML задаёт корень датасета. Абсолютный path используется как есть. Относительный сначала ищется в каталоге датасетов, затем рядом с самим YAML-файлом, а датасет, который предстоит скачать, попадает в каталог датасетов.

Этот каталог — ~/datasets, его переопределяет переменная окружения LIBREYOLO_DATASETS_DIR. Файла настроек для него нет.

Ключи YAML

path: my-dataset        # корень датасета
train: images/train     # нужен для обучения
val: images/val         # нужен для валидации
test: images/test       # необязателен
nc: 3                   # необязателен; должен согласовываться с names
names:
  0: person
  1: helmet
  2: vest
download: https://example.com/my-dataset.zip   # необязателен

train, val и test принимают каталог с изображениями, файл .txt с одним путём к изображению на строку или список, где смешано и то и другое. Строки в списке .txt могут быть относительными — тогда они разрешаются относительно каталога самого файла со списком, — а строки, начинающиеся с #, пропускаются.

names может быть списком или отображением с целочисленными ключами. nc необязателен; если присутствуют оба и они расходятся, doctor сообщает об этом как об ошибке.

Структура каталогов и файлы разметки

У детекции, сегментации, оценки позы и повёрнутых рамок структура одна. Путь к разметке выводится из пути к изображению: компонент каталога images заменяется на labels, а расширение — на .txt:

my-dataset/
  images/train/0001.jpg   ->   labels/train/0001.txt
  images/val/0002.jpg     ->   labels/val/0002.txt

Заменяется только целый компонент пути images, поэтому каталог с именем images_old остаётся нетронутым.

Строка детекции — это пять полей, все нормированы к [0, 1] по исходной ширине и высоте изображения:

<class_id> <cx> <cy> <w> <h>

Отсутствующий или пустой файл разметки означает, что на изображении нет объектов: при обучении оно идёт как фон, а не вызывает ошибку. Строка, в которой больше пяти полей, читается как полигон, и рамкой для неё становится габаритный прямоугольник этого полигона, поэтому экспорт сегментации, использованный для обучения детекции, загружается без ошибок. Doctor сообщает, сколько строк прошло по этому пути.

Другие задачи

Сегментация сохраняет ту же структуру, но со строками-полигонами <class_id> <x1> <y1> ... <xN> <yN> минимум из трёх точек. Строка детекции из пяти полей принимается и означает прямоугольный экземпляр.

Оценка позы добавляет в YAML kpt_shape: [K, D] и необязательную перестановку flip_idx. В каждой строке ровно 5 + K * D полей: рамка, затем K ключевых точек вида x y или x y v, где видимость — 0, 1 или 2.

Повёрнутые рамки используют ровно девять полей: класс, а за ним четыре угловые точки в нормированных координатах. Угол в файле не хранится.

Семантическая сегментация сопоставляет каждому изображению одноканальную маску того же разрешения; путь получается подстановкой masks_dir (по умолчанию masks) вместо images. Значение пикселя 255 означает «игнорировать». label_mapping при загрузке переводит исходные id в id для обучения.

Классификация вместо файлов разметки использует дерево ImageFolder: в train/ и val/ лежит по одному каталогу на класс. Соответствие класса и индекса задаётся отсортированным порядком имён каталогов.

Восстановление сопоставляет искажённый вход с чистым целевым изображением того же разрешения через input_dir и target_dir. Оценка глубины, нормали к поверхности и границы сопоставляют изображению плотную карту, каждая через свой ключ каталога.

Полный контракт по каждой задаче, включая соглашения о масштабе глубины и кодирование id паноптических сегментов в PNG, — это docs/dataset_schema.md в репозитории библиотеки.

Нативный COCO JSON

Файл аннотаций COCO JSON можно использовать напрямую. Добавьте отображение annotations, и путь сплита станет корнем с изображениями:

path: my-dataset
train: images/train
val: images/val
annotations:
  train: annotations/train.json
  val: annotations/val.json

Если names присутствует, имена категорий в JSON должны с ним совпадать, и именно names задаёт id меток, которые предсказывает модель. Без names id категорий COCO сортируются и плотно отображаются в 0..N-1.

Этот путь ожидает по одному каталогу с изображениями на сплит. Список путей или список изображений в .txt вызывает ошибку, а не загружает молча другой набор.

Автоскачивание

Датасет считается на месте, когда его путь train или val разрешается в непустой каталог или в существующий файл. Если это не так, а в YAML есть ключ download, дальнейшее решает его значение.

URL с http или https скачивается и, если это zip, распаковывается в корень датасета. Всё остальное считается встроенным Python-скриптом и запускается только при allow_download_scripts=True. Без этого скрипт пропускается с предупреждением, а обучение продолжается на том, что лежит на диске.

libreyolo train model=LibreYOLO9s.pt data=coco.yaml allow_download_scripts=true

Этот флаг ограничивает выполнение кода, а не доступ к сети. Скачивание по URL происходит в любом случае; флаг нужен именно блокам download: |. CLI печатает предупреждение, когда флаг включён, а doctor не включает его никогда.

Проверка датасета перед обучением

libreyolo doctor читает датасет для детекции и сообщает, что пойдёт не так, ещё до того, как в дело вступит GPU. При найденных ошибках он завершается с кодом 1, поэтому годится как CI-гейт.

libreyolo doctor my-dataset.yaml

libreyolo doctor my-dataset.yaml strict=true json=true

# Читает только разметку и YAML. Проверки на повреждения, дубликаты# и утечки между сплитами требуют пикселей, поэтому пропускаются.libreyolo doctor my-dataset.yaml fast=true

from libreyolo import doctor report = doctor.diagnose("my-dataset.yaml", imgsz=640) for finding in report.findings:    print(finding.severity.value, finding.check_id, finding.message) raise SystemExit(report.exit_code(strict=False))

Проверки разбиты на шесть семейств:

--only и --skip принимают id проверки или префикс семейства, поэтому skip=images,labels.tiny_object — корректная запись. --fast отбрасывает все проверки, которым нужно декодировать пиксели, то есть семейства images и splits.

Стоит знать о двух особенностях. С --strict на код возврата влияют не только ошибки, но и предупреждения. И doctor работает только с датасетами для детекции: датасет для оценки позы, сегментации или повёрнутых рамок отклоняется с сообщением о том, что именно распознано, вместо проверки по неподходящему контракту.

Смотрите также

• Гиперпараметры — про аргументы, которые принимает train(), когда данные на месте.
• Валидация и метрики — про оценку на сплите val или test.