DRerio LogAI v7.2.0

DRerio LogAI v7.2.0

The documentation and prerequisites release. v7.1.0 made the program install and
open without a terminal; putting that in front of people who have never
programmed left two gaps — the installer still required a terminal whenever a
prerequisite was missing, and the README explained none of the terms it used.

Relation to the published results

Unchanged. The validation and benchmark results reported in the associated
manuscripts were produced with release 4.0.0, available as tag v4.0.0,
which remains the version to check out for exact reproduction. Releases 5 through
7 are subsequent work on the codebase and were not used to generate any reported
result.

Installing this release

On Windows, download the source ZIP from this page, extract it somewhere
permanent, and double-click install.bat.

It now installs the prerequisites it needs. If Python 3.12 or Poetry is
missing, it offers to install them — Python through winget in user scope (no
administrator prompt), Poetry through its official installer — and puts Poetry on
your PATH. Answer Y to what it asks.

From a terminal, on any platform:

git clone https://github.com/MarkSant/DRerio-LogAI.git && cd DRerio-LogAI
poetry install
poetry run fetch-weights     # ~240 MiB of trained models, required
poetry run zebtrack

Python 3.12 or 3.13; not 3.14, where the pinned numpy has no wheel. No C
compiler is needed. Budget about 3 GB of free disk for the environment and the
models together.

Step-by-step instructions written for someone who has never opened a terminal:
docs/wiki/1_Installation.md (English) ·
docs/wiki/1_Instalacao.md (português).

The model assets are unchanged, and weights_manifest.json still points at
v7.0.0. That is deliberate: the manifest names a published release, so
fetch-weights works immediately rather than depending on this page.

What changed

The installer installs what is missing

Until now, a machine without Poetry got a PowerShell one-liner to paste and an
instruction to "add that folder to your PATH" — the single step of the install
that the researcher this script is written for cannot perform. A machine without
Python got the same shape of answer.

Three details decide whether this works on a clean machine, and all three were
learned by reading what the tools actually do:

• Poetry installed but not on PATH is the common case, because its own
  installer merely asks you to edit PATH and most people close the window.
  Find-PoetryExecutable looks in POETRY_HOME and the two default folders
  before giving up, and the script then uses the full path rather than the name.
• The user PATH is read and written raw, as REG_EXPAND_SZ.
  [Environment]::GetEnvironmentVariable expands %USERPROFILE%-style entries
  and SetEnvironmentVariable writes REG_SZ, so round-tripping through them
  would silently freeze every such entry in the PATH of whoever installs.
• A process does not see the PATH another process just changed. After winget
  runs, the session re-reads the registry, and the Python candidates include the
  per-user install folder — which is exactly where winget puts the interpreter.

-Yes accepts every offer without asking. Without it, an unattended run declines
rather than hanging: -NonInteractive makes Read-Host throw, and that is read
as "no".

A README for the person who runs experiments

The README opened with 200 lines of release highlights for versions 4 through 7
and only reached installation on line 297. Between installation and the end came
VS Code extensions, the directory tree and test-suite statistics — developer
material in the path of someone who only wants to analyse videos.

It now follows the order in which a user needs things: what it is, what it does,
installation in five steps, first run, models and OpenVINO, first project,
parameters, outputs, common problems. The version history moved to
docs/releases/INDEX.md.

Three sections are new, because they existed nowhere and are exactly what is
missing on a first launch:

• The six models, by camera angle. A lateral model on a top-down recording
  detects nothing at all, and nothing said so.
• The four roles and OpenVINO, with the per-hardware rule the getting-started
  window applies: NVIDIA card ⇒ leave it off; Intel without NVIDIA ⇒ turn it on.
• A parameter table — confidence, NMS, ByteTrack, analysis interval, ROI rule
  — with when to raise and when to lower each. The values were read out of
  config.yaml, not from memory: confidence 0.05, NMS 0.5, match 0.95, buffer
  150, max distance 400 px, and bbox_intersects as the default ROI rule.

Guides that describe this program

GETTING_STARTED.md described a different one: a 5-step wizard, Ctrl+N /
Ctrl+R / Ctrl+Shift+A shortcuts that do not exist, "NVIDIA GPU recommended",
JSON export and a YouTube channel. It was rewritten against the real interface —
7 steps for pre-recorded projects and 6 for live, the exact tab and button names,
the four model roles, the live flow with Arduino, and the files the program
really writes.

TROUBLESHOOTING.md told people to use poetry shell, removed in Poetry 2.0,
and asked for "Python 3.12 or higher", which includes 3.14 — where the install
fails.

Portuguese versions of the installation and user guides now exist alongside the
English ones, and the two link to each other.

The DOI badge, and the version numbers

The DOI badge rendered as a broken icon on GitHub, on phones and desktops alike.
Zenodo's badge endpoint answers 200 to a direct request, but it is rate-limited
to 120 requests per minute and sent with cache-control: no-cache; README images
are fetched through GitHub's shared image proxy, which serves thousands of
repositories from the same addresses and therefore takes HTTP 429 often. It is a
static shields.io badge now, with the same text and the same link to doi.org.

The five version declarations agree again. v7.1.0 was published with
src/zebtrack/__init__.py and .zenodo.json still reading 7.0.1 — and since
.zenodo.json's version overrides the tag name, that release's Zenodo record
is labelled 7.0.1.

Full changelog

See CHANGELOG.md for the complete list with the reasoning
behind each change.

DRerio LogAI v7.1.0

DRerio LogAI v7.1.0

The first-run release. v7.0.0 made the software citable; the work since then has
been about the interval between double-clicking the icon and starting the first
analysis — the part a researcher meets before any of the science.

This release supersedes the unreleased 7.0.1 entry in the changelog: v7.0.0 is
the only tag published so far, so everything below has accumulated since it.

Relation to the published results

Unchanged from v7.0.0. The validation and benchmark results reported in the
associated manuscripts were produced with release 4.0.0, available as tag
v4.0.0, which remains the version to check out for exact reproduction. Releases
5 through 7 are subsequent work on the codebase and were not used to generate any
reported result.

Installing this release

On Windows, download the source ZIP from this page and double-click
install.bat. It checks Python, checks Poetry, pins the environment to a
supported interpreter, installs the dependencies, downloads the models and
creates a DRerio LogAI icon on the Desktop and in the Start Menu.

From a terminal, on any platform:

git clone https://github.com/MarkSant/DRerio-LogAI.git && cd DRerio-LogAI
poetry install
poetry run fetch-weights     # ~240 MiB of trained models, required
poetry run zebtrack

No C compiler is needed any more — every dependency installs from a prebuilt
wheel. Budget about 3 GB of free disk for the virtual environment and the models
together. Python 3.12 or 3.13; not 3.14, where the pinned numpy has no wheel.

All six models are now installed

fetch-weights downloads all six trained models and verifies every file
against a SHA-256 recorded in weights_manifest.json. Previously it installed
four and left the two generalists — best_oi.pt and best_seg.pt — behind an
--all flag.

The reason they were excluded turned out to be circular. They were skipped
because the weight catalogue could not discover them: discovery globbed only
best_*_lateral.pt and best_*_topdown.pt, so a downloaded generalist landed in
weights/ and never appeared in the model panel. Fetching a file nothing could
select was pointless. The discovery gap was the real defect; with it fixed, the
download no longer has to model it. --all is still accepted and now changes
nothing.

The four specialists remain the defaults. They are trained for a specific camera
angle — a lateral model on a top-down scene returns nothing — so a generalist is
registered but never claims a default slot; it is something you opt into from the
model panel.

The model assets for this release are the same files published on v7.0.0,
byte for byte, and weights_manifest.json still points there. That is
deliberate: the manifest names a published release, so fetch-weights works
immediately rather than depending on this page.

What changed

The icon no longer looks dead for four seconds

The splash screen was created after the import block that builds the
coordinator graph, so the window only appeared once the heavy loading had already
finished. Under the desktop shortcut the app runs through pythonw.exe with no
console, so there was nothing at all to see: no window, no cursor change, no
taskbar entry.

Two costs sat in front of it, both looking like ordinary import lines —
zebtrack.utils imports torch in its module body (~1.1 s), and the DI
registration block pulls ultralytics, cv2 and matplotlib on top of it (~3 s).
The splash is now built before both, and the heavy loading runs under a progress
message.

The first-run benchmark now measures something

Its inference steps are guarded on an OpenVINO model existing, and on a fresh
install nothing has been converted yet — so every measurement step was skipped.
The whole benchmark finished in 0.2 seconds and recommended CPU at 0.0 FPS. That
result was then cached and never recomputed, leaving the machine configured from
a measurement that never happened.

It now converts one model to OpenVINO before measuring. This is not added
overhead: it is work the application pays anyway the first time OpenVINO is used
for real, moved out of your first analysis and into a moment where the splash can
explain the wait. A run that still measures nothing is marked inconclusive and is
not cached, so it retries on the next launch instead of freezing a guess.

The seven benchmark steps are also legible now. They were always sent to the
splash, but several finish in milliseconds and were overwritten within a single
frame, so the sequence existed only in the log.

A getting-started window, and a menu entry that should have existed

Opening the application for the first time gave you a complete interface and no
indication of what to do first — in particular, no hint that the six models need
assigning to roles. Worse, the model configuration panel had no menu entry at
all: it was reachable only from a button inside a project view.

There is now a getting-started window after the main window opens, explaining the
models, the four roles they fill, and whether OpenVINO is worth enabling on
your machine — it reads the detected hardware and names the devices rather than
offering generic advice. It is reachable afterwards from Help → Getting
Started, and the panel itself from Settings → Model settings.

Installing and launching without a terminal (from the unreleased 7.0.1 work)

• install.ps1 / install.bat and setup.sh: guided installation that stops at
  the first failing step and says what to do about it.
• A desktop and Start Menu shortcut targeting pythonw.exe -m zebtrack.
• Logging died on every record without a console. StreamHandler(sys.stdout)
  under pythonw got None, and the fallback to sys.stderr is None too —
  every record raised inside emit, silently.
• Camera detection needed a stderr to silence. A failed redirect closed the
  process's real stderr; the wizard then listed no cameras at all.
• The very first launch hung on a window that was never drawn. The language
  chooser called transient() on a withdrawn root, and a transient inherits its
  master's withdrawn state — so wait_window blocked forever on a window nobody
  could see, focus or close.
• A failure before Tk existed vanished without trace. Startup errors now
  reach a message box instead of a sys.stderr that does not exist.

Full changelog

See CHANGELOG.md for the complete list with the reasoning
behind each change.

DRerio LogAI v7.0.0

DRerio LogAI v7.0.0

Citable snapshot prepared for permanent archiving on Zenodo, in support of the
manuscripts describing the platform (validation study) and the multi-method
tracking benchmark.

Relation to the published results — read this first

The validation and benchmark results reported in the associated manuscripts were
produced with release 4.0.0, which remains available as tag v4.0.0 and is
the version to check out for exact reproduction of the reported numbers.

Releases 5, 6 and 7 are subsequent work on the codebase and were not used to
generate any reported result. This snapshot is archived as the citable state of
the software; the manuscripts cite tag v4.0.0 as the version under test and
this release as the archived platform.

Installing this release

Three steps, and the second one is new:

git clone https://github.com/MarkSant/DRerio-LogAI.git && cd DRerio-LogAI
poetry install
poetry run fetch-weights     # ~200 MB of trained models, required
poetry run zebtrack

fetch-weights downloads the four trained detector models from this release's
assets and verifies every file against a SHA-256 recorded in
weights_manifest.json. They are not in the repository because of their size,
and the application does not start without them.

Six models are attached. The four installed by default are the perspective
pair -- one segmentation and one detection model for the lateral view and for
the top-down view -- and they are the ones the weight catalogue discovers by
filename. --all adds best_oi.pt and best_seg.pt, 3-class generalists
that carry a zup-aqua class the perspective models do not; they match no
discovery glob and are registered through Add Weight....

A C compiler is required: one dependency (cython-bbox) ships only as a source
distribution. Budget about 3 GB of free disk for the virtual environment and the
models together. Full prerequisites in the README.

Changes since v6.0.0

Installation and first run — the reason this is a major version

• The trained models are now obtainable. They were git-ignored and no
  instruction anywhere said how to get them, so a fresh clone installed, passed
  the whole test suite — which mocks them — and then failed to open.
  poetry run fetch-weights closes that, with checksum verification and a
  download that is discarded rather than kept when it does not verify.
• Starting without models now says which models, in which folder, and which
  command installs them. It previously ran a full hardware benchmark, drew the
  splash to ~95%, and reported only "a fatal error occurred".
• config.yaml, weights/, weights_config.json and the OpenVINO cache are
  resolved against the repository root instead of the working directory, so the
  launch directory no longer decides whether the application finds its own
  configuration.
• --reset, --reset-weights and --reset-all now delete what they promise.
  Run from any other directory they matched nothing, deleted nothing, and still
  printed "Reset complete".
• The installation documentation stopped describing things that do not work: a
  troubleshooting entry invented a configuration key that fails validation and
  prevents the application from opening; both READMEs advised copying the whole
  config.yaml into the local override, which permanently shadows later
  defaults; three separate places claimed the models download automatically.

Live-camera workflow

• Real aquarium width and height can be entered in the live dialog. They were
  validated and used to derive the pixel/cm ratio of every distance, speed and
  cm-based metric, but no widget exposed them — a maze declared square produced
  95.8 px/cm on one axis against 60.1 on the other.
• Live post-analysis uses the project's settings snapshot instead of the shared
  settings object, so a project session is no longer analysed with the
  thresholds left behind by the last ad-hoc run.
• seg_overlap no longer degrades unconditionally in live sessions: the mask
  sidecar is written when the rule requires it.
• Re-detecting the arena no longer erases the ROIs.
• A thread lock timeout no longer surfaces as "session cancelled" and removes
  the session from the project.
• Standalone live sessions appear in the Reports tab; the chosen perspective
  reaches the arena detector; real aquarium shape is selectable without editing
  YAML.

Pre-recorded workflow

• Single-video: "1 animal" reaches the worker, so an artefact no longer becomes
  a second tracked object.
• Aquarium auto-detection honours segmentation, real shape and perspective;
  segmentation no longer returns the whole frame as the arena.
• 15.7 ms per frame of dead waiting removed from the pre-recorded worker.
• Imported arenas reappear in the Zones tab and the ROI button works again.
• Single-video thresholds and properties no longer leak into an open project's
  reports.

Reporting correctness

• Zones stopped disappearing from the summary, and with it from the unified
  report.
• A basename repeated across days no longer overwrites the summary and loses
  half the animals.
• The sharp-turn threshold now reaches the number it configures.
• The animal bounding box no longer blows up when the fish leaves the frame.
• The Parquet coordinate space is documented.

Interface and infrastructure

• A destroyed panel no longer raises TclError on project rebind; event-bus
  subscriptions no longer outlive the widget that made them.
• Input fields that froze, vanished, or stored a different value than shown.
• Coverage locked to a ratchet, hollow tests removed, the _extendedN test
  files consolidated.
• A cross-flow regression net so the pre-recorded pipeline keeps computing the
  numbers it was signed off on.

Earlier in this line

• v6.0.0 — English as the default interface language with a pt-BR locale and
  a CI scanner against untranslated strings; closed-loop logger now records the
  frame rate measured from capture timestamps in fps, with the configured
  value kept separately in fps_configured (the camera can exceed the
  configured rate, and in the reported sessions it did); repository curated for
  archiving; .zenodo.json added and CITATION.cff completed.
• v5.0.0-rc1 — detector parameter error boundary, UI cleanups, worktree
  tooling.

See CHANGELOG.md for the full history.

Licensing

Original source code: MIT, copyright Universidade Estadual Paulista (UNESP).
The application as distributed is effectively AGPL-3.0-or-later, because it
packages and requires Ultralytics YOLO (AGPL-3.0).

The trained YOLOv11 weights attached to this release are Ultralytics derivatives
and are likewise effectively AGPL-3.0. Their training imagery derives from the
ZebraFish-Detection dataset (Roboflow Universe), CC BY 4.0, attribution
required — and that obligation travels with the weights, including to anyone
who redistributes the files downloaded from this release.

Companion hardware designs: CERN-OHL-S v2. See LICENSE and NOTICE.

Intellectual property

Registered with the Brazilian National Institute of Industrial Property (INPI),
process BR 51 2026 005215-7. Patrimonial rights held by UNESP; moral rights
by the authors. A copyright deposit under Brazilian Law 9.609/98, it does not
restrict the open-source licensing above. Public release authorised by the UNESP
technology transfer office (AUIN).

Requirements

Python ≥ 3.12, < 3.15 · Ultralytics YOLO ≥ 8.3.179 · Intel OpenVINO ~2026.0 ·
PyTorch ≥ 2.8 · NumPy ~2.2 · OpenCV ~4.13. Runs GPU-free on integrated graphics.
Validated on Windows 11. Full dependency pins in pyproject.toml /
poetry.lock.

Funding and ethics

FAPESP grant 2023/14200-3. Animal procedures approved by the UNESP Animal Use
Ethics Committee (CEUA), protocol 4806060624.