158 lines
6.2 KiB
Markdown
158 lines
6.2 KiB
Markdown
# River Annotation Tool
|
|
|
|
A desktop application for manually annotating river video clips as part of the [HydroScan](https://github.com/HydroScan) project. Annotators draw pixel-level water masks over river footage and answer structured survey questions about flow conditions, lighting, and scene quality.
|
|
|
|
## 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 with uv (creates the virtual environment automatically)
|
|
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/zips> --out <path/to/output>
|
|
```
|
|
|
|
### Arguments
|
|
|
|
| Argument | Default | Description |
|
|
|---|---|---|
|
|
| `--data` | *(hardcoded path)* | Directory containing ZIP archives of clips |
|
|
| `--out` | `data/annotation_results/` | Directory where annotations are written |
|
|
| `--clip` | *(first unannotated clip)* | Open a specific clip by stem name (e.g. `left_20230501`) |
|
|
| `--time` | — | Target time of day `HH:MM` — picks the clip closest to this time for each day |
|
|
| `--daily` | off | Annotate one clip per day (at `--time`, default noon); advances to the next day on **Next** |
|
|
| `--skip-existing-day` | off | With `--daily`, skip entire days that already have any annotated clip |
|
|
| `--extras` | off | Also save GIFs and extra PNGs (see Output section) |
|
|
|
|
### Typical workflows
|
|
|
|
```sh
|
|
# Annotate clips in chronological order (default)
|
|
python -m river_annotation_tool.annotation_script --data data/clips --out data/out
|
|
|
|
# One clip per day, always at the noon recording
|
|
python -m river_annotation_tool.annotation_script --data data/clips --out data/out --daily --time 12:00
|
|
|
|
# Resume a daily run, skip days already touched
|
|
python -m river_annotation_tool.annotation_script --data data/clips --out data/out \
|
|
--daily --time 12:00 --skip-existing-day
|
|
|
|
# Annotate a single specific clip
|
|
python -m river_annotation_tool.annotation_script --data data/clips --out data/out \
|
|
--clip left_20230615T120000
|
|
```
|
|
|
|
## Controls
|
|
|
|
The window shows the video on the left (auto-playing) and the survey panel on the right.
|
|
|
|
| Action | How |
|
|
|---|---|
|
|
| Draw water mask | Click and drag on the video |
|
|
| Erase mask | Toggle **Eraser** button, then drag |
|
|
| Undo last stroke | **Undo** |
|
|
| Clear entire mask | **Clear** |
|
|
| Adjust brush size | Slider next to the erase controls |
|
|
| Save and continue | **Next** — saves current clip and loads the next one |
|
|
| Skip without saving | **Skip** — discards changes and loads the next one |
|
|
| Save only | **Save** — writes to disk without advancing |
|
|
| Restore last save | **Reload Saved** — reverts mask and answers to what was last written |
|
|
|
|
## Output
|
|
|
|
Each annotated clip produces a folder `<output_dir>/<clip_stem>/` with:
|
|
|
|
```
|
|
mask.png # Binary water mask at full source resolution (always)
|
|
metadata.json # Survey answers as JSON (always)
|
|
frame.png # Middle frame of the clip (always)
|
|
overlay.png # That frame with the mask blended in green (always)
|
|
|
|
# Only with --extras:
|
|
mask_vis.png # Mask rendered as a greyscale PNG
|
|
video_original_hires.gif # All frames at display resolution
|
|
video_original_lowres.gif # All frames at 50% of display resolution
|
|
video_overlay_hires.gif # Overlay GIF at display resolution
|
|
video_overlay_lowres.gif # Overlay GIF at 50% of display resolution
|
|
```
|
|
|
|
### Survey answers (`metadata.json`)
|
|
|
|
```json
|
|
{
|
|
"flow": "Turbulent | Laminar | Uncertain",
|
|
"shadows": "Yes | No | Uncertain",
|
|
"artifacts": "Yes | No | Uncertain",
|
|
"lighting": "Day | Night | Uncertain",
|
|
"exposure": "Overexposed | Underexposed | Both | Normal | Uncertain",
|
|
"snowing": "Yes | No | Uncertain",
|
|
"snow_on_ground":"Yes | No | Uncertain"
|
|
}
|
|
```
|
|
|
|
## How it works
|
|
|
|
### Clip format
|
|
|
|
Each clip is a ZIP archive containing a `left.mp4` video. The filename encodes the recording timestamp (e.g. `left_20230615T120000.zip`), which is used for sorting and daily filtering.
|
|
|
|
### Frame loading
|
|
|
|
Up to 100 frames are extracted from the video and scaled so the longest side is 480 px. This display-resolution copy is what the annotator works on; the full-resolution dimensions are remembered separately so the saved mask is upscaled back to the original size on export.
|
|
|
|
### Mask drawing
|
|
|
|
The mask is a binary NumPy array matching the display frame size. Each brush stroke stamps a filled circle of the selected radius, setting pixels to 1 (draw) or 0 (erase). The history stack stores a copy of the mask before each stroke, enabling unlimited undo. On save the mask is resized to the original video resolution with nearest-neighbour interpolation and written as an 8-bit PNG (0 or 255).
|
|
|
|
### Clip selection
|
|
|
|
`ClipSelector` scans the data directory, builds a sorted DataFrame of clips ordered by timestamp, and filters out clips that already have a `mask.png`. In daily mode it groups the remaining clips by calendar day and picks the one whose recording time is closest to the target hour; on **Next**, it moves to the first clip of the following day.
|
|
|
|
### Resuming
|
|
|
|
When a clip is loaded that already has a saved `mask.png` and `metadata.json`, the mask is restored at display resolution and the survey answers are pre-filled. **Reload Saved** lets you revert to the last save at any point during the current session.
|
|
|
|
## Repository structure
|
|
|
|
```
|
|
src/river_annotation_tool/
|
|
annotation_script.py # Entry point — argument parsing and app launch
|
|
annotator.py # Main QMainWindow — orchestrates all components
|
|
clip_selector.py # Clip-picking logic (daily mode, time filtering)
|
|
mask_canvas.py # Drawing widget — brush, undo, erase, mouse events
|
|
video_loader.py # ZIP extraction and frame resizing
|
|
config.py # Config constants, question definitions, defaults
|
|
__init__.py # Package version
|
|
pyproject.toml # Project metadata and dependencies
|
|
```
|
|
|
|
## Development
|
|
|
|
```sh
|
|
# Install pre-commit hooks
|
|
pre-commit install
|
|
pre-commit run --all-files # Run manually once
|
|
|
|
# Add a dependency
|
|
uv add <package>
|
|
uv add --dev <package> # Development-only
|
|
```
|