govinda-lienart/aquamind

Purpose and Entry Points

AquaMind is a data/ML pipeline for aquarium-fish video tracking, identity re-identification, annotation management, and behavior analysis. Primary operational entry points are executable scripts under scripts/, with project setup and orchestration likely driven by Makefile, config.yaml, and environment.yml.

Video Acquisition and Frame Preparation

Video assets are synchronized, decoded, and converted into curated frame datasets before labeling or model work. scripts/sync_videos.py handles source-video synchronization; scripts/extract_frames.py extracts imagery; scripts/prepare_dataset.py assembles training-ready data. Specialized selectors target difficult tracker cases: scripts/extract_crossing_frames.py and scripts/extract_ghost_frames.py.

Annotation and Database Boundary

Annotations appear to be managed through Label Studio and persisted into a relational AquaMind database. scripts/download_labelstudio.py and scripts/upload_labelstudio.py move labeling data across the external Label Studio boundary, while scripts/store_annotations.py writes normalized results. Database access/schema assets are concentrated in scripts/db.py, fixtures/aquamind_schema.sql, aquamind_dump.sql, and views.sql.

Tracking and Identity Resolution

The core vision flow runs a tracker, records diagnostics, and repairs identity continuity across detections. scripts/tracker.py is the primary tracking stage; scripts/evaluate_tracker.py, scripts/tracker_diagnostics.py, and scripts/tracker_viz.py assess output. Re-identification features and contrastive models are handled by scripts/reid_features.py, scripts/contrastive_reid.py, and scripts/eval_contrastive.py; scripts/stitch_ids.py likely merges fragmented track identities.

Dataset Curation and Model Training

Training data is derived from annotated frames and curated crops. scripts/curate_crops.py prepares image crops, while scripts/prepare_dataset.py produces the dataset structure consumed by ML stages. DVC controls the versioned dataset boundary through dataset.dvc, .dvc/config, and dataset.yaml. A Kaggle-oriented fine-tuning workload is available at kaggle/accumulate_finetune_kaggle.py, triggered locally through scripts/trigger_kaggle.py.

Experiment, Artifact, and Model Lifecycle

MLflow is the apparent experiment/artifact system: scripts/log_artifact_mlflow.py publishes artifacts and scripts/model_registry.py manages model lookup or promotion. scripts/logger.py provides shared run logging. This separates reproducible model metadata from local datasets and tracker outputs.

Analysis and Downstream Outputs

Post-tracking outputs feed behavior-specific analyses rather than a web-serving layer. scripts/analyse_behaviour.py and scripts/analyse_chasing.py consume tracking/identity results; scripts/parse_tracker_log.py supports operational analysis. Documentation describes the staged pipeline in docs/pipeline-overview.md, docs/stage_1.md, docs/stage_2.md, and docs/stage_3.md.

Runtime and Infrastructure

The project is Python-based, with dependencies declared in requirements.txt and Conda environment support in environment.yml. Material external systems are DVC-backed dataset storage, a SQL database, Label Studio, MLflow, and Kaggle. CI runs through GitHub Actions in .github/workflows/ci.yml and .github/workflows/test.yml.