From 97d2896bfd544c3c179d7b3d5ea3f2bdb3ccf0e6 Mon Sep 17 00:00:00 2001 From: asreva Date: Fri, 1 May 2026 10:28:48 +0200 Subject: [PATCH] First draft of readme (ty claude) --- README.md | 112 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 86 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e9f1c04..4af6ddd 100644 --- a/README.md +++ b/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 +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 \ + --out \ + [--clip ] +``` + +| 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 `//`: + +``` +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 +uv add --dev # Development-only +```