Metadata-Version: 2.1
Name: med-img-reg-utils
Version: 0.1.0
Summary: Medical image import, segmentation, and deformable registration utilities with UMI storage.
Author: med-img-reg-utils contributors
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: nibabel>=5.2
Requires-Dist: pydicom>=2.4
Requires-Dist: scikit-image>=0.22
Requires-Dist: SimpleITK>=2.3
Requires-Dist: convexAdam==0.2.0
Requires-Dist: trimesh>=4.0
Requires-Dist: tqdm>=4.66
Requires-Dist: click>=8.1
Requires-Dist: TotalSegmentator>=2.10
Requires-Dist: cupy-cuda12x[ctk]>=13.0; (platform_system == "Windows" or platform_system == "Linux") and (platform_machine == "AMD64" or platform_machine == "x86_64")
Requires-Dist: typing-extensions>=4.9
Provides-Extra: gui
Requires-Dist: PySide6>=6.7; extra == "gui"
Requires-Dist: pyqtgraph>=0.13; extra == "gui"
Requires-Dist: PyOpenGL>=3.1; extra == "gui"
Provides-Extra: gpu
Requires-Dist: torch>=2.2; extra == "gpu"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"

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

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

Linux/macOS:

```bash
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:

```bash
miru accelerators
```

Windows PowerShell:

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

Linux/macOS:

```bash
./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.

```bash
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

```bash
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

```bash
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.

![GUI import stage](https://raw.githubusercontent.com/GGN-2015/med-img-reg-utils/main/docs/images/gui-import.png)

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

![Real CT and MRI-T1 bone previews](https://raw.githubusercontent.com/GGN-2015/med-img-reg-utils/main/docs/images/gui-real-bone-previews.png)

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

![Real CT-to-MRI registration review](https://raw.githubusercontent.com/GGN-2015/med-img-reg-utils/main/docs/images/gui-real-registration-review.png)

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

![Real registered-volume slice review](https://raw.githubusercontent.com/GGN-2015/med-img-reg-utils/main/docs/images/gui-real-registered-volume-review.png)

## Documentation

- [API manual](docs/API.md)
- [Algorithm manual](docs/ALGORITHMS.md)
- [File formats](docs/FORMATS.md)
- [User guide](docs/USER_GUIDE.md)
