O LibrIA é um sistema de reconhecimento de Libras baseado em visão computacional, com fluxos host e embedded já integrados ao código. O repositório cobre coleta unificada em dataset/, treino, inferência em tempo real, calibração opcional de câmera e export de um bundle quantizado com pacote pronto para o Pico.
- Acessibilidade: Facilitar a comunicação entre pessoas surdas e ouvintes
- Educação: Apoiar o aprendizado de Libras
- Tecnologia: Demonstrar aplicações práticas de IA em visão computacional
- Inovação: Criar soluções inclusivas usando machine learning
- 🎥 Captura em tempo real via webcam
- 🤖 Fluxos host e embedded: Random Forest, LSTM, CNN estática quantizada e CNN temporal quantizada
- 📊 Pipeline completo de dados estáticos e temporais
- 🎯 Inferência contínua com feedback visual
- 📷 Calibração opcional de câmera com tabuleiro 9x6
- 📦 Bundle embedded exportável com pacote C/C++ para Pico
- 🏗️ Arquitetura modular e configurável por
FEATURE_MODE
👉 Índice Completo de Documentação - Referência rápida para encontrar o que você precisa
- CONTRIBUTING.md - Como contribuir para o projeto
- docs/DEVELOPMENT.md - Setup de desenvolvimento local
- docs/PULL_REQUEST_GUIDE.md - Guia de Pull Requests
- docs/ARCHITECTURE.md - Arquitetura visual com diagramas curtos e navegáveis
- docs/DATASETS.md - Datasets disponíveis e como obter dados
- docs/AVX_COMPATIBILITY.md - Guia para CPUs sem suporte AVX
- docs/video_format_changes.md - Mudanças de formatos de vídeo
- docs/model_architecture_equations.tex - (TEX disponível) Com fórmulas essenciais da arquitetura
- docs/latex/model_architecture_equations.pdf - (PDF disponível) Com fórmulas essenciais da arquitetura
- CODE_OF_CONDUCT.md - Código de conduta
- GOVERNANCE.md - Estrutura de governança e decisões
- CONTRIBUTORS.md - Lista de contribuidores
- ROADMAP.md - Visão futura do projeto
- CHANGELOG.md - Histórico de mudanças
- LICENSE - Licença MIT
| Tecnologia | Versão | Propósito |
|---|---|---|
| Python | 3.11+ | Linguagem principal |
| TensorFlow | 2.16.1 | Deep Learning para o pipeline temporal |
| Keras | 3.4.1 | API de alto nível |
| PyTorch | 2.5.1 | Alternativa de Deep Learning |
| OpenCV | 4.11+ | Captura e processamento de vídeo |
| MediaPipe | 0.10+ | Detecção de landmarks da mão |
| Scikit-learn | 1.6+ | Random Forest (modelo principal) |
| NumPy | 1.26+ | Computação numérica |
| Pandas | 2.2+ | Manipulação de dados |
| Matplotlib | 3.10+ | Visualização |
| Serialização | pickle | Salvar modelos e dados |
LibrIA/
├── 📁 src/ # Código principal
│ ├── 📁 model_training/ # Treino Random Forest e LSTM
│ ├── 📁 inference/ # Inferência estática e temporal
│ └── 📁 models/ # Modelos/experimentos adicionais
├── 📁 scripts/ # Utilitários de calibração e coleta unificada
├── 📁 config/ # Configurações centrais e arquivos de calibração
├── 📁 utils/ # Helpers compartilhados
├── 📁 dataset/ # Dataset unificado
│ ├── static/
│ └── temporal/
├── 📁 model/ # Artefatos treinados
│ ├── model.pickle
│ ├── libras_lstm.keras
│ ├── libras_lstm_labels.pickle
│ └── embedded_bundle/
├── 📁 docs/ # Documentação detalhada
├── 📄 Makefile # Automação de setup e execução
├── 📄 main.py # Interface principal por comandos
├── 📄 requirements.txt # Dependências principais
├── 📄 requirements-dev.txt # Dependências de desenvolvimento
├── 📄 test_setup.py # Verificação de ambiente
└── 📄 README.md # Visão geral do projeto
A forma mais rápida de começar é usando o Makefile:
# 1. Clone o repositório
git clone https://github.com/Gabryel-lima/LibrIA.git
cd LibrIA
# 2. Setup inicial (cria venv e instala dependências)
make setup
# 3. Verifique se tudo está funcionando
make verify-setup
# 4. Veja todos os comandos disponíveis
make help- Python 3.11 ou superior
- Webcam funcional
- Git
- CPU com suporte AVX (recomendado para funcionalidades completas)
- ℹ️ Sem suporte AVX? Veja Compatibilidade AVX
- CUDA/cuDNN (opcional, para GPU)
Se preferir configurar manualmente sem o Makefile:
# Clone o repositório
git clone https://github.com/Gabryel-lima/LibrIA.git
cd LibrIA
# Crie um ambiente virtual
python3.11 -m venv .venv
source .venv/bin/activate # Linux/Mac
# ou
.venv\Scripts\activate # Windows
# Instale as dependências (CPU)
pip install -r requirements.txt
# Ou para GPU (requer CUDA 12.4):
pip install -r requirements.txt -r requirements-gpu.txt
# Verifique a instalação
python -c "import cv2, mediapipe, sklearn; print('✓ Dependências instaladas!')"Use o comando para validar todo o ambiente:
make verify-setupOu manualmente:
python test_setup.pyO projeto agora utiliza Makefile para automatizar todas as operações:
# Ver todos os comandos e status do sistema
make help
# Setup inicial
make setup # Cria venv + instala dependências
make verify-setup # Valida o ambiente
make environment # Mostra informações do sistema
# Pipeline de ML
make dirs # Cria estrutura de diretórios
make collect-static # Coleta dataset estático unificado
make collect-temporal # Coleta dataset temporal unificado
make collect-minimal-dataset # Coleta o dataset mínimo completo
make train # Treina modelo Random Forest
make train-lstm # Treina modelo temporal LSTM
make train-embedded # Treina CNN estática quantizada
make train-embedded-temporal # Treina CNN temporal quantizada para J/Z
make train-embedded-all # Treina os dois modelos embedded e exporta o bundle
make export-embedded # Reempacota bundle e pacote do Pico
make train-hybrid # Retreina os dois modelos
make infer # Inferência em tempo real
make infer-lstm # Inferência temporal em tempo real
make infer-hybrid # Inferência híbrida
make infer-embedded # Verifica o bundle embedded com os datasets NPY
make run # Executa pipeline completo unificado
make run-lstm # Executa pipeline temporal completo
# Desenvolvimento
make test # Executa testes
make lint # Verifica código (requer dev dependencies)
make format # Formata código (requer dev dependencies)
make install-dev # Instala dependências de desenvolvimento
# Utilitários
make clean # Remove __pycache__, arquivos temporários
# Calibração de câmera
make generate-checkerboard # Gera a imagem do tabuleiro 9x6
make show-checkerboard # Exibe o tabuleiro gerado em tela cheia
make capture-calibration # Abre a webcam, salva imagens do tabuleiro e calibra
make calibrate-camera CALIBRATION_IMAGES='calibration/*.jpg'
make clean-all # Remove tudo (venv, dados, modelos) - CUIDADO!
make freeze # Gera requirements.lock com versões exatas
make update # Atualiza dependências
make status # Alias para 'environment'Para calibrar a câmera, use um tabuleiro de xadrez com 9x6 cantos internos. O fluxo recomendado e:
- Rodar make generate-checkerboard.
- Imprimir a imagem gerada ou exibi-la em outra tela com make show-checkerboard.
- Rodar make capture-calibration.
- Mover o tabuleiro em distâncias e ângulos diferentes.
- Pressionar espaco quando o status mostrar que o tabuleiro foi detectado.
- A calibração sera salva em config/camera_matrix.npy e config/dist_coeffs.npy.
Importante: a janela da webcam não desenha o tabuleiro automaticamente. A câmera precisa ver fisicamente a imagem impressa ou a tela com o tabuleiro aberto.
O Makefile detecta automaticamente:
- ✅ CUDA/GPU: Se disponível, instala com suporte GPU (CUDA 12.4)
- ✅ CPU: Fallback automático para CPU-only
- ✅ Python: Usa Python 3.11+
Você também pode usar o script main.py diretamente:
# Mostrar ajuda
python main.py help
# Executar pipeline completo
python main.py all
# Executar etapas individuais
python main.py collect_static # Coleta estática
python main.py collect_temporal # Coleta temporal
python main.py train # Treinar modelo
python main.py train_hybrid # Retreino estático + temporal com status code confiável
python main.py infer # Inferência em tempo real
python main.py infer_hybrid # Inferência híbrida com arbitragem
python main.py train_embedded_all # Treino embedded completo
python main.py export_embedded # Bundle e pacote do Pico
python main.py infer_embedded # Validação do bundle embeddedPara automação local, CI ou scripts de shell, main.py agora propaga sucesso ou falha via exit code: 0 quando o comando conclui e 1 quando alguma etapa retorna erro.
Se você quiser entender o projeto por etapas, sem um diagrama único gigante, use:
Esse guia separa o fluxo em blocos menores:
- entradas e comandos
- coleta e dataset
- treino host
- inferência host
- pipeline embedded
- export para Pico
- runtime no dispositivo
Cada diagrama termina com links para a sequência correta de leitura.
Para executar todo o pipeline de uma vez:
python main.py allEste comando irá:
- ✅ Coletar o dataset mínimo em
dataset/ - ✅ Treinar os modelos estático e temporal
- ✅ Executar inferência híbrida
make collect-static
make train
make inferO fluxo estático grava frame_XXX.png e sample_XXX.npy em dataset/static/<label>/ e treina um Random Forest salvo em model/model.pickle.
Durante a coleta estática, o projeto também grava sample_XXX_mirror.npy para espelhar a amostra no eixo X. Se a pasta da classe já tiver apenas frame_XXX.png, a coleta faz backfill automático dos sample_XXX.npy ausentes antes de abrir a captura ao vivo e gera as versões espelhadas junto com as originais.
make collect-static
make train-embeddedEsse fluxo reutiliza os sample_XXX.npy do dataset estático, treina uma CNN pequena sobre landmarks normalizados e exporta:
model/libria_embedded_cnn.kerasmodel/libria_embedded_cnn_int8.tflitemodel/libria_embedded_cnn_labels.json
Esse caminho foi pensado para deployment embedded e é o ponto de partida recomendado para portar letras estáticas para microcontroladores. Como a automação principal do projeto está baseada em .npy, essa trilha usa diretamente os landmarks já coletados.
make collect-temporal SEQUENCE_LABELS=J\ Z SEQUENCE_COUNT=30 SEQUENCE_LENGTH=30
make train-embedded-temporalEsse fluxo reutiliza seq_XXX.npy em dataset/temporal/, treina uma CNN temporal leve para capturar movimento e exporta:
model/libria_embedded_temporal_cnn.kerasmodel/libria_embedded_temporal_cnn_int8.tflitemodel/libria_embedded_temporal_cnn_labels.json
Para embedded, a estratégia recomendada passa a ser duas trilhas complementares:
- CNN estática para as letras sem movimento
- CNN temporal para
JeZ
Se quiser treinar as duas em sequência:
make train-embedded-allIsso já exporta automaticamente o bundle combinado em model/embedded_bundle/.
Se quiser apenas reempacotar os artefatos existentes:
make export-embeddedPara validar se o runtime híbrido está coerente com os .npy do projeto:
make infer-embeddedEsse comando não usa MediaPipe. Ele carrega o bundle quantizado, roda os modelos TFLite sobre sample_XXX.npy e seq_XXX.npy e reporta acurácia estática, temporal e híbrida.
O esqueleto de runtime no dispositivo ficou em:
src/interfaces/libria_embedded_runtime.hsrc/interfaces/libria_embedded_runtime.cpp
Observação importante sobre o MediaPipe:
- a coleta do dataset continua igual e não foi alterada
- o MediaPipe segue apenas no host para produzir os landmarks do dataset atual
- o bundle embedded usa o mesmo contrato geométrico de landmarks, mas não depende do MediaPipe em runtime
- no Pico, o caminho viável é reproduzir o mesmo layout normalizado de landmarks com outro extrator leve ou firmware dedicado
make collect-temporal SEQUENCE_LABELS=J\ Z SEQUENCE_COUNT=30 SEQUENCE_LENGTH=30
make train-lstm
make infer-lstmEsse fluxo grava sequências em dataset/temporal/, treina o modelo model/libras_lstm.keras e usa uma janela deslizante para inferência em tempo real.
Cada sequência válida também ganha uma contraparte seq_XXX_mirror.npy. No treino host e no treino temporal embedded, o carregador aceita o diretório temporal legado como fallback quando o caminho principal configurado existe, mas está vazio.
make collect-minimal-dataset
make train-hybrid
make infer-hybridEsse é o fluxo recomendado para validar a arquitetura com 24 classes estáticas e as sequências temporais de J e Z.
Na inferência híbrida, a etapa estática e a etapa temporal agora comparam a amostra original com sua versão espelhada e mantêm a hipótese de maior confiança antes da arbitragem final.
make generate-checkerboard
make show-checkerboard
make capture-calibrationArquivos gerados:
config/camera_matrix.npyconfig/dist_coeffs.npy
Esses parâmetros são usados de forma opcional no pré-processamento dos frames antes da extração dos landmarks.
O modo de features é configurado em config/settings.py:
bounding_box: 42 featureswrist_relative: 63 features
O padrão atual é wrist_relative.
O projeto trabalha com um dataset unificado em dataset/:
- Estático:
dataset/static/<label>/frame_XXX.png,sample_XXX.npyesample_XXX_mirror.npy - Temporal:
dataset/temporal/<label>/seq_XXX.npyeseq_XXX_mirror.npy
Recursos úteis:
- Dataset de apoio em
data/archives/ - Modelos treinados em
model/
Para detalhes de estrutura, formatos e artefatos, consulte docs/DATASETS.md.
O sistema reconhece todas as 26 letras do alfabeto em Libras:
| Letra | Classe | Letra | Classe | Letra | Classe |
|---|---|---|---|---|---|
| A | 0 | I | 8 | R | 17 |
| B | 1 | J | 9 | S | 18 |
| C | 2 | K | 10 | T | 19 |
| D | 3 | L | 11 | U | 20 |
| E | 4 | M | 12 | V | 21 |
| F | 5 | N | 13 | W | 22 |
| G | 6 | O | 14 | X | 23 |
| H | 7 | P | 15 | Y | 24 |
| Q | 16 | Z | 25 |
Nota: o fluxo estático recomendado usa 24 letras sem J e Z. Esses dois sinais ficam no pipeline temporal por dependerem de movimento.
- Captura: webcam → OpenCV
- Detecção: MediaPipe → landmarks da mão
- Features:
bounding_boxouwrist_relative - Treinamento: Random Forest
- Inferência: classificação por frame
- Captura: webcam → OpenCV
- Pré-processamento: calibração opcional da câmera
- Features: sequência de vetores por frame
- Treinamento: LSTM sobre janelas de 30 frames
- Inferência: classificação com buffer deslizante
- Algoritmo:
RandomForestClassifier - Features: configuráveis por
FEATURE_MODE - Persistência:
model/model.pickle - Metadados:
feature_modeenum_featuressalvos junto ao modelo
- Sequência padrão: 30 frames
- Feature size padrão: 63
- Persistência:
model/libras_lstm.keras - Mapa de labels:
model/libras_lstm_labels.pickle
O projeto também possui uma implementação de Transformer-based models para reconhecimento mais avançado. Para explorar modelos experimentais e futuras arquiteturas de deep learning, confira:
📁 src/models/transformer-gpt/ - Modelos Transformer e GPT em desenvolvimento
Estes modelos são uma alternativa em desenvolvimento ao Random Forest padrão, oferecendo potencial para:
- Reconhecimento temporal de sequências de gestos
- Melhor captura de nuances nos sinais
- Suporte a contexto e dependências de longo alcance
📖 Documentação Completa: Leia o README detalhado com instruções sobre:
- Dados para treinamento (interno e externo)
- Uso independente ou integrado ao projeto
- Exemplos de código prontos para usar
- Estratégias de integração com LibrIA
from utils.helpers import extract_landmarks_by_mode
results = hands.process(img_rgb)
if results.multi_hand_landmarks:
features = extract_landmarks_by_mode(
results.multi_hand_landmarks[0].landmark,
FEATURE_MODE,
)Arquivos mais importantes gerados pelo pipeline:
dataset/static/<label>/sample_XXX.npydataset/static/<label>/sample_XXX_mirror.npydataset/static/<label>/frame_XXX.pngdataset/temporal/<label>/seq_XXX.npydataset/temporal/<label>/seq_XXX_mirror.npymodel/model.picklemodel/libras_lstm.kerasmodel/libras_lstm_labels.pickletraining_plots/training_history_lstm.pngtraining_plots/training_history_embedded.pngtraining_plots/training_history_temporal_embedded.pngtraining_plots/accuracy/accuracy_*.pngconfig/camera_matrix.npyconfig/dist_coeffs.npy
Você pode modificar os parâmetros no arquivo config/settings.py:
# Configurações de coleta
COLLECTION_CONFIG = {
'static_samples_per_label': 30,
'temporal_samples_per_label': 30,
}
# Configurações de inferência
INFERENCE_CONFIG = {
'min_detection_confidence': 0.3,
'prediction_interval': 20, # Frames entre predições
}
# Configurações do modelo
MODEL_CONFIG = {
'n_estimators': 100,
'random_state': 42,
}- Modifique
STATIC_LABELSouTEMPORAL_LABELSemconfig/settings.py - Rode a coleta correspondente com
python main.py collect_staticoupython main.py collect_temporal - Retreine com
python main.py trainoupython main.py train_lstm
| Problema | Solução |
|---|---|
| Webcam não detectada | Verifique permissões e drivers |
| Baixa acurácia | Colete mais dados ou melhore a iluminação |
| Detecção instável | Ajuste min_detection_confidence |
| Erro de importação | Instale as dependências corretamente |
| Módulo não encontrado | Execute python main.py a partir da raiz do projeto |
illegal hardware instruction (core dumped) |
CPU sem suporte AVX - veja Compatibilidade AVX |
Para debug detalhado, verifique o arquivo libras.log:
tail -f libras.log- Makefile Profissional: Automação de todas as tarefas (setup, run, test, clean)
- Dependências Consolidadas: requirements.txt com versões exatas e suporte a GPU
- Estrutura Modular: Código organizado em módulos específicos
- Configurações Centralizadas: Todas as configurações em
config/settings.py - Utilitários Reutilizáveis: Funções auxiliares em
utils/helpers.py - Interface Unificada: Script principal
main.pycom comandos claros - Documentação Melhorada: Docstrings e comentários detalhados
- Tratamento de Erros: Melhor gestão de exceções
- Logging: Sistema de logs para debug
- Validação: Verificação de pré-requisitos antes da execução
- Reproduzibilidade: Lock files e CI/CD-ready
- Sem Pipenv: Substituído por venv padrão do Python + Makefile
Os arquivos e configurações obsoletas foram movidos para .deprecated-files/:
Pipfile→.deprecated-files/Pipfile(pipenv descontinuado)Pipfile.lock→.deprecated-files/Pipfile.locksetup-pipenv.sh→.deprecated-files/setup-pipenv.sh(obsoleto)setup-venv.sh→.deprecated-files/setup-venv.sh(substituído por Makefile)
Os arquivos de código antigos ainda estão em backup_old_files/ apenas como referência histórica de experimentos anteriores.
Contribuições são bem-vindas! Para contribuir:
- Fork o projeto
- Crie uma branch para sua feature (
git checkout -b feature/AmazingFeature) - Commit suas mudanças (
git commit -m 'Add some AmazingFeature') - Push para a branch (
git push origin feature/AmazingFeature) - Abra um Pull Request
- Suporte para números (0-9)
- Reconhecimento de palavras completas
- Interface gráfica (GUI)
- Modelo neural mais avançado
- Suporte para múltiplas mãos
- Testes automatizados
- CI/CD pipeline
Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.
Gabryel Lima
- LinkedIn: Gabryel Lima
- GitHub: @Gabryel-lima
- MediaPipe pela biblioteca de detecção de mãos
- OpenCV pelo processamento de imagens
- Scikit-learn pelos algoritmos de ML
- Comunidade Python pelo suporte
Se você encontrar algum problema ou tiver dúvidas:
- 📧 Email: gabbryellimasi@gmail.com
- 🐛 Issues: GitHub Issues
- 💬 Discussões: GitHub Discussions
⭐ Se este projeto te ajudou, considere dar uma estrela! ⭐