First draft of readme (ty claude)

README.md

@@ -1,37 +1,97 @@
-# river-annotation-tool
+# River Annotation Tool
 
-This project is made using [this template](https://github.com/SwissDataScienceCenter/innovation-cookiecutter).
-Next steps include:
+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.
 
- - [x] Create project from the Cookiecutter template.
- - [ ] Create a virtual environment to work in an isolated Python installation.
- - [ ] Install [pre-commit](https://pre-commit.com/) hooks.
- - [ ] Keep either [`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) or [`.github/`](https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python), according to your Git hosting platform.
- - [ ] Update `authors` and `description`, in `pyproject.toml`.
- - [ ] Add development and installation dependencies in `pyproject.toml`, with permissive version constraints.
- - [ ] Add a `LICENSE` file, if applicable. This is *highly recommended* if the project is open source.
- - [ ] Add a [`CITATION.cff`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files), to ease citation of your work.
- - [ ] Replace this `README.md` with a proper one. Among others, it must explain the overall context, the installation instructions, a quick start guide, and a repository structure description.
+## 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
 
-## Getting started
+## Requirements
 
-In order to use [pre-commit](https://pre-commit.com/) hooks, they need to be registered:
+- Python 3.12
+- [uv](https://docs.astral.sh/uv/) (recommended) or pip
+
+## Installation
 
 ```sh
-pre-commit install
-```
+# Clone the repository
+git clone <repo-url>
+cd river-annotation-tool
 
-It is a good practice to manually invoke hooks after installation, just in case:
-
-```sh
-pre-commit run --all-files
-```
-
-During development, install pinned dependencies in your virtual environment, including the module itself in [editable mode](https://setuptools.pypa.io/en/latest/userguide/development_mode.html), using:
-
-```sh
+# 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 .
 ```
 
-New dependencies can be added using [`uv add`](https://docs.astral.sh/uv/concepts/projects/dependencies/) (or `uv add --dev` for development dependencies), or by manually configuring `pyproject.toml` and using [`uv lock && uv sync`](https://docs.astral.sh/uv/concepts/projects/sync/).
+## 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
+```