Annotation GUI

Polygon-style annotation GUI.

Usage

Clone this repo and install the dependencies:

git clone https://github.com/cai4cai/tool-pose-annotation-gui.git
cd tool-pose-annotation-gui
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade pip
python3 -m pip install -e .[dev]

Run the polygon annotator:

python3 annotate_polygon.py --pairs-json ./images/pairs.json

Run the skeleton/pose annotator:

python3 annotate.py --image-glob "images/*.png" --visualise-only

Arguments

Only two CLI arguments are supported:

• --pairs-json (default: ./images/pairs.json)
• --mask-out (default: ./masks)

Example:

python3 annotate_polygon.py --pairs-json G:\NeuroPPEYE\stage2_paired\pairs.json --mask-out G:\NeuroPPEYE\stage2_paired\

--pairs-json root handling:

• Relative ref/target (or white/blue) paths are resolved from the parent folder of pairs.json.

--mask-out handling:

• If set to a parent folder (for example ...\stage2_paired\), a masks subfolder is automatically used/created.
• If set directly to a masks folder (for example ...\stage2_paired\masks), that folder is used.

pairs.json format

The loader supports either schema:

{"ref": "path/to/white.png", "target": "path/to/blue.png"}

or

{"white": "path/to/white.png", "blue": "path/to/blue.png"}

Optional metadata fields used by the GUI:

• motion_blur (editable checkbox, persisted to pairs.json)
• Biopsy (read-only checkbox)
• kinevo (relative/absolute folder path, opened by button)

Example item:

{
  "white": "case035/timepoint003/white.png",
  "blue": "case035/timepoint003/blue.png",
  "kinevo": "case035/Kinevo",
  "Biopsy": false,
  "motion_blur": false
}

GUI features

• Annotate on TAR and REF panels.
• If annotating on REF, polygon preview is shown on REF.
• Enter finalizes polygon and updates overlay on both REF and TAR.
• Frame jump: input a 1-based frame ID (for example 11) and click Go.
• Open corresponding Kinevo folder from current pair.
• Motion blur checkbox (editable, writes to pairs.json).
• Biopsy checkbox (read-only, from pairs.json).

Output

This annotator exports both:

• mask.png (binary mask)
• mask.json (polygon vertex coordinates used to create the mask)

The JSON format is:

{
  "polygons": [
    {"vertices": [[x, y], [x, y], [x, y]]}
  ]
}