labelroi

A Qt-based application for drawing and labeling polygon/polyline ROIs (Regions of Interest) on images and videos.

Features

• Image and Video Support: Load images (PNG, JPG, JPEG, BMP, TIFF) or MP4 videos (displays first frame)
• ROI Drawing: Draw polygon ROIs by clicking vertices, or polylines for open shapes
• ROI Naming: Double-click on any ROI to add or edit its name
• Smooth Navigation: Pan and zoom with mouse/trackpad gestures
• ROI Management: View ROI properties, delete individual ROIs, or clear all
• YAML Export/Import: Save ROIs to YAML files for later use or sharing
• Geometry Analysis: Automatic calculation of area, perimeter, and vertex count using Shapely

Quick Start

Run without installation (using uv)

The easiest way to use labelroi is with uv's tool run feature - no installation needed!

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run labelroi directly (one-time use)
uvx labelroi

# Or with a specific image/video
uvx labelroi path/to/image.png

This will automatically download and run labelroi with all its dependencies in an isolated environment.

Install as a tool (using uv)

For frequent use, you can install labelroi as a persistent tool:

# Install labelroi as a tool (adds to PATH)
uv tool install labelroi

# Now you can run it directly
labelroi

# Update to the latest version
uv tool upgrade labelroi

# Or install a specific version
uv tool install labelroi@0.1.0

This installs labelroi in an isolated environment and makes it permanently available in your PATH.

Updating

Update from PyPI (stable releases)

# If installed as a uv tool
uv tool upgrade labelroi

# If installed with pip
pip install --upgrade labelroi

# If installed with uv pip
uv pip install --upgrade labelroi

Update from GitHub main branch (latest development)

# Install/update directly from GitHub main branch
uv tool install --force --from git+https://github.com/talmolab/labelroi.git labelroi

# Or with pip
pip install --upgrade git+https://github.com/talmolab/labelroi.git

# Or run directly without installation
uvx --from git+https://github.com/talmolab/labelroi.git labelroi

Installation

Install from PyPI

# Using pip
pip install labelroi

# Or using uv
uv pip install labelroi

Install from Source

1. Clone the repository:

git clone https://github.com/talmolab/labelroi.git
cd labelroi

2. Install the package using uv:

uv pip install -e .

This will install labelroi and all its dependencies in editable mode.

Usage

Command Line Interface

Launch the application with:

labelroi

Or open with a specific image/video:

labelroi path/to/image.png
labelroi path/to/video.mp4

Drawing ROIs

1. Click "Start Drawing ROI" button
2. Left-click to add vertices to your polygon
3. Either:
   • Click on the first vertex (green dot) to close the polygon
   • Right-click to finish as a polyline (open shape)
4. Repeat to draw multiple ROIs (each gets a unique color)

ROI Naming

• Double-click on any ROI to add or edit its name
• Names appear as white labels on the ROI
• Clear the name to remove the label

Navigation Controls

Mouse/Trackpad:

• Scroll wheel: Zoom in/out
• Pinch gesture: Zoom in/out
• Middle-click + drag: Pan around
• Ctrl + Left-click + drag: Pan around
• Alt + Double-click: Reset zoom

Keyboard:

• Arrow keys or WASD: Pan
• +/=: Zoom in
• -: Zoom out
• 0 or Home: Reset zoom
• F1 or H: Show help

Saving and Loading ROIs

ROIs are automatically saved with the same name as your image/video file with a .rois.yml suffix:

• Image: my_image.png → ROIs: my_image.rois.yml
• Video: my_video.mp4 → ROIs: my_video.rois.yml

Click "Save ROIs to YAML" to save your ROIs. They will automatically load when you open the same image/video again.

YAML Format

The ROIs are saved in a human-readable YAML format:

image_file: /path/to/image.png
roi_count: 2
rois:
  - id: 1
    name: "Region A"
    type: polygon
    coordinates:
      - [100.5, 200.3]
      - [150.2, 250.7]
      - [100.8, 300.1]
    color: "#1f77b4"
    properties:
      vertex_count: 3
      perimeter: 172.5
      area: 1250.3
  - id: 2
    name: "Line B"
    type: polyline
    coordinates:
      - [200.0, 100.0]
      - [300.0, 150.0]
    color: "#ff7f0e"
    properties:
      vertex_count: 2
      perimeter: 111.8

Development

Running from Source

# Clone and enter directory
git clone https://github.com/talmolab/labelroi.git
cd labelroi

# Install in development mode
uv pip install -e .

# Run the application
python src/labelroi/labelroi.py

Dependencies

• numpy: Array operations
• matplotlib: Visualization and plotting
• shapely: Geometry operations
• qtpy: Qt compatibility layer
• PyQt5: Qt backend (can also use PyQt6, PySide2, or PySide6)
• sleap-io: Video file loading
• PyYAML: YAML file I/O

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Issues

If you encounter any problems, please file an issue at https://github.com/talmolab/labelroi/issues