First draft of readme (ty claude)
This commit is contained in:
112
README.md
112
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).
|
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.
|
||||||
Next steps include:
|
|
||||||
|
|
||||||
- [x] Create project from the Cookiecutter template.
|
## Features
|
||||||
- [ ] 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.
|
|
||||||
|
|
||||||
|
- 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
|
```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:
|
# Install dependencies (creates a virtual environment automatically with uv)
|
||||||
|
|
||||||
```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
|
|
||||||
uv sync
|
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
|
||||||
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user