mrid-python 0.1.3__tar.gz

mrid_python-0.1.3/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: mrid-python
+Version: 0.1.3
+Summary: Tools for working with 3D medical images and segmentations - registration, brain skull-stripping, etc.
+Author-email: Ivan Nikishev <nkshv2@gmail.com>
+Project-URL: Homepage, https://github.com/inikishev/mrid
+Project-URL: Repository, https://github.com/inikishev/mrid
+Project-URL: Issues, https://github.com/inikishev/mrid/isses
+Keywords: MRI,medical imaging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy
+Requires-Dist: SimpleITK
+
+<h1 align='center'>mrid</h1>
+
+mrid is a library for preprocessing of 3D images, particularly medical images.
+
+`mrid.Study` provides a convenient way to work with scans and provides all the tools (skull-stripping, registration, etc). See [this notebook](https://nbviewer.org/github/inikishev/mrid/blob/main/mrid_tutorial.ipynb) for an example of how to use it ([Google Colab](https://colab.research.google.com/drive/1d1MWPaGAqfK6q_5879LpwwxPCB-tbExe?usp=sharing)).
+
+All methods are also available as separate functions, see below.
+
+## Registering a scan
+
+All methods accept scans that can be a path to NIfTI, DICOM dir, sitk Image, numpy array or torch tensor, and return sitk.Image format.
+
+For registering you need to have SimpleITK-SimpleElastix installed (<https://pypi.org/project/SimpleITK-SimpleElastix/>)
+
+```python
+registered = mrid.register(moving, fixed) # returns sitk.Image
+```
+
+mrid includes downloaders for commonly used templates - MNI152 and SRI24: `mrid.get_mni152`, and `mrid.get_sri24`.
+
+```python
+t1_sri = mrid.register(t1, mrid.get_sri24("T1")) # returns sitk.Image
+```
+
+note you can always convert anything to numpy array using `mrid.tonumpy(src)`:
+
+```python
+t1_sri_np = mrid.tonumpy(t1_sri) # np.array
+```
+
+## Registering multiple scans
+
+If you have multiple scans that are already aligned, you can register one of them and use the same transformation to transform the rest. This can also be used to register segmentations.
+
+In this example we register T1 to SRI24 T1 template, and transform the rest
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+registered_data = mrid.register_D(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of sitk.Image registered to SRI24
+```
+
+If you have multiple scans that are not aligned (e.g. have different shapes, orientations), you can use `register_each`. This registers one scan to the target, and then registers all other scans to the first scan. In the example it registers T1 to SRI24, and then registers T2 and FLAIR to T1.
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+registered_data = mrid.register_each(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of sitk.Image registered to SRI24
+```
+
+## Inverse transform
+
+mrid provides a simple way to compute an inverse of registration, this is also another way to perform registration in general.
+
+```python
+reg = mrid.Registration()
+
+# first we need to fit a transform
+reg.find_transform(t1, mrid.get_sri24("T1"))
+
+# now we can use `reg.apply_transform` to transform any scan (assuming it is aligned to `t1`)
+t2_sri24 = reg.apply_transform(t2) # returns sitk.Image
+
+# use `apply_inverse_transform` to transform back to original space
+t2_recovered = reg.apply_inverse_transform(t2_sri24) # returns sitk.Image
+
+# when transforming segmentations, use nearest
+# neigbour interpolation to preserve edges
+seg = (mrid.tonumpy(t2_sri24) > 100).astype(np.uint8)
+seg_orig = reg.apply_inverse_transform(seg, use_nearest_interpolation=True) # returns sitk.Image
+```
+
+## Skullstripping
+
+For skullstripping mrid uses HD-BET model (<https://github.com/MIC-DKFZ/HD-BET>), and you need to have it installed (it uses torch). It works with pre/post contrast T1, T2 and FLAIR MRIs, but it expects them to be in MNI152 space (while many new datasets like BraTS are in SRI24). If your scans aren't in MNI152, the `skullstrip` function can register specified scan to MNI152, pass it to HD-BET, and then register back to original space, if `register_to_mni152` argument is specified.
+
+```python
+t1_skullstripped = mrid.skullstrip(t1) # if t1 is in MNI152
+t1_skullstripped = mrid.skullstrip(t1, register_to_mni152="T1") # if t1 is not in MNI152
+```
+
+HD-BET is generally very robust but it can remove parts of tumors adjascent to the skull, but this is true for all skullstripping tools.
+
+## Skullstripping multiple scans
+
+If you have multiple scans that are already aligned, you can compute brain mask on one of them (ideally post-contrast T1) and apply it to all scans.
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+skullstripped_data = mrid.skullstrip_D(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of skullstripped sitk.Image
+```
+
+## dcm2niix
+
+mrid provides a simple wrapper around [dcm2niix](https://github.com/rordenlab/dcm2niix), which is a very robust tool for converting DICOMs to NIfTI.
+
+```python
+# this saves output.nii.gz to output_path. It can save multiple files if there are multiple cases in "path/to/dicoms".
+mrid.utils.run_dcm2niix("path/to/dicoms", outfolder="output_path", outfname="output")
+```
+
+If you want to use it convert DICOMs directly to SimpleITK, use `dcm2sitk`:
+
+```python
+t1 = mrid.utils.dcm2sitk("path/to/dicoms") # returns sitk.Image with correct spatial information
+```
+dcm2niix is much slower compared to SimpleITK's series reader which mrid uses by default, but it's more careful about splitting different studies to different files, although it might fail with malformed DICOMs which are surprisingly common (where it would think each slice is a separate study).
+
+## Loading STL segmentations
+
+`stl2sitk` converts segmentations in STL format to `sitk.Image` given a reference `sitk.Image` that the STL should be aligned to. Basically something I encountered so I had to make this.
+
+```python
+seg = mrid.utils.stl2sitk("path/to/file.stl", reference) # returns sitk.Image (hopefully) aligned with `reference`
+```
+
+## How to install
+Either run
+```
+pip install mrid-python
+```
+or
+```
+pip install git+https://github.com/inikishev/mrid
+```

mrid_python-0.1.3/README.md

@@ -0,0 +1,126 @@
+<h1 align='center'>mrid</h1>
+
+mrid is a library for preprocessing of 3D images, particularly medical images.
+
+`mrid.Study` provides a convenient way to work with scans and provides all the tools (skull-stripping, registration, etc). See [this notebook](https://nbviewer.org/github/inikishev/mrid/blob/main/mrid_tutorial.ipynb) for an example of how to use it ([Google Colab](https://colab.research.google.com/drive/1d1MWPaGAqfK6q_5879LpwwxPCB-tbExe?usp=sharing)).
+
+All methods are also available as separate functions, see below.
+
+## Registering a scan
+
+All methods accept scans that can be a path to NIfTI, DICOM dir, sitk Image, numpy array or torch tensor, and return sitk.Image format.
+
+For registering you need to have SimpleITK-SimpleElastix installed (<https://pypi.org/project/SimpleITK-SimpleElastix/>)
+
+```python
+registered = mrid.register(moving, fixed) # returns sitk.Image
+```
+
+mrid includes downloaders for commonly used templates - MNI152 and SRI24: `mrid.get_mni152`, and `mrid.get_sri24`.
+
+```python
+t1_sri = mrid.register(t1, mrid.get_sri24("T1")) # returns sitk.Image
+```
+
+note you can always convert anything to numpy array using `mrid.tonumpy(src)`:
+
+```python
+t1_sri_np = mrid.tonumpy(t1_sri) # np.array
+```
+
+## Registering multiple scans
+
+If you have multiple scans that are already aligned, you can register one of them and use the same transformation to transform the rest. This can also be used to register segmentations.
+
+In this example we register T1 to SRI24 T1 template, and transform the rest
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+registered_data = mrid.register_D(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of sitk.Image registered to SRI24
+```
+
+If you have multiple scans that are not aligned (e.g. have different shapes, orientations), you can use `register_each`. This registers one scan to the target, and then registers all other scans to the first scan. In the example it registers T1 to SRI24, and then registers T2 and FLAIR to T1.
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+registered_data = mrid.register_each(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of sitk.Image registered to SRI24
+```
+
+## Inverse transform
+
+mrid provides a simple way to compute an inverse of registration, this is also another way to perform registration in general.
+
+```python
+reg = mrid.Registration()
+
+# first we need to fit a transform
+reg.find_transform(t1, mrid.get_sri24("T1"))
+
+# now we can use `reg.apply_transform` to transform any scan (assuming it is aligned to `t1`)
+t2_sri24 = reg.apply_transform(t2) # returns sitk.Image
+
+# use `apply_inverse_transform` to transform back to original space
+t2_recovered = reg.apply_inverse_transform(t2_sri24) # returns sitk.Image
+
+# when transforming segmentations, use nearest
+# neigbour interpolation to preserve edges
+seg = (mrid.tonumpy(t2_sri24) > 100).astype(np.uint8)
+seg_orig = reg.apply_inverse_transform(seg, use_nearest_interpolation=True) # returns sitk.Image
+```
+
+## Skullstripping
+
+For skullstripping mrid uses HD-BET model (<https://github.com/MIC-DKFZ/HD-BET>), and you need to have it installed (it uses torch). It works with pre/post contrast T1, T2 and FLAIR MRIs, but it expects them to be in MNI152 space (while many new datasets like BraTS are in SRI24). If your scans aren't in MNI152, the `skullstrip` function can register specified scan to MNI152, pass it to HD-BET, and then register back to original space, if `register_to_mni152` argument is specified.
+
+```python
+t1_skullstripped = mrid.skullstrip(t1) # if t1 is in MNI152
+t1_skullstripped = mrid.skullstrip(t1, register_to_mni152="T1") # if t1 is not in MNI152
+```
+
+HD-BET is generally very robust but it can remove parts of tumors adjascent to the skull, but this is true for all skullstripping tools.
+
+## Skullstripping multiple scans
+
+If you have multiple scans that are already aligned, you can compute brain mask on one of them (ideally post-contrast T1) and apply it to all scans.
+
+```python
+data = {"t1": "t1c.nii.gz", "t2": "t2w.nii.gz", "flair": "t2f.nii.gz"}
+skullstripped_data = mrid.skullstrip_D(data, key="t1", to=mrid.get_sri24("T1"))
+# dict of skullstripped sitk.Image
+```
+
+## dcm2niix
+
+mrid provides a simple wrapper around [dcm2niix](https://github.com/rordenlab/dcm2niix), which is a very robust tool for converting DICOMs to NIfTI.
+
+```python
+# this saves output.nii.gz to output_path. It can save multiple files if there are multiple cases in "path/to/dicoms".
+mrid.utils.run_dcm2niix("path/to/dicoms", outfolder="output_path", outfname="output")
+```
+
+If you want to use it convert DICOMs directly to SimpleITK, use `dcm2sitk`:
+
+```python
+t1 = mrid.utils.dcm2sitk("path/to/dicoms") # returns sitk.Image with correct spatial information
+```
+dcm2niix is much slower compared to SimpleITK's series reader which mrid uses by default, but it's more careful about splitting different studies to different files, although it might fail with malformed DICOMs which are surprisingly common (where it would think each slice is a separate study).
+
+## Loading STL segmentations
+
+`stl2sitk` converts segmentations in STL format to `sitk.Image` given a reference `sitk.Image` that the STL should be aligned to. Basically something I encountered so I had to make this.
+
+```python
+seg = mrid.utils.stl2sitk("path/to/file.stl", reference) # returns sitk.Image (hopefully) aligned with `reference`
+```
+
+## How to install
+Either run
+```
+pip install mrid-python
+```
+or
+```
+pip install git+https://github.com/inikishev/mrid
+```

mrid_python-0.1.3/mrid/__init__.py

@@ -0,0 +1,5 @@
+from . import utils
+from .atlas import get_mni152, get_sri24
+from .preprocessing import *
+from .loading import *
+from .study import Study

mrid_python-0.1.3/mrid/atlas/MNI152/__init__.py

@@ -0,0 +1,80 @@
+# https://zenodo.org/api/records/15470657/files-archive
+
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+__all__ = [
+    "get_mni152",
+]
+
+_ROOT = Path(os.path.dirname(__file__))
+
+_URLS = {
+    "2006 T1w symmetric": (
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_06_sym.nii.gz?download=1",
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_06_sym_bet.nii.gz?download=1",
+    ),
+    "2009a T1w symmetric": (
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_09a_sym.nii.gz?download=1",
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_09a_sym_bet.nii.gz?download=1",
+    ),
+    "2009a T2w symmetric": (
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t2_09a_sym.nii.gz?download=1",
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t2_09a_sym_bet.nii.gz?download=1",
+    ),
+    "2009a T1w asymmetric": (
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_09a_asym.nii.gz?download=1",
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t1_09a_asym_bet.nii.gz?download=1",
+    ),
+    "2009a T2w asymmetric": (
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t2_09a_asym.nii.gz?download=1",
+        "https://zenodo.org/records/15470657/files/icbm_mni152_t2_09a_asym_bet.nii.gz?download=1",
+    ),
+}
+
+_mni152_url = "https://zenodo.org/records/15470657/files/icbm_mni152_t1_06_sym_bet.nii.gz?download=1"
+
+def _download_template(type: str, bet:bool):
+    filename = f"{type} {bool(bet)}.nii.gz"
+    if filename in os.listdir(_ROOT):
+        raise RuntimeError(f"Template {type} is already downloaded")
+
+    import requests
+
+    response = requests.get(_URLS[type][bet], stream=True, timeout=30)
+    response.raise_for_status()
+
+    with open(_ROOT / f"{filename}", 'wb') as file:
+        shutil.copyfileobj(response.raw, file) # type:ignore
+
+def get_mni152(
+    type: Literal[
+        "2006 T1w symmetric",
+        "2009a T1w symmetric",
+        "2009a T2w symmetric",
+        "2009a T1w asymmetric",
+        "2009a T2w asymmetric",
+    ],
+    skullstripped: bool = False,
+):
+    """Returns path to .nii.gz file of specified MNI-152 template.
+
+    Descriptions of templates are available here https://zenodo.org/records/15470657
+    """
+    filename = f"{type} {bool(skullstripped)}.nii.gz"
+
+    if filename in os.listdir(_ROOT):
+        return str(_ROOT / filename)
+
+    print(f"{filename} will be downloaded from https://zenodo.org/records/15470657, this may take a few minutes.")
+    _download_template(type, skullstripped)
+
+    if filename not in os.listdir(_ROOT):
+        raise RuntimeError(
+            f"Failed to download {filename}; try downloading it manually from https://zenodo.org/records/15470657"
+        )
+
+    return str(_ROOT / filename)

mrid_python-0.1.3/mrid/atlas/SRI24/__init__.py

@@ -0,0 +1,77 @@
+"""This subpackage allows one to download SRI-24 brain atlas files from https://www.nitrc.org/projects/sri24/.
+
+The SRI24 atlas is licensed under the terms of the
+
+  Creative Commons Attribution-ShareAlike 3.0 Unported (CC BY-SA 3.0)
+
+license (https://creativecommons.org/licenses/by-...).
+
+In publications using the SRI24 atlas, please cite the following paper:
+
+  T. Rohlfing, N.M. Zahr, E.V. Sullivan, A. Pfefferbaum, "The SRI24
+  Multichannel Atlas of Normal Adult Human Brain Structure," Human
+  Brain Mapping, vol. 31, no. 5, pp. 798-819, 2010.
+
+  http://dx.doi.org/10.1002/hbm.20906
+
+"""
+import os
+import shutil
+import tempfile
+from pathlib import Path
+from typing import Literal
+
+__all__ = [
+    "get_sri24",
+]
+
+_ROOT = Path(os.path.dirname(__file__))
+
+_sri24_url = "https://www.nitrc.org/frs/download.php/4841/sri24_spm8.zip//?i_agree=1&download_now=1"
+
+def _download_sri24() -> None:
+    import requests
+
+    response = requests.get(_sri24_url, stream=True, timeout=30)
+    response.raise_for_status()
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        tmpdir = Path(tmpdir)
+        with open(tmpdir / "sri24_spm8.zip", 'wb') as file:
+            shutil.copyfileobj(response.raw, file) # type:ignore
+
+        shutil.unpack_archive(tmpdir / "sri24_spm8.zip", tmpdir / "sri24_spm8")
+
+        for file in os.listdir(tmpdir / "sri24_spm8" / "templates"):
+            shutil.copyfile(tmpdir / "sri24_spm8" / "templates" / file, _ROOT / file)
+
+
+def get_sri24(type: Literal["EPI", "EPI_brain", "PD", "PD_brain", "T1", "T1_brain", "T2", "T2_brain"]) -> str:
+    """Returns path to .nii file of specified SRI-24 template. Templates are downloaded if they haven't been downloaded already.
+
+    The following templates are available:
+    - `"T1"`: post-contrast T1-weighted MRI with skull;
+    - `"T1_brain"`: post-contrast T1-weighted MRI without skull;
+    - `"T2"`: T2-weighted MRI with skull;
+    - `"T2_brain"`: T2-weighted MRI without skull;
+    - `"EPI"`: echo-planar imaging MRI with skull;
+    - `"EPI_brain"`: echo-planar imaging MRU without skull;
+    - `"PD"`: proton density weighted spin-echo imaging MRI with skull;
+    - `"PD_brain"`: proton density weighted spin-echo imaging MRI without skull;
+
+    """
+    filename = f"{type}.nii"
+    if filename in os.listdir(_ROOT):
+        return str(_ROOT / filename)
+
+    print("SRI24 will be downloaded from https://www.nitrc.org/projects/sri24/, this may take a few minutes.")
+    _download_sri24()
+
+    if filename not in os.listdir(_ROOT):
+        raise RuntimeError(
+            f"Failed to download {filename}; try downloading it manually from https://www.nitrc.org/projects/sri24/, "
+            "then unpack the zip file, open it, open `templates` folder, you will see files such as `EPI.nii`. "
+            f"Copy all of those files to {_ROOT}."
+        )
+
+    return str(_ROOT / filename)

mrid_python-0.1.3/mrid/atlas/__init__.py

@@ -0,0 +1,7 @@
+from . MNI152 import get_mni152
+from .SRI24 import get_sri24
+
+__all__ = [
+    "get_mni152",
+    "get_sri24",
+]

mrid_python-0.1.3/mrid/loading/__init__.py

@@ -0,0 +1 @@
+from .convert import tonumpy, tositk, totensor, ImageLike

mrid_python-0.1.3/mrid/loading/convert.py

@@ -0,0 +1,68 @@
+import importlib.util
+import os
+from typing import TYPE_CHECKING, TypeAlias
+
+import numpy as np
+import SimpleITK as sitk
+
+from ..utils.torch_utils import TORCH_INSTALLED
+
+if TYPE_CHECKING:
+    import torch
+
+PREFER_DCM2NIIX = False
+ImageLike: TypeAlias = "np.ndarray | sitk.Image | torch.Tensor | str | os.PathLike"
+
+def read_dicoms(dir: str | os.PathLike) -> sitk.Image:
+    """reads a directory of DICOM files and returns a ``sitk.Image``"""
+    # load with dcm2niix
+    if PREFER_DCM2NIIX and importlib.util.find_spec("dcm2niix") is not None:
+        from ..utils.dcm2niix import dcm2sitk
+        return dcm2sitk(dir)
+
+    # load with SimpleITK
+    reader = sitk.ImageSeriesReader()
+    dicom_names = reader.GetGDCMSeriesFileNames(str(dir))
+
+    if not dicom_names:
+        raise FileNotFoundError(f"No DICOM series found in directory: {dir}")
+
+    reader.SetFileNames(dicom_names)
+    return reader.Execute()
+
+def _read_sitk(path: str | os.PathLike) -> sitk.Image:
+    if os.path.isfile(path): return sitk.ReadImage(str(path))
+    if os.path.isdir(path): return read_dicoms(str(path))
+    raise FileNotFoundError(f"{path} doesn't exist")
+
+def tositk(x: ImageLike) -> sitk.Image:
+    """Load an image into an ``sitk.Image`` object.
+    ``x`` can be a numpy array, a ``sitk.Image``, a ``torch.Tensor`` or a string (path to an image file)."""
+    if isinstance(x, np.ndarray): return sitk.GetImageFromArray(x)
+    if isinstance(x, sitk.Image): return x
+    if isinstance(x, (str, os.PathLike)): return _read_sitk(x)
+    if TORCH_INSTALLED:
+        import torch
+        if isinstance(x, torch.Tensor): return sitk.GetImageFromArray(x.numpy())
+    raise TypeError(f"Unsupported type {type(x)}")
+
+def tonumpy(x: ImageLike) -> np.ndarray:
+    """Load an image into a numpy.ndarray.
+    ``x`` can be a numpy array, a ``sitk.Image``, a ``torch.Tensor`` or a string (path to an image file)."""
+    if isinstance(x, np.ndarray): return x
+    if isinstance(x, sitk.Image): return sitk.GetArrayFromImage(x)
+    if isinstance(x, (str, os.PathLike)): return sitk.GetArrayFromImage(_read_sitk(x))
+    if TORCH_INSTALLED:
+        import torch
+        if isinstance(x, torch.Tensor): return x.numpy()
+    raise TypeError(f"Unsupported type {type(x)}")
+
+def totensor(x: ImageLike) -> "torch.Tensor":
+    """Load an image into a torch.Tensor.
+    ``x`` can be a numpy array, a ``sitk.Image``, a ``torch.Tensor`` or a string (path to an image file)."""
+    import torch
+    if isinstance(x, np.ndarray): return torch.from_numpy(x)
+    if isinstance(x, sitk.Image): return torch.from_numpy(sitk.GetArrayFromImage(x))
+    if isinstance(x, (str, os.PathLike)): return  torch.from_numpy(sitk.GetArrayFromImage(_read_sitk(x)))
+    if isinstance(x, torch.Tensor): return x
+    raise TypeError(f"Unsupported type {type(x)}")

mrid_python-0.1.3/mrid/preprocessing/__init__.py

@@ -0,0 +1,12 @@
+from .bias_field_correction import n4_bias_field_correction
+from .cropping import crop_bg, crop_bg_D
+from .registration import resample_to, register, register_D, register_each, resize, downsample, Registration
+from .skullstripping import skullstrip, skullstrip_D, run_hd_bet, predict_brain_mask
+
+__all__ = [
+    "n4_bias_field_correction",
+    "crop_bg", "crop_bg_D",
+    "resample_to", "register", "register_D", "register_each", "resize", "downsample",
+    "skullstrip", "skullstrip_D", "run_hd_bet", "predict_brain_mask"
+
+]

mrid_python-0.1.3/mrid/preprocessing/bias_field_correction.py

@@ -0,0 +1,28 @@
+import SimpleITK as sitk
+from ..loading.convert import tositk, ImageLike
+
+def n4_bias_field_correction(image: ImageLike, shrink: int = 4) -> sitk.Image:
+    """Perform N4 Bias Field Correction to correct low frequency intensity non-uniformity present in MRI image.
+
+    Args:
+        image (ImageLike): Input MRI image to be corrected. Can be any format supported by tositk conversion.
+        shrink (int, optional): Shrink factor for reducing image size before correction to speed up computation.
+                               Default is 4. If set to 1 or less, no shrinking is performed.
+
+    """
+    image = tositk(image)
+
+    norm_image = sitk.RescaleIntensity(image, 0, 255)
+    mask = sitk.OtsuThreshold(norm_image, 0, 1)
+
+    if shrink > 1:
+        reduced = sitk.Shrink(image, [shrink] * image.GetDimension())
+        mask = sitk.Shrink(mask, [shrink] * mask.GetDimension())
+
+    else: reduced = image
+
+    corrector = sitk.N4BiasFieldCorrectionImageFilter()
+    corrector.Execute(reduced, mask)
+    log_bias_field = corrector.GetLogBiasFieldAsImage(image)
+
+    return image / sitk.Cast(sitk.Exp(log_bias_field), image.GetPixelID())

mrid_python-0.1.3/mrid/preprocessing/cropping.py

@@ -0,0 +1,36 @@
+from collections.abc import Mapping
+from typing import Any
+import SimpleITK as sitk
+
+from ..loading.convert import tositk, ImageLike
+
+def _get_bbox(image: sitk.Image):
+    rescaled = sitk.RescaleIntensity(image, 0, 255)
+    filt = sitk.LabelShapeStatisticsImageFilter()
+    filt.Execute(sitk.OtsuThreshold(rescaled, 0, 255))
+    return filt.GetBoundingBox(255)
+
+
+def crop_bg(image: ImageLike) -> sitk.Image:
+    """Crops black background of a single 3D image via Otsu's thresholding.
+
+    Args:
+        image (ImageLike): Input 3D image to be cropped. Can be any format supported by tositk conversion.
+
+    Returns:
+        sitk.Image: Cropped image with black background removed, maintaining the same pixel type as input.
+    """
+    image = tositk(image)
+    bbox = _get_bbox(image)
+    return sitk.RegionOfInterest( image, bbox[int(len(bbox) / 2) :],  bbox[0 : int(len(bbox) / 2)],)
+
+def crop_bg_D(images: Mapping[str, ImageLike], key: str) -> dict[str, sitk.Image]:
+    """Finds the bounding box of ``images[key]`` and crops all images in ``images`` to that bounding box."""
+    images = {k: tositk(v) for k,v in images.items()}
+    reference = images[key]
+
+    bbox = _get_bbox(reference)
+
+    ret = {k: sitk.RegionOfInterest(v, bbox[int(len(bbox) / 2) :],  bbox[0 : int(len(bbox) / 2)]) for k,v in images.items()}
+    return ret
+