From 0750613304910c81a0b4695f60809a7aec33778a Mon Sep 17 00:00:00 2001 From: MarkSant Date: Sat, 15 Aug 2026 16:59:59 -0300 Subject: [PATCH] docs(readme): add What's New sections for v5.0 and v6.0 README only documented the v4.0 architectural rewrite as a milestone, leaving readers with no summary of the ~4.5 months of work that followed (ROI overhaul, closed-loop stimulation, i18n) or of the v6.0.0 archival snapshot itself. Adds two new sections, mirrored in README.pt-BR.md, built from git log/diff between the v4.0.0, v5.0.0-rc1 and v6.0.0 tags rather than from memory. --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++-- README.pt-BR.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 136 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a6ad99a9..16d6a9ca 100644 --- a/README.md +++ b/README.md @@ -74,11 +74,76 @@ terms. - **🏗️ Event-Driven Architecture**: modular, extensible system built on events - **📦 Standard Formats**: export to Parquet (data), Excel (metrics), and Word (reports) -## 🚀 Architecture Milestone: Version 4.0 +## 🚀 What's New in Version 6.0 + +Citable archival snapshot prepared for permanent deposit on Zenodo (DOI), in support of the +manuscripts describing the platform's validation and a multi-method tracking benchmark: + +- **📡 Closed-Loop Logger Correctness**: `fps` and `sampling_interval_ms` in + `5_ClosedLoop_.csv` now hold the frame rate **measured** from capture timestamps + (`FrameLedger.current_fps_measured()`), not the value configured in settings — a USB camera + routinely exceeds its configured rate. The configured (nominal) value is kept separately in + new `fps_configured` / `sampling_interval_ms_configured` columns. +- **📦 Archival Readiness**: `.zenodo.json` with complete metadata (authors, ORCID, licence, + INPI registration, funding); `CITATION.cff` updated to `6.0.0`; internal grant-agency material + (unpublished manuscripts, partial reports, proposals, a finance spreadsheet) curated out of the + publicly archived tree. +- **🌐 i18n & Docs Polish**: `README.md` split into an English source plus a Portuguese + translation (`README.pt-BR.md`); stale UI-label references fixed post-i18n; unused + `_on_send_selected_video_to_analysis` removed. + +## 🏗️ Milestone: Version 5.0 + +Roughly 4.5 months of work between the `v4.0.0` architectural rewrite and the `v6.0.0` archival +snapshot: a full ROI overhaul, closed-loop hardware stimulation, and the interface's move to +English as its source language. + +### Region-of-Interest Overhaul + +- **🎯 Canonical ROI Inclusion Rule**: a single resolver (`roi_rule_resolver`, project → global → + default) now backs report generation, live Arduino triggers, and the UI alike, replacing + divergent per-consumer logic. Modes: `centroid_in`, `centroid_in_on_buffered_roi`, + `bbox_intersects`, `seg_overlap`. +- **🔬 Multi-Animal ROI**: `(timestamp, track_id)` aggregation ends the "ghost centroid" bug; + per-animal (`por_animal`) and any-track group semantics; track-aware smoothing and episode + detection. +- **🎭 Real Segmentation-Overlap ROI**: `seg_overlap` reads recorded masks + (`3b_Mascaras_.parquet`) and degrades gracefully — never raises — to `bbox_intersects` + with a logged and reported warning when masks are unavailable. + +### Closed-Loop Stimulation & Hardware Robustness + +- **⚡ Per-Zone Arduino Command Bindings**: edge-triggered `on_enter`/`on_exit` tokens per ROI, + with binding-conflict detection and ACK-based inversion detection (the firmware's own reply + proves whether a binding is wired backwards). +- **📊 Closed-Loop Latency Logging**: software-only, ACK-timestamp characterization of the + ROI-trigger → LED-actuation pipeline (`5_ClosedLoop_.csv`), plus a non-blocking reference + firmware. +- **🗂️ Frame Ledger & Timeline Reconstruction**: `6_FrameLedger_` maps pipeline frame ↔ + real MP4 frame ↔ capture instant, recording every frame-loss mode (queue-full drop, write + failure, not-recording). +- **🔌 External Trigger Mode**: Arduino-gated recording start now reaches both the legacy panel + and the Progress-grid live flow through one decision gate (`external_trigger_gate`). + +### Per-Subject Duration & Live-Session Hardening + +- **⏱️ Per-Subject Recording Duration**: `session_duration_resolver` (subject override → block + default → project default → 300 s fallback), with a heterogeneous-duration warning on + partial/batch reports. +- **🐟 Multi-Aquarium & Live-Session Fixes**: zone-reuse detection, "Mark Batch as Complete" now + generates real reports, OpenVINO global-setting inheritance, corrected processing-tab counters. + +### Internationalization + +- **🌐 English as the Interface Source Language**: full Portuguese (pt-BR) locale catalogue; + translations resolved at call time, never at import time; an unaccented-Portuguese scanner in + CI to prevent regressions. + +## 🏗️ Architecture Milestone: Version 4.0 ### Complete Architectural Refactor -v4.0 represented a fundamental rewrite of the system, focused on stability, maintainability, and performance. It remains the architectural foundation of the current release; see [CHANGELOG.md](CHANGELOG.md) for what changed since then, through the current `v6.0.0`: +v4.0 represented a fundamental rewrite of the system, focused on stability, maintainability, and performance. It remains the architectural foundation of the versions above and of the current release; see [CHANGELOG.md](CHANGELOG.md) for the full per-change history: - **🏗️ Event-Driven Architecture**: complete refactor to eliminate direct coupling between components - Event system with `EventBus` for asynchronous communication diff --git a/README.pt-BR.md b/README.pt-BR.md index 2f859beb..a59832b9 100644 --- a/README.pt-BR.md +++ b/README.pt-BR.md @@ -75,11 +75,78 @@ termos legais. - **🏗️ Arquitetura Event-Driven**: Sistema modular e extensível baseado em eventos - **📦 Formatos Padrão**: Exportação para Parquet (dados), Excel (métricas) e Word (relatórios) -## 🚀 Marco Arquitetural: Versão 4.0 +## 🚀 Novidades na Versão 6.0 + +Snapshot citável preparado para depósito permanente no Zenodo (DOI), em apoio aos manuscritos +que descrevem a validação da plataforma e um benchmark multi-método de rastreamento: + +- **📡 Correção do Logger Closed-Loop**: `fps` e `sampling_interval_ms` em + `5_ClosedLoop_.csv` agora guardam a taxa **medida** a partir dos timestamps de captura + (`FrameLedger.current_fps_measured()`), não mais o valor configurado nas settings — uma câmera + USB costuma exceder a taxa configurada. O valor configurado (nominal) fica em colunas próprias, + `fps_configured` / `sampling_interval_ms_configured`. +- **📦 Pronto para Arquivamento**: `.zenodo.json` com metadados completos (autores, ORCID, + licença, registro INPI, financiamento); `CITATION.cff` atualizado para `6.0.0`; material + interno da agência de fomento (manuscritos inéditos, relatórios parciais, propostas, planilha + financeira) removido da árvore publicamente arquivada. +- **🌐 Polimento de i18n e Docs**: `README.md` dividido em fonte em inglês mais tradução em + português (`README.pt-BR.md`); referências de rótulos de UI desatualizadas corrigidas + pós-i18n; `_on_send_selected_video_to_analysis` (não utilizado) removido. + +## 🏗️ Marco: Versão 5.0 + +Cerca de 4,5 meses de trabalho entre a reescrita arquitetural da `v4.0.0` e o snapshot de +arquivamento `v6.0.0`: uma revisão completa de ROI, estimulação por hardware em malha fechada, e +a migração da interface para o inglês como língua-fonte. + +### Revisão de Região de Interesse (ROI) + +- **🎯 Regra Canônica de Inclusão de ROI**: um resolvedor único (`roi_rule_resolver`, projeto → + global → padrão) passa a valer para geração de relatórios, gatilhos ao vivo do Arduino e a UI, + substituindo lógica divergente por consumidor. Modos: `centroid_in`, + `centroid_in_on_buffered_roi`, `bbox_intersects`, `seg_overlap`. +- **🔬 ROI Multi-Animal**: agregação por `(timestamp, track_id)` acaba com o bug do "centroide + fantasma"; semântica de grupo `por_animal` e `any_track`; suavização e detecção de episódios + cientes da trilha. +- **🎭 ROI de Sobreposição de Segmentação Real**: `seg_overlap` lê máscaras gravadas + (`3b_Mascaras_.parquet`) e degrada graciosamente — nunca levanta exceção — para + `bbox_intersects`, com aviso registrado em log e reportado quando as máscaras não existem. + +### Estimulação Closed-Loop e Robustez de Hardware + +- **⚡ Comandos Arduino por Zona**: tokens `on_enter`/`on_exit` por ROI, disparados por borda, + com detecção de conflito de tokens e detecção de inversão via ACK (a resposta do próprio + firmware prova quando um binding está ligado ao contrário). +- **📊 Log de Latência Closed-Loop**: caracterização por software, baseada em timestamps de ACK, + do caminho gatilho-de-ROI → acionamento do LED (`5_ClosedLoop_.csv`), mais um firmware de + referência não-bloqueante. +- **🗂️ Ledger de Frames e Reconstrução da Linha do Tempo**: `6_FrameLedger_` mapeia frame + do pipeline ↔ frame real do MP4 ↔ instante de captura, registrando todo modo de perda de frame + (descarte por fila cheia, falha de escrita, fora de gravação). +- **🔌 Modo de Gatilho Externo**: o início de gravação condicionado ao Arduino agora chega tanto + ao painel legado quanto ao fluxo ao vivo da grade de Progresso por um único portão de decisão + (`external_trigger_gate`). + +### Duração por Sujeito e Robustez de Sessões Ao Vivo + +- **⏱️ Duração de Gravação por Sujeito**: `session_duration_resolver` (override do sujeito → + padrão do bloco → padrão do projeto → 300 s de fallback), com aviso de duração heterogênea em + relatórios parciais/em lote. +- **🐟 Correções Multi-Aquário e de Sessão Ao Vivo**: detecção de reuso de zonas, "Marcar Lote + Como Completo" agora gera relatórios de verdade, herança do OpenVINO global, contadores da aba + de processamento corrigidos. + +### Internacionalização + +- **🌐 Inglês como Língua-Fonte da Interface**: catálogo completo em português (pt-BR); + traduções resolvidas no momento da chamada, nunca no import; varredura de português sem + acento no CI para prevenir regressões. + +## 🏗️ Marco Arquitetural: Versão 4.0 ### Refatoração Arquitetural Completa -A v4.0 representou uma reescrita fundamental do sistema com foco em estabilidade, manutenibilidade e performance. Ela continua sendo a base arquitetural da versão atual; veja o [CHANGELOG.md](CHANGELOG.md) para o que mudou desde então, até a atual `v6.0.0`: +A v4.0 representou uma reescrita fundamental do sistema com foco em estabilidade, manutenibilidade e performance. Ela continua sendo a base arquitetural das versões acima e da versão atual; veja o [CHANGELOG.md](CHANGELOG.md) para o histórico completo por mudança: - **🏗️ Arquitetura Event-Driven**: Refatoração completa para eliminar acoplamento direto entre componentes - Sistema de eventos com `EventBus` para comunicação assíncrona