forensicface 0.6.0

A package for forensic face examination

forensicface

Install

pip install forensicface

Os arquivos onnx dos modelos de detecção (det_10g.onnx), pose (1k3d68.onnx) e sexo/idade (genderage.onnx) devem estar na pasta ~/.forensicface/models/<model_name>/

O arquivo onnx do modelo de reconhecimento (ex. adaface_ir101web12m.onnx) deve estar na pasta ~/.forensicface/models/<model_name>/*face*/

Para o modelo sepaelv6, o arquivo de reconhecimento kprpe_adaface_webface12m.onnx tambem deve estar nessa pasta. Este modelo recebe, alem da face alinhada 112x112, os cinco pontos-chave transformados para o sistema de coordenadas da face alinhada e normalizados para [0, 1].

O arquivo onnx do modelo de qualidade CR_FIQA (cr_fiqa_l.onnx) deve estar na pasta ~/.forensicface/models/<model_name>/cr_fiqa/

O modelo padrão é denominado sepaelv2. A partir da versão 0.1.5 é possível utilizar outros modelos.

Notas de migração (0.5.1)

• A dependência do pacote insightface foi removida.
• O diretório padrão dos modelos mudou para ~/.forensicface/models.
• É possível especificar outro diretório raiz para os modelos
  na inicialização do forensicface (parâmetro models_root)
• CUDA e CuDNN são instalados automaticamente no ambiente virtual
  onde o forensicface for instalado.

Documentação

• Tutoriais e exemplos: notebooks em nbs/, publicados com Quarto
• Referência de API: gerada via docstrings com quartodoc

Build local da documentação:

uv sync --extra docs
./scripts/build_docs.sh

No build_docs.sh, os notebooks são executados localmente antes de gerar o site. No CI (GitHub Actions), é usado ./scripts/build_docs_ci.sh, que renderiza sem executar notebooks novamente.

Saída do site: _docs/

Como utilizar

Importação da classe ForensicFace:

from forensicface.app import ForensicFace

Instanciamento do ForensicFace:

ff = ForensicFace(det_size=320, use_gpu=True, extended=True)

[ForensicFace] Initialized with configuration:
                loaded_models=['sepaelv2']
                modules=['detection', 'headpose', 'genderage', 'cr_fiqa']
                det_size=(256, 256)
                session_providers=all models use CUDAExecutionProvider

Processamento básico de imagens

Obter pontos de referência, distância interpupilar, representação vetorial, a face alinhada com dimensão fixa (112x112), estimativas de sexo, idade, pose (pitch, yaw, roll) e qualidade. Opcionalmente, é possível anotar a face alinhada com os pontos de referência utilizados no alinhamento (parâmetro draw_kypoints).

results = ff.process_image("obama2.png", draw_keypoints=True, single_face=True)
results.keys()

dict_keys(['keypoints', 'ipd', 'embedding', 'norm', 'bbox', 'det_score', 'aligned_face', 'gender', 'age', 'pitch', 'yaw', 'roll', 'fiqa_score'])

plt.imshow(results["aligned_face"])

Comparar duas imagens faciais e obter o escore de similaridade.

ff.compare("obama.png", "obama2.png")

0.8556093

Agregar embeddings de duas imagens faciais em uma única representação, com ponderação por qualidade

agg = ff.aggregate_from_images(["obama.png", "obama2.png"], quality_weight=True)
agg.shape

(512,)

Estimativa de qualidade CR-FIQA

Estimativa de qualidade pelo método CR-FIQA

Para desabilitar, instancie o forensicface com a opção extended = False:

ff = ForensicFace(extended=False)

Obs.: a opção extended = False também desabilita as estimativas de sexo, idade e pose.

good = ff.process_image("001_frontal.jpg")
bad = ff.process_image("001_cam1_1.jpg")
good["fiqa_score"], bad["fiqa_score"]

(2.3786173, 1.4386057)

Crédito dos modelos utilizados

• Detecção, sexo (M/F), idade e pose (pitch, yaw, roll): insightface

• Reconhecimento: adaface

• Estimativa de qualidade: CR-FIQA