PersonAnalysisPython인물 매칭신체 재식별

PersonAnalysis 시작하기: 얼굴 인식과 신체 ReID

InsightFace 2.1을 설치하고 Cheetah 모델과 참조 사진을 준비한 뒤, Python API로 이미지와 로컬 동영상 속 인물을 비교합니다.

2026-10-04•읽는 시간 8분

이 가이드에서 구축할 내용

PersonAnalysis는 사람 감지, 얼굴 인식, 신체 재식별(ReID)을 결합합니다. 현재 이미지의 인물을 사용자가 이름이나 ID를 지정해 등록한 참조와 비교합니다.

이 가이드는 CPU를 사용하며 특징 추출, 매칭, 선택적 신체 참조 업데이트를 구분합니다. 동영상에서는 동일한 인스턴스를 유지해 프레임 사이에 참조 정보가 남도록 합니다.

시작하기 전에

Python 3.10 이상. 가상 환경 사용을 권장합니다.
선명한 얼굴 하나가 있는 reference.jpg, scene.jpg, 처리 권한이 있는 짧은 고정 프레임률 동영상 clip.mp4.
첫 모델 다운로드를 위한 인터넷 연결 또는 로컬에 설치된 완전한 Cheetah 모델 패키지.

1. InsightFace 2.1 설치

사용할 Python 환경에서 다음 명령을 실행합니다. 기본 패키지에는 NumPy, OpenCV, CPU용 ONNX Runtime이 포함됩니다. PersonAnalysis에는 GUI나 PrivateFrame 추가 기능이 필요하지 않습니다.

NVIDIA CUDA를 사용하려면 먼저 InsightFace를 설치한 다음 onnxruntime을 onnxruntime-gpu로 교체하고 CUDAExecutionProvider를 명시적으로 선택합니다. 실행 환경 가이드를 참고하세요. PersonAnalysis는 CPU와 CUDA를 지원하며 Cheetah는 CoreML을 사용하지 않습니다.

Python API 설치 및 확인

python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"

2. Cheetah 선택 및 모델 준비

cheetah_s부터 시작하세요. 신체 감지 입력은 320×320이며 Buffalo S와 같은 얼굴 감지 및 인식 모델을 포함합니다. cheetah_l은 640×640 신체 감지기와 Buffalo L의 얼굴 모델을 사용합니다. 신체 ReID 모델은 같고, 기본 얼굴 감지 입력도 둘 다 640×640입니다.

공식 Cheetah 패키지가 없으면 처음 준비할 때 다운로드됩니다. 오프라인 사용 시 모델 배포 페이지에서 전체 압축 파일을 받아 ~/.insightface/models/cheetah_s/ 또는 cheetah_l/에 풉니다. manifest.json, MODEL.LICENSE, 네 개의 ONNX 파일은 추가 하위 폴더 없이 같은 위치에 있어야 합니다.

이 가이드는 name="cheetah_s"를 명시합니다. Python 생성자의 기본값은 cheetah_l입니다.
기존 패키지가 잘못된 경우 자동 교체하지 않고 오류를 알립니다. 완전한 압축 파일로 복구하세요.

3. 참조 등록, 특징 추출, 매칭

이미지 예제를 person_image.py로 저장해 reference.jpg 및 scene.jpg와 같은 폴더에 두고 python person_image.py를 실행합니다. 참조에는 사용 가능한 얼굴이 정확히 하나 있어야 합니다. accepted와 rejected를 확인하세요. person_001은 사용자가 지정하는 ID입니다.

get()은 디코딩된 OpenCV BGR uint8 이미지를 받아 현재 관측 결과를 반환합니다. match()는 참조와 비교해 허용된 얼굴 매칭을 우선하고, 그렇지 않으면 신체 참조를 시도합니다. 두 호출 모두 참조 라이브러리를 변경하지 않습니다.

예제에서는 auto_update가 꺼져 있습니다. 켜면 신뢰할 수 있는 얼굴 매칭과 명확한 얼굴·신체 연결이 있는 경우에만 update()가 신체 참조를 추가합니다. 신체만 매칭된 경우 참조를 늘리거나 새 ID를 만들지 않습니다. 프레임 전체를 매칭한 뒤 한 번에 업데이트하세요.

참조 등록 후 이미지 분석

import cv2
from insightface.app import PersonAnalysis

image = cv2.imread("scene.jpg")
if image is None:
    raise FileNotFoundError("scene.jpg")

with PersonAnalysis(name="cheetah_s") as app:
    registration = app.register("person_001", "reference.jpg")
    if registration.accepted == 0:
        raise ValueError(registration.rejected)

    observations = app.get(image)
    matches = app.match(observations)
    for result in matches:
        print(result.person_id, result.matched_by, result.similarity)

    auto_update = False
    if auto_update:
        changes = app.update(matches)
        print(changes.added, changes.replaced, changes.skipped)

4. 동영상에서 동일한 인스턴스 재사용

다음 예제를 person_video.py로 저장해 reference.jpg 및 clip.mp4와 함께 두고 python person_video.py를 실행합니다. 선택적 신체 참조 업데이트가 켜져 있으며 auto_update를 False로 바꾸면 꺼집니다.

고정 30 FPS 동영상에서 analysis_fps=2는 15프레임마다 분석합니다. 모든 프레임을 디코딩하지만 선택한 프레임만 모델에 전달합니다. 동영상 시간 기준의 상한이며 처리 속도를 보장하거나 재생을 기다리지 않습니다. 가변 프레임률 파일에는 실제 타임스탬프를 사용하세요.

이 예제는 순차적으로 읽습니다. 웹캠과 RTSP에는 데스크톱 기능을 사용해 최신 대기 프레임을 유지하고 실제 경과 시간에 따라 분석 빈도를 제한할 수 있습니다.

동영상 시간 기준 초당 최대 두 번 분석

import math
import cv2
from insightface.app import PersonAnalysis

analysis_fps = 2
auto_update = True
capture = cv2.VideoCapture("clip.mp4")
try:
    if not capture.isOpened():
        raise OSError("clip.mp4")
    source_fps = capture.get(cv2.CAP_PROP_FPS)
    if not math.isfinite(source_fps) or source_fps <= 0:
        raise ValueError("CAP_PROP_FPS")
    frame_step = max(1, math.ceil(source_fps / analysis_fps))

    with PersonAnalysis(name="cheetah_s") as app:
        registration = app.register("person_001", "reference.jpg")
        if registration.accepted == 0:
            raise ValueError(registration.rejected)
        frame_index = -1
        while True:
            ok, frame = capture.read()
            if not ok:
                if frame_index < 0:
                    raise OSError("clip.mp4")
                break
            frame_index += 1
            if frame_index % frame_step:
                continue
            matches = app.match(app.get(frame))
            if auto_update:
                app.update(matches)
            for result in matches:
                print(frame_index / source_fps, result.to_dict())
finally:
    capture.release()

5. 결과 해석 및 매칭 조정

person_id는 등록 ID 또는 None입니다. matched_by는 face, body, None 중 하나이며 similarity는 채택된 코사인 유사도이지 정답 확률이 아닙니다. result.observation의 body_bbox, reid_feature, face는 값이 있는지 확인한 뒤 사용하세요.

얼굴 사진만으로는 옷차림을 알 수 없습니다. 신원을 아는 신체 크롭을 body_images로 등록하거나 조건에 맞는 얼굴 매칭이 신체 참조를 추가하도록 합니다. 신체 매칭은 옷차림, 자세, 가림, 화질의 영향을 받습니다.

기본값은 face_similarity_threshold=0.45, reid_similarity_threshold=0.85, max_body_samples=4입니다. 새 인스턴스를 만들 때 PersonConfig로 변경하고 대표 영상으로 평가하세요. 설정 참조에 설명되어 있으며 기본값이 보정된 정확도를 보장하지는 않습니다.

참조는 현재 인스턴스의 메모리에만 존재하고 닫으면 해제됩니다. 자동 참조 내보내기, 데이터베이스, 재시작 복구는 없습니다.
결과는 현재 프레임을 설명합니다. SDK는 연속 궤적, 익명 ID, 등장 시간, 이벤트 이력을 유지하지 않습니다.
to_dict()는 앱에서 현재 출력을 저장할 때 유용하지만 참조 라이브러리 백업이 아니며 update()에 전달할 수 없습니다.

6. 데스크톱 기능 사용

다국어 Evaluation Studio는 로컬 동영상, 웹캠, RTSP 분석과 참조 사진, 분석 빈도 설정을 제공합니다. GUI 추가 기능을 설치하고 Cheetah S 또는 L을 선택한 다음 GUI 가이드를 따라 진행하세요.

데스크톱 앱 설치 및 실행

python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui

7. 사용 사례 평가 및 모델 라이선스 확인

선명한 얼굴, 뒷모습, 비슷한 옷차림, 가림, 미등록 인물을 포함해 확인하세요. 잘못된 매칭과 놓친 매칭을 검토한 뒤 임계값을 선택하고, 사용할 하드웨어와 입력에서 속도를 측정하세요.

SDK 코드는 MIT 라이선스입니다. 공개 Cheetah 사전 학습 패키지는 비상업적 이용 허가를 제공하며, 코드의 상업적 이용 권한이 모델의 상업적 이용까지 허용하지는 않습니다.

전체 API 가이드와 모델 이용 조건을 참고하세요. 배포 및 모델 허가는 InsightFace에 문의하세요. 기능과 모델 선택은 인물 분석 개요에서 확인할 수 있습니다.

애플리케이션에 맞게 Person Analysis를 평가하세요

입력 소스, 배포 환경, 상업적 요구 사항을 알려 주시면 모델 라이선스와 통합 방법을 논의할 수 있습니다.

문의하기