SIGMA - Sistema Integrado de Gestão e Monitoramento de Acesso

Aplicação de apoio ao controle de acesso, desenvolvida em Python com OpenCV, DeepFace e FaceNet. O sistema captura uma imagem da webcam do computador ou da ESP32-CAM, detecta o rosto e compara suas características com o banco facial cadastrado.

O SIGMA auxilia a decisão do operador. A identificação, por si só, não libera a entrada: o operador precisa clicar em Liberar acesso.

O que é necessário

Para uma instalação padrão usando a webcam e SQLite, a pessoa precisa de:

• Windows 10 ou superior;
• Python 3.10 ou superior instalado e disponível no comando py ou python;
• uma webcam funcionando e liberada nas permissões do Windows;
• fotos faciais autorizadas na pasta banco/ ou cadastro feito pela tela;
• internet na primeira instalação, para baixar as bibliotecas e o modelo FaceNet;
• espaço livre para o ambiente virtual, as bibliotecas do TensorFlow e o modelo facial.

Não é necessário instalar ou configurar PostgreSQL para usar o modo padrão. Também não é necessário ter uma ESP32-CAM quando a configuração estiver em modo="webcam".

Dependências Python

O arquivo requirements.txt instala todas as dependências do sistema Python:

Pacote	Função
opencv-python	Captura da webcam, leitura de imagens e detecção facial
numpy	Operações numéricas e comparação dos embeddings
requests	Comunicação HTTP com a ESP32-CAM
deepface	Geração dos embeddings faciais
tf-keras	Execução do modelo FaceNet
easyocr	Leitura do texto das placas veiculares
psycopg[binary]	Conexão opcional com PostgreSQL

O SQLite já faz parte do Python e não exige instalação adicional.

Hardware opcional

Escolha uma fonte de imagem:

• Webcam local: índice 0 por padrão. É a opção mais simples para testar.
• ESP32-CAM: placa configurada, conectada à mesma rede do computador e com o firmware de src/esp32camSET.ino carregado.

Instalação do zero

1. Obter o projeto

Se o projeto estiver em um repositório Git:

git clone URL_DO_REPOSITORIO
cd amostra-tecnica-cultural

Se ele já estiver no computador, abra o PowerShell diretamente na pasta que contém README.md, requirements.txt e SIGMA.bat.

2. Criar o ambiente virtual

py -3 -m venv .venv

Caso o comando py não exista, use:

python -m venv .venv

3. Instalar as dependências

.venv\Scripts\python.exe -m pip install --upgrade pip
.venv\Scripts\python.exe -m pip install -r requirements.txt

4. Cadastrar uma pessoa

Coloque uma foto válida em banco/, por exemplo banco/simioni.jpg. O nome simioni será usado como identificação no painel.

5. Iniciar

Use o arquivo SIGMA.bat, por duplo clique. Alternativamente:

.venv\Scripts\python.exe src\main.py

O arquivo SIGMA.bat cria o ambiente se necessário, instala dependências ausentes e inicia o painel. Se o Windows mostrar uma janela do terminal, ela deve permanecer aberta enquanto o SIGMA estiver executando.

O arquivo requirements.txt é a lista oficial das dependências do projeto. O ambiente .venv é local e não é salvo no Git. Na primeira execução do DeepFace, o download e o carregamento do modelo podem demorar alguns minutos.

Banco facial

Coloque uma foto por pessoa na pasta banco/. O nome do arquivo, sem a extensão, será exibido no painel. Exemplos:

banco/
	.gitkeep
	joao-silva.jpg
	maria-souza.png

Use fotos nítidas, com uma única pessoa e o rosto voltado para a câmera. São aceitos os formatos de imagem reconhecidos pelo OpenCV, como .jpg, .jpeg e .png.

As imagens do banco são dados pessoais e não são salvas no Git. O .gitignore mantém a pasta banco/ por meio do arquivo banco/.gitkeep, mas ignora as imagens colocadas nela. Para compartilhar o projeto, envie as fotos por um canal seguro e local separado do repositório.

Persistência dos registros

Além das fotos na pasta banco/, o SIGMA mantém uma tabela rostos com o nome, o caminho original, os bytes da imagem e o embedding facial. O embedding evita que o sistema dependa somente do processamento em memória durante a execução.

Por padrão, a aplicação usa SQLite e cria banco/sigma.db automaticamente. Esse arquivo é local e também não é salvo no Git. A cada inicialização, as fotos existentes em banco/ são cadastradas ou atualizadas na base.

SQLite

É a opção recomendada para uma instalação única no computador da guarda. Não exige servidor adicional. O padrão já está definido em config.py:

BancoConfig(tipo="sqlite", arquivo_sqlite="banco/sigma.db")

PostgreSQL

É indicado quando vários computadores precisam consultar a mesma base. Instale e execute um servidor PostgreSQL, crie o banco sigma e altere a configuração:

BancoConfig(
	tipo="postgresql",
	url_postgresql="postgresql://usuario:senha@localhost:5432/sigma",
)

O driver psycopg[binary] já está listado em requirements.txt. A tabela é criada automaticamente na primeira conexão. Nunca publique a URL contendo a senha; prefira uma variável de ambiente ou um arquivo de configuração local fora do Git.

Para aplicar a alteração, edite CONFIG_PADRAO em src/facerec/config.py:

CONFIG_PADRAO = Config(
	banco=BancoConfig(tipo="postgresql", url_postgresql="..."),
)

Operação do painel

1. Clique em Identificar.
2. Posicione a pessoa diante da câmera exibida no painel.
3. Aguarde a identificação de uma pessoa cadastrada.
4. Confira o nome e a distância apresentados.
5. Clique em Liberar pessoa somente depois da conferência visual.

Use Desligar câmera para interromper a captura e voltar ao estado inicial. Depois disso, Identificar liga a câmera novamente.

Identificação de placas veiculares

O SIGMA também localiza e lê a placa do veículo (carro ou moto) que chega ao posto de controle. O fluxo segue a ordem natural do posto: o guarda aponta primeiro para a placa e, em seguida, para o rosto de quem está conduzindo.

• A detecção de placa roda de forma independente da detecção de rosto: a câmera pode ler a placa antes mesmo de qualquer rosto aparecer no enquadramento.
• Assim como a identidade facial, a placa só é aceita após validações consecutivas (SIGMA_PLACA_VALIDACOES_NECESSARIAS), para evitar leituras erradas do OCR, e precisa estar previamente cadastrada (veja "Cadastro de placas" abaixo). Uma placa lida corretamente mas não cadastrada aparece como "NAO CADASTRADA" e não avança no fluxo.
• Depois que a placa é confirmada, o painel aguarda a identificação do motorista. Assim que um rosto é confirmado (nessa ordem, ou também na ordem inversa, se o rosto já tiver sido identificado antes), o SIGMA vincula automaticamente a placa à pessoa e libera o botão Liberar veículo.
• A pessoa continua podendo passar sozinha, sem veículo nenhum — o fluxo de identificação facial não muda nesse caso, e nenhuma placa precisa ser lida.
• O veículo só pode ser liberado quando está vinculado a um motorista identificado. Uma placa lida sem que ninguém tenha sido reconhecido como condutor fica em "aguardando motorista" e o botão Liberar veículo permanece bloqueado.
• Quando a pessoa e o veículo estão vinculados, o painel oferece três ações independentes:
  • Liberar pessoa: libera somente a identidade confirmada;
  • Liberar veículo: libera somente a placa vinculada a um motorista;
  • Liberar ambos: libera pessoa e veículo em uma única ação.
• Se o motorista já vinculado sair do enquadramento antes de qualquer liberação, a identificação da pessoa e o vínculo com o veículo são desfeitos juntos (é preciso reconhecer o motorista novamente). Uma placa já lida mas ainda não vinculada a ninguém não é perdida por causa de um rosto qualquer que apareça e suma da câmera.

A leitura de texto usa EasyOCR sobre a região encontrada por um classificador Haar Cascade de placas (já incluso no OpenCV). Pode ser ajustado por:

• SIGMA_PLACA_ATIVA: true (padrão) ou false para desligar a leitura de placas sem alterar o reconhecimento facial;
• SIGMA_PLACA_INTERVALO_SEGUNDOS: tempo mínimo entre leituras de OCR;
• SIGMA_PLACA_VALIDACOES_NECESSARIAS: quantidade de leituras consecutivas iguais antes de aceitar a placa; o padrão é 2.

São aceitos os formatos de placa brasileiros antigo (ABC1234) e Mercosul (ABC1D23). Assim como o FaceNet, o modelo do EasyOCR é baixado e carregado na primeira leitura, o que pode levar alguns segundos.

Cadastro de placas

As placas autorizadas ficam numa tabela veiculos, no mesmo banco configurado em BancoConfig (SQLite ou PostgreSQL). Há duas formas de cadastrar:

1. Pelo painel, usando a leitura ao vivo

Com a câmera ligada (Identificar), aponte para a placa e clique em Cadastrar veículo. O campo já vem preenchido com a última leitura da câmera (corrija se o OCR errou algum caractere); o campo "Responsável" é opcional, só para referência. Clique em Cadastrar placa para salvar. A partir daí, essa placa passa a ser reconhecida nas próximas identificações.

2. Pelo terminal, sem precisar de câmera

Use o script cadastrar_placa.py quando já se sabe a placa de cor (por exemplo, cadastro em lote antes do evento):

.venv\Scripts\python.exe src\cadastrar_placa.py ABC1D23
.venv\Scripts\python.exe src\cadastrar_placa.py ABC1D23 "Nome do responsável"

O script usa a mesma configuração de banco (CONFIG_PADRAO.banco) do painel, então uma placa cadastrada pelo terminal já aparece como autorizada na próxima vez que o SIGMA for iniciado — ou até no mesmo processo, se cadastrada antes de abrir o painel.

Cadastrar a mesma placa de novo apenas atualiza o responsável; não cria duplicata (placa é a chave primária da tabela).

Para cadastrar uma pessoa durante a feira, ligue a câmera, aguarde a imagem aparecer e clique em Cadastrar rosto. Informe o nome e clique em Capturar e cadastrar. A foto do frame atual será salva em banco/, o embedding será registrado no banco configurado e a pessoa ficará disponível para reconhecimento imediatamente. Use uma foto nítida, com apenas um rosto. Uma prévia é exibida antes da confirmação; o cadastro só é aceito quando exatamente um rosto é detectado. Após o cadastro, o resultado anterior é limpo e a identificação automática continua com o novo registro disponível.

O botão Liberar acesso permanece bloqueado para rostos não reconhecidos ou quando ocorre uma falha. A câmera é aberta somente durante a identificação e a visualização fica dentro da janela principal.

Ao clicar em Identificar, a câmera é ligada uma única vez e permanece ativa. Depois que uma identidade é confirmada, o sistema aguarda o clique em Liberar acesso sem fechar a câmera. Após a liberação, a confirmação anterior é limpa e a busca pela próxima pessoa continua automaticamente.

Durante a captura, um quadro verde indica que o rosto teve correspondência no banco, enquanto um quadro vermelho indica que ele ainda não foi reconhecido. O quadro verde não substitui as três validações consecutivas nem a conferência do operador.

Uma identificação confirmada fica associada ao rosto em foco. Se nenhum rosto for detectado por 2 segundos, o sistema esquece o resultado, bloqueia a liberação anterior e reinicia as três validações para a próxima pessoa. O tempo pode ser ajustado por SIGMA_TEMPO_FOCO_SEGUNDOS.

Na primeira validação após abrir o sistema, o DeepFace pode carregar o modelo FaceNet e levar alguns segundos. Essa tarefa ocorre em segundo plano: a tela e a visualização da câmera continuam responsivas. O log informa o início, o resultado e a duração de cada validação.

Configuração da câmera

As configurações ficam em src/facerec/config.py.

Para usar a webcam local:

CameraConfig(modo="webcam", indice_webcam=0)

Para usar a ESP32-CAM, altere o modo e o IP:

CameraConfig(modo="esp32", ip_esp32="192.168.88.14")

O endereço usado pelo Python é http://IP_DA_ESP32/foto. A ESP32-CAM deve estar ligada à mesma rede do computador e com o firmware de src/esp32camSET.ino carregado.

Também é possível ajustar:

• limite_distancia: quanto menor, mais rigorosa é a identificação;
• intervalo_segundos: tempo mínimo entre inferências do modelo;
• validacoes_necessarias: quantidade de validações consecutivas da mesma pessoa antes de aceitar a identidade; o padrão é 3;
• pasta_banco: localização das fotos cadastradas;
• modelo: modelo utilizado pelo DeepFace.

Configuração por ambiente

As configurações locais ficam fora do código. Para a aplicação Python, copie .env.example para .env e altere os valores necessários:

Copy-Item .env.example .env

O .env é ignorado pelo Git. Ele pode definir o modo da câmera, o IP da ESP32-CAM, os limites de reconhecimento e a conexão do banco. Nunca coloque senhas reais em .env.example, no README ou em arquivos versionados.

Para o firmware, copie esp32/secrets.h.example para esp32/secrets.h e preencha o SSID e a senha da rede:

Copy-Item esp32/secrets.h.example esp32/secrets.h

O arquivo esp32/secrets.h também é ignorado pelo Git. O Arduino IDE precisa dele na pasta do sketch para compilar esp32/ReconhecimentoPython.ino. O .env do Python não pode ser lido diretamente pelo firmware durante a compilação.

Credenciais publicadas em versões antigas devem ser trocadas na rede e no PostgreSQL. Remover uma credencial do arquivo atual não a remove do histórico do Git.

Estrutura principal

SIGMA.bat              Inicializador para Windows
TESTES.bat             Validação local da sintaxe e dos testes
requirements.txt       Dependências Python
banco/                 Fotos locais do banco facial
src/main.py            Entrada da aplicação
src/cadastrar_placa.py Cadastro de placas pelo terminal, sem câmera
src/facerec/app.py     Painel e fluxo de identificação
src/facerec/camera.py  Webcam e ESP32-CAM
src/facerec/detector.py Detecção dos rostos
src/facerec/placas.py  Detecção, leitura e cadastro de placas veiculares
src/facerec/embeddings.py Geração dos embeddings
src/facerec/banco.py   Comparação com o banco facial
src/facerec/persistencia.py Persistência de rostos e placas (SQLite/PostgreSQL)
src/facerec/config.py  Configurações do sistema

Solução de problemas

A webcam não abre

Verifique as permissões de câmera do Windows, feche outros programas que estejam usando a webcam e tente outro indice_webcam em config.py.

A ESP32-CAM não responde

Confirme o IP, a conexão Wi-Fi, o endereço /foto e se o computador consegue acessar a ESP32-CAM pela rede.

O banco está vazio

O SIGMA pode iniciar com a pasta contendo apenas .gitkeep e sigma.db. Ligue a câmera e use Cadastrar rosto para registrar a primeira pessoa. O arquivo .gitkeep serve apenas para manter a pasta no repositório e não é uma foto válida.

O modelo demora na primeira execução

Isso é esperado: o DeepFace baixa e inicializa o modelo FaceNet. Aguarde a conclusão mantendo a conexão com a internet.

Desenvolvimento

Para atualizar as dependências, edite requirements.txt e execute:

.venv\Scripts\python.exe -m pip install -r requirements.txt

Para verificar a sintaxe do projeto:

.venv\Scripts\python.exe -m compileall -q src

Testes automatizados

Os testes usam valores fictícios e não precisam de webcam, ESP32-CAM, fotos reais, PostgreSQL ou download do FaceNet. Eles verificam a persistência SQLite, o cache de embeddings, o filtro de arquivos do banco e a decisão de reconhecimento.

Para executar localmente com um único comando, dê duplo clique em TESTES.bat. O script cria a .venv se necessário, restaura o pip quando ele não estiver instalado, instala requirements-dev.txt, verifica a sintaxe e executa a suíte.

Também é possível executar pelo PowerShell:

.venv\Scripts\python.exe -m pip install -r requirements-dev.txt
$env:PYTHONPATH = "src"
.venv\Scripts\python.exe -m pytest

O arquivo pytest.ini deixa a execução verbosa por padrão: cada teste aparece listado individualmente com o resultado (PASSED/FAILED). O resultado esperado é semelhante a:

tests/test_banco.py::test_banco_vazio_inicia_e_nao_reconhece PASSED
tests/test_placas.py::test_aceita_placa_no_formato_antigo PASSED
...
18 passed

Se algum teste falhar, o pytest mostra o arquivo e a linha exatos da asserção que quebrou, junto com os valores comparados, por exemplo:

tests\test_placas.py:10: in test_aceita_placa_no_formato_antigo
    assert placa_valida("ABC1234") is True
E   AssertionError: assert False is True

O workflow .github/workflows/testes.yml executa essa suíte automaticamente no GitHub Actions a cada push e pull request. O ambiente de CI usa apenas as dependências leves de teste; não acessa hardware nem dados pessoais.

Os testes garantem o núcleo da aplicação. A câmera, a interface gráfica, o servidor PostgreSQL e a acurácia do modelo FaceNet ainda precisam de validação manual no ambiente real.

Limitações atuais

Os botões Liberar pessoa, Liberar veículo e Liberar ambos registram a autorização apenas na interface. O acionamento físico de uma fechadura ou cancela ainda precisa ser integrado a um endpoint/comando da ESP32-CAM ou a outro controlador de acesso.

A leitura de placas depende da qualidade da imagem e do ângulo da câmera. O classificador Haar Cascade usado para localizar a placa e a acurácia do EasyOCR ainda precisam de validação manual no ambiente real, assim como a webcam e o modelo FaceNet.