Metadata-Version: 2.4
Name: forensicface
Version: 0.5.1
Summary: A package for forensic face examination
Keywords: face,recognition,forensics,python
Author: Rafael O. Ribeiro
Author-email: Rafael O. Ribeiro <rafaeloliveiraribeiro@gmail.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: onnx
Requires-Dist: opencv-python-headless
Requires-Dist: onnxruntime-gpu[cuda,cudnn]>=1.25.0
Requires-Dist: scikit-image
Requires-Dist: imutils
Requires-Dist: tqdm
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/rafribeiro/forensicface
Project-URL: Documentation, https://rafribeiro.github.io/forensicface
Provides-Extra: dev
Description-Content-Type: text/markdown

# forensicface


## Install

``` sh
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*/`

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.  

## Como utilizar

Importação da classe ForensicFace:

``` python
from forensicface.app import ForensicFace
```

Instanciamento do ForensicFace:

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

``` console
[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`).

``` python
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'])

``` python
plt.imshow(results["aligned_face"])
```

![](index_files/figure-commonmark/cell-5-output-1.png)

Comparar duas imagens faciais e obter o escore de similaridade.

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

    0.8556093

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

``` python
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](https://github.com/fdbtrs/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.

``` python
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](https://github.com/deepinsight/insightface)

- Reconhecimento: [adaface](https://github.com/mk-minchul/AdaFace)

- Estimativa de qualidade: [CR-FIQA](https://github.com/fdbtrs/CR-FIQA)

