brainseg-containers 1.0.0.dev0__tar.gz

brainseg_containers-1.0.0.dev0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: brainseg-containers
+Version: 1.0.0.dev0
+Summary: wrapper for brain segmentation tools
+Author-email: Marius Causemann <mariusca@simula.no>
+Description-Content-Type: text/markdown
+Requires-Dist: nibabel
+Requires-Dist: fastremap
+Provides-Extra: test
+Provides-Extra: dev
+Requires-Dist: pdbpp; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: plot
+Requires-Dist: matplotlib; extra == "plot"
+Requires-Dist: nilearn; extra == "plot"
+Requires-Dist: numpy; extra == "plot"
+Requires-Dist: pandas; extra == "plot"
+Provides-Extra: docs
+Requires-Dist: jupyter-book<2.0.0; extra == "docs"
+Requires-Dist: jupytext; extra == "docs"
+Requires-Dist: ipykernel<7.0.0; extra == "docs"
+Requires-Dist: sphinx-codeautolink; extra == "docs"
+Provides-Extra: all
+Requires-Dist: brainseg-containers[dev,docs,plot,test]; extra == "all"
+
+# BrainSeg-container
+
+This repository provides a streamlined Python wrapper and CLI tool to automatically download, run, and standardize outputs from state-of-the-art brain segmentation tools using Apptainer / Singularity containers.
+
+Brain segmentation tools often have conflicting dependencies, complex installation steps, or require specific versions of system libraries. This package solves that problem by containerizing the tools and handling the execution, file binding, and label standardization for you.
+
+![h:8cm](https://github.com/MariusCausemann/brainseg/raw/main/images/comparison_grid.png)
+## The Tools
+
+This pipeline currently supports the following deep-learning-based segmentation tools. We may add more in the future.
+
+1. [**GOUHFI**](https://github.com/mafortin/GOUHFI)
+   This tool was designed to handle the challenges of Ultra-High Field MRI (7T+). It utilizes "domain randomization" during training, which allows it to remain robust across different MRI contrasts and resolutions, including standard clinical scans.
+
+   * **Resolution:** Native (preserves input resolution).
+
+   * **CSF Availability:** Yes (segments ventricles and subarachnoid space CSF).
+
+2. [**SynthSeg**](https://github.com/BBillot/SynthSeg)
+   Developed by the FreeSurfer team, this tool is famous for working "out of the box" on almost any kind of MRI scan (different contrasts, resolutions, or messy clinical data) without needing retraining.
+
+   * **Resolution:** Fixed 1mm isotropic (always resamples input to 1mm).
+
+   * **CSF Availability:** Yes.
+
+3. [**FastSurfer**](https://github.com/Deep-MI/FastSurfer)
+   A rapid deep-learning-based segmentation tool that is optimized for speed, finishing in minutes rather than hours.
+
+   * **Resolution:** Native (but experimental below 0.7mm).
+
+   * **CSF Availability:** No (segments ventricles, but ignores subarachnoid space CSF).
+
+4. [**SimNIBS (Charm)**](https://github.com/simnibs/simnibs)
+   The "Complete Head Anatomy Reconstruction Method" from the SimNIBS suite. While designed for modeling brain stimulation (TMS/TES), it produces high-quality segmentation of extra-cerebral tissues (skull, scalp, etc.) in addition to the brain.
+
+   * **Resolution:** Native (pipeline uses the upsampled output to match input).
+
+   * **CSF Availability:** Yes.
+   * **Segmented regions:** Charm provides the following segmentation labels: White-Matter, Gray-Matter, CSF, Bone, Scalp, Eye_bals, Compact_bone, Spongy_bone, Blood, Muscle, Cartilage, Fat, Electrode, Saline_or_gel
+
+## Comparison Output
+
+The pipeline can automatically generate a comparison grid so you can quickly inspect the differences between the tools.
+
+## Getting Started
+
+### Prerequisites
+
+You must have Apptainer (or Singularity) installed on your system to run the containers.
+
+* Ubuntu/Debian: `sudo apt install apptainer`
+* Conda/Mamba: `conda install -c conda-forge apptainer `
+
+
+### Installation
+
+You can install the package directly via pip:
+
+```bash
+pip install brainseg-containers
+```
+
+*(Optional) If you want to use the plotting and comparison features, install with the `plot` extras:*
+```bash
+pip install brainseg-containers[plot]
+```
+
+---
+
+## Usage
+
+The package provides a simple command-line interface. The first time you run a specific tool, the wrapper will automatically download the corresponding container from the GitHub Container Registry and store it in `~/.brainseg_containers/`.
+
+### Basic Command
+
+```bash
+brainseg-containers -t <tool_name> -i <input_file.nii.gz> -o <output_file.nii.gz>
+```
+
+**Available Tools:** `synthseg`, `gouhfi`, `fastsurfer`, `simnibs`
+
+### Examples
+
+**Run GOUHFI on a single subject:**
+```bash
+brainseg-containers -t gouhfi -i inputs/sub-01_T1w.nii.gz -o results/sub-01_gouhfi.nii.gz
+```
+
+**Run SynthSeg on the same subject:**
+```bash
+brainseg-containers -t synthseg -i inputs/sub-01_T1w.nii.gz -o results/sub-01_synthseg.nii.gz
+```
+
+*Note: You can optionally provide a custom path to a pre-downloaded `.sif` image using the `--container` flag.*
+
+
+### Note on Labels
+
+Different tools use different numbers to represent brain regions. To make comparison easier, this pipeline automatically **remaps** the output labels of FastSurfer and GOUHFI to match the standard FreeSurfer lookup table.

brainseg_containers-1.0.0.dev0/README.md

@@ -0,0 +1,99 @@
+# BrainSeg-container
+
+This repository provides a streamlined Python wrapper and CLI tool to automatically download, run, and standardize outputs from state-of-the-art brain segmentation tools using Apptainer / Singularity containers.
+
+Brain segmentation tools often have conflicting dependencies, complex installation steps, or require specific versions of system libraries. This package solves that problem by containerizing the tools and handling the execution, file binding, and label standardization for you.
+
+![h:8cm](https://github.com/MariusCausemann/brainseg/raw/main/images/comparison_grid.png)
+## The Tools
+
+This pipeline currently supports the following deep-learning-based segmentation tools. We may add more in the future.
+
+1. [**GOUHFI**](https://github.com/mafortin/GOUHFI)
+   This tool was designed to handle the challenges of Ultra-High Field MRI (7T+). It utilizes "domain randomization" during training, which allows it to remain robust across different MRI contrasts and resolutions, including standard clinical scans.
+
+   * **Resolution:** Native (preserves input resolution).
+
+   * **CSF Availability:** Yes (segments ventricles and subarachnoid space CSF).
+
+2. [**SynthSeg**](https://github.com/BBillot/SynthSeg)
+   Developed by the FreeSurfer team, this tool is famous for working "out of the box" on almost any kind of MRI scan (different contrasts, resolutions, or messy clinical data) without needing retraining.
+
+   * **Resolution:** Fixed 1mm isotropic (always resamples input to 1mm).
+
+   * **CSF Availability:** Yes.
+
+3. [**FastSurfer**](https://github.com/Deep-MI/FastSurfer)
+   A rapid deep-learning-based segmentation tool that is optimized for speed, finishing in minutes rather than hours.
+
+   * **Resolution:** Native (but experimental below 0.7mm).
+
+   * **CSF Availability:** No (segments ventricles, but ignores subarachnoid space CSF).
+
+4. [**SimNIBS (Charm)**](https://github.com/simnibs/simnibs)
+   The "Complete Head Anatomy Reconstruction Method" from the SimNIBS suite. While designed for modeling brain stimulation (TMS/TES), it produces high-quality segmentation of extra-cerebral tissues (skull, scalp, etc.) in addition to the brain.
+
+   * **Resolution:** Native (pipeline uses the upsampled output to match input).
+
+   * **CSF Availability:** Yes.
+   * **Segmented regions:** Charm provides the following segmentation labels: White-Matter, Gray-Matter, CSF, Bone, Scalp, Eye_bals, Compact_bone, Spongy_bone, Blood, Muscle, Cartilage, Fat, Electrode, Saline_or_gel
+
+## Comparison Output
+
+The pipeline can automatically generate a comparison grid so you can quickly inspect the differences between the tools.
+
+## Getting Started
+
+### Prerequisites
+
+You must have Apptainer (or Singularity) installed on your system to run the containers.
+
+* Ubuntu/Debian: `sudo apt install apptainer`
+* Conda/Mamba: `conda install -c conda-forge apptainer `
+
+
+### Installation
+
+You can install the package directly via pip:
+
+```bash
+pip install brainseg-containers
+```
+
+*(Optional) If you want to use the plotting and comparison features, install with the `plot` extras:*
+```bash
+pip install brainseg-containers[plot]
+```
+
+---
+
+## Usage
+
+The package provides a simple command-line interface. The first time you run a specific tool, the wrapper will automatically download the corresponding container from the GitHub Container Registry and store it in `~/.brainseg_containers/`.
+
+### Basic Command
+
+```bash
+brainseg-containers -t <tool_name> -i <input_file.nii.gz> -o <output_file.nii.gz>
+```
+
+**Available Tools:** `synthseg`, `gouhfi`, `fastsurfer`, `simnibs`
+
+### Examples
+
+**Run GOUHFI on a single subject:**
+```bash
+brainseg-containers -t gouhfi -i inputs/sub-01_T1w.nii.gz -o results/sub-01_gouhfi.nii.gz
+```
+
+**Run SynthSeg on the same subject:**
+```bash
+brainseg-containers -t synthseg -i inputs/sub-01_T1w.nii.gz -o results/sub-01_synthseg.nii.gz
+```
+
+*Note: You can optionally provide a custom path to a pre-downloaded `.sif` image using the `--container` flag.*
+
+
+### Note on Labels
+
+Different tools use different numbers to represent brain regions. To make comparison easier, this pipeline automatically **remaps** the output labels of FastSurfer and GOUHFI to match the standard FreeSurfer lookup table.

brainseg_containers-1.0.0.dev0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system] # Require setuptool version due to https://github.com/pypa/setuptools/issues/2938
+requires = ["setuptools>=61.0.0", "wheel"]
+
+[project]
+dependencies = [
+    "nibabel","fastremap"
+]
+name = "brainseg-containers"
+version = "1.0.0.dev0"
+description = "wrapper for brain segmentation tools"
+authors = [{ name = "Marius Causemann", email = "mariusca@simula.no" }]
+license = { file = "LICENSE" }
+readme = "README.md"
+
+
+[project.scripts]
+brainseg = "brainseg.clients.runner:main"
+brainseg_relabel = "brainseg.clients.remap_labels:main"
+
+
+[project.optional-dependencies]
+test = []
+dev = ["pdbpp", "ipython", "mypy", "ruff"]
+plot = ["matplotlib","nilearn", "numpy", "pandas"]
+docs = [
+    "jupyter-book<2.0.0",
+    "jupytext",
+    "ipykernel<7.0.0",     # Note: Remove once https://github.com/ipython/ipykernel/issues/1450 is in a release
+    "sphinx-codeautolink",
+]
+all = ["brainseg-containers[test,dev,docs,plot]"]
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]
+testpaths = ["tests"]
+
+[tool.mypy]
+ignore_missing_imports = true
+# Folders to exclude
+exclude = ["docs/", "build/"]
+# Folder to check with mypy
+files = ["src", "tests"]
+
+[tool.ruff]
+src = ["src", "tests", "docs"]
+line-length = 100
+indent-width = 4
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+"brainseg.data" = ["*.txt"]
+
+[tool.ruff.lint]
+select = [
+    # Pyflakes
+    "F",
+    # Pycodestyle
+    "E",
+    "W",
+    # isort
+    "I001",
+]
+
+
+[tool.ruff.lint.isort]
+known-first-party = ["brainseg"]
+known-third-party = ["numpy", "pytest"]
+section-order = [
+    "future",
+    "standard-library",
+    "mpi",
+    "third-party",
+    "first-party",
+    "local-folder",
+]

brainseg_containers-1.0.0.dev0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

brainseg_containers-1.0.0.dev0/src/brainseg/clients/compare_segs.py

@@ -0,0 +1,155 @@
+import argparse
+import math
+import matplotlib.pyplot as plt
+from nilearn import plotting
+from matplotlib.colors import ListedColormap
+import numpy as np
+import pandas as pd
+import nibabel as nib
+plt.style.use('dark_background')
+
+
+lut_path = "resources/freesurfer-label-list-lut.txt"
+
+def create_exact_colormap(lut_path, alpha=0.5):
+    """
+    Creates a sparse ListedColormap where the index matches the label ID exactly.
+    Indices not found in the LUT are transparent (alpha=0).
+    """
+
+    # Read LUT (handles whitespace and comments)
+    df = pd.read_csv(
+        lut_path, 
+        sep=r"\s+", 
+        comment="#", 
+        header=None, 
+        names=["index", "name", "r", "g", "b", "a"],
+        dtype={"index": int, "r": int, "g": int, "b": int}
+    )
+    
+    # 1. Determine the size of the colormap needed
+    # We need an array large enough to hold the highest label ID found.
+    # e.g., if max ID is 14175, we need 14176 entries (0 to 14175).
+    max_id = df["index"].max()
+
+    df.loc[df["name"]=="CSF", ['r', 'g', 'b']] = [0, 255, 255]
+    
+    # 2. Initialize RGBA array with Transparent (0,0,0,0)
+    # nilearn will overlay this on the T1, so 0 alpha means "show T1"
+    lut_colors = np.zeros((max_id + 1, 4))
+    
+    # 3. Fill in the specific indices defined in the LUT
+    # Normalize 0-255 RGB to 0-1 for Matplotlib
+    indices = df["index"].values
+    rgbs = df[["r", "g", "b"]].values / 255.0
+    
+    # Set RGB colors
+    lut_colors[indices, 0:3] = rgbs
+    # Set Alpha to 1.0 (Opaque) for defined labels
+    lut_colors[indices, 3] = alpha
+    
+    # Create the discrete colormap
+    # 'N' is implicitly len(lut_colors), ensuring 1:1 mapping
+    custom_cmap = ListedColormap(lut_colors, name="FreeSurfer_Discrete")
+    
+    return custom_cmap, max_id
+
+
+def get_ventricle_center(seg_path):
+    """
+    Calculates coordinates centered specifically on the ventricles.
+    """
+    print(f"Calculating center from ventricles in: {seg_path}")
+    img = nib.load(seg_path)
+    
+    # FreeSurfer Standard Labels for Ventricles:
+    # 4: Left-Lateral-Ventricle
+    # 14: 3rd-Ventricle
+    # 43: Right-Lateral-Ventricle
+    target_labels = [4, 14, 43]
+    
+    # Create binary mask of ventricles
+    mask_data = np.isin(img.get_fdata(), target_labels).astype(float)
+    
+    new_img = nib.Nifti1Image(mask_data, img.affine, img.header)
+    
+    return plotting.find_xyz_cut_coords(new_img)
+
+
+fs_labeled = ["synthseg", "gouhfi", "fastsurfer"]
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generate a grid of segmentation overlays in ortho view (Sagittal, Coronal, Axial)."
+    )
+    
+    parser.add_argument("-i", "--image", required=True, help="Path to the T1w anatomical image (background).")
+    parser.add_argument("-s", "--segs", required=True, nargs='+', help="List of segmentation NIfTI files.")
+    parser.add_argument("-o", "--output", default="seg_comparison_ortho.png", help="Path to save the output image.")
+
+    args = parser.parse_args()
+
+    cmap, vmax = create_exact_colormap(lut_path, alpha=0.6)
+
+    # 1. Setup Grid
+    n_segs = len(args.segs)
+    cols = 1
+    rows = math.ceil(n_segs / cols)
+    
+    # Calculate figure size: Allocate more width (10 inches) per column for the ortho view
+    fig, axes = plt.subplots(
+        rows, cols, 
+        figsize=(8 * cols, 2.45 * rows), 
+        gridspec_kw={'wspace': 0, 'hspace': 0} 
+    )    
+    plt.subplots_adjust(left=0, right=1, bottom=0, top=1)
+    # Flatten axes for consistent indexing
+    if n_segs > 1:
+        axes = axes.flatten()
+    else:
+        axes = [axes]
+
+    # 2. Determine Cut Coordinates automatically
+    cut_coords = get_ventricle_center(args.segs[0])
+    
+    print(f"Visualizing ortho slices at coordinates: {np.round(cut_coords,2)}")
+
+    # 3. Loop through segmentations and plot
+    for i, seg_path in enumerate(args.segs):
+        print(f"Processing: {seg_path}")
+        ax = axes[i]
+        # Determine title from filename
+        title = seg_path.split("/")[-1].replace(".nii.gz", "").replace(".nii", "").replace("_seg", "")
+        
+        plotting.plot_roi(
+            roi_img=seg_path,
+            bg_img=args.image,
+            axes=ax,
+            display_mode='ortho',  # Shows Sagittal, Coronal, and Axial cuts
+            cut_coords=cut_coords, # Ensures all models show the exact same anatomical point
+            cmap="tab20", #cmap,
+            vmax=vmax if title in fs_labeled else None,
+            vmin=0,
+            #title=title,
+            alpha=0.4,
+            resampling_interpolation='nearest',
+            annotate=False,
+            draw_cross=True,
+            black_bg=True,
+            colorbar=False  
+        )
+        fig.text(0.01, 0.95, title,
+            transform=ax.transAxes,
+            horizontalalignment='left',
+            verticalalignment='top',
+            color="white",
+            fontsize=10,
+            weight='bold',
+            zorder=1000
+        )
+
+    plt.savefig(args.output, dpi=300, pad_inches=0.0, bbox_inches='tight')
+    print(f"Saved comparison to: {args.output}")
+
+if __name__ == "__main__":
+    main()

brainseg_containers-1.0.0.dev0/src/brainseg/clients/remap_labels.py

@@ -0,0 +1,27 @@
+import argparse
+import os
+from brainseg.remap import remap_file
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Exchange NIfTI labels from an old schema to a new schema using fastremap."
+    )
+    
+    # Required arguments
+    parser.add_argument("-i", "--input", required=True, help="Path to the input .nii.gz file")
+    parser.add_argument("-o", "--output", required=True, help="Path to save the remapped .nii.gz file")
+    parser.add_argument("--old-txt", required=True, help="Text file containing old label mapping")
+    parser.add_argument("--new-txt", required=True, help="Text file containing new label mapping")
+    
+    # Optional flag
+    parser.add_argument("--inplace", action="store_true", help="Perform remap in-place to save memory")
+
+    args = parser.parse_args()
+
+    print(f"--- Processing: {os.path.basename(args.input)} ---")
+
+    remap_file(args.input, args.old_txt, args.new_txt, args.output)
+    print(f"Success! Saved to: {args.output}")
+
+if __name__ == "__main__":
+    main()