NIfTI Phantom Specification

The “NIfTI phantom specification” describes the storage of data suitable for MR imaging simulations. A phantom consists of one or more NIfTI files for per-voxel data and a single JSON file that defines the phantom and references the NIfTI files.

1. Storage

The naming of files is a convention: implementations can but are not required to reject non-conforming names. The supported convention is:

📂 subj42
├ 📄 subj42.nii.gz
├ 📄 subj42_dB0.nii.gz
├ 📄 subj42_B1+.nii.gz
├ ...
├ 📄 subj42-3T.json
└ 📄 subj42-7T.json

The phantom name is subj42, used as directory name and file prefix. It is available in two variants: subj42-3T.json and subj42-7T.json. Contents of the JSON file are described in Section 4.

Per-voxel data is stored in <name>_<property>.nii(.gz) files; the density map omits the property postfix. See Section 2 for properties and Section 3 for the NIfTI format requirements. The density property is required for every tissue loaded from NIfTI (as opposed to a constant value).

2. Phantom Definition

Units

The JSON file contains a "units" field that explicitly specifies the unit of each property. Currently, only the default units listed below are supported; automatic conversion may be added in the future.

System

The JSON file contains a "system" field that describes the physical system of the MRI experiment.

The gyro value implicitly defines the nucleus: 42.5764 MHz/T corresponds to ^1H. Tissue properties (particularly relaxation times and dB0) are specific to the system they were measured at. A phantom defined at 3T should not be used in a 7T simulation without adjusting tissue values accordingly.

Tissue Properties

The following properties are defined by the NIfTI phantom specification. If stored as per-voxel NIfTI data, the file postfix should match the key (e.g.: subj42_dB0.nii.gz).

3. NIfTI Data

Per-voxel tissue properties are stored in .nii files following the NIfTI v1.1 specification, optionally gzip-compressed (.nii.gz).

• Each file contains a single property for all tissues
• Data must be 4-dimensional (use singleton dimensions for non-3D data)
  • Dimensions 1-3: spatial (size 1 if unused)
  • Dimension 4: tissue index
• All NIfTI files must share the same resolution and orientation
• Spatial data should follow the RAS+ convention (index 0: R, 1: A, 2: S, growing towards positive) to ensure correct orientation for tools ignoring the affine matrix
• The affine matrix must transform data into RAS+ using mm as units (as per NIfTI spec)

4. JSON Phantom File

The phantom is defined in a .json file with the following structure:

{
  "file_type": "nifti_phantom_v1",
  "units": {
    "gyro": "MHz/T",
    "B0": "T",
    "T1": "s",
    "T2": "s",
    "T2'": "s",
    "ADC": "10^-3 mm^2/s",
    "dB0": "Hz",
    "B1+": "rel",
    "B1-": "rel"
  },
  "system": {
    "gyro": 42.5764,
    "B0": 3.0
  },
  "tissues": {
    "gm": {
      "density": "subj42.nii.gz[0]",
      "T1": 1.56,
      "T2": 0.083,
      "T2'": 0.32,
      "ADC": 0.83,
      "dB0": "subj42_dB0.nii.gz[0]",
      "B1+": [
        "subj42_B1+.nii.gz[0]",
        "subj42_B1+.nii.gz[1]",
        "subj42_B1+.nii.gz[2]",
        "subj42_B1+.nii.gz[3]",
        "subj42_B1+.nii.gz[4]",
        "subj42_B1+.nii.gz[5]",
        "subj42_B1+.nii.gz[6]",
        "subj42_B1+.nii.gz[7]"
      ]
    },
    "wm": {
      "density": "subj42.nii.gz[1]",
      "T1": 0.83,
      "dB0": "subj42_dB0.nii.gz[0]"
    },
    "fat": {
      "density": "subj42.nii.gz[4]",
      "dB0": {
        "file": "subj42_dB0.nii.gz[0]",
        "func": "x - 420"
      }
    }
  }
}

• file_type: must be "nifti_phantom_v1".
• units: units for all properties (see Units).
• system: physical system parameters (see System).
• tissues: keys are arbitrary tissue names; values define tissue properties.

Each tissue must have a density of type file_ref (it defines the tissue’s shape). All other properties are optional and fall back to their default values. B1+ and B1- are lists of maps to support multi-channel data (a single-element list is valid).

Tissue Property Values

Each property in a tissue can be set via one of three methods:

file_ref

A file reference has the form <file_name>[<index>]. The file must be a .nii(.gz) in the same directory as the JSON file. The index selects a volume along the 4th dimension of the NIfTI file, allowing multiple tissues’ data to share a single file.

mapping_func

A mapping function is an equation evaluated per voxel. It supports basic arithmetic (+ - * / ( )) and the following variables:

Examples: