mrzerocore 0.4.3__cp37-abi3-musllinux_1_2_aarch64.whl

MRzeroCore/phantom/nifti_phantom.py

@@ -0,0 +1,210 @@
+from dataclasses import dataclass
+from typing import Literal, Any
+from pathlib import Path
+
+
+@dataclass
+class PhantomUnits:
+    gyro: Literal["MHz/T"]
+    B0: Literal["T"]
+    T1: Literal["s"]
+    T2: Literal["s"]
+    T2dash: Literal["s"]
+    ADC: Literal["10^-3 mm^2/s"]
+    dB0: Literal["Hz"]
+    B1_tx: Literal["rel"]
+    B1_rx: Literal["rel"]
+
+    @classmethod
+    def default(cls):
+        return cls(
+            gyro="MHz/T",
+            B0="T",
+            T1="s",
+            T2="s",
+            T2dash="s",
+            ADC="10^-3 mm^2/s",
+            dB0="Hz",
+            B1_tx="rel",
+            B1_rx="rel",
+        )
+
+    @classmethod
+    def from_dict(cls, config: dict[str, str]):
+        # Currently this is only for documentation and no other units than the
+        # default units are supported. This definetly can change in the future
+        # but the implementation has no priority right now
+        default = cls.default()
+        assert default.to_dict() == config, "Only default units are supported for now"
+        return default
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "gyro": self.gyro,
+            "B0": self.B0,
+            "T1": self.T1,
+            "T2": self.T2,
+            "T2'": self.T2dash,
+            "ADC": self.ADC,
+            "dB0": self.dB0,
+            "B1+": self.B1_tx,
+            "B1-": self.B1_rx,
+        }
+
+
+@dataclass
+class PhantomSystem:
+    gyro: float
+    B0: float
+
+    @classmethod
+    def from_dict(cls, config: dict[str, float]):
+        return cls(**config)
+
+    def to_dict(self) -> dict[str, float]:
+        return {"gyro": self.gyro, "B0": self.B0}
+
+
+@dataclass
+class NiftiRef:
+    file_name: Path
+    tissue_index: int
+
+    @classmethod
+    def parse(cls, config: str):
+        import re
+
+        regex = re.compile(r"(?P<file>.+?)\[(?P<idx>\d+)\]$")
+        m = regex.match(config)
+        if not m:
+            raise ValueError("Invalid file_ref", m)
+        return cls(file_name=Path(m.group("file")), tissue_index=int(m.group("idx")))
+    
+    def to_str(self) -> str:
+        return f"{self.file_name}[{self.tissue_index}]"
+
+
+@dataclass
+class NiftiMapping:
+    file: NiftiRef
+    func: str
+
+    @classmethod
+    def parse(cls, config: dict[str, Any]):
+        return cls(file=NiftiRef.parse(config["file"]), func=config["func"])
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "file": self.file.to_str(),
+            "func": self.func
+        }
+
+
+@dataclass
+class NiftiTissue:
+    density: NiftiRef
+    T1: float | NiftiRef | NiftiMapping
+    T2: float | NiftiRef | NiftiMapping
+    T2dash: float | NiftiRef | NiftiMapping
+    ADC: float | NiftiRef | NiftiMapping
+    dB0: float | NiftiRef | NiftiMapping
+    B1_tx: list[float | NiftiRef | NiftiMapping]
+    B1_rx: list[float | NiftiRef | NiftiMapping]
+
+    @classmethod
+    def default(cls, density: NiftiRef):
+        return cls.from_dict({"density": density})
+
+    @classmethod
+    def from_dict(cls, config: dict[str, Any]):
+        def parse_prop(prop):
+            if isinstance(prop, float):
+                return float(prop)
+            elif isinstance(prop, str):
+                return NiftiRef.parse(prop)
+            else:
+                return NiftiMapping.parse(prop)
+
+        return cls(
+            density=NiftiRef.parse(config["density"]),
+            T1=parse_prop(config.get("T1", float("inf"))),
+            T2=parse_prop(config.get("T2", float("inf"))),
+            T2dash=parse_prop(config.get("T2'", float("inf"))),
+            ADC=parse_prop(config.get("ADC", 0.0)),
+            dB0=parse_prop(config.get("dB0", 1.0)),
+            B1_tx=[parse_prop(ch) for ch in config.get("B1+", [1.0])],
+            B1_rx=[parse_prop(ch) for ch in config.get("B1-", [1.0])],
+        )
+
+    def to_dict(self) -> dict:
+        def serialize_prop(prop):
+            if isinstance(prop, float):
+                return prop
+            elif isinstance(prop, NiftiRef):
+                return prop.to_str()
+            elif isinstance(prop, NiftiMapping):
+                return prop.to_dict()
+            else:
+                raise ValueError("Unsupported property type", type(prop))
+
+        return {
+            "density": self.density.to_str(),
+            "T1": serialize_prop(self.T1),
+            "T2": serialize_prop(self.T2),
+            "T2'": serialize_prop(self.T2dash),
+            "ADC": serialize_prop(self.ADC),
+            "dB0": serialize_prop(self.dB0),
+            "B1+": [serialize_prop(ch) for ch in self.B1_tx],
+            "B1-": [serialize_prop(ch) for ch in self.B1_rx],
+        }
+
+
+@dataclass
+class NiftiPhantom:
+    file_type = "nifti_phantom_v1"
+    units: PhantomUnits
+    system: PhantomSystem
+    tissues: dict[str, NiftiTissue]
+
+    @classmethod
+    def default(cls, gyro=42.5764, B0=3.0):
+        return cls(PhantomUnits.default(), PhantomSystem(gyro, B0), {})
+
+    @classmethod
+    def load(cls, path: Path | str):
+        import json
+
+        with open(path, "r") as f:
+            config = json.load(f)
+        return cls.from_dict(config)
+
+    def save(self, path: Path | str):
+        import json
+        import os
+        path = Path(path)
+
+        os.makedirs(path.parent, exist_ok=True)
+        with open(path, "w") as f:
+            json.dump(self.to_dict(), f, indent=2)
+
+    @classmethod
+    def from_dict(cls, config: dict):
+        assert config["file_type"] == "nifti_phantom_v1"
+        units = PhantomUnits.from_dict(config["units"])
+        system = PhantomSystem.from_dict(config["system"])
+        tissues = {
+            name: NiftiTissue.from_dict(tissue)
+            for name, tissue in config["tissues"].items()
+        }
+
+        return cls(units, system, tissues)
+
+    def to_dict(self) -> dict:
+        return {
+            "file_type": self.file_type,
+            "units": self.units.to_dict(),
+            "system": self.system.to_dict(),
+            "tissues": {
+                name: tissue.to_dict() for name, tissue in self.tissues.items()
+            },
+        }

MRzeroCore/phantom/sim_data.py

@@ -0,0 +1,200 @@
+from __future__ import annotations
+from typing import Callable, Any, Optional, Dict
+import torch
+from numpy import pi
+
+
+class SimData:
+    """This class contains the physical data for simulating a MRI sequence.
+
+    It is not intended to create this class directly, but rather to use one of
+    the :class:`SimData` builders / loaders. Those are made fore specific
+    tasks and can be converted into :class:`SimData`, but also attach
+    metadata to the output so it can be converted back. The attributes of this
+    class are nothing but the data needed for simulation, so it can describe
+    a single voxel, randomly distributed voxels, a BrainWeb phantom, ...
+
+    Attributes
+    ----------
+    PD : torch.Tensor
+        Per voxel proton density
+    T1 : torch.Tensor
+        Per voxel T1 relaxation time (seconds)
+    T2 : torch.Tensor
+        Per voxel T2 relaxation time (seconds)
+    T2dash : torch.Tensor
+        Per voxel T2' dephasing time (seconds)
+    D: torch.Tensor
+        Isometric diffusion coefficients [10^-3 mm^2/s]
+    B0 : torch.Tensor
+        Per voxel B0 inhomogentity (Hertz)
+    B1 : torch.Tensor
+        (coil_count, voxel_count) Per coil and per voxel B1 inhomogenity
+    coil_sens : torch.Tensor
+        (coil_count, voxel_count) Per coil sensitivity (arbitrary units)
+    size : torch.Tensor
+        Physical size of the phantom. If a sequence with normalized gradients
+        is simulated, size is used to scale them to match the phantom.
+    avg_B1_trig : torch.Tensor
+        (361, 3) values containing the PD-weighted avg of sin/cos/sin²(B1*flip)
+    voxel_pos : torch.Tensor
+        (voxel_count, 3) Voxel positions. These can be anywhere, but for easy
+        sequence programming they should be in the range [-0.5, 0.5[
+    nyquist : torch.Tensor
+        (3, ) tensor: Maximum frequency encoded by the data
+    dephasing_func : torch.Tensor -> torch.Tensor
+        A function describing the intra-voxel dephasing. Maps a k-space
+        trajectory (events, 3) to the measured attenuation (events).
+    recover_func : SimData -> Any
+        A function that can recover the original data that was used to create
+        this instance. Usually a lambda that captures meta data like a mask.
+    """
+
+    def __init__(
+        self,
+        PD: torch.Tensor,
+        T1: torch.Tensor,
+        T2: torch.Tensor,
+        T2dash: torch.Tensor,
+        D: torch.Tensor,
+        B0: torch.Tensor,
+        B1: torch.Tensor,
+        coil_sens: torch.Tensor,
+        size: torch.Tensor,
+        voxel_pos: torch.Tensor,
+        nyquist: torch.Tensor,
+        dephasing_func: Callable[[torch.Tensor, torch.Tensor], torch.Tensor],
+        recover_func: Callable[[SimData], Any] | None = None,
+        phantom_motion=None,
+        voxel_motion=None,
+        tissue_masks: Optional[Dict[str,torch.Tensor]] = None,
+    ) -> None:
+        """Create a :class:`SimData` instance based on the given tensors.
+
+        All parameters must be of shape ``(voxel_count, )``, only B1 and
+        coil_sens have an additional first dimension for multiple coils.
+
+        Parameters
+        ----------
+        normalize : bool
+            If true, applies B0 -= B0.mean(), B1 /= B1.mean(), PD /= PD.sum()
+        """
+        if not (PD.shape == T1.shape == T2.shape == T2dash.shape == B0.shape):
+            raise Exception("Mismatch of voxel-data shapes")
+        if not PD.ndim == 1:
+            raise Exception("Data must be 1D (flattened)")
+        if B1.ndim < 2 or B1.shape[1] != PD.numel():
+            raise Exception("B1 must have shape [coils, voxel_count]")
+        if coil_sens.ndim < 2 or coil_sens.shape[1] != PD.numel():
+            raise Exception("coil_sens must have shape [coils, voxel_count]")
+
+        self.PD = PD.clamp(min=0)
+        self.T1 = T1.clamp(min=1e-6)
+        self.T2 = T2.clamp(min=1e-6)
+        self.T2dash = T2dash.clamp(min=1e-6)
+        self.D = D.clamp(min=1e-6)
+        self.B0 = B0.clone()
+        self.B1 = B1.clone()
+        self.tissue_masks = tissue_masks
+        if self.tissue_masks is None:
+            self.tissue_masks = {}
+        self.coil_sens = coil_sens.clone()
+        self.size = size.clone()
+        self.voxel_pos = voxel_pos.clone()
+        self.avg_B1_trig = calc_avg_B1_trig(B1, PD)
+        self.nyquist = nyquist.clone()
+        self.dephasing_func = dephasing_func
+        self.recover_func = recover_func
+
+        self.phantom_motion = phantom_motion
+        self.voxel_motion = voxel_motion
+
+    def cuda(self) -> SimData:
+        """Move the simulation data to the default CUDA device.
+
+        The returned :class:`SimData` is equivalent to :attr:`self` if the data
+        already was on the GPU.
+        """
+        return SimData(
+            self.PD.cuda(),
+            self.T1.cuda(),
+            self.T2.cuda(),
+            self.T2dash.cuda(),
+            self.D.cuda(),
+            self.B0.cuda(),
+            self.B1.cuda(),
+            self.coil_sens.cuda(),
+            self.size.cuda(),
+            self.voxel_pos.cuda(),
+            self.nyquist.cuda(),
+            self.dephasing_func,
+            self.recover_func,
+            self.phantom_motion,
+            self.voxel_motion,
+            tissue_masks={
+                k: v.cuda() for k, v in self.tissue_masks.items()
+            },
+        )
+
+    def cpu(self) -> SimData:
+        """Move the simulation data to the CPU.
+
+        The returned :class:`SimData` is equivalent to :attr:`self` if the data
+        already was on the CPU.
+        """
+        return SimData(
+            self.PD.cpu(),
+            self.T1.cpu(),
+            self.T2.cpu(),
+            self.T2dash.cpu(),
+            self.D.cpu(),
+            self.B0.cpu(),
+            self.B1.cpu(),
+            self.coil_sens.cpu(),
+            self.size.cpu(),
+            self.voxel_pos.cpu(),
+            self.nyquist.cpu(),
+            self.dephasing_func,
+            self.recover_func,
+            self.phantom_motion,
+            self.voxel_motion,
+            tissue_masks={
+                k: v.cpu() for k, v in self.tissue_masks.items()
+            },
+        )
+
+    @property
+    def device(self) -> torch.device:
+        """The device (either CPU or a CUDA device) the data is stored on."""
+        return self.PD.device
+
+    def recover(self) -> Any:
+        """Recover the data that was used to build this instance."""
+        if self.recover_func is None:
+            raise Exception("No recover function was provided")
+        else:
+            return self.recover_func(self)
+
+
+def calc_avg_B1_trig(B1: torch.Tensor, PD: torch.Tensor) -> torch.Tensor:
+    """Return a (361, 3) tensor for B1 specific sin, cos and sin² values.
+
+    This function calculates values for sin, cos and sin² for (0, 2pi) * B1 and
+    then averages the results, weighted by PD. These 3 functions are the non
+    linear parts of a rotation matrix, the resulting look up table can be used
+    to calcualte averaged rotations for the whole phantom. This is useful for
+    the pre-pass, to get better magnetization estmates even if the pre-pass is
+    not spatially resolved.
+    """
+    # With pTx, there are now potentially multiple B1 maps with phase.
+    # NOTE: This is a (probably suboptimal) workaround
+    B1 = B1.sum(0).abs()
+
+    B1 = B1.flatten()[:, None]  # voxels, 1
+    PD = (PD.flatten() / PD.sum())[:, None]  # voxels, 1
+    angle = torch.linspace(0, 2*pi, 361, device=PD.device)[None, :]  # 1, angle
+    return torch.stack([
+        (torch.sin(B1 * angle) * PD).sum(0),
+        (torch.cos(B1 * angle) * PD).sum(0),
+        (torch.sin(B1 * angle/2)**2 * PD).sum(0)
+    ], dim=1).type(torch.float32)

MRzeroCore/phantom/tissue_dict.py

@@ -0,0 +1,269 @@
+from .voxel_grid_phantom import VoxelGridPhantom
+from .sim_data import SimData
+from .nifti_phantom import NiftiPhantom, NiftiTissue, NiftiRef, NiftiMapping
+from pathlib import Path
+import torch
+import numpy as np
+from typing import Literal
+from functools import lru_cache
+
+
+class TissueDict(dict[str, VoxelGridPhantom]):
+    @classmethod
+    def load(cls, path: Path | str, config: NiftiPhantom | None = None):
+        """Load a NIfTI phantom into a dictionary of tissues.
+        
+        This class is a Python dictionary where the keys are the names of the
+        tissues (as written in the `phantom.json`) and the values are
+        VoxelGridPhantoms (typically tissues).
+        The dictionary is extended by additional methods for saving as NIfTI
+        phantom, interpolation, slicing, combining all tissues into a single
+        VoxelGridPhantom with weighted voxels, and finally for converting all
+        tissues into `SimData` (with overlapping tissues / partial-volume).
+
+        Parameters
+        ----------
+        path: Path | str
+            Either the path to the `phantom.json` configuration file _or_ the
+            directory where the NIfTIs are found (if config is provided).
+        config: NiftiPhantom
+            Optional configuration - can be used to load a NIfTI phantom config
+            and modify it in-memory before loading the actual data.
+        """
+        if config:
+            base_dir = Path(path)
+        else:
+            base_dir = Path(path).parent
+            config = NiftiPhantom.load(path)
+
+        # NOTE: Unit conversion is ignored. Currently no other than the default
+        # units are supported (conversion factor 1); this might change in the future
+
+        return TissueDict({
+            name: load_tissue(tissue, base_dir)
+            for name, tissue in config.tissues.items()
+        })
+    
+    def save(self, path_to_json: str | Path, gyro=42.5764, B0=3.0):
+        from pathlib import Path
+        import os
+        import nibabel as nib
+
+        path_to_json = Path(path_to_json)
+        base_name = path_to_json.stem
+        base_dir = path_to_json.parent
+        os.makedirs(base_dir, exist_ok=True)
+
+        density = []
+        T1 = []
+        T2 = []
+        T2dash = []
+        ADC = []
+        dB0 = []
+        B1_tx = []
+        B1_rx = []
+
+        def save_tissue(tissue: VoxelGridPhantom):
+            config = {}
+
+            def save_map(name, map, nifti):
+                ext = f"_{name}" if name != "density" else ""
+                # Multi-channel data when setting the same property multiple times
+                def set(value):
+                    if name in config:
+                        config[name].append(value)
+                    else:
+                        config[name] = value
+
+                if map.std() < 1e-5:
+                    set(float(map.mean()))
+                else:
+                    # Check if map is shared with other tissues
+                    for idx, nifti_map in enumerate(nifti):
+                        if torch.equal(map, nifti_map):
+                            set(f"{base_name}{ext}.nii.gz[{idx}]")
+                            return
+                    # Not shared, write new map
+                    set(f"{base_name}{ext}.nii.gz[{len(nifti)}]")
+                    nifti.append(map)
+
+            save_map("density", tissue.PD, density)
+            save_map("T1", tissue.T1, T1)
+            save_map("T2", tissue.T2, T2)
+            save_map("T2'", tissue.T2dash, T2dash)
+            save_map("ADC", tissue.D, ADC)
+            save_map("dB0", tissue.B0, dB0)
+            config["B1+"] = []
+            for channel in tissue.B1:
+                save_map("B1+", channel, B1_tx)
+            config["B1-"] = []
+            for channel in tissue.coil_sens:
+                save_map("B1-", channel, B1_rx)
+
+            return NiftiTissue.from_dict(config)
+
+        # Generate all tissues (and fill the prop maps)
+        tissues = {tissue: save_tissue(self[tissue]) for tissue in self.keys()}
+
+        # Write the NIfTIs
+        size = np.asarray(next(iter(self.values())).size)
+        vs = 1000 * size / np.asarray(density[0].shape)
+        affine = np.array(
+            [
+                [+vs[0], 0, 0, -size[0] / 2 * 1000],
+                [0, +vs[1], 0, -size[1] / 2 * 1000],
+                [0, 0, +vs[2], -size[2] / 2 * 1000],
+                [0, 0, 0, 0],  # Row ignored
+            ]
+        )
+
+        def save_nifti(prop, name):
+            if len(prop) > 0:
+                ext = f"-{name}" if name != "density" else ""
+                file_name = base_dir / f"{base_name}{ext}.nii.gz"
+                data = np.stack(prop, -1)
+
+                print(f"Storing '{file_name}' - {data.shape}")
+                nib.save(nib.nifti1.Nifti1Image(data, affine), file_name)
+        
+        save_nifti(density, "density")
+        save_nifti(T1, "T1")
+        save_nifti(T2, "T2")
+        save_nifti(T2dash, "T2'")
+        save_nifti(ADC, "ADC")
+        save_nifti(dB0, "dB0")
+        save_nifti(B1_tx, "B1+")
+        save_nifti(B1_rx, "B1-")
+
+        config = NiftiPhantom.default(gyro, B0)
+        config.tissues = tissues
+        config.save(path_to_json)
+    
+    def interpolate(self, x: int, y: int, z: int):
+        return TissueDict({
+            name: phantom.interpolate(x, y, z) for name, phantom in self.items()
+        })
+    
+    def slices(self, slices: list[int]):
+        return TissueDict({
+            name: phantom.slices(slices) for name, phantom in self.items()
+        })
+    
+    def combine(self) -> VoxelGridPhantom:
+        """Combine individual maps to mixed-tissue (no partial volume) phantom."""
+        phantoms = list(self.values())
+
+        PD = sum(p.PD for p in phantoms)
+        segmentation = [p.PD / PD for p in phantoms]
+        
+        from copy import deepcopy
+        combined = deepcopy(phantoms[0])
+        combined.PD = PD
+        combined.T1 = sum(seg * p.T1 for seg, p in zip(segmentation, phantoms))
+        combined.T2 = sum(seg * p.T2 for seg, p in zip(segmentation, phantoms))
+        combined.T2dash = sum(seg * p.T2dash for seg, p in zip(segmentation, phantoms))
+        combined.D = sum(seg * p.D for seg, p in zip(segmentation, phantoms))
+        combined.B0 = sum(seg * p.B0 for seg, p in zip(segmentation, phantoms))
+        combined.B1 = sum(seg[None, ...] * p.B1 for seg, p in zip(segmentation, phantoms))
+        
+        return combined
+
+    def build(self, PD_threshold: float = 1e-6,
+              voxel_shape: Literal["sinc", "box", "point"] = "sinc"
+              ) -> SimData:
+        data_list = [self[tissue].build(PD_threshold, voxel_shape) for tissue in self]
+
+        return SimData(
+            PD=torch.cat([obj.PD for obj in data_list]),
+            T1=torch.cat([obj.T1 for obj in data_list]),
+            T2=torch.cat([obj.T2 for obj in data_list]),
+            T2dash=torch.cat([obj.T2dash for obj in data_list]),
+            D=torch.cat([obj.D for obj in data_list]),
+            B0=torch.cat([obj.B0 for obj in data_list]),
+            B1=torch.cat([obj.B1 for obj in data_list], 1),
+            coil_sens=torch.cat([obj.coil_sens for obj in data_list], 1),
+            voxel_pos=torch.cat([obj.voxel_pos for obj in data_list], 0),
+            tissue_masks=torch.stack([obj.tissue_masks for obj in data_list]),
+            size=data_list[0].size,
+            nyquist=data_list[0].nyquist,
+            dephasing_func=data_list[0].dephasing_func,
+        )
+
+# ============================
+# Helpers for importing NIfTIs
+# ============================
+
+def load_tissue(config: NiftiTissue, base_dir: Path) -> VoxelGridPhantom:
+    density, affine = load_file_ref(base_dir, config.density)
+    size = np.abs(density.shape @ affine[:3, :3]) / 1000  # affine is in mm
+
+    def lp(cfg):
+        return torch.as_tensor(load_property(cfg, base_dir, density, affine))
+
+    return VoxelGridPhantom(
+        PD=torch.as_tensor(density),
+        size=torch.as_tensor(size),
+        T1=lp(config.T1),
+        T2=lp(config.T2),
+        T2dash=lp(config.T2dash),
+        D=lp(config.ADC),
+        B0=lp(config.dB0),
+        B1=torch.stack([lp(cfg) for cfg in config.B1_tx], 0),
+        coil_sens=torch.stack([lp(cfg) for cfg in config.B1_rx], 0),
+    )
+
+
+def load_property(config: float | NiftiRef | NiftiMapping,
+                  base_dir: Path, density_mat: np.ndarray, target_affine: np.ndarray
+                  ) -> np.ndarray:
+    
+    if isinstance(config, float):
+        return np.full_like(density_mat, config)
+
+    if isinstance(config, NiftiRef):
+        data, affine = load_file_ref(base_dir, config)
+        assert np.all(affine == target_affine)
+        return data
+
+    if isinstance(config, NiftiMapping):
+        data, affine = load_mapping(base_dir, config)
+        assert np.all(affine == target_affine)
+        return data
+
+    raise TypeError("Config must be a float, file_ref or mapping", type(config))
+
+def load_mapping(base_dir: Path, file_mapping: NiftiMapping) -> tuple[np.ndarray, np.ndarray]:
+    data, affine = load_file_ref(base_dir, file_mapping.file)
+
+    # TODO - SAFETY: Don't use eval but a custom (imported?) expression parser.
+    print(f"Executing mapping function: '{file_mapping.func}'")
+    return eval(
+        file_mapping.func,
+        {"__builtins__": None},
+        {
+            "x": data,
+            "x_min": data.min(),
+            "x_max": data.max(),
+            "x_mean": data.mean(),
+            "x_std": data.std()
+        }
+    ), affine
+
+
+def load_file_ref(base_dir: Path, file_ref: NiftiRef) -> tuple[np.ndarray, np.ndarray]:
+    print(f"Loading NIfTI (file={file_ref.file_name}, index={file_ref.tissue_index})")
+    file = file_ref.file_name
+    index = file_ref.tissue_index
+    if not file.is_absolute():
+        file = (base_dir / file).resolve()
+
+    data, affine = _load_cached(str(file))
+    return data[:, :, :, index], affine
+
+
+# Use a small cache to avoid reloading NIfTIs every time
+@lru_cache(maxsize=20)
+def _load_cached(file_name):
+    import nibabel
+    img = nibabel.loadsave.load(file_name)
+    return np.asarray(img.dataobj), img.get_sform()