Если рамка детектора выглядит правильно, а готовая миниатюра режет лоб, проблема обычно возникает между detection и crop. Частые причины: EXIF-поворот применили после распознавания, координаты рассчитаны на уменьшенную или letterbox-картинку, либо рамку лица без полей сразу растянули под нужный формат. Сначала сохраните диагностическое изображение с bbox на том же массиве пикселей, который режет crop.

Исправленный конвейер должен быть однозначным: нормализовать ориентацию, определить размер, подготовить input модели, запомнить scale и padding, выполнить detection, вернуть координаты в нормализованный оригинал, выбрать лицо и только потом вычислить кадр. Каждый этап пишет размеры и координаты, но не сохраняет исходное фото дольше установленного срока.

Ошибка локализуется по первому неверному изображению

АртефактЧто на нём проверитьЕсли уже неверно
normalized.jpgориентация и width×heightEXIF обработан не до detection
model_input.jpgresize или поля letterboxневерный scale/padding
detections.jpgbbox и 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 выбора

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

Контрольный набор покрывает геометрию и реальный ввод

  1. JPEG с EXIF Orientation 6 и 8; рамка после нормализации остаётся на лице.
  2. Портрет 9:16, горизонтальная фотография и квадрат с одинаковым output profile.
  3. Лицо у каждого края кадра — crop не выходит за границы и не добавляет чёрную полосу.
  4. Два лица одинакового размера — система следует явному правилу, а не случайному порядку детектора.
  5. Маленькое лицо на большом фоне — quality gate не выдаёт ложную «хорошую» миниатюру.
  6. Повторная обработка одного файла даёт тот же bbox, policy version и итоговый hash.

Для диагностики нужны исходные dimensions и Orientation, версия модели, input size, score/NMS thresholds, transform, все bbox до и после mapping и выбранный crop profile. Сам файл передавайте только по разрешённому каналу и удаляйте по политике хранения. Исправление завершено, когда контрольные рамки совпадают на каждом этапе, а спорные групповые фото переходят в ручной выбор вместо тихой порчи.

Проверенные источники