Metadata-Version: 2.1
Name: medics-ext-volume-labeler
Version: 202608272320
Summary: Volume labeling extension for MedICS - 3D volumetric data annotation and analysis
Author-email: MedICS <medics.support@gmail.com>
License: MIT
Project-URL: Homepage, https://Medical-Image-Computing-Suite.github.io
Project-URL: Documentation, https://github.com/Medical-Image-Computing-Suite/Community/wiki
Project-URL: Issues, https://github.com/Medical-Image-Computing-Suite/Community/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Healthcare Industry
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: medics
Requires-Dist: vtk>=9.0.0
Requires-Dist: Pillow>=9.0.0
Requires-Dist: natsort>=8.0.0
Requires-Dist: imagecodecs>=2022.5.0
Provides-Extra: build
Requires-Dist: pyinstaller>=6.0.0; extra == "build"
Requires-Dist: pyinstaller-hooks-contrib>=2024.0; extra == "build"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"

# 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:

```text
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)

```bash
pip install medics-ext-volume-labeler
```

### Requirements

- Python ≥ 3.11

---

## Credits

Developed by the MedICS Team.
