Introdução ao PersonAnalysis: reconhecimento facial e ReID corporal
Instale o InsightFace 2.1, escolha o Cheetah, registre fotos de referência e compare pessoas em imagens ou vídeos locais com a API Python.
O que você vai construir
O PersonAnalysis combina detecção de pessoas, reconhecimento facial e reidentificação corporal (ReID). Compara pessoas na imagem atual com referências registradas com nomes ou identificadores escolhidos por você.
Este guia usa a CPU e separa extração de características, comparação e atualização opcional das referências corporais. Mantenha a mesma instância durante o vídeo para preservar as referências entre quadros.
Antes de começar
- Python 3.10 ou mais recente, de preferência em um ambiente virtual.
- reference.jpg com um único rosto nítido, scene.jpg e um vídeo curto clip.mp4 com taxa de quadros constante que você tenha autorização para processar.
- Acesso à Internet para baixar os modelos pela primeira vez ou um pacote Cheetah completo instalado localmente.
1. Instalar o InsightFace 2.1
Execute os comandos no ambiente Python que pretende usar. O pacote básico inclui NumPy, OpenCV e ONNX Runtime para CPU; o PersonAnalysis não exige as extensões GUI ou PrivateFrame.
Para NVIDIA CUDA, instale primeiro o InsightFace, substitua onnxruntime por onnxruntime-gpu e selecione CUDAExecutionProvider explicitamente. Consulte o guia do ambiente de execução. O PersonAnalysis aceita CPU e CUDA; o Cheetah não usa CoreML.
python -m pip install --upgrade "insightface==2.1"
python -c "from insightface.app import PersonAnalysis; print(PersonAnalysis.__name__)"2. Escolher o Cheetah e preparar os modelos
Comece pelo cheetah_s: o detector corporal usa entradas de 320×320 e os modelos faciais são os mesmos do Buffalo S. O cheetah_l usa um detector corporal de 640×640 e os modelos faciais do Buffalo L. Ambos incluem o mesmo modelo ReID e usam 640×640 para detecção facial por padrão.
Um pacote oficial Cheetah ausente é baixado na primeira preparação. Para uso offline, obtenha o arquivo completo na página de modelos e extraia em ~/.insightface/models/cheetah_s/ ou cheetah_l/. Mantenha manifest.json, MODEL.LICENSE e os quatro arquivos ONNX juntos, sem uma pasta adicional aninhada.
- O guia define name="cheetah_s" explicitamente; o construtor Python usa cheetah_l por padrão.
- Um pacote existente inválido gera um erro e não é substituído automaticamente. Repare-o com o arquivo completo.
3. Registrar, extrair características e comparar
Salve o exemplo de imagem como person_image.py ao lado de reference.jpg e scene.jpg e execute python person_image.py. A referência deve conter exatamente um rosto utilizável. Confira accepted e rejected antes de continuar. person_001 é um identificador atribuído por você.
get() recebe uma imagem OpenCV BGR uint8 decodificada e retorna as observações atuais. match() compara com as referências: prioriza uma correspondência facial aceita e, se não houver, tenta referências corporais. Nenhuma dessas chamadas altera a biblioteca.
O exemplo desativa auto_update. Quando ativado, update() pode adicionar uma referência corporal após uma correspondência facial confiável e uma associação clara entre rosto e corpo. Uma correspondência apenas corporal não amplia referências nem cria identidades. Compare todo o quadro antes de atualizar.
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. Reutilizar a instância em um vídeo
Salve o próximo exemplo como person_video.py ao lado de reference.jpg e clip.mp4 e execute python person_video.py. As atualizações corporais opcionais estão ativadas; use auto_update=False para desativá-las.
Em um vídeo constante de 30 FPS, analysis_fps=2 analisa um quadro a cada quinze. Todos são decodificados, mas apenas os selecionados entram nos modelos. O limite se refere ao tempo do vídeo, sem garantir velocidade de processamento ou aguardar a reprodução. Para taxa variável, use os horários reais dos quadros.
Este exemplo faz leitura sequencial. Para webcams ou RTSP, o fluxo de desktop conserva o quadro pendente mais recente e limita a análise pelo tempo decorrido.
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. Ler resultados e ajustar a comparação
person_id é o identificador registrado ou None. matched_by pode ser face, body ou None; similarity é a similaridade de cosseno aceita, não uma probabilidade de acerto. Leia body_bbox, reid_feature e face em result.observation, verificando valores ausentes.
Uma foto de rosto não descreve a roupa. Registre um recorte corporal conhecido com body_images ou permita que correspondências faciais válidas adicionem referências corporais. Roupas, pose, oclusão e qualidade da imagem afetam a comparação corporal.
Os padrões incluem face_similarity_threshold=0.45, reid_similarity_threshold=0.85 e max_body_samples=4. Altere-os por PersonConfig ao criar uma nova instância e avalie vídeos representativos. A referência de configuração explica os parâmetros; os valores iniciais não garantem precisão calibrada.
- As referências ficam apenas na memória desta instância e são liberadas ao fechá-la. Não há exportação automática de referências, banco de dados ou recuperação após reiniciar.
- Os resultados descrevem o quadro atual. O SDK não mantém trajetórias, identidades anônimas, duração de presença ou histórico de eventos.
- to_dict() ajuda seu aplicativo a salvar as saídas atuais; não salva a biblioteca de referências e não pode ser usado como entrada de update().
6. Experimentar o aplicativo de desktop
O Evaluation Studio multilíngue oferece análise de vídeos locais, webcams e RTSP, com fotos de referência e controles de frequência. Instale a extensão GUI, escolha Cheetah S ou L e siga o guia da interface.
python -m pip install --upgrade "insightface[gui]==2.1"
insightface-gui7. Avaliar o uso e verificar a licença
Teste rostos nítidos, pessoas de costas, roupas semelhantes, oclusões e pessoas não registradas. Revise correspondências incorretas e ausentes antes de escolher limiares. Meça a velocidade no equipamento e nas entradas previstos.
O código do SDK usa a licença MIT. Os pacotes públicos Cheetah pré-treinados têm autorização não comercial; o uso comercial do código não concede esse direito sobre os modelos.
Leia o guia completo da API e os termos dos modelos. Para implantação e autorização, entre em contato com a InsightFace. Veja funções e modelos na visão geral do Person Analysis.
Avalie o Person Analysis para sua aplicação
Compartilhe suas fontes de entrada, ambiente de implantação e requisitos comerciais para discutir licenciamento de modelos e integração.
Entre em contato