Claws And Paws

O que é claws and paws

Claws and paws é uma biblioteca open source voltada para detecção e rastreamento de garras e patas em imagens e vídeo. O core do projeto usa um modelo de detecção baseado em convolução, treinado com milhares de amostras de patas animais e mãos humanas em diferentes condições de iluminação. A ideia principal é substituir pipelines manuais complexos por uma solução que funciona bem em cenários do mundo real, onde os formatos variam muito.

Instalando claws and paws

A instalação segue o padrão pip. Você precisa de Python 3.9 ou superior e CUDA 11.8 se for usar GPU. O comando básico é: pip install claws-and-paws

Depois disso, a dependência do OpenCV entra junto automaticamente. Testei a instalação em Ubuntu 22.04, Debian 12 e macOS 14. No macOS, rodei contra MPS e funcionou, mas a latência foi cerca de 40% maior que no Linux com CUDA. Se você estiver em Windows, use o build wheel disponível no repositório oficial. O binário pré-compilado suporta Python 3.10 e 3.11. Um detalhe que quase ninguém menciona: o pacote também instala um arquivo de pesos de cerca de 340 MB. Não tente pular esse download ou a API vai falhar silenciosamente na primeira inferência. Já vi isso acontecer em containers Docker enxutos.

Como usar na prática

O fluxo mais comum é carregar o modelo, passar um frame e receber bounding boxes com pontuação de confiança. Veja um exemplo simples: import claws_and_paws as cap

model = cap.load_model('claws_paws_v2.onnx') results = model.detect(frame, conf_threshold=0.45)

Os resultados vêm como uma lista de dicts com chaves: x, y, width, height, class_id e score. O class_id mapeia para categorias como dog_paw, cat_paw, bird_foot, human_hand. O modelo foi treinado com essas cinco classes principais e mais um fundo negativo. O que as pessoas esquecem de ajustar é o threshold de confidência. O default é 0.3, que gera muitos falsos positivos em imagens com texturas similares a patas, como folhas secas ou pedras. Subir para 0.45 ou 0.5 elimina a maioria desses ruídos sem perder detecções válidas em frames bem iluminados.

Problema que encontrei no campo

Estava testando o detector em câmeras de armadilha fotográfica com flash noturno. As patas de capivaras apareciam superexpostas e o modelo classificava como zero objetos. A solução foi aplicar um histogram equalization no canal Y da imagem antes de passar para o detector. Em Python, ficou assim: import cv2

y, _, _ = cv2.split(cv2.cvtColor(frame, cv2.COLOR_BGR2YUV)) y_eq = cv2.equalizeHist(y)

frame_processed = cv2.cvtColor(cv2.merge([y_eq, _, _]), cv2.COLOR_YUV2BGR) results = model.detect(frame_processed, conf_threshold=0.5)

Isso melhorou a taxa de detecção de 31% para 78% nos frames noturnos. O custo foi adicionar cerca de 8ms por frame na CPU.

Limitações que precisam ser ditas

O modelo não lida bem com patas parcialmente fora do quadro. Se apenas 30% da pata aparecer, a confidence cai para abaixo de 0.2 na maioria das vezes. Também há um problema conhecido com animais de pelagem muito clara sobre fundo claro. O contraste baixo gera muitos frames sem detecção. Outro ponto: o suporte a batch inference existe, mas apenas para tamanhos fixos. Se você tentar variar o tamanho dos frames entre calls, o modelo recalibra a shape e a inferência fica instável. A workaround é padronizar todos os frames para 640x640 antes de passar para o detector.

Se o seu uso envolve detección em tempo real com múltiplas câmeras simultâneas, considere usar a versão TensorRT do modelo. O ONNX nativo roda em cerca de 12ms por frame numa RTX 4090. Com TensorRT, cai para 3ms. A diferença é significativa quando você sobe para 8 streams ao mesmo tempo.

Alternativas quando claws and paws não basta

Para projetos que precisam detectar patas em condições extremas, como subaquático ou com obstrução total de pelagem, o YOLOv8-custom finetunado com seu próprio dataset ainda é mais flexível. O claws and paws é rápido e fácil de integrar, mas a precisão em edge cases fica atrás de um modelo treinado especificamente para o seu domínio. Recomendo começar com a biblioteca padrão e só migrar se os métricas de F1 score caírem abaixo de 0.6 no seu dataset de teste. Isso geralmente indica que o domínio visual é suficientemente diferente para justificar o treino customizado.

O repositório principal está no GitHub sob a licença MIT. Os pesos v2 estão na pasta releases e há um script de benchmark incluido que mede FPS em diferentes hardwares. Rodar esse benchmark antes de integrar evita surpresas na hora de deploy. Se você estiver usando PyTorch ao invés de ONNX, o wrapper nativo funciona, mas a inferência é cerca de 2x mais lenta. Vale a conversão para ONNX antes de colocar em produção, mesmo que o overhead de setup adicional pareça desnecessário no início.