med-img-reg-utils 0.1.0

Medical image import, segmentation, and deformable registration utilities with UMI storage.

med-img-reg-utils

Medical image import, tissue segmentation, bone/joint-aware multimodal registration, and registered-volume generation for Python.

This repository provides a runnable research/engineering prototype for:

• importing NIfTI (.nii, .nii.gz), DICOM, and STL images into .umi (Unified Medical Image) files;
• storing all UMI volumes as NumPy 3D arrays in x, y, z = LPS order with isotropic voxel size metadata;
• segmenting baseline bone and soft-tissue masks for CT/CBCT/STL, with machine-learning model segmentation required for MRI-T1 bone masks;
• treating Image A as the fixed reference and resampling the complete moving Image B volume into the Image A LPS grid;
• using LPS-constrained bone/joint rigid initialization followed by GPU ConvexAdam MIND-SSC deformable soft-tissue refinement;
• saving the registered Image B as .umi and, optionally, its compressed bidirectional intermediate field as .umf;
• using the tool from both CLI and Qt GUI entry points.

Clinical note: the registration path uses published ConvexAdam/MIND-SSC and TotalSegmentator components, but this integrated application is still a research engineering tool. Clinical use requires anatomy- and task-specific validation.

Install

Create or reuse a virtual environment, then install the package.

Windows PowerShell:

py -3.13 -m venv venv
.\venv\Scripts\python.exe -m pip install -e ".[gui,dev]"

Linux/macOS:

python3 -m venv venv
./venv/bin/python -m pip install -e ".[gui,dev]"

On Windows/Linux x86_64, the base install automatically installs cupy-cuda12x[ctk], including the CUDA toolkit headers needed by CuPy kernel compilation. Unsupported platforms skip that CUDA wheel. TotalSegmentator uses its own model runtime for CT/MR segmentation; CuPy can detect a GPU even when PyTorch is still CPU-only. Check this with:

miru accelerators

Windows PowerShell:

.\venv\Scripts\python.exe -m pip install -e ".[gpu]"

Linux/macOS:

./venv/bin/python -m pip install -e ".[gpu]"

MRI-T1 bone segmentation is intentionally model-only. The default CT/MR segmentation backend is TotalSegmentator fast multilabel mode. The GUI checks and pre-caches the required TotalSegmentator CT/MR weights during startup; if the cache is already present, startup skips the download step.

pip install TotalSegmentator
miru models init --backend totalsegmentator
miru models status --backend totalsegmentator
miru register fixed.umi moving.umi moving_registered.umi --segmentation-backend auto

CLI

miru accelerators
miru models status --backend totalsegmentator
miru import-image patient_ct.nii.gz patient_ct.umi --type CT --voxel-size 1.0
miru import-image femur.stl femur.umi --type STL --voxel-size 0.5
miru import-image meter_scale_femur.stl femur.umi --type STL --stl-unit m
miru register fixed.umi moving.umi moving_registered.umi --field-output field.umf \
  --control-spacing 8 --device auto --soft-tissue-backend convex-adam-mind
miru self-test fixed.umi --max-rotation 20 --seed 42
miru self-test scan.nii.gz --type CT --voxel-size 1.0 --max-rotation 20
miru field-info field.umf

GUI

miru gui

The GUI can import images, load fixed Image A and moving Image B, run cancellable registration jobs, save Registered Image B, run an independent single-image self-registration test, and review both bone 3D overlays and orthogonal fixed/registered/fusion slices. The Help button explains each stage, parameter, and test route in the application.

Interface preview

The screenshots below use an anonymized real lower-leg CT/MRI-T1 case with reference annotations. No patient identifiers are shown.

1. Import images

Load existing UMI files or import NIfTI, DICOM, and STL sources from the compact three-stage workbench.

2. Inspect real CT and MRI-T1 bone surfaces

Image A and Image B are reconstructed independently so the user can inspect the bone surfaces before starting registration and adjust compute, segmentation, and advanced registration settings.

3. Review the registration result

The review stage provides a bone 3D tab and a registered-volume tab. The latter shows fixed Image A, Registered Image B, and blend/checkerboard fusion views in axial, coronal, and sagittal planes. Registered Image B is the primary output; the UMF field remains available as an optional intermediate artifact.

4. Compare Registered Image B in the fixed Image A grid

The software resamples the complete moving MRI-T1 volume into the fixed CT grid. This real-case review is positioned at the annotated tumor region and shows all three orthogonal planes with blend fusion.

Documentation

• API manual
• Algorithm manual
• File formats
• User guide