# River Annotation Tool

A desktop application for manually annotating river video clips as part of the [HydroScan](https://github.com/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](https://docs.astral.sh/uv/) (recommended) or pip

## Installation

```sh
# 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

```sh
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

```sh
# 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
```