Imported from ReinanArgolo/IC-Botos_Track (AGENTS.md). Install upstream with npx skills add ReinanArgolo/IC-Botos_Track. Copyright stays with the author.

Repository Guidelines

Objetivo do projeto

Este repositório desenvolve uma metodologia para extrair, quantificar e visualizar a formação espacial de botos em vídeos aéreos zenitais. O sistema deve produzir representações geométricas, métricas, eventos candidatos e visualizações auditáveis. Não atribua interpretações comportamentais definitivas sem validação dos pesquisadores do PPGZOO.

Estrutura e organização

O repositório ainda está em fase inicial. Ao adicionar conteúdo, use:

• src/: detecção, rastreamento, geometria, eventos, exportação e visualização;
• tests/: testes que espelhem os módulos de src/;
• docs/: decisões metodológicas e formatos de dados;
• project_sources/: artigos e documentos de referência;
• configs/: parâmetros científicos e caminhos, sem números mágicos;
• outputs/: resultados gerados, normalmente ignorados pelo Git.

Antes de propor mudanças, inspecione os formatos reais de detecções, tracks e resultados. Não invente interfaces, calibrações ou arquivos ausentes.

Princípios metodológicos

Represente cada grupo como um grafo espacial: nós são botos e arestas descrevem relações como distância e direção relativa. Mantenha separados:

• coordenadas no frame, corrigidas pela câmera, relativas ao grupo e normalizadas;
• métricas instantâneas e métricas dependentes de identidade;
• valores em pixels e valores em metros;
• observações reais e posições interpoladas;
• implementação, resultado testado, proposta, hipótese e item sujeito à validação biológica.

Falhas de detecção podem alterar artificialmente contagem, centroide, área e eventos. Use “possível fissão” e “possível fusão” até validação. Todo limiar deve ser configurável e justificado pelos dados.

Desenvolvimento, estilo e testes

Use Python com quatro espaços, type hints, docstrings e nomes snake_case. Crie funções pequenas e registre unidades explicitamente. Quando o projeto ganhar ferramentas, documente comandos exatos no README e mantenha uma interface previsível, como make test, make lint e make run.

Teste métricas geométricas com exemplos sintéticos de resultado conhecido. Testes devem ser determinísticos e independentes de rede. Mudanças metodológicas devem incluir testes de regressão e avaliação do impacto de detecções ausentes.

Fluxo de contribuição

Antes de implementar, apresente um diagnóstico curto da arquitetura e confirme a etapa correta de integração. Preserve alterações alheias à tarefa. Ao concluir, informe arquivos modificados, comandos executados, saídas esperadas, suposições e limitações.

Use commits curtos e imperativos, por exemplo feat: calcular raio de giracao. Pull requests devem explicar propósito, método, validação, novas dependências e impacto científico. Não faça commit ou push sem solicitação explícita.

Comunicação

Responda em português brasileiro, salvo solicitação contrária. Use linguagem científica clara, sem inventar resultados, exagerar contribuições ou apresentar hipóteses como fatos.