mrzerocore 0.2.5__cp37-abi3-win_amd64.whl → 0.2.7__cp37-abi3-win_amd64.whl

MRzeroCore/__init__.py

@@ -2,12 +2,13 @@ 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 import brainweb
+from .phantom.brainweb import generate_brainweb_phantoms
 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 .reconstruction import reco_adjoint
 from .pulseq.exporter import pulseq_write_cartesian
+
 # Currently not exposed directly as it is not required by typical use cases
 # and also not documented. Used internally by Sequence.from_seq_file.
 # Might re-expose later as it contains sequence plotting functionality

MRzeroCore/phantom/brainweb/__init__.py

@@ -1,31 +1,167 @@
-# The brainweb script contains tools for handling with Brainweb itself.
-# Because the API is not final yet, we just expose the very basic
-# download functionality here.
+from typing import Literal
+import json
+import gzip
+import requests
 import os
-from . import brainweb
-from .brainweb import SUBJECTS
+import numpy as np
+# from perlin_numpy import generate_perlin_noise_3d
 
 
-def generate_phantom(
-        subject: int,
-        output: str = os.path.join(os.getcwd(), "brainweb"),
-        scale: int = 1
-        ):
-    """Generate an mr0 phantom from BrainWeb data.
+# Load the brainweb data file that contains info about tissues, subjects, ...
+brainweb_data_path = os.path.join(os.path.dirname(os.path.realpath(__file__)),
+                                  "brainweb_data.json")
+brainweb_data = json.load(open(brainweb_data_path))
 
-    Downloads segmentation data from https://brainweb.bic.mni.mcgill.ca/
-    and fills it with literature T1, T2, ... data to generate an mr0 phantom.
+
+def load_tissue(subject: int, alias: str, cache_dir: str) -> np.ndarray:
+    download_alias = f"subject{subject:02d}_{alias}"
+    file_name = download_alias + ".i8.gz"  # 8 bit signed int, gnuzip
+    file_path = os.path.join(cache_dir, file_name)
+
+    # Download and cache file if it doesn't exist yet
+    if not os.path.exists(file_path):
+        print(f"Downloading '{download_alias}'", end="", flush=True)
+        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)
+        print(" - ", end="")
+
+    # Load the raw BrainWeb data and add it to the return array
+    with gzip.open(file_path) as f:
+        print(f"Loading {os.path.basename(file_path)}", end="", flush=True)
+        # 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
+    data = tmp.reshape(362, 434, 362).swapaxes(0, 2).astype(np.float32)
+
+    print(" - done")
+    return data / 255.0
+
+
+def gen_noise(range: float, res: np.ndarray) -> np.ndarray:
+    if range == 0:
+        return 1
+    else:
+        freq = 20
+        padded_res = (res + freq - 1) // freq * freq
+        # noise = generate_perlin_noise_3d(padded_res, (freq, freq, freq))
+        noise = np.random.random(padded_res)
+        return 1 + range * noise[:res[0], :res[1], :res[2]]
+
+
+def downsample(array: np.ndarray, factor: int) -> np.ndarray:
+    # crop array to multiple of factor
+    shape = (np.array(array.shape) // factor) * factor
+    array = array[:shape[0], :shape[1], :shape[2]]
+
+    tmp = np.zeros(shape // factor)
+    for x in range(factor):
+        for y in range(factor):
+            for z in range(factor):
+                tmp += array[x::factor, y::factor, z::factor]
+
+    return tmp / factor**3
+
+
+def generate_brainweb_phantoms(
+        output_dir: str,
+        config: Literal["3T", "7T-noise", "3T-highres-fat"] = "3T"):
+    """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/
+
+    All tissue data etc. are stored in `brainweb_data.json`. To ensure
+    consistent configurations and reproducible results, available configs are
+    stored in this file as well. They specify which field strength to use,
+    which tissues to include, as well as the downsampling and noise levels.
+
+    The emitted files are compressed numpy files, which can be loaded with
+    `np.load(file_name)`. They contain the following arrays:
+
+     - `PD_map`: Proton Density [a.u.]
+     - `T1_map`: T1 relaxation time [s]
+     - `T2_map`: T2 relaxation time [s]
+     - `T2dash_map`: T2' relaxation time [s]
+     - `D_map`: Isotropic Diffusion coefficient [10^-3 mm² / s]
+     - `tissue_XY`: Tissue segmentation for all included tissues
 
     Parameters
     ----------
-    subject : int
-        Subject ID. Use `mr0.brainweb.SUBJECTS` for a list of valid ID.
-    output : str
-        Path to output folder for the resulting phantoms ('subjectXX.npz').
-        Will also be used to cache the downloaded segmentation data.
-    scale : int
-        Amount of downsampling, e.g., a value of 2 will produce half-res data.
+    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.
+    config: ["3T", "7T-noise", "3T-highres-fat"]
+        The configuration for which the maps are generated.
     """
-    brainweb.CACHE_PATH = output
-    phantom = brainweb.Phantom.load(subject, scale)
-    phantom.save()
+    config_data = brainweb_data["configs"][config]
+    cache_dir = os.path.join(output_dir, "cache")
+
+    try:
+        os.makedirs(cache_dir)
+    except FileExistsError:
+        pass
+
+    # Map resolution:
+    res = np.array([362, 434, 362]) // config_data["downsample"]
+
+    def noise() -> np.ndarray:
+        return gen_noise(config_data["noise"], res)
+
+    for subject in brainweb_data["subjects"]:
+        print(f"Generating '{config}', subject {subject}")
+        maps = {
+            "FOV": np.array([0.181, 0.217, 0.181]),
+            "PD_map": np.zeros(res, dtype=np.float32),
+            "T1_map": np.zeros(res, dtype=np.float32),
+            "T2_map": np.zeros(res, dtype=np.float32),
+            "T2dash_map": np.zeros(res, dtype=np.float32),
+            "D_map": np.zeros(res, dtype=np.float32),
+        }
+
+        for tissue in config_data["tissues"]:
+            tissue_map = sum([
+                load_tissue(subject, alias, cache_dir)
+                for alias in brainweb_data["download-aliases"][tissue]
+            ])
+            tissue_map = downsample(tissue_map, config_data["downsample"])
+            maps["tissue_" + tissue] = tissue_map
+
+            field_strength = config_data["field-strength"]
+            tissue_data = brainweb_data["tissues"][field_strength][tissue]
+
+            # Separate noise maps is slower but uncorrelated.
+            # Might be better for training or worse - could be configurable
+            print("Adding tissue to phantom", end="", flush=True)
+            maps["PD_map"] += tissue_data["PD"] * tissue_map * noise()
+            maps["T1_map"] += tissue_data["T1"] * tissue_map * noise()
+            maps["T2_map"] += tissue_data["T2"] * noise()
+            maps["T2dash_map"] += tissue_data["T2'"] * tissue_map * noise()
+            maps["D_map"] += tissue_data["D"] * tissue_map * noise()
+            print(" - done")
+
+        file = os.path.join(output_dir, f"subject{subject:02d}_{config}.npz")
+        print(f"Saving to '{os.path.basename(file)}'", end="", flush=True)
+        np.savez_compressed(file, **maps)
+        print(" - done\n")
+
+
+if __name__ == "__main__":
+    print("This is for testing only, use generate_brainweb_phantoms directly!")
+    file_dir = os.path.dirname(os.path.realpath(__file__))
+    output_dir = os.path.join(file_dir, "output")
+
+    for config in brainweb_data["configs"].keys():
+        generate_brainweb_phantoms(output_dir, config)

MRzeroCore/phantom/brainweb/brainweb_data.json

@@ -0,0 +1,93 @@
+{
+  "configs": {
+    "3T": {
+      "field-strength": "3T",
+      "tissues": ["gm", "wm", "csf"],
+      "downsample": 3,
+      "noise": 0
+    },
+    "7T-noise": {
+      "field-strength": "7T",
+      "tissues": ["gm", "wm", "csf"],
+      "downsample": 3,
+      "noise": 0.2
+    },
+    "3T-highres-fat": {
+      "field-strength": "3T",
+      "tissues": ["gm", "wm", "csf", "fat"],
+      "downsample": 1,
+      "noise": 0
+    }
+  },
+  "subjects": [
+    4, 5, 6, 18, 20, 38, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54
+  ],
+  "download-aliases": {
+    "gm": ["gry"],
+    "wm": ["wht"],
+    "csf": ["csf", "ves"],
+    "fat": ["fat", "mus", "m-s", "dura", "fat2"]
+  },
+  "tissues": {
+    "3T": {
+      "gm": {
+        "PD": 0.8,
+        "T1": 1.56,
+        "T2": 0.0083,
+        "T2'": 0.32,
+        "D": 0.83
+      },
+      "wm": {
+        "PD": 0.7,
+        "T1": 0.83,
+        "T2": 0.075,
+        "T2'": 0.18,
+        "D": 0.65
+      },
+      "csf": {
+        "PD": 1,
+        "T1": 4.16,
+        "T2": 1.65,
+        "T2'": 0.059,
+        "D": 3.19
+      },
+      "fat": {
+        "PD": 1,
+        "T1": 0.37,
+        "T2": 0.125,
+        "T2'": 0.012,
+        "D": 0.1
+      }
+    },
+    "7T": {
+      "gm": {
+        "PD": 0.8,
+        "T1": 1.67,
+        "T2": 0.043,
+        "T2'": 0.82,
+        "D": 0.83
+      },
+      "wm": {
+        "PD": 0.7,
+        "T1": 1.22,
+        "T2": 0.037,
+        "T2'": 0.65,
+        "D": 0.65
+      },
+      "csf": {
+        "PD": 1,
+        "T1": 4.0,
+        "T2": 0.8,
+        "T2'": 0.204,
+        "D": 3.19
+      },
+      "fat": {
+        "PD": 1,
+        "T1": 0.374,
+        "T2": 0.125,
+        "T2'": 0.0117,
+        "D": 0.1
+      }
+    }
+  }
+}

MRzeroCore/phantom/brainweb/{phantom_values.txt → brainweb_data_sources.txt}

@@ -1,3 +1,8 @@
+! 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)

MRzeroCore/phantom/sim_data.py

@@ -32,9 +32,9 @@ class SimData:
         (coil_count, voxel_count) Per coil and per voxel B1 inhomogenity
     coil_sens : torch.Tensor
         (coil_count, voxel_count) Per coil sensitivity (arbitrary units)
-    fov : torch.Tensor
-        Physical size of the phantom, needed for diffusion (meters).
-        More specifically, a gradient moment of 1 has a wavelength of fov
+    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
@@ -60,7 +60,7 @@ class SimData:
         B0: torch.Tensor,
         B1: torch.Tensor,
         coil_sens: torch.Tensor,
-        fov: torch.Tensor,
+        size: torch.Tensor,
         voxel_pos: torch.Tensor,
         nyquist: torch.Tensor,
         dephasing_func: Callable[[torch.Tensor, torch.Tensor], torch.Tensor],
@@ -93,7 +93,7 @@ class SimData:
         self.B0 = B0.clone()
         self.B1 = B1.clone()
         self.coil_sens = coil_sens.clone()
-        self.fov = fov.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()
@@ -115,7 +115,7 @@ class SimData:
             self.B0.cuda(),
             self.B1.cuda(),
             self.coil_sens.cuda(),
-            self.fov.cuda(),
+            self.size.cuda(),
             self.voxel_pos.cuda(),
             self.nyquist.cuda(),
             self.dephasing_func,
@@ -137,7 +137,7 @@ class SimData:
             self.B0.cpu(),
             self.B1.cpu(),
             self.coil_sens.cpu(),
-            self.fov.cpu(),
+            self.size.cpu(),
             self.voxel_pos.cpu(),
             self.nyquist.cpu(),
             self.dephasing_func,

MRzeroCore/phantom/voxel_grid_phantom.py

@@ -1,4 +1,5 @@
 from __future__ import annotations
+from typing import Literal
 from scipy import io
 import numpy as np
 import torch
@@ -42,13 +43,6 @@ class VoxelGridPhantom:
     As it is bandwidth limited, we assume that there is no signal above the
     Nyquist frequency. This leads to the usage of sinc-shaped voxels.
 
-    This phantom has two FOVs: ``base_fov`` encodes the physical size in meters
-    and is set on load. ``rel_fov`` is initially 1 and is changed by some
-    operations like reducing the phantom to a few slices. This allows to either
-    use only ``rel_fov`` in the simulation so that the sequence can still
-    assume an FOV of 1, or to use ``base_fov * rel_fov`` and use SI units in
-    the sequence definition.
-
     Attributes
     ----------
     PD : torch.Tensor
@@ -67,10 +61,8 @@ class VoxelGridPhantom:
         (coil_count, sx, sy, sz) tensor of RF coil profiles
     coil_sens : torch.Tensor
         (coil_count, sx, sy, sz) tensor of coil sensitivities
-    base_fov : torch.Tensor
-        Base size of the original loaded data, in meters.
-    rel_fov : torch.Tensor
-        Actual phantom size relative to ``base_fov``.
+    size : torch.Tensor
+        Size of the data, in meters.
     """
 
     def __init__(
@@ -83,8 +75,7 @@ class VoxelGridPhantom:
         B0: torch.Tensor,
         B1: torch.Tensor,
         coil_sens: torch.Tensor,
-        base_fov: torch.Tensor,
-        rel_fov: torch.Tensor,
+        size: torch.Tensor,
     ) -> None:
         """Set the phantom attributes to the provided parameters.
 
@@ -99,30 +90,31 @@ class VoxelGridPhantom:
         self.B0 = B0
         self.B1 = B1
         self.coil_sens = coil_sens
-        self.base_fov = base_fov
-        self.rel_fov = rel_fov
+        self.size = size
 
     def build(self, PD_threshold: float = 1e-6,
-              use_SI_FoV: bool = False, voxel_shape="sinc") -> SimData:
+              voxel_shape: Literal["sinc", "box", "point"] = "sinc"
+              ) -> SimData:
         """Build a :class:`SimData` instance for simulation.
 
         Arguments
         ---------
-        PD_threshold: float
+        PD_threshold : float
             All voxels with a proton density below this value are ignored.
-        use_SI_FoV: bool
-            If set to ``True``, the built :class:`SimData` will use its
-            physical size in meters. If set to ``False``, the ``rel_fov`` is
-            used, which means a sequence FOV of 1 is assumed.
         """
         mask = self.PD > PD_threshold
 
-        fov = (self.base_fov * self.rel_fov) if use_SI_FoV else (self.rel_fov)
         shape = torch.tensor(mask.shape)
         pos_x, pos_y, pos_z = torch.meshgrid(
-            fov[0] * torch.fft.fftshift(torch.fft.fftfreq(int(shape[0]), device=self.PD.device)),
-            fov[1] * torch.fft.fftshift(torch.fft.fftfreq(int(shape[1]), device=self.PD.device)),
-            fov[2] * torch.fft.fftshift(torch.fft.fftfreq(int(shape[2]), device=self.PD.device)),
+            self.size[0] *
+            torch.fft.fftshift(torch.fft.fftfreq(
+                int(shape[0]), device=self.PD.device)),
+            self.size[1] *
+            torch.fft.fftshift(torch.fft.fftfreq(
+                int(shape[1]), device=self.PD.device)),
+            self.size[2] *
+            torch.fft.fftshift(torch.fft.fftfreq(
+                int(shape[2]), device=self.PD.device)),
         )
 
         voxel_pos = torch.stack([
@@ -132,11 +124,11 @@ class VoxelGridPhantom:
         ], dim=1)
 
         if voxel_shape == "box":
-            dephasing_func = lambda t, n: sinc(t, 0.5 / n)
+            def dephasing_func(t, n): return sinc(t, 0.5 / n)
         elif voxel_shape == "sinc":
-            dephasing_func = lambda t, n: sigmoid(t, n)
+            def dephasing_func(t, n): return sigmoid(t, n)
         elif voxel_shape == "point":
-            dephasing_func = lambda t, _: identity(t)
+            def dephasing_func(t, _): return identity(t)
         else:
             raise ValueError(f"Unsupported voxel shape '{voxel_shape}'")
 
@@ -149,11 +141,12 @@ class VoxelGridPhantom:
             self.B0[mask],
             self.B1[:, mask],
             self.coil_sens[:, mask],
-            self.base_fov * self.rel_fov,  # Always SI, only used for diffusion
+            self.size,
             voxel_pos,
-            torch.tensor(shape, device=self.PD.device) / 2 / fov,
+            torch.tensor(shape, device=self.PD.device) / 2 / self.size,
             dephasing_func,
-            recover_func=lambda d: recover(mask, self.base_fov, self.rel_fov, d)
+            recover_func=lambda d: recover(
+                mask, self.base_fov, self.rel_fov, d)
         )
 
     @classmethod
@@ -182,11 +175,14 @@ class VoxelGridPhantom:
         B0 -= (B0 * weight).sum()
         B1 /= (B1 * weight).sum()
 
+        try:
+            size = torch.tensor(data['FOV'])
+        except KeyError:
+            size = torch.tensor([0.192, 0.192, 0.192])
+
         return cls(
             PD, T1, T2, T2dash, D, B0, B1[None, ...],
-            coil_sens=torch.ones(1, *PD.shape),
-            base_fov=torch.tensor([0.192, 0.192, 0.192]),
-            rel_fov=torch.ones(3)
+            torch.ones(1, *PD.shape), size,
         )
 
     @classmethod
@@ -255,8 +251,7 @@ class VoxelGridPhantom:
             data[..., 3],  # B0
             data[..., 4][None, ...],  # B1
             coil_sens=torch.ones(1, *data.shape[:-1]),
-            base_fov=torch.tensor([0.2, 0.2, 0.008]),
-            rel_fov=torch.ones(3)
+            size=torch.tensor([0.2, 0.2, 0.008]),
         )
 
     def slices(self, slices: list[int]) -> VoxelGridPhantom:
@@ -274,9 +269,6 @@ class VoxelGridPhantom:
         """
         assert 0 <= any([slices]) < self.PD.shape[2]
 
-        # fov = self.rel_fov.clone()
-        # fov[2] *= len(slices) / self.PD.shape[2]
-
         def select(tensor: torch.Tensor):
             return tensor[..., slices].view(
                 *list(self.PD.shape[:2]), len(slices)
@@ -291,8 +283,7 @@ class VoxelGridPhantom:
             select(self.B0),
             select(self.B1).unsqueeze(0),
             select(self.coil_sens).unsqueeze(0),
-            self.base_fov.clone(),
-            self.rel_fov.clone(),
+            self.size.clone(),
         )
 
     def scale_fft(self, x: int, y: int, z: int) -> VoxelGridPhantom:
@@ -331,8 +322,7 @@ class VoxelGridPhantom:
             scale(self.B0),
             scale(self.B1.squeeze()).unsqueeze(0),
             scale(self.coil_sens.squeeze()).unsqueeze(0),
-            self.base_fov.clone(),
-            self.rel_fov.clone(),
+            self.size.clone(),
         )
 
     def interpolate(self, x: int, y: int, z: int) -> VoxelGridPhantom:
@@ -379,17 +369,13 @@ class VoxelGridPhantom:
             resample(self.B0),
             resample_multicoil(self.B1),
             resample_multicoil(self.coil_sens),
-            self.base_fov.clone(),
-            self.rel_fov.clone(),
+            self.size.clone(),
         )
 
     def plot(self) -> None:
         """Print and plot all data stored in this phantom."""
         print("VoxelGridPhantom")
-        print(
-            f"FOV: base * rel = {self.base_fov} * {self.rel_fov} "
-            f"= {self.base_fov * self.rel_fov}"
-        )
+        print(f"size = {self.size}")
         # Center slice
         s = self.PD.shape[2] // 2
         # Warn if we only print a part of all data
@@ -434,39 +420,37 @@ class VoxelGridPhantom:
         plt.imshow(self.coil_sens[0, :, :, s].T.cpu(), vmin=0, origin="lower")
         plt.colorbar()
         plt.show()
-        
+
     def plot3D(self, data2print: int = 0) -> None:
         """Print and plot all slices of one selected data stored in this phantom."""
         print("VoxelGridPhantom")
-        print(
-            f"FOV: base * rel = {self.base_fov} * {self.rel_fov} "
-            f"= {self.base_fov * self.rel_fov}"
-        )
+        print(f"size = {self.size}")
         print()
-        
+
         label = ['PD', 'T1', 'T2', "T2'", "D", "B0", "B1", "coil sens"]
-        
+
         tensors = [
-            self.PD, self.T1, self.T2, self.T2dash, self.D, self.B0, 
+            self.PD, self.T1, self.T2, self.T2dash, self.D, self.B0,
             self.B1.squeeze(0), self.coil_sens
         ]
-        
+
         # Warn if we only print a part of all data
         print(f"Plotting {label[data2print]}")
-        
+
         tensor = tensors[data2print].squeeze(0)
-        
-        util.plot3D(tensor,figsize=(20, 5))
+
+        util.plot3D(tensor, figsize=(20, 5))
         plt.title(label[data2print])
         plt.show()
 
 
-def recover(mask, base_fov, rel_fov, sim_data: SimData) -> VoxelGridPhantom:
+def recover(mask, sim_data: SimData) -> VoxelGridPhantom:
     """Provided to :class:`SimData` to reverse the ``build()``"""
     def to_full(sparse):
         assert sparse.ndim < 3
         if sparse.ndim == 2:
-            full = torch.zeros([sparse.shape[0], *mask.shape])
+            full = torch.zeros(
+                [sparse.shape[0], *mask.shape], dtype=sparse.dtype)
             full[:, mask] = sparse.cpu()
         else:
             full = torch.zeros(mask.shape)
@@ -482,8 +466,7 @@ def recover(mask, base_fov, rel_fov, sim_data: SimData) -> VoxelGridPhantom:
         to_full(sim_data.B0),
         to_full(sim_data.B1),
         to_full(sim_data.coil_sens),
-        base_fov,
-        rel_fov
+        sim_data.size
     )