Volume Labeler

Volume Labeler is a MedICS extension for annotating 3D first volume (and related) volumes. You can paint labels on B-frames or the enface projection, constrain work to a retinal slab using boundary curves, inspect labels in 3D, and export maps for later use.

---

Opening the extension

1. Launch MedICS.
2. Open Volume Labeler from the Extensions menu (or your host’s extension list).
3. The tab opens immediately; panels fill in after a short moment.

---

Interface overview

┌──────────────┬─────────────────────────────────────────────────────────┐
│ Left panel   │ Toolbox (brush, thresholds, Propagation, Value, Note) │
│ Load / maps  ├──────────────────┬──────────────────┬───────────────────┤
│ / labels     │ B-frame A        │ B-frame B        │ Boundaries        │
│              │                  │                  │ Upper / Lower /   │
│              │                  │                  │ Frame             │
│              ├──────────────────┴──────────────────┴───────────────────┤
│              │ Enface projection                                       │
│              │ 3D Viewer (label volume)                                │
└──────────────┴─────────────────────────────────────────────────────────┘
 Status bar: volume shape, dtype, counts, second volume info, mouse / pixel values

Area	What it is
Left panel	Load volume/boundaries/labels; manage label maps and label classes
Toolbox	Painting tools, tool size/shape, propagation step, measurements, notes
B-frame A	Left cross-section: first volume underlay, optional second volume overlay, labels
B-frame B	Right cross-section: primary first volume volume and labels
Boundaries	Upper/lower slab layers, offsets, and current frame index
Enface	Top-down projection through the slab; paint here to label whole columns
3D Viewer	Discrete 3D rendering of the active label map
Status bar	Loaded volume info, mouse position, and short status messages

Typical width balance: B-frame A ≈ B-frame B ≈ enface/3D column.

---

Quick start

1. Click Load Data... and choose a volume (or drag a file onto the window).
2. Optionally load boundaries and/or a label map (or rely on auto-detected sidecars).
3. In the left panel, select a label map and a label class (color).
4. Choose Brush (or another tool) in the toolbox and paint on B-frame B, B-frame A, or the enface.
5. Step through frames with the frame spinbox or arrow keys.
6. Check Value (measurements) and the 3D Viewer.
7. Click Save... or Save to WS to store your maps.

---

Loading data

Volume

Load Data... opens a file dialog. Supported types include:

• .med, .tif / .tiff, .mat
• first volume-related: .first volume, .ffirst volume, .ifirst volume, .dcm, .img

You can also:

• Drag and drop files or folders onto the window
• Drop a workspace variable (when MedICS provides that mime type)

If a volume is already open, you are asked:

Choice	Effect
Replace	Clears current labels for that session and loads the new volume
Overlay	Keeps the current volume data and uses the new file overlay on existed volume data
Cancel	Does nothing

Settings... opens loader settings if you use custom MedICS volume/label loader modules.

Automatic companions

When a volume loads, the extension looks next to it for:

Sidecar	Purpose
<base>_lmp.tiff or <base>_lmp.med	Label map (newest preferred if both exist)
Boundary/segmentation files such as seg.mat, _seg.mat, segmentation.mat, .med variants	Layer curves for Upper/Lower
second volume siblings such as <base>.ssada, <base>.second volume, <base>_second volume.*, <base>_second volume.*	second volume overlay

Boundaries

Use Load Boundaries... (*.json, *.mat, *.med, *.dcm).

Then set:

• Upper / Lower layer names from the loaded curves
• + offsets (pixels) for each boundary

The slab between Upper and Lower drives enface projection and slab visualization on the B-frames. Changing layers or offsets refreshes the enface after a short delay.

Label maps

Load Label Map... accepts:

• *.tiff / *.tif, *.med, *.mat, *.png

MAT/MED files written by this extension store data under a top-level label tag. Older volumelabeler layouts are still recognized.

You can also drop label files or load labeled arrays from the workspace when prompted.

---

Label maps and classes

Maps

• Default map name: Default
• Add... — create another named map
• Select a map in the tree to paint/edit that volume
• Delete column — remove a map (at least one map must remain)

Each map is a full 3D label volume aligned with the first volume (frames × depth × A-scans) shape.

Label classes

The Label tree lists paint classes (name, color, edit):

• Click a row to set the active paint label
• Use the color button or Edit to change name/color/description

Painting writes that class index into the active map.

---

Painting tools

Configure tools in the top toolbox, then paint on B-frame A, B-frame B, or the enface.

Tool	Use
Brush	Paint the active label
ChangeLabel	Change existing labels under the cursor
T-Min	Label voxels darker than the clicked value (+ offset v +)
T-Max	Label voxels brighter than the clicked value (+ offset)
T-Range	Label voxels within a value window around the click

Shared options:

Control	Meaning
Tool size	Brush diameter (pixels)
Shape	disk, square, or rod
Angle	Orientation for rod (and related) shapes
Fill holes	Fill holes smaller than N pixels
Region filter	Remove connected regions smaller than N pixels
Propagation	Step size for ← / → frame shortcuts (see below)

On each viewer you can:

• Show/Hide label overlay
• Adjust transparency
• Tune contrast with the low/high spinboxes and colorbar

B-frame A colorbar controls the second volume overlay colormap when a second volume is present. B-frame B colorbar controls first volume display contrast.

Enface painting

The enface shows a projection of the first volume (and labels) through the current slab.

• Projection modes: Mean, Maximum, Minimun, Thickness
• Painting on the enface updates the 3D label volume along depth (synced in the background)
• The yellow/line indicator marks the current B-frame; drag it to change frame

---

Frame navigation

Control	Action
Frame spinbox (boundary bar)	Jump to a 1-based frame index
↑	Previous frame (−1)
↓	Next frame (+1)
←	Jump back by Propagation frames
→	Jump forward by Propagation frames

Arrow shortcuts apply when the Volume Labeler tab is focused, and are ignored while typing in text fields or spin boxes.

---

3D Viewer

The 3D view shows the active label map (not the raw first volume intensities).

Control	Options
Lighting	Headlight, Three Lights, Ambient, Studio (default)
Reset Camera	Restore a default view

Labels that touch the volume edge are rendered with a transparent pad so outer faces do not appear black. Enface-sized volumes are displayed with a square lateral aspect in 3D (matching the squared enface view).

---

Measurements and notes

• Value tab — per-label Volume (voxels) and Area (pixels) for the active map (with percentages)
• Note tab — free text stored with the label maps when you save

Measurements update as you edit labels (with light background processing).

---

Saving

Save...

Opens Save Label Map As with:

Format	Content
TIFF (.tiff / .tif)	All maps stacked along the frame axis, with colormap and description metadata
MAT (.mat)	Dict under tag label: maps, labels, notes
MED (.med)	Same label payload in MedICS HDF5 form

Default name is typically <volume_basename>_lmp.<ext>.

Save to WS

Prompts for a workspace variable name and stores the current maps in the MedICS workspace (when a workspace manager is available).

---

Status bar

When a volume is loaded you will see something like:

Vol 1/1  |  Shape: 128 x 640 x 512  |  dtype: float32  |  range: [0, 255]  |  second volume: …

Mouse position and pixel/index values update as you move over B-frames or the enface. Short messages appear for load/save and drag-and-drop hints.

---

Tips and troubleshooting

Topic	Tip
Nothing paints	Select a label class and enable a tool (Brush, etc.); ensure the label overlay is visible
Enface looks stretched	Non-square volumes are upsampled to a square for display; painting maps back to native size
Wrong slab / empty enface	Check Upper/Lower layers and offsets; load a valid boundary file
Black 3D faces	Edge labels should render correctly after recent padding fixes; try Reset Camera or Ambient lighting
Shortcuts ignored	Click inside the Volume Labeler tab (not a text field)
Second volume	Prefer Overlay to keep first volume and add flow/angiography on B-frame A

---

Installation

From PyPI (when published)

pip install medics-ext-volume-labeler

Requirements

• Python ≥ 3.11

---

Credits

Developed by the MedICS Team.