A desktop application for manually annotating river video clips as part of the HydroScan project. It lets annotators draw pixel-level masks over river regions of interest and answer structured survey questions about flow conditions, lighting, and scene quality.

Features

Load river video clips from ZIP archives (containing MP4s)
Draw and erase masks with an adjustable brush on video frames
Cycle through all frames with auto-playback at native FPS
Answer structured questions across three categories: River, Scene, and Weather
Resume saved annotation sessions; exports masks, metadata, and overlay GIFs

Requirements

Python 3.12
uv (recommended) or pip

Installation

# Clone the repository
git clone <repo-url>
cd river-annotation-tool

# Install dependencies (creates a virtual environment automatically with uv)
uv sync

# Or with pip
python -m venv .venv
.venv\Scripts\activate       # Windows
# source .venv/bin/activate  # macOS/Linux
pip install -e .

Usage

python -m river_annotation_tool.annotation_script \
    --data <path/to/zip/files> \
    --out  <path/to/output/dir> \
    [--clip <clip_name>]

Argument	Default	Description
`--data`	`../torrent-flow/data/examples_for_annotations/`	Directory containing ZIP files
`--out`	`data/annotation_results/`	Output directory for saved annotations
`--clip`	(first clip)	Specific clip to open (e.g. `left_20230501`)

Controls

Action	How
Draw mask	Click and drag on the canvas
Erase mask	Toggle Eraser button, then drag
Undo last stroke	Undo button
Play/pause frames	Play / Pause button
Save annotation	Save button
Change brush size	Slider in the toolbar

Output

Each clip is saved to <output_dir>/<clip_stem>/:

mask.png                   # Binary mask at full resolution
metadata.json              # Survey answers
frame.png                  # Key frame
mask_vis.png               # Mask visualisation
overlay.png                # Frame + mask overlay
video_original_hires.gif
video_original_lowres.gif
video_overlay_hires.gif
video_overlay_lowres.gif

Repository Structure

src/river_annotation_tool/
    annotation_script.py   # Main GUI application
    __init__.py            # Package version
pyproject.toml             # Project metadata and dependencies
requirements.txt           # Pinned dependencies (generated)

Development

# Install pre-commit hooks
pre-commit install
pre-commit run --all-files   # Run hooks manually once

# Add a dependency
uv add <package>
uv add --dev <package>       # Development-only