Когда в пайплайне детекции всё настроено, но mAP не растёт, проблема часто кроется не в модели, а в разметке после аугментации. Изображение может быть отражено, обрезано или повернуто, но координаты боксов при этом либо не обновляются, либо интерпретируются неверно. Код не падает, массивы выглядят корректно, обучение идёт — но модель учится на искажённых данных.

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

Форматы ограничивающих боксов

Разные датасеты и фреймворки используют разные форматы координат. Albumentations поддерживает пять из них. В A.BboxParams нужно указать coord_format — тот формат, в котором представлена ваша разметка.

Поддерживаемые форматы:

• pascal_voc: [x_min, y_min, x_max, y_max] — в пикселях, используется в PASCAL VOC и многих кастомных датасетах.
• albumentations: [x_min, y_min, x_max, y_max] — нормализованные значения [0, 1], внутренний формат библиотеки.
• coco: [x_min, y_min, width, height] — в пикселях.
• yolo: [x_center, y_center, width, height] — нормализованные значения [0, 1], используется в Ultralytics YOLO и Darknet.
• cxcywh: [x_center, y_center, width, height] — в пикселях, аналог YOLO, но без нормализации.

Например, для изображения 640 × 480 и бокса от (98, 345) до (420, 462):

• pascal_voc: [98, 345, 420, 462]
• albumentations: [0.153, 0.719, 0.656, 0.962]
• coco: [98, 345, 322, 117]
• yolo: [0.405, 0.841, 0.503, 0.244]
• cxcywh: [259, 403.5, 322, 117]

Самая частая ошибка — неверный coord_format. Данные при этом выглядят правдоподобно, ошибок нет, но боксы указывают не туда. Всегда проверяйте, в каком формате выдаёт разметку ваш инструмент или датасет.

Сборка пайплайна для детекции

Используйте A.Compose и передайте в неё A.BboxParams, чтобы библиотека знала, как обрабатывать боксы:

В одном пайплайне можно смешивать разные трансформации:

• Пиксельные (например, RandomBrightnessContrast) — меняют только изображение.
• Пространственные (например, HorizontalFlip) — обновляют и изображение, и координаты боксов.

Это обеспечивает согласованность: боксы всегда соответствуют аугментированному изображению.

Если нужно проверить, какие трансформации поддерживают боксы, используйте таблицу совместимости в документации Albumentations.

Передача меток и метаданных

Можно передавать только координаты боксов, без меток. Но если к каждому боксу нужно привязать класс, ID или другой атрибут — есть два способа.

Способ 1: отдельные поля через label_fields

Укажите имена полей в label_fields и передайте их как отдельные аргументы:

Поля могут содержать строки или числа. При фильтрации боксов соответствующие записи в этих полях удаляются автоматически — синхронизация поддерживается без вмешательства.

Этот подход удобен не только для классов:

• Видео: добавьте frame_ids, чтобы отслеживать, из какого кадра пришёл бокс.
• Instance segmentation: передайте instance_ids, чтобы сохранить связь между маской и боксом.

Способ 2: упаковка метаданных в массив bbox

Если метаданные числовые, их можно добавить как дополнительные столбцы в массив боксов. Например, форма (num_boxes, 6): 4 координаты + 2 столбца метаданных.

Этот способ компактнее, но подходит только для числовых данных. Для строк или именованных полей лучше использовать label_fields.

Что делает A.BboxParams

A.BboxParams управляет интерпретацией и фильтрацией боксов. Основные параметры:

• coord_format — обязательный: один из 'pascal_voc', 'albumentations', 'coco', 'yolo', 'cxcywh'.
• bbox_type — 'hbb' для обычных боксов, 'obb' для ориентированных.
• label_fields — имена полей с метками, привязанными к боксам.
• min_area — минимальная площадь бокса в пикселях после аугментации. Меньшие удаляются.
• min_visibility — минимальная доля исходной площади бокса, которая должна остаться видимой.
• min_width, min_height — минимальные ширина и высота.
• clip_bboxes_on_input — обрезать боксы по границам изображения до аугментации. Полезно при разметке за пределами кадра.
• filter_invalid_bboxes — удалять невалидные боксы (например, с x_max < x_min) до аугментации.
• max_accept_ratio — максимальное отношение сторон. Боксы с превышением отбрасываются.

На практике ключевыми часто становятся: coord_format, label_fields, min_visibility и настройки обработки некорректной разметки (clip_bboxes_on_input + filter_invalid_bboxes).

Работа с неидеальной разметкой

В реальных данных боксы могут выходить за границы изображения. Чтобы избежать проблем:

• Включите clip_bboxes_on_input=True — координаты будут обрезаны до аугментации.
• Включите filter_invalid_bboxes=True — удалятся вырожденные боксы (нулевой ширины/высоты).

Когда использовать min_area и min_visibility

После кропа боксы могут превратиться в узкие полосы. Два фильтра помогают избавиться от таких случаев:

• min_area — фильтрует по абсолютной площади. Подходит, если важен физический размер объекта.
• min_visibility — фильтрует по доле исходной площади. Полезно, когда важно, сколько объекта осталось в кадре.

Часто min_visibility оказывается более эффективным: он не даёт обучаться на почти полностью обрезанных объектах.

Стратегии кадрирования

Обычный RandomCrop может выдать кадр без единого бокса. Для детекции это бесполезный пример. Лучше использовать bbox-aware альтернативы:

• AtLeastOneBboxRandomCrop — гарантирует хотя бы один бокс в кадре.
• BBoxSafeRandomCrop — сохраняет все боксы, подбирая область кропа так, чтобы ничего не потерять.
• RandomSizedBBoxSafeCrop — сохраняет все боксы, затем масштабирует к целевому размеру. Один из самых полезных вариантов для обучения.

Для детекции не стоит использовать обычный RandomCrop бездумно — он подходит для классификации, но не для задач с разметкой.

Типичные ошибки

Неверный coord_format

Главная ошибка. Например, разметка в формате YOLO, но указан coord_format='coco'. Код работает, но боксы смещаются. Всегда визуально проверяйте аугментированные примеры перед обучением.

Все боксы отфильтровались

Агрессивные кропы + жёсткие min_area или min_visibility могут привести к пустому массиву bboxes. Датасет или цикл обучения должны уметь обрабатывать такие случаи:

• пропускать примеры без боксов;
• использовать bbox-safe кропы, чтобы минимизировать потери.

Перепутаны нормализованные и абсолютные координаты

Формат yolo требует значений [0, 1]. Если подать пиксельные координаты, они будут обрезаны до [0, 1] — результат: крошечный бокс в углу. Обратная ошибка: нормализованные координаты в формате pascal_voc — боксы станут размером в доли пикселя и быстро отфильтруются.

Добавлена трансформация без поддержки bbox

Не все трансформации поддерживают боксы. Если добавить несовместимую в пайплайн с A.BboxParams, Albumentations выбросит исключение при инициализации. Это хорошо — ошибка видна сразу. Но всё равно проверяйте таблицу совместимости, особенно при сборке сложных пайплайнов.

Визуализация после A.Normalize

A.Normalize переводит пиксели в float, вычитает среднее и делит на std. Изображение выглядит как шум. Для отладки визуализируйте данные до A.Normalize и A.ToTensorV2.

Заключение

Аугментация в детекции — это не просто разнообразие изображений. Это синхронизация трансформаций и меток. Ошибки в формате координат, агрессивные кропы или неправильная фильтрация приводят к обучению на сломанной разметке.

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

Практический чек-лист:

1. Убедитесь, что coord_format соответствует реальному формату разметки.
2. Передайте все привязанные к боксам метки через label_fields или упакуйте в массив.
3. Для кропов используйте bbox-aware варианты, а не RandomCrop.
4. Настройте min_visibility и min_area под задачу, не оставляйте значения по умолчанию.
5. Перед обучением визуализируйте десятки аугментированных примеров с наложенными боксами.

Когда в пайплайне детекции всё вроде настроено правильно, аmAPупорно не растёт, проблема нередко оказывается не в модели и не в оптимизаторе, а в разметке после аугментации. Вы отразили изображение, сделали кроп, повернули кадр, а координаты боксов либо не сдвинулись, либо были интерпретированы в неправильном формате. Код не падает, массивы выглядят валидно, обучение идёт — но модель учится на мусоре.

Именно поэтому аугментация для детекции отличается от аугментации для классификации. Здесь недостаточно «поменять пиксели». Нужно, чтобы каждая пространственная трансформация двигала и изображение, и все ограничивающие боксы строго синхронно.

Если вы только входите в тему аугментаций, полезно сначала посмотреть два предыдущих материала:

• Аугментации изображений: как улучшить качество моделей без новых данных
• Как подбирать аугментации: гипотезы, протокол и метрики

Этот текст опирается на те идеи, но отвечает на более узкий и практический вопрос: как правильно применять аугментации, если ваши метки — это ограничивающие боксы.

В основе статьи лежитдокументация Albumentations, open-source библиотеки для аугментации изображений с15k+ звёзд на GitHub и 140M+ загрузок.

Содержание

1. Форматы ограничивающих боксов
2. Сборка пайплайна для детекции
3. Передача меток и метаданных
4. Что делаетA.BboxParams
5. Стратегии кадрирования
6. Типичные ошибки
7. Что почитать дальше

Форматы ограничивающих боксов

Разные датасеты и фреймворки используют разные соглашения о координатах. Albumentations поддерживает пять форматов. ВA.BboxParamsнужно передать тот, который уже использует ваша разметка, через параметрcoord_format.

Координаты

Где встречается

pascal_voc

[x_min, y_min, x_max, y_max]

PASCAL VOC, многие кастомные датасеты

albumentations

[x_min, y_min, x_max, y_max]

Нормализованные значения[0, 1]

Внутренний формат Albumentations

[x_min, y_min, box_width, box_height]

[x_center, y_center, box_width, box_height]

Нормализованные значения[0, 1]

Ultralytics YOLO, Darknet

[x_center, y_center, box_width, box_height]

Формат как у YOLO, но без нормализации

Если вы приходите изUltralytics(YOLOv5/YOLOv8/YOLOv11), ваши аннотации уже лежат в форматеyolo, значит вBboxParamsнужно указыватьcoord_format='yolo'.

Для изображения размером640 × 480и бокса от пикселя(98, 345)до(420, 462)одни и те же координаты будут выглядеть так:

• pascal_voc:[98, 345, 420, 462]— углы в пикселях
• albumentations:[0.153, 0.719, 0.656, 0.962]— те же углы, но нормализованные по размерам изображения
• coco:[98, 345, 322, 117]— верхний левый угол плюс ширина(420 - 98)и высота(462 - 345)
• yolo:[0.405, 0.841, 0.503, 0.244]— центр плюс размер, всё нормализовано
• cxcywh:[259, 403.5, 322, 117]— центр плюс размер в пикселях

Самая частая ошибка в работе с bbox — неверныйcoord_format. Числа всё равно будут выглядеть правдоподобно, пайплайн не выбросит исключение, но каждый ограничивающий бокс укажет не туда. Поэтому первое, что стоит перепроверить в любой задаче детекции, — какой именно формат отдаёт ваш инструмент разметки или исходный датасет.

Как собрать пайплайн для детекции

СоздайтеA.Composeи передайте в негоA.BboxParams, чтобы библиотека знала, как интерпретировать и обновлять ограничивающие боксы:

В одном пайплайне можно свободно смешивать разные типы трансформаций. Пиксельные трансформации вродеRandomBrightnessContrastменяют только изображение и не трогают боксы. Пространственные трансформации вродеHorizontalFlipобновляют и пиксели, и координаты боксов. За счёт этого результат остаётся согласованным: ограничивающие боксы всегда соответствуют аугментированному изображению.

Если хотите быстро проверить, какие трансформации вообще поддерживаютbboxes, есть публичная таблица совместимости:Поддерживаемые типы таргетов по трансформациям.

Как применять пайплайн

Загрузите изображение и подготовьте боксы как массив NumPy формы(num_boxes, 4):

Дальше передайте всё в transform. Метки нужно подавать через именованные аргументы с теми же именами, которые указаны вlabel_fields:

На выходе боксов может оказаться меньше, чем было на входе. Это нормально: боксы, которые полностью ушли за пределы изображения или стали слишком маленькими после аугментации, Albumentations отфильтрует автоматически.

Как привязывать метаданные к bbox

Метки классов не обязательны. Можно передавать только координаты, вообще без дополнительной информации:

Но если к каждому боксу нужно привязать класс, идентификатор объекта, флаг сложности или что-то ещё, есть два нормальных способа это сделать.

Способ 1: отдельные поля через label_fields

Объявите имена полей вlabel_fieldsи передайте каждое отдельным аргументом. Значения могут быть и строками, и числами:

Таких полей можно объявить сколько угодно. Если в ходе аугментации какой-то ограничивающий бокс отфильтровывается, соответствующая запись удаляется из каждого поля автоматически. Синхронизацию руками поддерживать не нужно.

Этот механизм полезен не только для классов. Любую информацию, которую нужно сохранить вместе с боксом после кропов и фильтрации, можно передавать черезlabel_fields.

Видео.Если вы складываете боксы из нескольких кадров в один массивbboxes, можно добавить полеframe_ids, чтобы отслеживать, из какого кадра пришёл каждый бокс:

После аугментацииresult['frame_ids']покажет, какие боксы пережили фильтрацию и из каких кадров они пришли.

Instance segmentation.Если каждому боксу соответствует маска экземпляра, можно передатьinstance_ids, чтобы связь между маской и bbox не потерялась:

Способ 2: упаковать метаданные прямо в массив bbox

Если вся метаинформация числовая, её можно просто добавить в массив боксов как дополнительные столбцы. Например, массив формы(num_boxes, 6)содержит 4 столбца координат и ещё 2 столбца метаданных:

Этот способ компактнее, но подходит только для числовых признаков. Если нужны строковые классы или доступ к полям по именам,label_fieldsудобнее.

Что реально управляет A.BboxParams

ИменноA.BboxParamsопределяет, как Albumentations интерпретирует и фильтрует ограничивающие боксы:

• coord_format— обязательный параметр. Один из'pascal_voc','albumentations','coco','yolo','cxcywh'.
• bbox_type—'hbb'для обычных осево-выровненных боксов с 4 координатами или'obb'для ориентированных боксов с углом. Для повернутых объектов есть отдельный разбор:Ориентированные ограничивающие боксы.
• label_fields— список имён аргументов, в которых лежат метки и другая информация, привязанная к каждому боксу.
• min_area— минимальная площадь бокса в пикселях после аугментации. Всё, что меньше, отбрасывается. По умолчанию0.0.
• min_visibility— минимальная доля исходной площади, которая должна остаться видимой после аугментации. По умолчанию0.0.
• min_width— минимальная ширина бокса в пикселях или нормализованных единицах. По умолчанию0.0.
• min_height— минимальная высота бокса в пикселях или нормализованных единицах. По умолчанию0.0.
• clip_bboxes_on_input— обрезать координаты по границам изображениядоаугментации. Полезно, если исходная разметка частично выходит за пределы кадра. По умолчаниюFalse.
• filter_invalid_bboxes— удалить невалидные боксы вродеx_max < x_minдоаугментации. Если включёнclip_bboxes_on_input=True, фильтрация происходит уже после обрезки координат. По умолчаниюFalse.
• max_accept_ratio— максимально допустимое отношение сторонmax(w / h, h / w). Боксы, которые его превышают, отбрасываются. ЗначениеNoneотключает эту проверку.

На практике чаще всего важны не все параметры сразу, а четыре вещи:coord_format,label_fields,min_visibilityи поведение на кривой разметке (clip_bboxes_on_inputплюсfilter_invalid_bboxes).

Что делать с неидеальной разметкой

В реальных датасетах боксы нередко выходят за границы изображения. Причин много: ошибки разметки, старые кропы, инструменты, которые позволяют рисовать bbox за пределами кадра.

В таком случае есть смысл включить:

clip_bboxes_on_input=Trueжёстко ограничит координаты границами изображения до аугментации.filter_invalid_bboxes=Trueпосле этого уберёт вырожденные случаи вроде боксов нулевой ширины или высоты.

Когда нужны min_area и min_visibility

После кропа часть боксов превращается в тонкие обрезки по краям кадра. Формально они ещё существуют, но обучающего сигнала часто уже не несут.

min_areaубирает боксы, которые стали слишком маленькими в абсолютном смысле.min_visibilityубирает боксы, у которых после кропа осталось слишком мало от исходной площади. Выбор между ними зависит от задачи:

• если важен физический размер бокса после трансформации — смотрите наmin_area;
• если важна доля объекта, которая реально осталась в кадре, — смотрите наmin_visibility.

Во многих детекционных пайплайнах именноmin_visibilityоказывается самым полезным фильтром: он не даёт обучать модель на почти полностью отрезанных объектах.

Кропы в детекции: обычный RandomCrop часто плохая идея

RandomCropлегко выдаёт кропы, на которых не остаётся ни одного ограничивающего бокса. Для классификации это не проблема. Для детекции — это впустую потраченный обучающий пример.

Поэтому в Albumentations есть bbox-aware варианты кропа:

• AtLeastOneBboxRandomCropгарантирует, что после кропа в кадре останетсяхотя бы одинбокс. Остальные могут потеряться. Это полезно, когда объектов много и вы хотите более разнообразные кропы.
• BBoxSafeRandomCropгарантирует, что сохранятсявсебоксы. Область кропа подбирается так, чтобы ничего не потерять. Это подходит для редких объектов или сценариев, где нельзя терять ни одной аннотации.
• RandomSizedBBoxSafeCropберёт случайную область изображения, сохраняетвсебоксы, а потом делает ресайз к целевому размеру. На практике это один из самых полезных вариантов для обучения детекторов: он даёт вариацию масштаба и кадрирования, не ломая разметку.

Если коротко: для детекции не стоит бездумно вставлять обычныйRandomCropтолько потому, что он хорошо работает в классификации.

Где пайплайн с bbox ломается чаще всего

Неверный coord_format

Это ошибка номер один. Если ваши аннотации лежат в формате YOLO, а вы передалиcoord_format='coco', код отработает без жалоб — но каждый ограничивающий бокс уедет в неправильную область изображения.

Именно поэтому визуальная проверка аугментированных примеров перед обучением обязательна. Смотрите не только на картинку, но и на наложенные боксы.

Все боксы отфильтровались

Агрессивные кропы в комбинации с жёсткимиmin_areaилиmin_visibilityлегко приводят к ситуации, когда после аугментацииbboxesстановится пустым массивом.

Ваш класс датасета или тренировочный цикл должны уметь это переживать:

• либо пропускать такие примеры;
• либо использовать bbox-safe кропы, чтобы не получать пустые таргеты слишком часто.

Перепутали нормализованные и абсолютные координаты

Форматyoloожидает значения в диапазоне[0, 1]. Если вы передали туда пиксельные координаты, пайплайн обрежет их к[0, 1], и в результате получится крошечный бокс в углу.

Обратная ошибка тоже типична: если подать нормализованные координаты какpascal_voc, боксы окажутся размером в доли пикселя и почти сразу отфильтруются.

Добавили трансформацию без поддержки bbox

Не каждая трансформация умеет обновлять координаты боксов. Если в пайплайн сA.BboxParamsдобавить несовместимую трансформацию, Albumentations выбросит исключение уже при инициализации. Это хорошее поведение: ошибка всплывает сразу, а не в середине обучения.

Но всё равно стоит заранее смотреть втаблицу поддерживаемых таргетов, особенно если вы собираете длинный кастомный пайплайн.

Визуализируете данные после A.Normalize

A.Normalizeпереводит пиксели вfloat, вычитает среднее и делит на стандартное отклонение. Если попытаться отрисовать изображение после этого шага, оно будет выглядеть как шум.

Поэтому для визуальной отладки детекционного пайплайна смотрите изображениядоA.NormalizeидоA.ToTensorV2.

Заключение

Аугментация в детекции — это не просто «сделать картинку разнообразнее». Здесь любая пространственная трансформация автоматически становится задачей синхронизации таргетов. Если формат координат выбран неверно, если кропы режут объекты слишком агрессивно, если фильтрация настроена без пониманияmin_visibility, модель начинает учиться на сломанной разметке.

Практически это означает очень простую вещь: сначала добейтесь корректной геометрии и корректной фильтрации bbox, и только потом наращивайте агрессивность аугментаций.

Практический чек-лист:

1. Проверьте, чтоcoord_formatсовпадает с реальным форматом вашей разметки.
2. Вынесите все связанные с bbox метки и идентификаторы вlabel_fields, если они не упакованы прямо в массив.
3. Для кропов в детекции предпочитайте bbox-aware варианты вместо обычногоRandomCrop.
4. Подберитеmin_visibilityиmin_areaпод свою задачу, а не оставляйте значения по умолчанию наугад.
5. Перед полноценным обучением обязательно визуализируйте несколько десятков аугментированных примеров с наложенными боксами.

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