🐧 PenguinTrack

Face Tracking para Jogos - Similar ao OpenTrack/FreeTrack

Sistema de rastreamento facial em tempo real que converte movimentos da cabeça em dados de controle de câmera para jogos e simuladores.

✨ Características

• 🎯 Rastreamento facial preciso com MediaPipe
• 🎮 Múltiplos protocolos de saída: FreeTrack, UDP, Mouse, Joystick
• 🔧 Configuração em tempo real sem necessidade de reiniciar
• 🎨 Visualização 3D elegante com cubo rotativo
• 🐧 Multiplataforma: Windows, Linux, macOS
• ⚡ Alto desempenho: 60+ FPS
• 🔄 Filtros avançados para suavização e redução de ruído

🚀 Instalação Rápida

Pré-requisitos

• Python 3.8+
• Câmera webcam
• Dependências do sistema (ver INSTALL.md)

Instalação Automática

git clone https://github.com/seu-usuario/PenguinTrack.git
cd PenguinTrack
pip install -r requirements.txt
python main.py

Instalação via pip (em breve)

pip install penguintrack
penguintrack

🎮 Compatibilidade com Jogos

✅ Linux

• UDP + OpenTrack: Euro Truck Simulator 2, DCS World, X-Plane
• Mouse Virtual: War Thunder, World of Tanks
• Veja LINUX_GAME_COMPATIBILITY.md

✅ Windows

• FreeTrack: Todos os jogos compatíveis
• TrackIR: Jogos compatíveis via emulação
• UDP: Simuladores modernos

📋 Protocolos de Saída

Protocolo	Linux	Windows	Descrição
UDP	✅	✅	Universal, recomendado
FreeTrack	❌	✅	Padrão para jogos Windows
Mouse	⚠️	✅	Para testes, limitado
Joystick	⚠️	✅	Dispositivo virtual

🏗️ Estrutura do Projeto

PenguinTrack/
├── src/                    # Código fonte principal
│   ├── core/              # Módulos principais
│   │   ├── face_tracker.py    # Rastreamento facial MediaPipe
│   │   ├── filters.py         # Filtros e suavização
│   │   └── config_manager.py  # Gerenciamento de configuração
│   ├── ui/                # Interface de usuário
│   │   ├── cube3d.py          # Visualização 3D
│   │   └── avatar3d.py        # Avatar alternativo
│   ├── output/            # Protocolos de saída
│   │   └── output_manager.py  # Gerenciador de protocolos
│   └── utils/             # Utilitários
│       └── udp_receiver.py    # Receptor UDP para testes
├── tests/                 # Testes e validação
├── demos/                 # Demonstrações
├── docs/                  # Documentação
├── assets/                # Recursos (imagens, etc.)
├── scripts/               # Scripts de inicialização
└── main.py               # Aplicação principal

⚙️ Configuração

Interface Gráfica

1. Execute python main.py
2. Configure protocolos na aba "Saída"
3. Ajuste filtros na aba "Filtros"
4. Calibre na aba "Calibração"

Linha de Comando

# Teste dos protocolos
python tests/test_outputs.py

# Teste do sistema completo
python tests/test_system.py

# Demo dos controles
python demos/demo_axis_controls.py

🛠️ Desenvolvimento

Configurar ambiente

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# ou .venv\Scripts\activate  # Windows
pip install -r requirements.txt

Executar testes

python -m pytest tests/
python tests/test_basic.py
python tests/test_system.py

Contribuir

1. Fork o projeto
2. Crie uma branch: git checkout -b feature/nova-funcionalidade
3. Commit: git commit -m 'Adiciona nova funcionalidade'
4. Push: git push origin feature/nova-funcionalidade
5. Abra um Pull Request

📊 Benchmarks

• Latência: < 10ms (câmera 60fps)
• CPU: 10-15% (Intel i5 moderna)
• RAM: ~100MB
• Precisão: ±0.5° em condições ideais

🔧 Solução de Problemas

Problemas Comuns

• Câmera não detectada: Verifique permissões e drivers
• Lag/Tremor: Ajuste filtros na aba "Filtros"
• Protocolo não funciona: Veja logs na aba "Saída"

Logs e Debug

python main.py --debug
python tests/test_outputs.py  # Testa protocolos

Veja docs/TROUBLESHOOTING.md para mais detalhes.

📚 Documentação

• 📦 Instalação Detalhada
• 🎮 Compatibilidade Linux
• 🔧 Melhorias de Interface
• 🎨 Melhorias Visuais
• 🎯 Controles dos Eixos

🤝 Contribuidores

• Desenvolvimento Principal: PenguinTrack Team
• Inspiração: OpenTrack, FreeTrack projects
• Tecnologias: MediaPipe (Google), OpenCV

📄 Licença

Este projeto está licenciado sob a MIT License - veja LICENSE para detalhes.

🙏 Agradecimentos

• MediaPipe pela tecnologia de rastreamento facial
• OpenTrack pela inspiração
• Comunidade de simuladores por feedback e testes

---

🐧 PenguinTrack - Rastreamento facial livre e open source para todos!