SpatioTemporal Labeler is a cross-platform desktop editor for 3D and 3D+t medical image segmentation, including 4D flow MRI workflows. It combines linked spatial and temporal views with real-time 3D label rendering and metadata-preserving NRRD/NIfTI I/O.
- Linked X-Y, X-Z, Y-Z, and selectable X-T/Y-T/Z-T views
- Automatic initial display of the frame with the strongest aggregate finite signal
- Hover status with voxel indices, RAS coordinates, image intensity, and label value
- Coalesced all-label 3D updates during time navigation
- Multiple image sequences, label sequences, and integer labels
- Unified image/label import classification, drag-and-drop, and resizable selectable-plane previews for other loaded images
- Physical round or square brush and eraser footprints
- Adjacent-frame snap brush with cyclic temporal neighbors, configurable local image-similarity matching, and optional all-frame scope
- Immediate 2D/3D scissors lasso for label erase or replacement, including all-time-frame edits
- Closed-contour raster drawing with interior fill
- Right-drag temporary erase, Shift-hover linked positioning, Shift-drag panning, and middle-drag window level/width with per-image persistence and live values in other-image previews
- Optional all-time-frame spatial editing as one undoable operation
- Applied threshold mask entry with percentage sliders, automatic methods, live candidate preview, replacement, checkbox/delete control, and bypass
- Diverse per-label colors with double-click color editing, row-menu rename/opacity controls, and a global label opacity control
- Live window level/width sliders in a separate display panel
- 2D/3D seed region growing that stops at other labels
- Per-label morphology with physical
mmradii andmm³component volumes - Physical signed-distance interpolation between user-selected label keyframes
- Automatic all-frame replication or selected-frame placement when mapping 3D labels to a 4D image
- Independent closed, smoothed, decimated surface rendering for each label
- Persistent 3D style, lighting, smoothing, and detail controls in Settings
- Metadata-preserving read/write for 3D/4D NRRD and NIfTI files
- English and Simplified Chinese interface
Download the package for your platform from the latest release. Portable packages include Python, Qt, VTK, and all runtime dependencies.
| Platform | Release asset | Run |
|---|---|---|
| Windows 10/11 x64 | SpatioTemporalLabeler-<version>-windows-x64.zip |
Extract and open SpatioTemporalLabeler/SpatioTemporalLabeler.exe |
| Linux x86_64 | SpatioTemporalLabeler-<version>-linux-x86_64.tar.gz |
Extract and run SpatioTemporalLabeler/SpatioTemporalLabeler |
Each package also contains per-user install and uninstall scripts. No administrator access is required.
Every release includes a pure Python wheel and source distribution. Install the current release directly from GitHub:
python -m pip install "https://github.com/AssociatedPrimeIdeal/SpatioTemporalLabeler/releases/download/v0.3.1/spatiotemporal_labeler-0.3.1-py3-none-any.whl"Alternatively, download the wheel from the release and install it locally:
python -m pip install spatiotemporal_labeler-0.3.1-py3-none-any.whlLaunch the installed application with spatiotemporal-labeler. Python 3.9 or newer is required. Runtime dependencies are installed automatically by pip.
The repository includes an 18-frame PCMRA image and matching label sequence in examples/sample-data.
spatiotemporal-labeler examples/sample-dataWhen a directory is provided, every direct .nrrd, .nii, and .nii.gz file is loaded. Files whose names contain seg, mask, or label are opened as label sequences; the remaining files are opened as image sequences.
When present, pcmra.seq.nrrd is selected as the initial display image and seg.seq.nrrd as the initial label sequence. A 4D image initially opens on the earliest frame with the largest whole-frame sum of absolute finite voxel intensities; NaN and infinite values are ignored.
You can also launch without arguments and load or drop NRRD/NIfTI files:
spatiotemporal-labeler| Input | Action |
|---|---|
| Left drag | Use the selected brush, eraser, scissors lasso, or contour tool |
| Alt + left drag in 3D | Rotate the 3D camera |
| Right drag | Temporarily erase without changing the selected tool |
| Hold Shift and move | Move the linked spatial cursor without editing |
| Shift + left drag | Pan a 2D view |
| Middle drag | Adjust window width horizontally and window level vertically in the dragged view |
| Double-click an other-image preview | Make that image sequence active |
| Double-click a label row | Change that label's color |
| Ctrl + wheel | Zoom a 2D view |
| Shift + wheel | Change brush or eraser diameter |
| Wheel in a spatial view | Change its orthogonal slice |
| Drag a locator-line arrow | Move that X, Y, or Z cursor coordinate and update linked slices |
| Double-click | Confirm a pending contour, otherwise fill/restore the entire 2x2 view panel |
B, N, E, S, L, G |
Brush, adjacent-frame snap brush, eraser, scissors lasso, contour, or seed grow |
Hold I and move |
Pick labels continuously without changing the selected tool |
Hold H |
Temporarily hide all 2D label overlays |
R |
Reset 2D zoom and pan, or auto-window and reset the hovered other-image preview |
| Left / Right | Step through time frames |
Hold CapsLock |
Temporarily apply spatial edits to all frames |
Hold Q |
Bypass a checked applied threshold mask while drawing or erasing |
Ctrl+Z, Ctrl+Y |
Undo or redo |
Esc |
Cancel a pending contour or active lasso preview |
Enable All time frames to apply one spatial gesture in every frame. Ordinary tools repeat the same X/Y/Z coordinates; the adjacent-frame snap brush searches locally for the corresponding image position. Temporal-view edits always affect the exact time pixels drawn.
The snap brush compares a reference patch R with each candidate patch C using zero-mean normalized cross-correlation: sum((R - mean(R)) * (C - mean(C))) / sqrt(sum((R - mean(R))^2) * sum((C - mean(C))^2)). It ranks correlation with a small distance penalty, rejects candidates outside the pixel-radius maximum displacement, and skips target frames below the minimum similarity. It targets all temporal frames by default; its tool panel can switch to a configurable number of cyclic frames on each side and also controls patch radius in pixels, maximum displacement in pixels (default 5 px), and minimum accepted similarity. Time is cyclic, so the frames before the first and after the last wrap to the opposite end. When a checked applied threshold mask is active, both candidate centers and every written label voxel are restricted to that mask. After a stroke, voxels newly added by propagation are highlighted in yellow in the spatial and temporal views until the next edit, undo/redo, or active image/label-sequence change.
Image and label sequences are normalized internally to canonical RAS [X,Y,Z,T]; 3D sources use a singleton T axis. Saving reverses the source transform and preserves the original dimensionality and relevant NRRD/NIfTI metadata. When a spatially matching 3D label sequence is opened over a 4D image, it can be copied to every frame (the default) or placed in one selected frame; the mapped result becomes a new unsaved 4D label sequence. Other editing requires a matching voxel grid.
SpatioTemporal Labeler is distributed under the GNU General Public License v3.0.