Quick start#

This page shows how to install Larmor, simulate a small phantom and look at the result in the viewer. It takes a few minutes and needs no data download.

Install#

Larmor needs Python 3.14 or newer. The following command installs it together with the viewer:

pip install "larmor-dmri[viewer]"

If you do not have Python 3.14, uv can install it for you along with Larmor: uv tool install "larmor-dmri[viewer]". The Install page describes the other ways.

Simulate#

A phantom is a description of a piece of tissue from which Larmor simulates the diffusion MRI signal, so that the true answer is known for every voxel. Larmor ships with a phantom called crossing. It has two fibre bundles that cross at 90 degrees, one along x and one along y, each in its own tissue with different parameters. The grid has 40 x 40 x 40 voxels of 1 mm. The following command simulates a scan of it and writes the result into a new folder:

lar simulate crossing crossing-sim --snr 30 --seed 1

--snr 30 adds Rician noise at a level that gives a signal-to-noise ratio of 30 in the b = 0 signal of a voxel full of white matter, and --seed 1 fixes the random numbers so that every run gives the same images. The simulation takes a few seconds.

The folder crossing-sim then holds the diffusion-weighted images in dwi.nii.gz, with their gradients in dwi.bval and dwi.bvec. It also holds the ground truth: the fraction of each voxel that each tissue and bundle fills, the masks, and the true fibre directions in peaks.nii.gz. The bundles are saved as .tck files, and the phantom file is saved so that lar simulate can run it again. The simulation guide describes each file.

View#

lar bv --simulation crossing-sim

This opens the folder in BrainViewer, the viewer that comes with Larmor. It shows the diffusion images as a volume and the masks as coloured overlays on top of them. There is one mask for each tissue, covering the voxels that the tissue fills by at least half. The mask mask_bundles.nii.gz covers both bundles together, including the crossing, where neither tissue alone fills half of a voxel. The viewer also draws the bundles’ streamlines and the true fibre directions as short lines, and it opens the phantom in the Phantom editor, where you can change its settings and run the simulation again.

Clicking in a 2D view moves the crosshair to that point, and the Volume index option in the panel on the right chooses which diffusion volume is shown. The viewer’s guide describes the window.

Next#

On this page