Если рамка детектора выглядит правильно, а готовая миниатюра режет лоб, проблема обычно возникает между detection и crop. Частые причины: EXIF-поворот применили после распознавания, координаты рассчитаны на уменьшенную или letterbox-картинку, либо рамку лица без полей сразу растянули под нужный формат. Сначала сохраните диагностическое изображение с bbox на том же массиве пикселей, который режет crop.
Исправленный конвейер должен быть однозначным: нормализовать ориентацию, определить размер, подготовить input модели, запомнить scale и padding, выполнить detection, вернуть координаты в нормализованный оригинал, выбрать лицо и только потом вычислить кадр. Каждый этап пишет размеры и координаты, но не сохраняет исходное фото дольше установленного срока.
Ошибка локализуется по первому неверному изображению
| Артефакт | Что на нём проверить | Если уже неверно |
|---|---|---|
| normalized.jpg | ориентация и width×height | EXIF обработан не до detection |
| model_input.jpg | resize или поля letterbox | неверный scale/padding |
| detections.jpg | bbox и landmarks на input | порог или модель |
| mapped_bbox.jpg | рамка на оригинале | ошибка обратного преобразования |
| final_crop.jpg | поля и aspect ratio | ошибка crop policy |
Не начинайте с изменения confidence threshold. Если mapped bbox уехал вдвое, порог не исправит математику. Сравните четыре числа `x, y, w, h`, размеры входа и исходника, коэффициент scale и padding по обеим осям. Для одной контрольной фотографии эти значения легко пересчитать вручную.
EXIF-поворот применяется раньше любых координат
from PIL import Image, ImageOps
with Image.open(source_path) as opened:
image = ImageOps.exif_transpose(opened).convert('RGB')
width, height = image.size
# Все следующие координаты относятся именно к image.
image.save(debug_dir / 'normalized.jpg', quality=90)`ImageOps.exif_transpose` физически применяет Orientation и удаляет соответствующие данные из результата. После этого width/height могут поменяться местами. Если детектор видел неповёрнутый JPEG, а Pillow повернул его только перед `crop`, оси и начало координат уже относятся к разным изображениям.
Resize и letterbox требуют обратной функции
OpenCV FaceDetectorYN принимает размер входа и возвращает bbox с верхним левым углом, шириной, высотой и пятью landmarks. При прямом resize коэффициенты по X и Y могут различаться; при letterbox масштаб один, но появляются поля. Храните transform как данные запроса, а не восстанавливайте его по округлённому output.
# Letterbox: input = original * scale + padding
def map_box_to_original(box, scale, pad_x, pad_y, width, height):
x, y, w, h = box
left = (x - pad_x) / scale
top = (y - pad_y) / scale
right = (x + w - pad_x) / scale
bottom = (y + h - pad_y) / scale
left = max(0, min(width, left))
top = max(0, min(height, top))
right = max(left, min(width, right))
bottom = max(top, min(height, bottom))
return left, top, right - left, bottom - topОкругляйте только финальные границы crop. Раннее приведение к int на нескольких шагах накапливает смещение, заметное на маленьких лицах. Если кадр уже был повернут или отражён матрицей, для bbox и landmarks нужна обратная матрица этого преобразования, а не только деление на scale.
Главное лицо выбирается продуктовым правилом
Самая большая рамка подходит для одиночного портрета, но на фотографии с ведущим и гостем может выбрать ближайшего к камере. Центр кадра тоже не всегда главный. Зафиксируйте политику: например, максимальный score среди лиц, которые занимают допустимую долю кадра и находятся в центральной зоне; при близких кандидатах не обрезать автоматически, а показать выбор.
- Ноль лиц: сохранить исходное соотношение сторон через contain/pad или запросить ручную точку фокуса.
- Одно уверенное лицо: построить кадр с запасом над головой и по плечам.
- Несколько лиц в групповом режиме: взять объединяющий bbox, если он помещается в целевой aspect ratio.
- Несколько конкурирующих лиц в режиме аватара: не угадывать, вернуть кандидатов интерфейсу.
- Слишком маленькое лицо: не увеличивать его безусловно — предупредить о качестве.
Crop расширяет лицо и сохраняет целевой aspect ratio
def crop_around_face(image, box, output_size=(800, 1000)):
x, y, w, h = box
W, H = image.size
target = output_size[0] / output_size[1]
crop_w, crop_h = w * 2.0, h * 2.4
if crop_w / crop_h < target:
crop_w = crop_h * target
else:
crop_h = crop_w / target
crop_w, crop_h = min(crop_w, W), min(crop_h, H)
cx, cy = x + w / 2, y + h / 2
left = min(max(cx - crop_w / 2, 0), W - crop_w)
top = min(max(cy - crop_h * 0.45, 0), H - crop_h)
region = image.crop((round(left), round(top),
round(left + crop_w), round(top + crop_h)))
return region.resize(output_size, Image.Resampling.LANCZOS)Коэффициенты 2.0 и 2.4 — не стандарт OpenCV, а стартовая продуктовая настройка: подтвердите её на своём наборе фотографий. Вертикальный центр в примере немного поднят, чтобы оставить место плечам, но границы всегда зажаты внутри изображения. Для баннера, документа и аватара нужны разные профили, а не один набор чисел.
Quality gate останавливает плохую автоматику
| Проверка | Что измерять | Действие при провале |
|---|---|---|
| геометрия | bbox внутри width×height | ошибка transform, не публиковать |
| уверенность | score детектора | ручной выбор или fallback |
| детализация | ширина лица в пикселях | не увеличивать до мыльного аватара |
| поза | landmarks и наклон | расширить поля или выбрать другой кадр |
| группа | число и расположение лиц | объединяющий crop или UI выбора |
Порог подбирается на размеченной выборке, а не на пяти удачных портретах. Считайте отдельно долю обрезанных лбов, потерянных групп, неверно выбранных лиц и ручных исправлений. Автоматическое решение может быть быстрым, но низкая уверенность должна оставаться наблюдаемым состоянием, а не скрытой ошибкой.
Контрольный набор покрывает геометрию и реальный ввод
- JPEG с EXIF Orientation 6 и 8; рамка после нормализации остаётся на лице.
- Портрет 9:16, горизонтальная фотография и квадрат с одинаковым output profile.
- Лицо у каждого края кадра — crop не выходит за границы и не добавляет чёрную полосу.
- Два лица одинакового размера — система следует явному правилу, а не случайному порядку детектора.
- Маленькое лицо на большом фоне — quality gate не выдаёт ложную «хорошую» миниатюру.
- Повторная обработка одного файла даёт тот же bbox, policy version и итоговый hash.
Для диагностики нужны исходные dimensions и Orientation, версия модели, input size, score/NMS thresholds, transform, все bbox до и после mapping и выбранный crop profile. Сам файл передавайте только по разрешённому каналу и удаляйте по политике хранения. Исправление завершено, когда контрольные рамки совпадают на каждом этапе, а спорные групповые фото переходят в ручной выбор вместо тихой порчи.