Arena Annotator — API Documentation

Interactive polygon & circle annotation for scientific arenas.

Back to GitHub

arena_annotator (Polygon)

╔═══════════════════════════════════════════════════════════════════════╗ ║ ░█▀█░█▀▄░█▀▀░█▀█░█▀█░░░█▀█░█▀█░█▀█░█▀█░▀█▀░█▀█░▀█▀░█▀█░█▀▄░░ ║ ║ ░█▀█░█▀▄░█▀▀░█░█░█▀█░░░█▀█░█░█░█░█░█░█░░█░░█▀█░░█░░█░█░█▀▄░░ ║ ║ ░▀░▀░▀░▀░▀▀▀░▀░▀░▀░▀░░░▀░▀░▀░▀░▀░▀░▀▀▀░░▀░░▀░▀░░▀░░▀▀▀░▀░▀░░ ║ ║ ║ ║ Interactive polygon annotation for scientific arenas v1.0 ║ ║ ── click. drag. export. science. ── ║ ╚═══════════════════════════════════════════════════════════════════════╝

Mark arena boundaries or ROIs in experimental images by clicking polygon vertices. Drag to reposition, right-click to delete. Exports to COCO JSON, YOLO-v8 polygon, and Pascal VOC XML.

Only needs: matplotlib, numpy, Pillow — all pip/conda friendly, no Qt, no OpenCV, no exotic deps. Runs on macOS, Linux, Windows.

pip install matplotlib numpy Pillow

License: MIT Author: Bart R.H. Geurten

arena_annotator.discover_images(directory=None, image_path=None, filelist=None)[source]

Locate image files from one of three input modes.

Exactly one of the three arguments should be set (enforced by CLI).

Parameters:

  • directory – Scan this folder for common image extensions.

  • image_path – Single image file path.

  • filelist – Text file with one image path per line (# = comment).

Returns:

Sorted list of resolved, absolute image paths.

Raises:

SystemExit – If the source is invalid or yields zero images.

arena_annotator.export_coco(annotations, labels, output_dir)[source]

Write all annotations as a single COCO-format JSON.

Produces annotations_coco.json containing images, annotations with polygon segmentation masks, bounding boxes, and vertex labels stored under the attributes key.

Returns:

Path to the written JSON file.

arena_annotator.export_yolo(annotations, output_dir)[source]

Write one YOLO-v8 polygon label file per annotated image.

Format: <class_id> x1 y1 x2 y2 ... xN yN with coordinates normalised to [0, 1] by image width/height. Class is always 0.

Returns:

List of written file paths.

arena_annotator.export_voc(annotations, labels, output_dir)[source]

Write one Pascal VOC XML file per annotated image.

Standard VOC <bndbox> is included for compatibility. An additional <polygon> element carries the per-vertex (x, y, label) triples for tools that support the extended format.

Returns:

List of written file paths.

class arena_annotator.PolygonAnnotator(images, n_vertices, labels, output_dir, formats)[source]

Bases: object

Interactive matplotlib GUI for placing polygon vertices on images.

Boots a figure window, wires up mouse/key events, and manages the full annotation lifecycle: click-to-place, drag-to-adjust, right-click-to-delete, sidecar persistence, and batch export.

The constructor blocks on plt.show() — control returns when the user closes the window or presses Q/Esc.

arena_annotator.parse_args()[source]

Build the argparse parser, validate inputs, resolve the output dir.

Returns:

(args, labels, formats, output_dir) — everything main() needs to boot the annotator.

arena_annotator.main()[source]

Parse CLI, discover images, print status, and launch the GUI.

circle_annotator (Circle)

╔═══════════════════════════════════════════════════════════════════════╗ ║ ░█▀▀░▀█▀░█▀▄░█▀▀░█░░░█▀▀░░░█▀█░█▀█░█▀█░█▀█░▀█▀░█▀█░▀█▀░█▀█░█▀▄░ ║ ║ ░█░░░░█░░█▀▄░█░░░█░░░█▀▀░░░█▀█░█░█░█░█░█░█░░█░░█▀█░░█░░█░█░█▀▄░ ║ ║ ░▀▀▀░▀▀▀░▀░▀░▀▀▀░▀▀▀░▀▀▀░░░▀░▀░▀░▀░▀░▀░▀▀▀░░▀░░▀░▀░░▀░░▀▀▀░▀░▀░ ║ ║ ║ ║ Interactive circle annotation for round scientific arenas v1.0 ║ ║ ── click. drag. export. science. ── ║ ╚═══════════════════════════════════════════════════════════════════════╝

Mark circular arena boundaries in experimental images by clicking a centre point and then a second point to set the radius. Drag centre to reposition, drag the rim handle to resize. Exports to COCO JSON, YOLO-v8, and Pascal VOC XML.

Only needs: matplotlib, numpy, Pillow — all pip/conda friendly, no Qt, no OpenCV, no exotic deps. Runs on macOS, Linux, Windows.

pip install matplotlib numpy Pillow

License: MIT Author: Bart R.H. Geurten

circle_annotator.discover_images(directory=None, image_path=None, filelist=None)[source]

Locate image files from one of three input modes.

Exactly one of the three arguments should be set (enforced by CLI).

Parameters:

  • directory – Scan this folder for common image extensions.

  • image_path – Single image file path.

  • filelist – Text file with one image path per line (# = comment).

Returns:

Sorted list of resolved, absolute image paths.

Raises:

SystemExit – If the source is invalid or yields zero images.

circle_annotator.export_coco(annotations, output_dir)[source]

Write all annotations as a single COCO-format JSON.

Produces annotations_coco.json containing images and annotations with polygon segmentation masks (circle approximated as N-gon), bounding boxes, and the native circle parameters (centre_x, centre_y, radius) stored under the attributes key.

Parameters:

  • annotations – Dict mapping image paths to annotation dicts, each containing centre, radius, image_width, and image_height keys.

  • output_dir – Directory to write the JSON file into.

Returns:

Path to the written JSON file.

circle_annotator.export_yolo(annotations, output_dir)[source]

Write one YOLO-v8 polygon label file per annotated image.

The circle is approximated as an N-gon. Format: <class_id> x1 y1 x2 y2 ... xN yN with coordinates normalised to [0, 1] by image width/height. Class is always 0.

Parameters:

  • annotations – Dict mapping image paths to annotation dicts.

  • output_dir – Directory to write label files into.

Returns:

List of written file paths.

circle_annotator.export_voc(annotations, output_dir)[source]

Write one Pascal VOC XML file per annotated image.

Standard VOC <bndbox> is included for compatibility. An additional <circle> element carries the native centre and radius, and a <polygon> element carries the N-gon approximation for tools that only support polygonal annotations.

Parameters:

  • annotations – Dict mapping image paths to annotation dicts.

  • output_dir – Directory to write XML files into.

Returns:

List of written file paths.

class circle_annotator.CircleAnnotator(images, output_dir, formats)[source]

Bases: object

Interactive matplotlib GUI for placing circles on images.

Interaction model:

  1. First left-click sets the circle centre.

  2. Second left-click sets the radius (distance from centre to the clicked point).

  3. After both are placed, drag the centre to reposition and drag the rim handle (shown at 3-o’clock on the circumference) to resize.

The constructor blocks on plt.show() — control returns when the user closes the window or presses Q/Esc.

Parameters:

  • images – List of absolute image file paths.

  • output_dir – Directory for sidecar JSON and exported annotations.

  • formats – List of export format strings (coco, yolo, voc).

circle_annotator.parse_args()[source]

Build the argparse parser, validate inputs, resolve the output dir.

Returns:

Tuple of (args, formats, output_dir) — everything main() needs to boot the annotator.

circle_annotator.main()[source]

Parse CLI, discover images, print status, and launch the GUI.

Indices and tables