# Primeiros passos com o DRerio LogAI Do programa recém-instalado até um relatório pronto, na ordem em que você vai fazer de verdade. Versão em inglês: [Getting Started](GETTING_STARTED.md). Este guia descreve a interface como ela é: cada item de menu, botão e passo abaixo existe e tem exatamente o nome que o programa usa (as telas em inglês aparecem com os rótulos originais entre parênteses quando isso ajuda a achar o botão). ## Conteúdo - [Antes da primeira análise](#antes-da-primeira-análise) - [A primeira abertura](#a-primeira-abertura) - [Configurando os modelos de detecção](#configurando-os-modelos-de-detecção) - [A janela principal](#a-janela-principal) - [Que tipo de projeto criar](#que-tipo-de-projeto-criar) - [Criando um projeto pré-gravado](#criando-um-projeto-pré-gravado-7-passos) - [Desenhando a arena e as ROIs](#desenhando-a-arena-e-as-rois) - [Processando os vídeos](#processando-os-vídeos) - [Relatórios e resultados](#relatórios-e-resultados) - [Projetos ao vivo](#projetos-ao-vivo) - [Analisando um vídeo único, sem projeto](#analisando-um-vídeo-único-sem-projeto) - [Teclado e mouse](#teclado-e-mouse) - [Para onde ir depois](#para-onde-ir-depois) - [Glossário](#glossário) ## Antes da primeira análise Você precisa de: - **O programa instalado** — veja [Instalação e configuração](../1_Instalacao.md). - **Seus vídeos**, ou uma câmera conectada. MP4 é o formato mais seguro; AVI, MOV e MKV funcionam, e em geral tudo que o OpenCV abre. - **As dimensões físicas do aquário, em centímetros** (largura e altura da área que a câmera vê). Sem elas, distâncias e velocidades só podem ser reportadas em pixels. - **Uma decisão sobre o ângulo da câmera**: lateral (de lado, como no novel tank test) ou de cima (como num campo aberto). O modelo de detecção depende disso. ## A primeira abertura 1. **A pergunta de idioma.** A resposta é gravada em `config.local.yaml`. O idioma do sistema operacional não é consultado de propósito. Mude depois em **Configurações → Idioma...**. 2. **Uma tela de abertura com o teste de hardware.** Ela converte um modelo para OpenVINO e mede quão rápido cada dispositivo disponível o executa, para escolher o backend. Esta é a abertura mais lenta que você terá: o resultado fica em cache. 3. **A janela principal.**  4. **A janela de Primeiros passos**, que explica os modelos e lê o seu hardware para dizer se vale ligar o OpenVINO aqui. O botão dela abre o painel de modelos; esse painel também está sempre em **Configurações → Definições de modelo...**, e esta janela em **Ajuda → Primeiros passos...**. ## Configurando os modelos de detecção Faça isso uma vez, antes da primeira análise. **Configurações → Definições de modelo...** ### Quais são os seis modelos O `fetch-weights` (executado pelo instalador) coloca seis modelos YOLO treinados em `weights/`: | Modelo | Tipo | Ângulo da câmera | | --- | --- | --- | | `best_det_lateral.pt` | detecção — uma caixa em volta do animal | lateral (de lado) | | `best_seg_lateral.pt` | segmentação — o contorno do animal | lateral | | `best_det_topdown.pt` | detecção | de cima | | `best_seg_topdown.pt` | segmentação | de cima | | `best_oi.pt` | detecção | qualquer (generalista, menos preciso) | | `best_seg.pt` | segmentação | qualquer (generalista, menos preciso) | **Um modelo treinado para um ângulo não acha nada no outro.** Um modelo lateral observando uma gravação feita de cima não reporta peixe nenhum, mesmo com o peixe bem visível. Combinar o modelo com a sua câmera é a configuração mais importante desta tela. ### Os quatro papéis Em **Pesos padrão por papel**, um modelo é atribuído a cada papel: - 🐠 **Aquário (Detecção)** — acha o tanque como um retângulo - 🐠 **Aquário (Segmentação)** — acha a forma real do tanque - 🐟 **Animal (Detecção)** — acha cada peixe como uma caixa - 🐟 **Animal (Segmentação)** — acha cada peixe como uma máscara Os quatro especialistas já vêm atribuídos. Escolha o par que corresponde ao seu ângulo de câmera; os generalistas existem para montagens que os especialistas não atendem, e são escolha explícita. **Detecção ou segmentação?** A detecção é mais leve e basta quando a posição aproximada resolve. A segmentação é melhor quando a precisão espacial importa — regiões pequenas, bordas, vários animais próximos — e é **obrigatória** se você pretende usar a regra de ROI `seg_overlap`, que compara a máscara do animal com a região. ### OpenVINO | Sua máquina | O que fazer | | --- | --- | | Tem placa de vídeo NVIDIA | Deixe o OpenVINO desligado — PyTorch com CUDA costuma ser mais rápido | | CPU Intel / vídeo integrado / NPU, sem NVIDIA | Ligue: é o que torna o rastreamento rápido aqui | | Nenhum dos dois | Deixe desligado; a análise roda na CPU, mais devagar | Marque **Otimizar com OpenVINO (para hardware Intel)**, escolha o **dispositivo OpenVINO**, selecione os pesos que pretende usar e clique em **Converter para OpenVINO**. A conversão acontece uma vez por peso e fica em cache; o catálogo mostra ✓ Pronto, ⏳ Convertendo ou ✗ Falhou. O mesmo painel oferece **Adicionar peso...** (registrar um modelo treinado por você), **Validar caminhos**, **Reescanear a pasta de pesos**, manutenção do cache OpenVINO e **Refazer o benchmark de hardware**. ## A janela principal Antes de abrir qualquer projeto, a tela inicial oferece: | Botão | O que faz | | --- | --- | | **Criar Novo Projeto** | Abre o assistente de projeto | | **Abrir Projeto Existente** | Reabre uma pasta de projeto criada antes | | **Analisar Vídeo Único** | Um vídeo, sem projeto, sem desenho experimental | | **Analisar Câmera ao Vivo** | Uma sessão ao vivo avulsa, sem projeto | | **Configuração Global de Modelos...** | O mesmo painel de **Configurações → Definições de modelo...** | | **Diagnóstico Global...** | Roda os modelos ativos contra um quadro de exemplo e informa o que encontraram | O painel **Status do Modelo de Detecção**, logo abaixo, informa os pesos ativos por papel, o estado do OpenVINO e o hardware detectado — vale uma olhada antes de começar um lote longo. ## Que tipo de projeto criar | Você tem | Use | | --- | --- | | Vídeos já gravados, organizados em pastas por grupo/dia/sujeito | **Criar Novo Projeto** → experimental (pré-gravado) | | Uma câmera, e experimentos ainda por fazer | **Criar Novo Projeto** → ao vivo | | Um vídeo, para olhar rapidamente | **Analisar Vídeo Único** | | Uma câmera, para um teste rápido sem estrutura | **Analisar Câmera ao Vivo** | O projeto é o que dá a estrutura grupo/dia/sujeito, o acompanhamento de status por vídeo e o relatório unificado do experimento inteiro. Os dois modos avulsos dispensam tudo isso. ## Criando um projeto pré-gravado (7 passos)  ### Passo 1 — Descoberta - **Tipo de projeto**: *Experimental (vídeos pré-gravados com grupos, dias, sujeitos)*. - **Organização das pastas**: se as suas pastas significam algo (ex.: `Grupo_CBD/Dia_1/...`), se servem só para organizar, ou se não existem (tudo numa pasta só). - **Arquivos Parquet existentes**: o que fazer com arquivos de análise que já estejam ao lado dos vídeos — importar a arena, importar as zonas, importar tudo, ou começar do zero. > **Recusar aqui é respeitado.** Um projeto criado sobre uma pasta com arena e ROIs de um estudo > anterior chegou a adotá-las em silêncio no primeiro duplo clique, e o relatório saía completo, > medido contra a arena errada. **📂 Carregar modelo...** restaura as respostas de um assistente que você salvou antes. ### Passo 2 — Seleção de vídeos **📁 Adicionar arquivos...** para vídeos individuais, **📂 Adicionar pasta...** para uma árvore inteira. A **prévia da estrutura** mostra como a seleção foi entendida; os vídeos dentro das pastas são enumerados no passo seguinte ao próximo.  ### Passo 3 — Calibração física  - **Largura (cm)** e **Altura (cm)** do aquário: é isso que converte pixels em centímetros, então toda distância, velocidade e métrica em cm depende daqui. Meça a área que a câmera realmente vê. - **Número de aquários (vídeos)**: mais de um quando vários tanques são filmados lado a lado no mesmo vídeo. - **Animais por aquário**. - **Intervalo de análise (quadros)**: analisa um quadro a cada N (10 por padrão). Menor significa mais detalhe temporal e mais tempo de processamento. - **🧠 Análise comportamental**: opções de tigmotaxia e geotaxia. ### Passo 4 — Detecção automática do desenho A estrutura de pastas e os nomes dos arquivos viram **Grupos**, **Dias** e **Sujeitos**, com um valor de confiança e um resumo do que foi encontrado. - **🔄 Reanalisar** depois de mudar algo. - **✏️ Editar desenho** para corrigir à mão. - **🔧 Regex personalizada** quando sua nomenclatura exige um padrão explícito. Confirme os nomes dos grupos antes de seguir: tudo daí para frente — pastas, relatórios, comparações — é construído a partir deles. ### Passo 5 — Modelos e Pesos  Método (segmentação ou detecção) e peso, separadamente para **Aquário (detecção da arena)** e **Animais (rastreamento)**; a chave do OpenVINO e o dispositivo; e os parâmetros do detector: | Parâmetro | Padrão | O que faz | | --- | --- | --- | | Confiança mínima (0–1) | 0,05 | O quanto o modelo precisa estar certo para aceitar uma detecção | | NMS (sobreposição, 0–1) | 0,5 | O quanto duas detecções podem se sobrepor antes de uma ser descartada | | Track Threshold (0–1) | 0,25 | Confiança mínima para uma detecção manter uma trilha viva | | Match Threshold (0–1) | 0,95 | O quanto a associação entre quadros é permissiva (maior = mais permissivo) | | Track Buffer (quadros) | 150 | Por quanto tempo um animal perdido mantém a identidade | | Distância máxima (px) | 400 | O quanto um animal pode se deslocar entre quadros analisados e ainda ser o mesmo | | IoU Threshold (0–1) | 0,05 | Abaixo dessa sobreposição, o pareamento recorre à distância entre centros | > **Ajuste um parâmetro de cada vez, em torno de ±0,05, e teste.** Mexer em dois ao mesmo tempo > torna o resultado impossível de atribuir. **🔄 Restaurar padrões recomendados** desfaz o > experimento. ### Passo 6 — Configuração de importação Por vídeo, o que importar dos arquivos encontrados ao lado dele: **Arena**, **ROIs**, **Trajetória**. Quando já existem ROIs, escolha a estratégia: **Substituir**, **Mesclar (manter as duas)** ou **Manual (perguntar)**. ### Passo 7 — Confirmação Nome e local do projeto, o resumo de todas as respostas, e **💾 Salvar como modelo** para reaproveitar a configuração no próximo estudo. **Finalizar** cria o projeto. ## Desenhando a arena e as ROIs Na aba **Configuração de Zonas**, trabalhando sobre um quadro real da sua gravação.  1. **📹 Selecionar vídeo para desenho** e depois **📹 Carregar quadro do vídeo selecionado**. 2. **A arena** — use **Detectar Aquário (Auto)**, que propõe um polígono (a **Suavização (quadros)** reduz o ruído dessa detecção), ou **Polígono Principal** para desenhar você mesmo. Clique nos vértices, depois **✓ Fechar polígono** e **💾 Salvar esta área**. 3. **As regiões de interesse** — **Região de Interesse (ROI)**, um polígono por região. Dê nome a cada uma: as métricas saem por ROI com esses nomes. 4. **Modelos** — **💾 Salvar** guarda o conjunto atual de regiões; **📂 Importar** aplica um conjunto salvo a outro vídeo ou projeto. 5. **✅ Finalizar e Salvar Projeto**. Errar é barato: **↶ Desfazer (Ctrl+Z)** e **↷ Refazer (Ctrl+Y)**, e **❌ Descartar** abandona o polígono em desenho. **A regra de inclusão** decide o que conta como o animal estar dentro de uma região: | Regra | Dentro quando | | --- | --- | | `bbox_intersects` (padrão) | A caixa em volta do animal sobrepõe a região | | `centroid_in` | O centro do animal está dentro da região | | `centroid_in_on_buffered_roi` | O mesmo, numa região expandida ou contraída por uma margem | | `seg_overlap` | A máscara do animal sobrepõe a região acima de uma fração (0,3 por padrão) | A `seg_overlap` precisa de máscaras, que só existem se tiverem sido gravadas — método de segmentação, persistência de máscaras ligada e essa regra em vigor. Quando faltam, a análise recorre a `bbox_intersects` e avisa no relatório, em vez de falhar. Com vários aquários num vídeo, o **Modo de processamento** escolhe entre **Simultâneo (1 passada, mais rápido)** e **Sequencial (2 passadas, 1 aquário por vez)**, e **🐟 Aquário ativo** seleciona qual deles você está desenhando. As zonas pertencem ao vídeo em que foram desenhadas. Um vídeo sem zonas próprias usa o padrão do projeto. ## Processando os vídeos Em **Controle Principal**: - **Analisar Vídeo(s) Selecionado(s)** — os selecionados na árvore. - **Processar Vídeos Pendentes...** — tudo que ainda não foi processado. - **Adicionar Vídeos/Pastas ao Projeto...** — para ampliar o projeto depois.  A aba **Análise de Vídeo** acompanha a execução: quadros processados, detecções, tempo decorrido e estimado, e a sobreposição com o ID de trilha e a confiança de cada animal. É lá também que se escolhe quais `track_id` manter — todos, ou um específico. A árvore do projeto mostra o estado de cada vídeo, por grupo, dia e sujeito:  **Quanto tempo leva, mais ou menos:** num notebook Intel típico, com OpenVINO ligado e o intervalo de análise padrão de 10, um vídeo de 5 minutos em 1080p leva alguns minutos. Baixar o intervalo para 1 multiplica isso por cerca de dez. ## Relatórios e resultados A aba **Processamento e Relatórios** gera: - **🧾 Relatórios parciais** — por vídeo: trajetória, sumário e relatório Word. - **Relatórios unificados** — uma comparação de todo o projeto, em `/unified_reports/`, com uma planilha de dados mais estatísticas descritivas, um CSV, um Word com boxplots comparativos e um manifesto JSON da execução. Duplo clique em qualquer item abre o arquivo. ### Os arquivos gerados, por vídeo ```text