napari-padbound

A napari plugin for controlling image annotation workflows with MIDI controllers via padbound.

Use physical pads, knobs, faders, and buttons to navigate slices, select labels, adjust brush size, zoom, undo/redo, and more — with real-time LED feedback showing your current label colors on the controller.

Features

• Auto-detection — Automatically finds and connects to any padbound-supported MIDI controller
• Smart control mapping — Automatically assigns available hardware controls to napari functions based on controller capabilities
• Slice navigation — Coarse and fine navigation through 3D+ data volumes via faders or knobs
• Slice stepping — Increment/decrement slices one at a time via navigation buttons
• Zoom control — Logarithmic zoom mapping (0.01x–10x) via knobs or faders
• Brush size control — Logarithmic brush size adjustment (1–100px) for label painting
• Label selection — Select labels by pressing pads; pad 1 is the eraser, remaining pads map to labels 1, 2, 3, ...
• LED color feedback — Pads display actual label colors from the napari colormap, with the selected label pulsing (on RGB-capable controllers)
• Dimension rolling — Cycle through dimension views (XY, YZ, XZ) via navigation buttons
• Undo/redo — Transport buttons for edit history on the active Labels layer
• Graceful degradation — Three feedback strategies (RGB color, binary toggle, none) adapt automatically to controller capabilities

Supported Controllers

Any controller with a padbound plugin works automatically. Currently supported:

How Control Mapping Works

The plugin automatically discovers available controls and assigns them by priority:

Continuous controls (assigned in order: faders first, then knobs, then encoders):

1. First control → Coarse slice (full range of the data volume)
2. Second control → Fine slice (±64 slices around the coarse position)
3. Third control → Brush size (logarithmic, 1–100px)
4. Fourth control → Zoom (logarithmic, 0.01x–10x)

Pads → Label selection (pad 1 = eraser, pad 2+ = labels)

Navigation buttons → Up/Down = slice step, Left/Right = dimension roll

Transport buttons → Stop = undo, Play = redo

The widget displays the detected controller and its mapped controls so you can see what each physical control does.

Installation

pip install napari-padbound

For development:

git clone https://github.com/uermel/napari-padbound.git
cd napari-padbound
pip install -e ".[dev,testing]"

Usage

1. Connect a supported MIDI controller via USB
2. Open napari
3. Go to Plugins > padbound to open the widget
4. Load a 3D image and create a Labels layer
5. Use your controller to navigate slices, select labels, and annotate

The widget shows the connected controller name and the mapping of physical controls to napari functions. If no controller is detected, the widget will indicate this.

Development

# Linting
ruff check src/
ruff format src/
black src/

# Run tests
pytest

Contributing

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

License

Distributed under the terms of the BSD-3 license, napari-padbound is free and open source software.

Issues

If you encounter any problems, please file an issue along with a detailed description.