mrzerocore 0.4.3__cp37-abi3-musllinux_1_2_aarch64.whl

MRzeroCore/__init__.py

@@ -0,0 +1,22 @@
+import numpy
+if not hasattr(numpy, "int"):
+    numpy.int = int
+if not hasattr(numpy, "float"):
+    numpy.float = float
+if not hasattr(numpy, "complex"):
+    numpy.complex = complex
+
+from .sequence import PulseUsage, Pulse, Repetition, Sequence, chain
+from .phantom.voxel_grid_phantom import VoxelGridPhantom
+from .phantom.custom_voxel_phantom import CustomVoxelPhantom
+from .phantom.sim_data import SimData
+from .phantom.brainweb import generate_brainweb_phantoms
+from .phantom.nifti_phantom import NiftiPhantom, NiftiTissue, NiftiRef, NiftiMapping
+from .phantom.tissue_dict import TissueDict
+from .simulation.isochromat_sim import isochromat_sim
+from .simulation.pre_pass import compute_graph, compute_graph_ext, Graph
+from .simulation.main_pass import execute_graph
+from .simulation.sig_to_mrd import sig_to_mrd
+from .reconstruction import reco_adjoint
+from .pulseq.exporter import pulseq_write_cartesian
+from . import util

MRzeroCore/phantom/brainweb/.gitignore

@@ -0,0 +1 @@
+brainweb*/

MRzeroCore/phantom/brainweb/__init__.py

@@ -0,0 +1,192 @@
+import numpy as np
+from pathlib import Path
+
+
+def load_tissue(subject: int, alias: str, cache_dir: Path) -> np.ndarray:
+    import os
+    import requests
+    import gzip
+
+    download_alias = f"subject{subject:02d}_{alias}"
+    file_name = download_alias + ".i8.gz"  # 8 bit signed int, gnuzip
+    file_path = cache_dir / file_name
+
+    # Download and cache file if it doesn't exist yet
+    if not os.path.exists(file_path):
+        response = requests.post(
+            "https://brainweb.bic.mni.mcgill.ca/cgi/brainweb1",
+            data={
+                "do_download_alias": download_alias,
+                "format_value": "raw_byte",
+                "zip_value": "gnuzip"
+            }
+        )
+        with open(file_path, "wb") as f:
+            f.write(response.content)
+
+    # Load the raw BrainWeb data and add it to the return array
+    with gzip.open(file_path) as f:
+        # BrainWeb says this data is unsigned, which is a lie
+        tmp = np.frombuffer(f.read(), np.uint8) + 128
+
+    # Vessel bugfix: most of background is 1 instead of zero
+    if alias == "ves":
+        tmp[tmp == 1] = 0
+    
+    # Convert to RAS+ [x, y, z] indexing and [0..1] range
+    data = tmp.reshape(362, 434, 362).swapaxes(0, 2).astype(np.float32) / 255.0
+
+    return data
+
+
+def generate_B0_B1(mask):
+    """Generate a somewhat plausible B0 and B1 map.
+
+    Visually fitted to look similar to the numerical_brain_cropped
+    """
+    x_pos, y_pos, z_pos = np.meshgrid(
+        np.linspace(-1, 1, mask.shape[0]),
+        np.linspace(-1, 1, mask.shape[1]),
+        np.linspace(-1, 1, mask.shape[2]),
+        indexing="ij"
+    )
+    B1 = np.exp(-(0.4*x_pos**2 + 0.2*y_pos**2 + 0.3*z_pos**2))
+    dist2 = (0.4*x_pos**2 + 0.2*(y_pos - 0.7)**2 + 0.3*z_pos**2)
+    B0 = 7 / (0.05 + dist2) - 45 / (0.3 + dist2)
+
+    # Normalize such that the average over the mask is 0 or 1
+    
+    B0 -= B0[mask].mean()
+    B1 /= B1[mask].mean()
+    B0[~mask] = 0
+    B1[~mask] = 0
+
+    return B0, B1
+
+
+def generate_brainweb_phantoms(output_dir: str, subject_count: int | None = None):
+    """Generate BrainWeb phantom maps for the selected configuration.
+
+    Raw tissue segmentation data is provided by the BrainWeb Database:
+    http://www.bic.mni.mcgill.ca/brainweb/
+
+    The generated phantoms are stored as MR-zero
+    [NIfTI phantoms](https://mrsources.github.io/MRzero-Core/nifti-overview.html).
+    Settings for the generated phantoms are stored in `brainweb_data.json`.
+
+    Parameters
+    ----------
+    output_dir: str
+        The directory where the generated phantoms will be stored to. In
+        addition, a `cache` folder will be generated there too, which contains
+        all the data downloaded from BrainWeb to avoid repeating the download
+        for all configurations or when generating phantoms again.
+    subject_count: int
+        Number of phantoms to generate. BrainWeb provides 20 different segmented
+        phantoms. If you don't need as many, you can lower this number to only
+        generate the first `count` phantoms. If `None`, all phantoms are generated.
+    """
+    import os
+    import json
+    from tqdm import tqdm
+    import nibabel as nib
+    from ..nifti_phantom import NiftiPhantom, NiftiTissue, NiftiRef, NiftiMapping
+
+    cache_dir = Path(output_dir) / "cache"
+    config_file = Path(__file__).parent / "brainweb_data.json"
+    os.makedirs(cache_dir, exist_ok=True)
+
+    # Load the brainweb data file that contains info about tissues and subjects
+    with open(config_file) as f:
+        config = json.load(f)
+
+    if subject_count is None:
+        subject_count = len(config["subjects"])
+
+    # Voxel index to physical coordinates in millimeters:
+    # Brainweb has 0.5 mm voxel size; we center the brain.
+    affine = np.array(
+        [
+            [0.5, 0, 0, -90.5],  # X: Right
+            [0, 0.5, 0, -108.5], # Y: Anterior
+            [0, 0, 0.5, -90.5],  # Z: Superior
+            [0, 0, 0, 0],        # ignored
+        ]
+    )
+
+
+    number_of_downloads = subject_count * sum(len(maps) for maps in config["download-aliases"].values())
+    number_of_saves = subject_count * 3  # density, B0, B1
+    number_of_jsons = subject_count * len(config["fields"])
+    total = number_of_downloads + number_of_saves + number_of_jsons
+
+    with tqdm(total=total) as pbar:
+        for subject in config["subjects"][:subject_count]:
+            phantom_name = f"brainweb-subj{subject:02d}"
+            phantom_dir = Path(output_dir) / phantom_name
+
+            pbar.set_description(str(phantom_dir))
+            os.makedirs(phantom_dir, exist_ok=True)
+
+            tissue_indices = {}
+            density_maps = []
+            for tissue, density in config["density"].items():
+                density_map = 0
+
+                for alias in config["download-aliases"][tissue]:
+                    pbar.set_postfix_str(f"loading 'subject{subject:02d}_{alias}'")
+                    density_map += density * load_tissue(subject, alias, cache_dir)
+                    pbar.update()
+
+                tissue_indices[tissue] = len(density_maps)
+                density_maps.append(density_map)
+
+            pbar.set_postfix_str(f"saving '{phantom_name}.nii.gz'")
+            nib.loadsave.save(
+                nib.nifti1.Nifti1Image(np.stack(density_maps, -1), affine),
+                phantom_dir / f"{phantom_name}.nii.gz"
+            )
+            pbar.update()
+
+            B0, B1 = generate_B0_B1(sum(density_maps) > 0)
+            pbar.set_postfix_str(f"saving '{phantom_name}_dB0.nii.gz'")
+            nib.loadsave.save(
+                nib.nifti1.Nifti1Image(B0[..., None], affine),
+                phantom_dir / f"{phantom_name}_dB0.nii.gz"
+            )
+            pbar.update()
+            pbar.set_postfix_str(f"saving '{phantom_name}_B1+.nii.gz'")
+            nib.loadsave.save(
+                nib.nifti1.Nifti1Image(B1[..., None], affine),
+                phantom_dir / f"{phantom_name}_B1+.nii.gz"
+            )
+            pbar.update()
+
+            for field in config["fields"]:
+                phantom = NiftiPhantom.default(B0=field)
+                pbar.set_postfix_str(f"saving '{phantom_name}-{field}T.json'")
+                density_maps = []
+
+                for tissue in config["tissues"]:
+                    tissue_config = config["props"][str(field)][tissue]
+
+                    phantom.tissues[tissue] = NiftiTissue(
+                        density=NiftiRef(Path(f"{phantom_name}.nii.gz"), tissue_indices[tissue]),
+                        T1=tissue_config["T1"],
+                        T2=tissue_config["T2"],
+                        T2dash=tissue_config["T2'"],
+                        ADC=tissue_config["ADC"],
+                        dB0=NiftiRef(Path(f"{phantom_name}_dB0.nii.gz"), 0),
+                        B1_tx=[NiftiRef(Path(f"{phantom_name}_B1+.nii.gz"), 0)],
+                        B1_rx=[1.0],
+                    )
+                    if tissue == "fat":
+                        phantom.tissues["fat"].dB0 = NiftiMapping(
+                            file=NiftiRef(Path(f"{phantom_name}_dB0.nii.gz"), 0),
+                            func=config["dB0-fat-remap"][str(field)]
+                        )
+
+                phantom.save(phantom_dir / f"{phantom_name}-{field}T.json")
+                pbar.update()
+        
+        pbar.close()

MRzeroCore/phantom/brainweb/brainweb_data.json

@@ -0,0 +1,92 @@
+{
+  "subjects": [
+    4, 5, 6, 18, 20, 38, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54
+  ],
+  "fields": [3, 7],
+  "tissues": ["gm", "wm", "csf", "vessels", "fat"],
+  "download-aliases": {
+    "gm": ["gry"],
+    "wm": ["wht"],
+    "csf": ["csf"],
+    "vessels": ["ves"],
+    "fat": ["fat", "mus", "m-s", "dura", "fat2"]
+  },
+  "dB0-fat-remap" : {
+    "3": "x - 440",
+    "7": "x - 1020"
+  },
+  "density": {
+    "gm": 0.8,
+    "wm": 0.7,
+    "csf": 1.0,
+    "vessels": 1.0,
+    "fat": 1.0
+  },
+
+  "props": {
+    "3": {
+      "gm": {
+        "T1": 1.56,
+        "T2": 0.083,
+        "T2'": 0.32,
+        "ADC": 0.83
+      },
+      "wm": {
+        "T1": 0.83,
+        "T2": 0.075,
+        "T2'": 0.18,
+        "ADC": 0.65
+      },
+      "csf": {
+        "T1": 4.16,
+        "T2": 1.65,
+        "T2'": 0.059,
+        "ADC": 3.19
+      },
+      "vessels": {
+        "T1": 4.16,
+        "T2": 1.65,
+        "T2'": 0.059,
+        "ADC": 3.19
+      },
+      "fat": {
+        "T1": 0.37,
+        "T2": 0.125,
+        "T2'": 0.012,
+        "ADC": 0.1
+      }
+    },
+    "7": {
+      "gm": {
+        "T1": 1.67,
+        "T2": 0.043,
+        "T2'": 0.82,
+        "ADC": 0.83
+      },
+      "wm": {
+        "T1": 1.22,
+        "T2": 0.037,
+        "T2'": 0.65,
+        "ADC": 0.65
+      },
+      "csf": {
+        "T1": 4.0,
+        "T2": 0.8,
+        "T2'": 0.204,
+        "ADC": 3.19
+      },
+      "vessels": {
+        "T1": 4.0,
+        "T2": 0.8,
+        "T2'": 0.204,
+        "ADC": 3.19
+      },
+      "fat": {
+        "T1": 0.374,
+        "T2": 0.125,
+        "T2'": 0.0117,
+        "ADC": 0.1
+      }
+    }
+  }
+}

MRzeroCore/phantom/brainweb/brainweb_data_sources.txt

@@ -0,0 +1,74 @@
+! NOTE
+7T maps are not checked as thrououghly. Only source so far:
+https://cds.ismrm.org/protected/14MProceedings/PDFfiles/3208.pdf
+
+
+# T1 and T2 times, taken from:
+# https://mri-q.com/uploads/3/4/5/7/34572113/normal_relaxation_times_at_3t.pdf
+# Value taken from paper with most participants (draw: closest to mean of all)
+# Studies that are outliers are ignored (WM T2 time)
+
+# T2' calculated from T2 and T2*, taken from:
+# https://www.sciencedirect.com/science/article/pii/S0730725X07001701?via%3Dihub
+
+# Water / Fat T2': https://link.springer.com/article/10.1007/s00723-015-0737-5 (4.7 T)
+
+# Errors are uncertenties of studies, not data on variation in one measurement
+
+Brainweb Tissues:
+ - CSF
+   T1: 4163 ± 263
+	T2: 1650 (approx, taken from https://www.ncbi.nlm.nih.gov/pmc/articles/PMC5973950/)
+	T2*: 57.1 -> T2': 59.1
+
+ - Gray Matter
+   T1: 1558 ± 88
+	T2: 83 ± 4
+   T2*: 66.0 ± 1.4 -> T2': 322
+
+ - White Matter
+   T1: 830 ± 0
+	T2: 75 ± 3
+   T2*: 53.2 ± 1.2 -> T2': 183
+	T2': 56 ± 1
+
+ - Fat
+   T1: 374 ± 45
+	T2: 125
+	T2* = 10.7 -> T2': 11.7
+
+# The following values are not used for phantom generation
+
+ - Muscle
+   T1: 1100 ± 59
+	T2: 40
+
+ - Muscle/Skin
+
+ - Skull
+    Probably similar to Bone marrow, but they don't overlap in the images
+
+ - Blood vessels
+    Probably similar to CSF (mostly water)
+
+ - Connective (region around fat)
+    Overlaps nearly fully with Fat
+
+ - Dura matter
+    Very little volume, probably not noticable at lower resolutions
+
+ - Bone marrow
+    T1: 586 ± 73
+	T2: 127
+
+
+Diffusion:
+Values taken from https://onlinelibrary.wiley.com/doi/10.1002/jmri.1076
+10^-3 mm² / s
+CSF: 3.19 ± 0.10
+WM:  0.65 ± 0.03
+GM:  0.83 ± 0.05
+
+No great source for fat, https://onlinelibrary.wiley.com/doi/10.1002/mrm.24535
+says it barely diffuses
+FAT: ~0.1

MRzeroCore/phantom/custom_voxel_phantom.py

@@ -0,0 +1,240 @@
+from __future__ import annotations
+from typing import Callable
+import torch
+from numpy import pi
+import matplotlib.pyplot as plt
+from .sim_data import SimData
+
+
+def heaviside(t: torch.Tensor, size: torch.Tensor) -> torch.Tensor:
+    """Sinc voxel (real space) dephasing function.
+
+    The size describes the distance from the center to the first zero crossing.
+    This is not differentiable because of the discontinuity at ±size/2.
+    """
+    return torch.prod(torch.heaviside(
+        0.5/size - t.abs(), torch.tensor(0.5)
+    ), dim=1)
+
+
+def sigmoid(t: torch.Tensor, size: torch.Tensor) -> torch.Tensor:
+    """Differentiable approximation of the sinc voxel dephasing function.
+
+    The size describes the distance from the center to the first zero crossing.
+    A narrow sigmoid is used to avoid the discontinuity of a heaviside.
+    """
+    return torch.prod(torch.sigmoid((0.5/size - t.abs() + 0.5) * 100), dim=1)
+
+
+def sinc(t: torch.Tensor, size: torch.Tensor) -> torch.Tensor:
+    """Box voxel (real space) dephasing function.
+
+    The size describes the total extends of the box shape.
+    """
+    return torch.prod(torch.sinc(t * size), dim=1)
+
+
+def gauss(t: torch.Tensor, size: torch.Tensor) -> torch.Tensor:
+    """Normal distribution shaped voxel dephasing function.
+
+    This function is not normalized. The size describes the variance.
+    """
+    return torch.prod(torch.exp(-0.5 * size * t**2), dim=1)
+
+
+class CustomVoxelPhantom:
+    """Class for manually specifying phantoms from a list of voxels.
+
+    This can be useful to test the simulation or to simulate the point spread
+    function. All voxels have the same size and shape but can have different
+    physical properties.
+
+    Attributes
+    ----------
+    voxel_pos : torch.Tensor
+        (voxel_count, 3) tensor of voxel positions in SI units [m]
+    PD : torch.Tensor
+        1D tensor containing the Proton Density of all voxels
+    T1 : torch.Tensor
+        1D tensor containing the T1 relaxation of all voxels
+    T2 : torch.Tensor
+        1D tensor containing the T2 relaxation of all voxels
+    T2dash : torch.Tensor
+        1D tensor containing the T2' dephasing of all voxels
+    D : torch.Tensor
+        1D tensor containing the Diffusion coefficient of all voxels
+    B0 : torch.Tensor
+        1D tensor containing the dB0 off-resonance
+    B1 : torch.Tensor
+        1D tensor containing the relative B1 field strength
+    voxel_shape : str
+        Can be one of ``["sinc", "exact_sinc", "box", "gauss"]``
+    voxel_size : torch.Tensor
+        3-element tensor containing the size of a voxel
+    """
+
+    def __init__(self,
+                 pos: list[list[float]] | torch.Tensor,
+                 PD: float | list[float] | torch.Tensor = 1.0,
+                 T1: float | list[float] | torch.Tensor = 1.5,
+                 T2: float | list[float] | torch.Tensor = 0.1,
+                 T2dash: float | list[float] | torch.Tensor = 0.05,
+                 D: float | list[float] | torch.Tensor = 1,
+                 B0: float | list[float] | torch.Tensor = 0,
+                 B1: float | list[float] | torch.Tensor = 1,
+                 voxel_size=0.1, voxel_shape="sinc"
+                 ) -> None:
+        """Create a phantom consisting of manually placed voxels.
+
+        See :class:`CustomVoxelPhantom` attributes for explanation of the
+        parameters. They can be single floats to set all voxels, or anything
+        that can be converted to a 1D torch.Tensor for individual values for
+        every voxel.
+        """
+        pos = torch.tensor(pos)
+        assert pos.ndim == 2
+        assert pos.shape[1] == 3
+
+        voxel_size = torch.tensor(voxel_size).squeeze()
+        if voxel_size.ndim == 0:
+            voxel_size = torch.full((3, ), voxel_size)
+        assert voxel_size.ndim == 1 and voxel_size.numel() == 3
+
+        assert voxel_shape in ["sinc", "exact_sinc", "box", "gauss"]
+
+        def expand(t) -> torch.Tensor:
+            # Input must either be a scalar or a 1D tensor with the correct len
+            t = torch.tensor(t).squeeze()
+            if t.ndim == 0:
+                return torch.full((pos.shape[0], ), t)
+            elif t.ndim == 1:
+                assert t.numel() == pos.shape[0]
+                return t
+            else:
+                assert False
+
+        self.voxel_pos = pos
+        self.PD = expand(PD)
+        self.T1 = expand(T1)
+        self.T2 = expand(T2)
+        self.T2dash = expand(T2dash)
+        self.D = expand(D)
+        self.B0 = expand(B0)
+        self.B1 = expand(B1)
+        self.voxel_shape = voxel_shape
+        self.voxel_size = voxel_size
+
+    def build(self) -> SimData:
+        """Build a :class:`SimData` instance for simulation."""
+        # TODO: until the dephasing func fix is here, this only works on the
+        # device self.voxel_size happens to be on
+        size = self.voxel_pos.max(0).values - self.voxel_pos.min(0).values
+
+        return SimData(
+            self.PD,
+            self.T1,
+            self.T2,
+            self.T2dash,
+            self.D,
+            self.B0,
+            self.B1[None, :],
+            torch.ones(1, self.PD.numel()),
+            size,
+            self.voxel_pos,
+            torch.tensor([float('inf'), float('inf'), float('inf')]),
+            build_dephasing_func(self.voxel_shape, self.voxel_size),
+            recover_func=lambda d: recover(self.voxel_size, self.voxel_shape, d)
+        )
+
+    def generate_PD_map(self) -> torch.Tensor:
+        """Convenience function for MRTwin_pulseq to generate a PD map."""
+        return self.generate_maps([self.PD, ])[0].abs()[:, :, None]
+
+    def generate_maps(self, props) -> list[torch.Tensor]:
+        # Best way to accurately plot this is to generate a k-space -> FFT
+        # We only render a 2D image with a FOV of 1
+        kx, ky = torch.meshgrid(
+            torch.linspace(-64, 63, 128),
+            torch.linspace(-64, 63, 128),
+        )
+        trajectory = torch.stack([
+            kx.flatten(),
+            ky.flatten(),
+            torch.zeros(kx.numel()),
+        ], dim=1)
+
+        # All voxels have the same shape -> same intra-voxel dephasing
+        dephasing = build_dephasing_func(
+            self.voxel_shape, self.voxel_size
+        )(trajectory, None)
+
+        kspaces = [torch.zeros(128, 128, dtype=torch.cfloat) for _ in range(len(props))]
+        # Iterate over all voxels and render them into the kspaces
+        for pos in self.voxel_pos:
+            rot = torch.exp(-2j*pi * (trajectory @ pos))
+            
+            for i in range(len(props)):
+                kspaces[i] += props[i] * (rot * dephasing).view(128, 128)
+        
+        # FFT the rendered k-spaces to get the maps
+        norm = self.voxel_size[0] * self.voxel_size[1] # 2D plot, ignore thickness
+        return [
+            torch.fft.fftshift(torch.fft.ifft2(kspace * norm, norm="forward"))
+            for kspace in kspaces
+        ]
+
+    def plot(self) -> None:
+        """Print and plot all data stored in this phantom."""
+        maps = self.generate_maps([self.PD, self.T1, self.T2, self.T2dash, self.D])
+        titles = ["PD", "T1", "T2", "T2'", "D"]
+
+        print("CustomVoxelPhantom")
+        print(f"Voxel shape: {self.voxel_shape}")
+        print(f"Voxel size: {self.voxel_size}")
+        plt.figure(figsize=(12, 6))
+        for i in range(5):
+            plt.subplot(231 + i)
+            plt.title(titles[i])
+            plt.imshow(maps[i].abs().T, origin="lower", vmin=0)
+            plt.xticks([-0.5, 63.5, 127.5], [-1, 0, 1])
+            plt.yticks([-0.5, 63.5, 127.5], [-1, 0, 1])
+            plt.grid()
+            plt.colorbar()
+        plt.show()
+
+
+# TODO: dephasing funcs can store tensors that need to switch device on demand.
+# Maybe it is necessary to make a dephasing func class that can do that.
+def build_dephasing_func(shape: str, size: torch.Tensor,
+                         ) -> Callable[[torch.Tensor, torch.Tensor], torch.Tensor]:
+    """Helper function to get the correct dephasing function."""
+    if shape == "sinc":
+        return lambda t, _: sigmoid(t, size)
+    elif shape == "exact_sinc":
+        return lambda t, _: heaviside(t, size)
+    elif shape == "box":
+        return lambda t, _: sinc(t, size)
+    elif shape == "gauss":
+        return lambda t, _: gauss(t, size)
+    else:
+        raise ValueError("shape not implemented:", self.voxel_shape)
+
+
+def recover(voxel_size: torch.Tensor, voxel_shape: str, sim_data: SimData
+            ) -> CustomVoxelPhantom:
+    """Provided to :class:`SimData` to reverse the ``build()``"""
+    # We don't recover B0, B1 and coil_sens per design - but that could change
+    return CustomVoxelPhantom(
+        # These can be taken directly from the phantom
+        sim_data.voxel_pos.cpu(),
+        sim_data.PD.cpu(),
+        sim_data.T1.cpu(),
+        sim_data.T2.cpu(),
+        sim_data.T2dash.cpu(),
+        sim_data.D.cpu(),
+        0,  # B0
+        1,  # B1
+        # These must be provided (captured in the recover_func lambda)
+        voxel_size,
+        voxel_shape
+    )