Skip to content

README.md

Latest commit

 

History

History
101 lines (77 loc) · 4.55 KB

README.md

File metadata and controls

101 lines (77 loc) · 4.55 KB
Raw

monalisa-python

Python port of Monalisa, the MattechLab toolbox for non-Cartesian and Cartesian MRI reconstruction, developed within the HES-SO Open Research Data programme (2026).

The port is faithful first: every upstream MATLAB function bmFoo of src/ becomes monalisa/<same folder>/bmFoo.py with the same name, the same argument order, the same array shapes (column-major) and the same precision (single → float32/complex64). Each ported function is validated against golden recordings of the MATLAB implementation; see docs/porting_method.md and CONVENTIONS.md.

What works

  • Gridded reconstruction bmMathilda (1D/2D/3D, with or without coil combination, cropping), the numba port of the gridding MEX kernels and the deapodization bmK.
  • Sparse gridding operators bmTraj2SparseMat (Gn, Gu, Gut), bmSparseMat, forward/adjoint non-Cartesian Fourier operators bmShanna / bmNakatsha, bmNasha.
  • Trajectories and volume elements: 3D phyllotaxis radial, Voronoi full/center-out radial 2D/3D, Cartesian, Voronoi box, random partial Cartesian.
  • Raw data: Siemens twix .dat (via twixtools) and ISMRMRD .mrd readers with automatic steady-state detection.
  • Coil sensitivity estimation from body + surface coil scans (automatic mask).
  • Binning and mitosius (data split into bins, MATLAB-compatible v7.3 files in both directions).
  • Iterative reconstructions: Sensa, Steva, Sleva; chain reconstructions TevaMorphosia, TevaDuoMorphosia and SensitivaMorphosia, with or without deformation matrices.
  • Demons registration for motion-compensated reconstructions (bmImDeformFieldChain_imRegDemons23, bmImDeformFieldSheet_imRegDemons23): MATLAB's imregdemons is replaced by SimpleITK's demons, so no MATLAB licence is needed; see docs/validation_registration.md.
  • Tutorial 1 end to end: examples/tutorial_1/tutorial_1.ipynb (notebook with figures) or tutorial_1.py (script).

Interactive steps of the MATLAB version (dialogs, ROI drawing) are parameters in Python; the MATLAB image viewers are not ported. Live status: PORTING_STATUS.md.

Install

git clone https://github.com/MattechLab/monalisa-python.git
cd monalisa-python
pip install -e ".[io,reg]"            # numpy, scipy, numba + raw-data readers + SimpleITK (registration)
pip install -e ".[io,reg,notebook]"   # + JupyterLab and matplotlib, for the tutorial notebook
pip install -e ".[dev,io]"            # + pytest, ruff (development)

The package installs as monalisa-python and is imported as monalisa.

Reading MATLAB .mat files

import scipy.io as sio
d = sio.loadmat("data.mat")        # MATLAB -v7 and older (the default of MATLAB save)

from monalisa.readWrite._mat73 import loadmat73
r = loadmat73("reconstructions.mat")   # -v7.3 (HDF5): large files, and the files written here

loadmat returns MATLAB logical arrays as uint8: convert masks with .astype(bool) before indexing with them.

Example: gridded reconstruction of a 2D radial acquisition

import scipy.io as sio
import monalisa as ml

d = sio.loadmat("monalisa/demo/data_demo/data_2_static_radial_simulated_from_cartesian/data.mat")
ve = ml.bmVolumeElement(d["t"], "voronoi_full_radial2")
C = ml.bmImResize(d["C"], [32, 32], d["frSize"])
x0 = ml.bmMathilda(d["y"], d["t"], ve, C, d["N_u"], d["frSize"], d["dK_u"])

Tutorial 1 (3D radial brain scan, Siemens raw data):

python demo/data_demo/data_8_tutorial_1/download_data.py   # raw data, about 7.9 GB (once)
jupyter lab examples/tutorial_1/tutorial_1.ipynb           # or:
python examples/tutorial_1/tutorial_1.py --data demo/data_demo/data_8_tutorial_1 --out results

Tests

pytest                       # unit tests + replay of all MATLAB recordings found in fixtures/matlab

MATLAB recordings are produced with tools/matlab_capture (requires MATLAB and the upstream repository at the commit in monalisa.UPSTREAM_COMMIT):

matlab -batch "addpath('tools/matlab_capture'); run_capture('static2d', fullfile(pwd,'fixtures','matlab'), '/path/to/monalisa')"

Scenarios: static2d, volume_elements, tutorial_coilsense, ismrmrd, tutorial_recon (see tools/matlab_capture/scenarios). The end-to-end comparison of tutorial 1 is opt-in: MONALISA_E2E_DATA=/path/to/data_8_tutorial_1 pytest tests/e2e -s.

License

Apache License 2.0, see LICENSE.