From 3db2104bdff3fd8fbbeb2151d738aa117e9055d5 Mon Sep 17 00:00:00 2001 From: MarkSant Date: Sat, 15 Aug 2026 15:24:42 -0300 Subject: [PATCH 1/2] docs: refresh stale Portuguese UI labels in English-language docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Several user-facing docs promised English but still quoted Portuguese button/tab labels that the i18n migration (PR #467, main@45ba1685) had already renamed to English msgids. Every label below was re-verified against src/zebtrack/locales/pt_BR/LC_MESSAGES/zebtrack.po rather than translated by hand, since some labels changed shape (not just language) during the migration. docs/wiki/2_Full_Tutorial.md: - "Configuração de Zonas" -> "Zone Configuration" - "Detectar Aquário (Auto)" -> "Detect Aquarium (Auto)" - "Templates salvos" -> ROI Templates section / Template: combobox - "Importar e Aplicar Arquivo..." -> "Import and Apply File..." - "Salvar Zonas Atuais" -> "Save Current Zones" - "Configuração Avançada" -> "Advanced Settings" - "Adicionar e Processar Novos Vídeos/Pastas" -> "Add Videos/Folders to the Project..." - "Progresso do Experimento" -> "Experiment Progress" - "Relatórios" tab -> "Processing and Reports" - "Gerar Relatório Unificado (Todos)" -> "Unified Report (All)" - "Apagar Relatórios Unificados" -> "Delete Everything" - "Geotaxis Zona 1/2" -> "Geotaxis Zone 1/2" (actual report column headers) - dropped the stale "5-step wizard (v1.7)" claim, pointed to the new first_tracking_run.md walkthrough instead docs/guides/user/arduino-bindings.md and external-trigger.md: - "Usar Arduino" -> "Use Arduino for synchronization" - "Configuração de Zonas" -> "Zone Configuration" - "Comandos Arduino por Zona" -> "Per-Zone Arduino Commands (Optional)" - "Entrar"/"Sair" -> "Enter"/"Exit" - "Adicionar / Atualizar" / "Remover" / "Limpar" -> "Add / Update" / "Remove" / "Clear" - "Testar" -> "Test" - "Modo de Gatilho Externo" -> "External Trigger Mode" - "Iniciar" -> "Start" - "Aguardando sinal externo..." -> "Waiting for external signal..." - error/warning message quotes updated to their real English msgids docs/tutorials/first_tracking_run.md was rewritten end to end (was fully Portuguese) and restructured to match the current wizard, which now has 9 possible steps split across two flows (pre-recorded: Discovery, File Selection, Physical Calibration, Automatic Design Detection, Models and Weights, Import Configuration, Confirmation; live: Discovery, Experimental Design, Live Recording Configuration, Physical Calibration, Models and Weights, Confirmation) rather than the 5-step flow it used to document. Also dropped a reference to tests/manual/wizard_release_check.py, which no longer exists. Co-Authored-By: Claude Sonnet 5 --- docs/guides/user/arduino-bindings.md | 20 +- docs/guides/user/external-trigger.md | 40 +- docs/tutorials/first_tracking_run.md | 530 +++++++++++++-------------- docs/wiki/2_Full_Tutorial.md | 28 +- 4 files changed, 307 insertions(+), 311 deletions(-) diff --git a/docs/guides/user/arduino-bindings.md b/docs/guides/user/arduino-bindings.md index 856830c2..fd85e231 100644 --- a/docs/guides/user/arduino-bindings.md +++ b/docs/guides/user/arduino-bindings.md @@ -17,10 +17,10 @@ sends every configured *exit* token once, as a "turn everything off" sweep. ## Prerequisites -- A **live** project created with **"Usar Arduino"** enabled in the wizard +- A **live** project created with **"Use Arduino for synchronization"** enabled in the wizard (live configuration step), with the correct serial **port** selected. - The Arduino connected and flashed with your sketch. -- At least one **ROI** defined in the **"Configuração de Zonas"** tab. +- At least one **ROI** defined in the **"Zone Configuration"** tab. The serial port (and baud rate) is a per-machine setting in [`config.local.yaml`](../../../config.local.yaml): @@ -39,14 +39,14 @@ command. ## Configure bindings -1. Open the project and go to the **"Configuração de Zonas"** tab. +1. Open the project and go to the **"Zone Configuration"** tab. 2. Define your ROIs as usual. -3. In the **"Comandos Arduino por Zona"** panel (bottom of the left column): +3. In the **"Per-Zone Arduino Commands (Optional)"** panel (bottom of the left column): - Click **🔄 ROIs** to load the ROI names you just defined. - Pick a ROI from the **ROI** dropdown. - - Type the integer to send in **Entrar** (on enter) and/or **Sair** (on exit). - - Click **Adicionar / Atualizar**. The row appears in the table and is saved. -4. Repeat for each ROI. Use **Remover** / **Limpar** to edit the table. + - Type the integer to send in **Enter** (on enter) and/or **Exit** (on exit). + - Click **Add / Update**. The row appears in the table and is saved. +4. Repeat for each ROI. Use **Remove** / **Clear** to edit the table. You only ever *type* the short integer token — everything else is a selection. @@ -62,7 +62,7 @@ The bundled `Program_Final.ino` maps integers to LED on/off pairs: | `7` | Red LED 2 ON | `8` | Red LED 2 OFF | To light Red LED 1 while a fish is in the ROI named `Direita`, set that ROI's -binding to **Entrar = 1**, **Sair = 2**. The LED turns on when the fish enters, +binding to **Enter = 1**, **Exit = 2**. The LED turns on when the fish enters, stays on while it remains, and turns off when it leaves — and the end-of-session sweep guarantees it is off after recording stops. @@ -81,8 +81,8 @@ sweep guarantees it is off after recording stops. ## Troubleshooting -- **Panel not visible** — the project is not live, or **"Usar Arduino"** was not - enabled at creation. A note in the panel explains this. +- **Panel not visible** — the project is not live, or **"Use Arduino for + synchronization"** was not enabled at creation. A note in the panel explains this. - **ROI dropdown empty** — define ROIs first, then click **🔄 ROIs**. - **Nothing happens on the device** — check the port in `config.local.yaml` matches the connected Arduino, and that your sketch acts on the integers you diff --git a/docs/guides/user/external-trigger.md b/docs/guides/user/external-trigger.md index 14d203fa..6e3fb6cc 100644 --- a/docs/guides/user/external-trigger.md +++ b/docs/guides/user/external-trigger.md @@ -12,13 +12,13 @@ independent and can be used together. ## Do I need this? (short answer: probably not) **No. The mode is OPT-IN and ships disabled.** If you leave the box unticked -nothing changes: recording starts when you click "Iniciar", exactly as before. +nothing changes: recording starts when you click "▶️ Start", exactly as before. No Arduino is required, nothing blocks, no warning appears. -Ticking **"Usar Arduino"** does **not** enable the trigger either — they are two -separate checkboxes. You can use the Arduino purely for per-zone commands and -keep starting recordings by hand. Unticking "Usar Arduino" clears and disables -the trigger checkbox along with it. +Ticking **"Use Arduino for synchronization"** does **not** enable the trigger +either — they are two separate checkboxes. You can use the Arduino purely for +per-zone commands and keep starting recordings by hand. Unticking "Use Arduino +for synchronization" clears and disables the trigger checkbox along with it. ## The contract: your sketch must SPEAK @@ -77,16 +77,16 @@ To stop from hardware, send `Serial.println(0)` the same way. If you never send ## Step by step -1. **In the wizard** (step 3, "Configuração de Gravação ao Vivo"): - - tick **"Usar Arduino para sincronização"** — the port is detected and +1. **In the wizard** (step 3, "Live Recording Configuration"): + - tick **"Use Arduino for synchronization"** — the port is detected and preselected automatically (the app prefers the one that answers the handshake and has "Arduino" in its description); - - click **"Testar"** to confirm the port opens; - - tick **"Modo de Gatilho Externo (External Trigger)"**. + - click **"🔌 Test"** to confirm the port opens; + - tick **"External Trigger Mode"**. 2. **Finish the wizard** and open the project. The port is opened at load time. -3. **In the Progress grid**, click a subject and then **"▶️ Iniciar"**. +3. **In the Progress grid**, click a subject and then **"▶️ Start"**. - Recording does **not** start. The notice - **"Aguardando sinal externo... (porta COMx)"** appears. + **"Waiting for external signal... (port COMx)"** appears. - Zones are requested BEFORE this wait — the polygon must be ready before we sit waiting for a signal. 4. **Fire the trigger.** On receiving `1`, recording begins. @@ -114,24 +114,24 @@ analysis time. | Situation | Message | What to do | | --------- | ------- | ---------- | -| Trigger on, **"Usar Arduino" off** | "…exige um Arduino configurado" | Enable the Arduino in the project, or turn the trigger off | -| Trigger on, Arduino on, **port not connected** | "…o Arduino não está conectado (porta COMx)" | Check the cable and that no other program holds the port; reopen the project | +| Trigger on, **"Use Arduino for synchronization" off** | "…requires a configured Arduino." | Enable the Arduino in the project, or turn the trigger off | +| Trigger on, Arduino on, **port not connected** | "…the Arduino is not connected (port COMx)" | Check the cable and that no other program holds the port; reopen the project | The second case is common and quiet: if the cable is loose when you open the -project, a "modo offline" warning appears and the project opens anyway. Without -this refusal the session would arm and wait for a signal that has no way to -arrive. +project, a "Could not connect to the Arduino on port {port}. Running in +offline mode." warning appears and the project opens anyway. Without this +refusal the session would arm and wait for a signal that has no way to arrive. ## Troubleshooting | Symptom | Likely cause | | ------- | ------------ | -| Stuck on "Aguardando sinal externo" forever | The sketch is not sending a bare number. `Serial.println("1")` with quotes is text, not a trigger — check in the IDE's Serial Monitor | -| Nothing happens and no notice appears | The trigger is not enabled in the project; check "Config. Avançadas" / the project JSON | -| "Não foi possível conectar" when opening the project | Port held by the Arduino IDE's Serial Monitor — close it (one program per port) | +| Stuck on "Waiting for external signal... (port COMx)" forever | The sketch is not sending a bare number. `Serial.println("1")` with quotes is text, not a trigger — check in the IDE's Serial Monitor | +| Nothing happens and no notice appears | The trigger is not enabled in the project; check the "Advanced Settings" tab / the project JSON | +| "Could not connect to the Arduino on port {port}. Running in offline mode." when opening the project | Port held by the Arduino IDE's Serial Monitor — close it (one program per port) | | Fires on its own, untouched | Button pin declared as `INPUT` instead of `INPUT_PULLUP` — a floating pin oscillates | | Fires with a long delay | `delay()` inside `loop()`. Use `millis()` | -| DRerio logs the event but does not record | No session armed. The `1` only counts after "▶️ Iniciar"; before that it is logged and ignored | +| DRerio logs the event but does not record | No session armed. The `1` only counts after "▶️ Start"; before that it is logged and ignored | ## References diff --git a/docs/tutorials/first_tracking_run.md b/docs/tutorials/first_tracking_run.md index 92abfe77..49b03041 100644 --- a/docs/tutorials/first_tracking_run.md +++ b/docs/tutorials/first_tracking_run.md @@ -1,85 +1,99 @@ -# Wizard de Criação de Projetos - Guia do Usuário +# Project Wizard Walkthrough: Your First Tracking Run -**Versão:** 1.7 -**Última Atualização:** 2025-10-12 +**Last updated:** 2026-08-15 -## Visão Geral +## Overview -O Wizard de Criação de Projetos é um assistente inteligente de 5 etapas que automatiza a criação de projetos no DRerio LogAI. Desde a versão 1.6 ele é a experiência padrão (a flag `ui_features.use_wizard_for_project_creation` deve permanecer habilitada). Ele detecta automaticamente o design experimental, importa zonas de arquivos Parquet existentes e configura estratégias de processamento otimizadas para cada vídeo. +The Project Creation Wizard is the smart, multi-step assistant that automates +project creation in DRerio LogAI. It is the standard experience (the +`ui_features.use_wizard_for_project_creation` flag should stay enabled). It +detects the experimental design automatically, imports zones from existing +Parquet files, and configures a processing strategy for every video. -**Novidade v1.7:** A janela do wizard agora usa tamanho fixo largo (1150x550px) com layout de 3 colunas. Todas as perguntas da primeira etapa são exibidas lado a lado, maximizando o uso do espaço horizontal e minimizando a altura. Espaçamentos compactos e 220px de margem inferior garantem que os botões de navegação fiquem sempre visíveis. Compatível com telas 1366x768+. +The wizard window targets **1050×780 px**, is resizable down to **900×650 px**, +and centers itself on the screen while leaving room for the taskbar. -### Benefícios +### Benefits -- ✅ **Detecção Automática de Design**: Identifica grupos, dias e estrutura experimental -- ✅ **Importação Inteligente de Parquets**: Reaproveita arenas, ROIs e trajetórias já processadas -- ✅ **Configuração Granular**: Controle individual por vídeo do que importar -- ✅ **Economia de Tempo**: Evita reprocessamento desnecessário -- ✅ **Validação Inteligente**: Previne erros antes da criação do projeto +- ✅ **Automatic Design Detection** — identifies groups, days, and experimental structure +- ✅ **Smart Parquet Import** — reuses arenas, ROIs, and trajectories already processed +- ✅ **Granular Configuration** — per-video control over what to import +- ✅ **Time Savings** — avoids unnecessary reprocessing +- ✅ **Smart Validation** — catches errors before project creation -## As 5 Etapas +## The steps differ by project type -### Etapa 1: Descoberta - Entendendo Seu Contexto +The wizard shows a different sequence of steps depending on what you picked in +Discovery: -**Objetivo:** Definir o tipo de projeto e intenções de importação. +- **Pre-recorded (Experimental / Exploratory)** — 7 steps: Discovery → File + Selection → Physical Calibration → Automatic Design Detection → Models and + Weights → Import Configuration → Project Confirmation and Creation. +- **Live** — 6 steps: Discovery → Experimental Design → Live Recording + Configuration → Physical Calibration → Models and Weights → Project + Confirmation and Creation. There is no folder scan, so File Selection, + Automatic Design Detection, and Import Configuration are skipped; camera and + optional Arduino setup replace them. See + [`arduino-bindings.md`](../guides/user/arduino-bindings.md) and + [`external-trigger.md`](../guides/user/external-trigger.md) for that path. -#### Configurações +This tutorial walks through the **pre-recorded** flow, which covers the common +case of tracking videos you already have on disk. -##### 1.1 Tipo de Projeto - -- **Experimental**: Para estudos com grupos de tratamento, controles, design temporal - - Exemplo: Comparar efeito de drogas em grupos Control vs Treatment ao longo de 5 dias - -- **Exploratório**: Para análises abertas, testes rápidos, projetos sem design formal - - Exemplo: Testar configuração de câmera, validar parâmetros de detecção - -**1.2 Organização de Pastas** (somente para projetos experimentais) - -- **Não tenho estrutura de pastas**: Todos os vídeos estão numa pasta única -- **Pastas = Design Experimental**: Pastas representam grupos/dias (ex: `/Control/Day01/`) -- **Pastas = Organização**: Pastas são apenas organizacionais, sem significado experimental - -##### 1.3 Arquivos Parquet Existentes +--- -- **Não possuo arquivos Parquet**: Processar tudo do zero -- **Importar somente zonas** (arena + ROIs): Gerar apenas trajetórias -- **Importar tudo disponível**: Usar todos os dados existentes +## Step 1 · Discovery -💡 **Dica**: Se você já processou vídeos antes, selecione a importação de Parquets para economizar tempo! +**Goal:** Define the project type and import intentions. ---- +### 1. Project Type -### Etapa 2: Seleção de Arquivos +- **Experimental (pre-recorded videos with groups, days, subjects)** — studies + with treatment groups, controls, a time design + - Example: comparing drug effect across Control vs. Treatment groups over 5 days +- **Exploratory (pre-recorded videos, free-form analysis)** — open-ended + analyses, quick tests, projects with no formal design + - Example: testing camera setup, validating detection parameters +- **Live (record straight from the camera in real time)** — recording + experiments live using a camera connected to the computer -**Objetivo:** Selecionar os vídeos e/ou pastas para o projeto. +### 2. Folder Organization (experimental projects only) -#### Opções de Seleção +- **Yes - folders represent the experimental structure (e.g. Group/Day/)** +- **Yes - but only for organization (arbitrary names)** +- **No - every video is in a single directory** -##### 2.1 Adicionar Vídeos Individuais +### 3. Existing Parquet Files -- Clique em "Adicionar Vídeos..." -- Selecione arquivos `.mp4`, `.avi`, ou `.mov` -- Suporta seleção múltipla (Ctrl+Click ou Shift+Click) +- **No - start from scratch** — process everything from zero +- **Yes - I want to import only the arena** +- **Yes - I want to import zones (arena and ROIs)** — import arena/ROIs, regenerate trajectories +- **Yes - I want to import everything (zones + trajectory)** -##### 2.2 Adicionar Pastas +Use **📂 Load Template...** at the top of the step to reload a previously +saved wizard template (see [Templates](#templates) below) instead of +answering these questions from scratch. -- Clique em "Adicionar Pasta..." -- Selecione pasta raiz contendo vídeos -- Scan recursivo: encontra vídeos em subpastas automaticamente +💡 **Tip:** if you already processed videos before, pick a Parquet import +option to save time. -##### 2.3 Remover Seleções +--- -- Selecione item na lista -- Clique em "Remover Selecionado" +## Step 2 · File Selection -##### 2.4 Pré-visualização da Estrutura +**Goal:** Select the videos and/or folders for the project. -- A árvore "Pré-visualização da Estrutura" mostra as primeiras pastas/arquivos detectados -- Útil para validar se escolheu a raiz correta antes de avançar -- Prévia limitada a três níveis e 120 nós para manter a interface responsiva -- Arquivos soltos aparecem agrupados em "Arquivos Individuais" +- **📁 Add Files...** — pick individual `.mp4`, `.avi`, or `.mov` files (supports multi-select) +- **📂 Add Folder...** — pick a root folder; the scan is recursive and finds videos in subfolders automatically +- **❌ Remove Selected** — removes the item currently selected in the list +- **🗑️ Clear All** — removes every selected video and folder +- The **Selection Summary** panel shows a running count of files/folders selected +- The **Selected Items** list and the **Structure Preview** tree (columns + **Folder / File** and **Summary**) show the first folders/files detected — + useful to confirm you picked the right root before advancing. Loose files + are grouped under **Individual Files**. -#### Exemplo de Estrutura +### Example structure ```text Experimento_Canabidiol/ @@ -96,240 +110,241 @@ Experimento_Canabidiol/ └── Subject02.mp4 ``` -💡 **Dica**: Para projetos com estrutura de pastas, use "Adicionar Pasta..." na raiz - a árvore mostrará a hierarquia e o wizard detectará o design automaticamente! +💡 **Tip:** for folder-structured projects, use **📂 Add Folder...** on the +experiment root — the preview tree shows the hierarchy and the wizard detects +the design automatically in the next steps. --- -### Etapa 3: Detecção Automática +## Step 3 · Physical Calibration -**Objetivo:** Analisar vídeos e detectar design experimental automaticamente. +**Goal:** Set the physical dimensions of the arena to convert pixels into +centimetres, and the detection/tracking cadence. -#### O que é Detectado +- **Video and Animal Configuration**: **Number of aquariums (videos)** and **Animals per aquarium** +- **Physical Aquarium Dimensions**: **Width (cm)** and **Height (cm)** +- **⚙️ Advanced Settings**: **Analysis interval (frames)** — how often detection runs +- **🧠 Behavioural Analysis** section for related settings -**3.1 Design Experimental** (somente projetos experimentais) +See [`COORDINATE_SYSTEMS.md`](../reference/COORDINATE_SYSTEMS.md) for how +these values map onto the arena/ROI coordinate system. -- **Grupos**: Control, Treatment, Dose_Low, Dose_High, etc. -- **Dias**: Day01, Day02, D1, D2, etc. -- **Sujeitos**: Subject01, S01, Fish_01, etc. -- **Confiança**: Percentual de certeza da detecção (0-100%) +--- -##### 3.2 Análise de Parquets +## Step 4 · Automatic Design Detection -- **Arena**: `*_arena.parquet` (coordenadas do tanque) -- **ROIs**: `*_rois.parquet` (regiões de interesse) -- **Trajetória**: `*_trajectory.parquet` (dados de rastreamento) -- **Status por Vídeo**: Quais arquivos existem para cada vídeo +**Goal:** Analyze videos and existing Parquet files, and detect the +experimental design automatically (skipped for Exploratory projects). -##### 3.3 Regex Personalizado (Pré-visualização ao Vivo) +The **Detection Results** panel reports: -- Clique em "Regex Customizado" para editar padrões de grupos/dias/sujeitos -- A tabela de pré-visualização atualiza automaticamente conforme você digita -- Erros de regex aparecem em linha (sem pop-ups interruptivos) -- O campo de teste também avalia automaticamente o caminho digitado +- **📊 Videos found** +- **📦 Existing Parquet Files** — counts for Arena, ROIs, Trajectory, and videos that are Complete (all three) +- **🎯 Experimental Design Detected** — Groups, Days, subjects per group, the pattern used, and a **Confidence** percentage (higher is more reliable; treat values below ~70% with caution) +- **⚙️ Current Detector Configuration** — aquarium/animal method and weight, OpenVINO status -#### Padrões de Detecção +Actions available in this step: -1. **Grupos como Pastas**: `/Control/Day01/video.mp4` -2. **Dias como Pastas**: `/Day01/Control/video.mp4` -3. **Pastas Mistas**: `/Control_Day01/video.mp4` -4. **Baseado em Nome**: `Control_Day01_Subject01.mp4` +- **🔄 Re-analyze** — rerun detection (e.g. after changing files) +- **✏️ Edit Design** — manually correct groups/days/subjects when detection gets it wrong +- **🔧 Custom Regex** — supply your own group/day/subject patterns; the preview updates live as you type, and errors show inline instead of as interruptive pop-ups -💡 **Dica**: A confiança de detecção indica a consistência do padrão. Valores acima de 70% são confiáveis. Se a tabela de pré-visualização destacar "Erro", ajuste os padrões antes de confirmar. +The wizard recognizes folder-based patterns (groups and/or days as folders, +mixed folder layouts) as well as filename-based patterns +(`Control_Day01_Subject01.mp4`-style names). --- -## Templates curados e QA contínuo - -- O repositório distribui templates base (`resources/wizard_templates/*.json`) empacotados automaticamente por `scripts/build_templates.py`. O arquivo final `dist/wizard_templates.zip` é anexado pelo pipeline CI. -- Antes de publicar um release execute `python tests/manual/wizard_release_check.py` para validar os templates, conferir traduções e seguir o checklist manual. -- Use `scripts/compile_translations.py` para garantir que os relatórios Word/Excel gerados pelo wizard utilizem os catálogos atualizados (`pt_BR`). -- Qualquer ajuste no wizard deve atualizar a documentação, rodar a suíte `tests/test_wizard*.py` e revisitar os scripts manuais descritos acima. - ---- +## Step 5 · Models and Weights -### Etapa 4: Configuração de Importação +**Goal:** Choose detection methods, weights, and tracking parameters — this +step did not exist in older wizard versions and is new since the OpenVINO +integration. -**Objetivo:** Definir estratégia de processamento individual para cada vídeo. +- **Methods and Weights per Role**: separate **Aquarium (arena detection)** + and **Animals (tracking)** roles, each with its own method + (**Segmentation (seg)** / **Detection (det)**) and weight file +- **Acceleration / OpenVINO**: **Use OpenVINO (requires converting the weight)** toggle plus an **OpenVINO device** selector +- **Detection Parameters (YOLO)**: **Minimum confidence (0-1)** and **NMS (overlap, 0-1)** +- **Tracking Parameters (ByteTrack)**: **Use ByteTrack (Recommended)**, **Track Threshold (0-1)**, **Match Threshold (0-1)**, **Track Buffer (frames)**, **Max distance (px)**, **IoU Threshold (0-1)** +- **🔄 Restore Recommended Defaults** resets all of the above -#### Padrões Inteligentes Pré-Configurados +💡 **Tip shown in the app:** adjust ONE parameter at a time (±0.05) and test. -O wizard aplica automaticamente uma configuração inicial baseada em suas escolhas da Etapa 1: +--- -| Escolha na Etapa 1 | Vídeo com Arena | Vídeo com ROIs | Vídeo com Trajetória | Ação Sugerida | -| ------------------------ | --------------- | -------------- | -------------------- | ---------------------------- | -| Importar tudo disponível | ✅ | ✅ | ✅ | **SKIP** (dados completos) | -| Importar tudo disponível | ✅ | ✅ | ❌ | **IMPORT_ZONES** (rastrear) | -| Importar tudo disponível | ✅ | ❌ | ❌ | **PARTIAL** (importar arena) | -| Importar somente zonas | ✅ | ✅ | ❌/✅ | **IMPORT_ZONES** (rastrear) | -| Não importar Parquets | ❌/✅ | ❌/✅ | ❌/✅ | **FULL** (do zero) | +## Step 6 · Import Configuration -#### Opções de Importação (por vídeo) +**Goal:** Define the per-video processing strategy. -##### Colunas Interativas +### Bulk actions -- **Arena**: ✅ Importar coordenadas do tanque de `*_arena.parquet` -- **ROIs**: ✅ Importar regiões de interesse de `*_rois.parquet` -- **Trajetória**: ✅ Importar dados de rastreamento de `*_trajectory.parquet` +- **Import All Arenas** +- **Import All ROIs** +- **Import All Trajectories** +- **Import Everything** -##### Ação Derivada Automaticamente +### Videos and Strategies table -- **SKIP**: Todos os dados existem - pular processamento -- **IMPORT_ZONES**: Importar arena + ROIs, gerar nova trajetória -- **PARTIAL**: Importar somente arena -- **FULL**: Processar tudo do zero (sem importação) +Columns: **Video**, **Arena**, **ROIs**, **Trajectory**, **Action**. Double-click +a cell to toggle it; the **Action** column recomputes automatically: -#### Como Personalizar +| Arena | ROIs | Trajectory | Action (internal code) | Label shown | +| ----- | ---- | ---------- | ------------------------------ | ------------------------ | +| ✅ | ✅ | ✅ | `SKIP` | Skip (complete data) | +| ✅ | ✅ | ❌ | `IMPORT_ZONES` | Import Zones + track | +| ✅ | ❌ | ❌ | `PARTIAL` | Partial (arena only) | +| ❌/✅ | ❌/✅| ❌/✅ | `FULL` | Full (from scratch) | -1. **Duplo-clique** na célula da tabela para alternar ✅ ⟷ ❌ -2. A coluna "Ação" atualiza automaticamente -3. Resumo no rodapé mostra contagem por ação +- **🏟 Arena \| 🎯 ROIs \| 🧭 Trajectory** legend: **✓** import, **⏸** do not import, **✗** unavailable (no Parquet found) +- **ROI Strategy** for conflicts between imported and newly drawn ROIs: + **Replace (overwrite)**, **Merge (keep both ROIs)** (conflicts are renamed), + or **Manual (ask)** (ask for each conflict) -💡 **Dica**: Use SKIP para vídeos já processados e IMPORT_ZONES para reaproveitar zonas desenhadas! +💡 **Tip:** use Skip for already-processed videos and Import Zones + track to +reuse drawn zones while regenerating trajectories. --- -### Etapa 5: Confirmação - -**Objetivo:** Revisar todas as configurações e criar o projeto. - -#### Informações Exibidas - -##### 5.1 Resumo do Design +## Step 7 · Project Confirmation and Creation -- Tipo de projeto (Experimental / Exploratório) -- Grupos detectados e confiança -- Total de vídeos selecionados +**Goal:** Review every setting and create the project. -##### 5.2 Plano de Processamento +The **Project Summary** panel reflects everything chosen in the previous +steps: project type, detected design (groups/days/confidence), hardware +(camera/Arduino, for live projects), calibration, detector configuration, +folder structure preview, processing plan (estimated at **~5 minutes per +video** to process; Skip is instant), and existing/imported Parquet counts. -- Quantidade de vídeos por ação (SKIP, IMPORT_ZONES, PARTIAL, FULL) -- Estimativa de tempo (5 minutos por vídeo a processar) +Final fields: -##### 5.3 Parquets Existentes +- **Project Name:** — auto-suggested (e.g. `Experiment_Control` for the + first detected group, or `Experimental_Project` / `Exploratory_Project` + otherwise); editable +- **Location:** — defaults to `Documents`; use **Browse...** to change it +- **💾 Save as Template** — stores every answer from this run (see + [Templates](#templates) below) so a future project can start from the same + configuration -- Total de arquivos arena, ROIs, trajetória, completos +The wizard validates the project name and location before letting you finish +— it will not allow an empty name, special characters, a non-writable +location, or a duplicate project name in the same location. -##### 5.4 Estratégia de ROIs - -- Como resolver conflitos entre ROIs existentes e novos (Substituir / Mesclar / Manual) - -#### Configurações Finais - -##### Nome do Projeto - -- Gerado automaticamente com base no design detectado -- Editável manualmente -- Regras: Somente letras, números, espaços, `_` e `-` - -##### Localização +--- -- Padrão: `Documentos` -- Clique em "Procurar..." para alterar -- Validação: Pasta deve existir e ter permissão de escrita +## Templates -#### Validações Finais +Two independent template mechanisms exist: -✅ Nome do projeto não pode estar vazio -✅ Nome não pode conter caracteres especiais (`@`, `#`, `$`, `/`, etc.) -✅ Localização deve existir e ser acessível -✅ Não pode existir projeto com mesmo nome na localização -✅ Pelo menos 1 vídeo deve estar selecionado +- **Curated baseline templates** shipped with the repo under + `resources/wizard_templates/*.json`, packaged by `scripts/build_templates.py` + into `dist/wizard_templates.zip` in CI. Use `scripts/compile_translations.py` + to make sure Word/Excel reports generated by the wizard use the up-to-date + `pt_BR` catalog. +- **User-saved templates**, created with **💾 Save as Template** on the + Confirmation step and reloaded with **📂 Load Template...** on the + Discovery step (file filter: **Wizard Templates** `*.json`). Loading one + pre-fills every step; review each step before continuing. -💡 **Dica**: Revise cuidadosamente todas as configurações - não será possível alterar após criar o projeto! +Any wizard change should update this documentation, run the `tests/test_wizard*.py` +suite, and review the developer guide at +[`docs/guides/developer/wizard.md`](../guides/developer/wizard.md). --- -## Fluxo Recomendado por Cenário +## Recommended Flow by Scenario -### Cenário 1: Projeto Novo (sem Parquets) +### Scenario 1: New Project (no Parquets) -1. **Etapa 1**: Experimental + Pastas = Design Experimental + Não possuo Parquets -2. **Etapa 2**: Adicionar Pasta... (raiz do experimento) -3. **Etapa 3**: Verificar design detectado (grupos e dias) -4. **Etapa 4**: Todos os vídeos em FULL (processar do zero) -5. **Etapa 5**: Confirmar e criar +1. **Discovery**: Experimental + "folders represent the experimental structure" + "start from scratch" +2. **File Selection**: Add Folder... (experiment root) +3. **Automatic Design Detection**: verify the detected design (groups and days) +4. **Import Configuration**: all videos default to `FULL` (process from scratch) +5. **Confirmation**: confirm and create -**Resultado**: Projeto criado com design detectado, todos os vídeos serão processados. +**Result:** project created with the detected design; every video gets processed. --- -### Cenário 2: Importar Zonas de Projeto Anterior +### Scenario 2: Import Zones from a Previous Project -1. **Etapa 1**: Experimental + Pastas = Design Experimental + **Importar somente zonas** -2. **Etapa 2**: Adicionar vídeos com `*_arena.parquet` e `*_rois.parquet` adjacentes -3. **Etapa 3**: Wizard detecta arenas e ROIs existentes -4. **Etapa 4**: Vídeos com arena+ROIs → **IMPORT_ZONES** (rastrear novamente) -5. **Etapa 5**: Confirmar +1. **Discovery**: Experimental + folder structure + **"Yes - I want to import zones (arena and ROIs)"** +2. **File Selection**: add videos with adjacent `*_arena.parquet` and `*_rois.parquet` files +3. **Automatic Design Detection**: the wizard detects the existing arenas/ROIs +4. **Import Configuration**: videos with arena+ROIs → `IMPORT_ZONES` (track again) +5. **Confirmation**: confirm -**Resultado**: Arena e ROIs importadas, novas trajetórias geradas sem redesenhar zonas. +**Result:** arena and ROIs imported; new trajectories generated without redrawing zones. --- -### Cenário 3: Reaproveitar Processamento Completo +### Scenario 3: Reuse a Fully Processed Run -1. **Etapa 1**: Experimental + **Importar tudo disponível** -2. **Etapa 2**: Adicionar vídeos com `*_trajectory.parquet` adjacentes -3. **Etapa 3**: Wizard detecta dados completos -4. **Etapa 4**: Vídeos completos → **SKIP**, novos vídeos → **FULL** -5. **Etapa 5**: Confirmar +1. **Discovery**: Experimental + **"Yes - I want to import everything (zones + trajectory)"** +2. **File Selection**: add videos with adjacent `*_trajectory.parquet` files +3. **Automatic Design Detection**: the wizard detects complete data +4. **Import Configuration**: complete videos → `SKIP`; new videos → `FULL` +5. **Confirmation**: confirm -**Resultado**: Vídeos já processados são pulados, apenas novos são processados. +**Result:** already-processed videos are skipped; only new videos are processed. --- -### Cenário 4: Projeto Exploratório Rápido +### Scenario 4: Quick Exploratory Project -1. **Etapa 1**: **Exploratório** + Não possuo Parquets -2. **Etapa 2**: Adicionar 1-2 vídeos de teste -3. **Etapa 3**: Sem detecção de design (exploratory não detecta) -4. **Etapa 4**: FULL para todos -5. **Etapa 5**: Nome automático "Projeto_Exploratorio_20251004" +1. **Discovery**: **Exploratory** + "start from scratch" +2. **File Selection**: add one or two test videos +3. **Automatic Design Detection**: skipped (exploratory projects don't detect a design) +4. **Import Configuration**: `FULL` for everything +5. **Confirmation**: the project name auto-suggests `Exploratory_Project` -**Resultado**: Projeto simples criado rapidamente para testes. +**Result:** a simple project created quickly for testing. --- -## Perguntas Frequentes - -### 1. O que acontece se eu não tiver estrutura de pastas? - -O wizard funcionará normalmente, mas não detectará design automaticamente. Você poderá configurar manualmente as ações por vídeo na Etapa 4. +## Frequently Asked Questions -### 2. Posso editar a detecção de design? +### 1. What happens if I have no folder structure? -Na versão 1.6, a detecção é automática e não editável. Se a confiança for baixa (<70%), considere reorganizar pastas ou renomear arquivos para seguir um dos 4 padrões suportados. +The wizard still works, but it won't auto-detect a design. Configure each +video's action manually in Import Configuration. -### 3. O que é a "confiança" de detecção? +### 2. Can I edit the detected design? -É um percentual calculado com base em: +Yes. Use **✏️ Edit Design** on the Automatic Design Detection step to correct +groups/days/subjects by hand, or **🔧 Custom Regex** to supply your own +detection patterns. If confidence is low (below ~70%), consider reorganizing +folders/filenames first. -- **Consistência** do padrão (50%) -- **Cobertura** dos vídeos (30%) -- **Ausência de outliers** (20%) +### 3. What is detection "Confidence"? -Valores acima de 70% são confiáveis. +A percentage reflecting how consistent the detected pattern is across your +videos. Higher values are more reliable; treat anything clearly below 70% +with caution and double-check the detected design before continuing. -### 4. Posso voltar para etapas anteriores? +### 4. Can I go back to previous steps? -Sim! Use o botão "< Voltar" a qualquer momento. Seus dados serão preservados. +Yes — the **< Back** button is available at any time; your data is preserved. -### 5. Posso cancelar o wizard? +### 5. Can I cancel the wizard? -Sim. Clique em "Cancelar" a qualquer momento. O wizard pedirá confirmação se você já tiver preenchido dados. +Yes. Click **Cancel** at any time. -### 6. O que acontece se eu escolher SKIP mas o vídeo não tiver todos os dados? +### 6. What if I choose Skip but the video is missing data? -O wizard não permite SKIP sem dados completos. A validação na Etapa 4 garante que SKIP só seja aplicado a vídeos com arena + ROIs + trajetória. +The wizard won't allow `SKIP` without complete data — Import Configuration +only allows it when arena + ROIs + trajectory all exist. -### 7. Quanto tempo demora o processamento? +### 7. How long does processing take? -Estimativa: **~5 minutos por vídeo** para processamento FULL. IMPORT_ZONES é mais rápido (~2-3 min). SKIP é instantâneo. +Estimate: **~5 minutes per video** for `FULL` processing. `IMPORT_ZONES` is +faster (only trajectory generation runs). `SKIP` is instant. -### 8. Os arquivos Parquet devem estar na mesma pasta que os vídeos? +### 8. Do the Parquet files need to be in the same folder as the videos? -Sim. O wizard busca arquivos com padrão `{video_name}_arena.parquet`, `{video_name}_rois.parquet`, `{video_name}_trajectory.parquet` na mesma pasta do vídeo correspondente. - -Exemplo: +Yes. The wizard looks for `{video_name}_arena.parquet`, +`{video_name}_rois.parquet`, and `{video_name}_trajectory.parquet` next to +the matching video: ```text /Videos/ @@ -341,95 +356,76 @@ Exemplo: --- -## Solução de Problemas +## Troubleshooting -### Problema: "Nenhum design detectado" mesmo com estrutura de pastas +### "No design detected" despite a folder structure -**Causa**: Estrutura não segue um dos 4 padrões suportados. +**Cause:** the structure doesn't follow one of the recognized patterns. -**Solução**: +**Solution:** -1. Verifique se pastas/nomes seguem padrões consistentes -2. Use palavras-chave reconhecidas: Control, Treatment, Day, D, Subject, S -3. Considere reorganizar pastas ou usar projeto Exploratório +1. Check that folders/names follow a consistent pattern. +2. Use recognizable keywords: Control, Treatment, Day, D, Subject, S. +3. Try **🔧 Custom Regex** to describe your own naming pattern, or reorganize + into an Exploratory project. --- -### Problema: Wizard não encontra arquivos Parquet existentes +### The wizard doesn't find existing Parquet files -**Causa**: Arquivos não seguem convenção de nomenclatura. +**Cause:** files don't follow the naming convention. -**Solução**: +**Solution:** -1. Renomeie Parquets para `{video_name}_arena.parquet`, etc. -2. Certifique-se de que estão na mesma pasta do vídeo -3. Verifique extensão: `.parquet` (não `.pq` ou `.parq`) +1. Rename Parquets to `{video_name}_arena.parquet`, etc. +2. Make sure they sit in the same folder as the video. +3. Check the extension is `.parquet` (not `.pq` or `.parq`). --- -### Problema: Confiança de detecção muito baixa (<50%) +### Detection confidence is very low -**Causa**: Inconsistência na estrutura de pastas/nomes. +**Cause:** inconsistent folder/name structure. -**Solução**: +**Solution:** -1. Revise estrutura e identifique outliers (vídeos fora do padrão) -2. Renomeie pastas/arquivos para seguir padrão consistente -3. Ou use projeto Exploratório e configure manualmente +1. Review the structure and identify outliers (videos that don't fit the pattern). +2. Rename folders/files to follow a consistent pattern. +3. Or switch to an Exploratory project and configure manually. --- -### Problema: "Projeto já existe" ao criar - -**Causa**: Já existe pasta com mesmo nome na localização. - -**Solução**: - -1. Escolha nome diferente -2. Ou selecione localização diferente -3. Ou remova/renomeie projeto existente +### "Project already exists" when creating ---- +**Cause:** a folder with the same name already exists at that location. -## Atalhos de Teclado +**Solution:** -| Atalho | Ação | -| -------- | -------------------------- | -| `Enter` | Avançar para próxima etapa | -| `Esc` | Cancelar wizard | -| `Alt+V` | Voltar para etapa anterior | -| `Alt+P` | Próxima etapa | -| `Ctrl+A` | Adicionar vídeos (Etapa 2) | -| `Ctrl+F` | Adicionar pasta (Etapa 2) | -| `Delete` | Remover seleção (Etapa 2) | +1. Choose a different name. +2. Or pick a different location. +3. Or remove/rename the existing project. --- -## Glossário +## Glossary -- **Arena**: Coordenadas do tanque de experimentação -- **ROI**: Região de Interesse (zones dentro do tanque) -- **Trajetória**: Dados de rastreamento (posições dos animais ao longo do tempo) -- **Parquet**: Formato de arquivo colunar usado para armazenar dados de tracking -- **SKIP**: Pular processamento (dados completos já existem) -- **IMPORT_ZONES**: Importar arena e ROIs, gerar nova trajetória -- **PARTIAL**: Importar somente arena -- **FULL**: Processar tudo do zero (sem importação) -- **Design Experimental**: Estrutura formal do experimento (grupos, dias, sujeitos) -- **Confiança de Detecção**: Percentual de certeza na detecção automática de design +- **Arena**: the experimental tank's coordinates +- **ROI**: Region of Interest (zones inside the tank) +- **Trajectory**: tracking data (animal positions over time) +- **Parquet**: the columnar file format used to store tracking data +- **SKIP** (`Skip (complete data)`): skip processing — complete data already exists +- **IMPORT_ZONES** (`Import Zones + track`): import arena and ROIs, generate a new trajectory +- **PARTIAL** (`Partial (arena only)`): import only the arena +- **FULL** (`Full (from scratch)`): process everything from zero (no import) +- **Experimental Design**: the study's formal structure (groups, days, subjects) +- **Detection Confidence**: percentage reflecting how certain the automatic design detection is --- -## Suporte +## Support -Para reportar problemas ou sugerir melhorias: +To report problems or suggest improvements: - GitHub Issues: -- Documentação técnica complementar: `docs/guides/developer/wizard.md` -- Arquitetura: `docs/explanation/architecture.md` - ---- - -**Versão do Wizard:** 1.7 -**Schema Version:** 1 -**Última Atualização:** 2025-10-14 +- Complementary developer docs: `docs/guides/developer/wizard.md` +- Architecture: `docs/explanation/architecture.md` diff --git a/docs/wiki/2_Full_Tutorial.md b/docs/wiki/2_Full_Tutorial.md index fe5619b6..7e9ee6f1 100644 --- a/docs/wiki/2_Full_Tutorial.md +++ b/docs/wiki/2_Full_Tutorial.md @@ -7,7 +7,7 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ## Step 1 · Launch the wizard 1. Open a terminal in the project root and run `poetry run zebtrack`. -2. Click **"Create Project"**. The 5-step wizard (v1.7) opens automatically. +2. Click **"Create Project"**. The wizard opens automatically (step count varies by project type — see [`docs/tutorials/first_tracking_run.md`](../tutorials/first_tracking_run.md) for the full walkthrough). 3. Follow the discovery step: - Choose **Experimental**, **Exploratory**, or **Live** mode. - Tell the wizard whether you want to reuse existing Parquet files (arena/ROIs/trajectory). @@ -26,11 +26,11 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ## Step 2 · Configure arenas and ROIs -1. Go to the **"Configuração de Zonas"** tab. -2. Use **Detectar Aquário (Auto)** or draw the main arena manually. -3. Apply previously saved templates with the **Templates salvos** combobox. Use **📂 Importar e Aplicar Arquivo...** to load templates directly from JSON files. +1. Go to the **"Zone Configuration"** tab. +2. Use **Detect Aquarium (Auto)** or draw the main arena manually. +3. Apply previously saved templates from the **ROI Templates** section using the **Template:** combobox. Use **📂 Import and Apply File...** to load templates directly from JSON files. 4. Draw or edit ROIs. The editor now clamps vertices to the arena boundary and highlights clamped points (orange handles with extra circles), ensuring valid polygons. -5. Save the current layout as a template with **💾 Salvar Zonas Atuais** so that future projects can reuse them. +5. Save the current layout as a template with **💾 Save Current Zones** so that future projects can reuse them. > 🛈 When editing ROIs, the cyan snapping indicator and the handles stay within the arena boundaries, preventing accidental drags outside the valid area. @@ -38,7 +38,7 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ## Step 3 · Tune detector settings -1. Open the **Configuração Avançada** tab to review `config.local.yaml` in-app. The editor validates values in real time using the Pydantic schema. +1. Open the **Advanced Settings** tab to review `config.local.yaml` in-app. The editor validates values in real time using the Pydantic schema. 2. Configure detector thresholds (confidence/NMS), choose between YOLO and OpenVINO weights, and enable optional features like the UI event queue or Arduino integration. 3. Switch back to the main tab and pick the detector plugin you want to run. @@ -48,7 +48,7 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ### Pre-recorded projects -1. In **Main Control**, click **"Adicionar e Processar Novos Vídeos/Pastas"**. +1. In **Main Control**, click **"Add Videos/Folders to the Project..."**. 2. Confirm the wizard’s processing plan. DRerio LogAI handles detection → tracking → analysis automatically. 3. The overlay view displays: - Current frame with bounding boxes. @@ -57,7 +57,7 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ### Live projects -1. Use the **Progresso do Experimento** grid to select the subject/day. +1. Use the **Experiment Progress** grid to select the subject/day. 2. Configure countdowns or fixed durations if desired. 3. Start the session from **Main Control**. Video recording and analysis happen in one pass. @@ -65,8 +65,8 @@ This tutorial walks through the complete DRerio LogAI workflow: creating a proje ## Step 5 · Review results and export reports -1. Open the **Relatórios** tab once processing finishes. -2. Select specific videos or use **Gerar Relatório Unificado (Todos)** for an aggregated summary. +1. Open the **Processing and Reports** tab once processing finishes. +2. Select specific videos or use **📚 Unified Report (All)** for an aggregated summary. 3. Choose the export format: - Excel (`.xlsx`) tidy tables. - CSV (`.csv`) for interoperability. @@ -83,8 +83,8 @@ Reports now include enhanced velocity and geotaxis metrics: | **Mean Speed (cm/s)** | Average swimming velocity | | **Max Speed (cm/s)** | Maximum instantaneous velocity | | **Median Speed (cm/s)** | Median velocity (robust to outliers) | -| **Geotaxis Zona 1 - Fundo (%)** | Time spent in bottom zone | -| **Geotaxis Zona 2 (%)** | Time spent in middle zone | +| **Geotaxis Zone 1 - Bottom (%)** | Time spent in bottom zone | +| **Geotaxis Zone 2 (%)** | Time spent in middle zone | > 📝 **Note**: Column names in Word reports now display with proper units (e.g., "Max Speed (cm/s)" instead of "Max Speed Cm S"). @@ -95,14 +95,14 @@ The unified report has been robustly improved: - **Identification & Metadata**: Uses the current project structure (Day/Group/Subject) to populate columns, automatically fixing "Unknown" or stale metadata from old files. - **De-duplication**: Duplicate "Group" columns (e.g. `group` vs `group_id`) are automatically resolved to a single standard 'Group'. - **Readable Colors**: ROI Colors are displayed as human-readable names (e.g. "Red", "Dark Blue") in Excel, replacing raw RGB tuples. -- **Report Management**: A new **"🗑️ Apagar Relatórios Unificados"** button allows you to safely clear old aggregated reports. The system now automatically handles OneDrive sync locks and read-only files during deletion. +- **Report Management**: A new **"🗑️ Delete Everything"** button (next to the unified-report actions) allows you to safely clear old aggregated reports. The system now automatically handles OneDrive sync locks and read-only files during deletion. --- ## Step 6 · Tips and QA - Run `poetry run pytest -q` and `poetry run ruff check .` before sharing results. -- Use `tests/manual/wizard_release_check.py` to validate new templates and translations. +- Run the `tests/test_wizard*.py` suite after changing wizard templates or translations. - Keep `config.local.yaml` under version control (if it contains shared lab defaults) or document overrides in your project README. - Consult `docs/reference/operational_reference.md` for formulas, ROI metrics, Arduino integration, and troubleshooting checklists. From 45924e2aadce25a01bca9ebcf5b6d3b6cefd953c Mon Sep 17 00:00:00 2001 From: Marco Sant Ana Date: Sat, 15 Aug 2026 15:41:21 -0300 Subject: [PATCH 2/2] Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- docs/guides/user/external-trigger.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/user/external-trigger.md b/docs/guides/user/external-trigger.md index 6e3fb6cc..5b8c24bb 100644 --- a/docs/guides/user/external-trigger.md +++ b/docs/guides/user/external-trigger.md @@ -114,8 +114,8 @@ analysis time. | Situation | Message | What to do | | --------- | ------- | ---------- | -| Trigger on, **"Use Arduino for synchronization" off** | "…requires a configured Arduino." | Enable the Arduino in the project, or turn the trigger off | -| Trigger on, Arduino on, **port not connected** | "…the Arduino is not connected (port COMx)" | Check the cable and that no other program holds the port; reopen the project | +| Trigger on, **"Use Arduino for synchronization" off** | "External trigger mode requires a configured Arduino." | Enable the Arduino in the project, or turn the trigger off | +| Trigger on, Arduino on, **port not connected** | "The Arduino is not connected — check the cable and whether the port is in use by another program." | Check the cable and that no other program holds the port; reopen the project | The second case is common and quiet: if the cable is loose when you open the project, a "Could not connect to the Arduino on port {port}. Running in