brain-stl 0.0.1__tar.gz

brain_stl-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Lukas Fisch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

brain_stl-0.0.1/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.3
+Name: brain-stl
+Version: 0.0.1
+Summary: Turn your brain MRI into a printable 3D model in seconds 🧠➡️🖨️
+Home-page: https://github.com/codingfisch/brain_stl
+License: MIT
+Author: codingfisch
+Author-email: l_fisc17@wwu.de
+Requires-Python: >=3.9,<4.0
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: PyMCubes
+Requires-Dist: dcm2niix
+Requires-Dist: deepmriprep
+Requires-Dist: fast_simplification (==0.1.7)
+Requires-Dist: niftiview
+Requires-Dist: trimesh
+Project-URL: Repository, https://github.com/codingfisch/brain_stl
+Description-Content-Type: text/markdown
+
+# brain-stl 🧠
+The **easiest** and **fastest** way to turn brain MRI scans into **3D printable models** 🖨️ powered by [`deepmriprep`](https://github.com/wwu-mmll/deepmriprep) ✨
+
+[Use the Colab demo](https://colab.research.google.com/drive/10WSG_qmKnbYrFTwZOlXsIgbda8iz2duQ?usp=sharing) or **install** it locally via `pip install brain_stl` 💨
+
+By default, the model is saved as `brain.stl`, but you can customize the filename along with other options like
+- **Threshold**: Pick a value between 0 and 3 for different tissue types (see GIF left, `2.5`: white matter only) 🧠
+- **Hollowness**: Adjust how hollow the brain is (enables faster printing) 💨
+- **Text**: Add personalized text that works as a support structure 🔤
+- **Smoothing**: Achieve a polished surface via iterative Laplacian smoothing ✨
+- **Mesh Reduction**: Simplify the mesh to reduce the size of `brain.stl` ✂️
+
+![gif](https://github.com/user-attachments/assets/64f10b4f-b136-4e86-8ef4-37f9fe0d8fa7)
+
+## Usage 💻
+To get your first `brain.stl` just run
+```python
+from brain_stl import run_brain_stl
+
+run_brain_stl()  # per default output_folder='.' (current folder)
+```
+and a publicly available brain MRI scan (from [OpenNeuro](https://openneuro.org/)) will be used 🌐
+
+Scan files can be inputted in NifTi (`.nii` or `.nii.gz`) or DICOM (`.dcm` or  [folder](https://pydicom.github.io/pydicom/stable/tutorials/filesets.html)) format
+```python
+from brain_stl import run_brain_stl
+
+run_brain_stl('/path/to/scan.nii.gz')  # or '/path/to/dicom_folder'
+```
+The main arguments of `run_brain_stl` are
+- **`scan_filepath`**: Path to the input scan (if `None`, use scan from `url`). Default: `None`
+- **`output_folder`**: Folder to save the `.stl` file and other outputs. Default: `'.'`
+- **`stl_name`**: Name of the example `.stl` file (without extension). Default: `'brain'`
+
+<details>
+  <summary><b>Click here</b>, to see <b>all</b> remaining <b>arguments</b> 📑</summary>
+
+- **`nifti_name`**: If DICOM produces multiple NifTis, this NifTi filename is used to proceed. Default: `None`
+- **`url`**: URL to download a brain scan if no `scan_filepath` is provided. Default: `OPENNEURO_URL`
+- **`use_cache`**: If `True`, reuses intermediate outputs (e.g., tissue data). Default: `False`
+- **`threshold`**: Threshold tissue value (`0.5`: fluid, `1.5`: gray matter, `2.5`: white matter). Default: `1.5`
+- **`hollow`**: How hollow the brain is (0 to 1). Default: `0`
+- **`in_template_space`**: If `True`, the 3D model is in standardized (template) orientation. Default: `False`
+- **`mesh_reduction`**: Fraction of mesh reduction (0 to 1) for smaller `.stl` file size. Default: `0` (no reduction)
+- **`smooth_iter`**: Number of iterations for Laplacian smoothing. Default: `0` (none)
+- **`smooth_lamb`**: Strength of each Laplacian smoothing step. Default: `0.2`
+- **`text`**: Custom text used as structural support. Default: `None`
+  - **`text2`**: Second line of text. Default: `None`
+  - **`textsize`**: Size (height) of the text. Default: `120`
+  - **`textback`**: Coronal (depth) position of the back of the text. Default: `300`
+  - **`textfront`**: Coronal (depth) position of the front of the text. Default: `330`
+  - **`textlinelength`**: Length of line below the text. Default: `10`
+
+</details>
+
+
+## Command-Line Interface 🖥️
+Process your first brain scan from the terminal by just running
+```bash
+brain-stl
+```
+Without providing any arguments, it downloads a publicly available scan and creates a `brain.stl` of it 🧠
+
+Run `brain-stl --help` (+copy&paste into ChatGPT) to understand the usage of custom settings 💡
+
+## Share Your Brains 🧠🌐
+Use `create_gif.py` to get a GIF of your model and share it on social media with the hashtag `#brain-stl` 🤗
+

brain_stl-0.0.1/README.md

@@ -0,0 +1,67 @@
+# brain-stl 🧠
+The **easiest** and **fastest** way to turn brain MRI scans into **3D printable models** 🖨️ powered by [`deepmriprep`](https://github.com/wwu-mmll/deepmriprep) ✨
+
+[Use the Colab demo](https://colab.research.google.com/drive/10WSG_qmKnbYrFTwZOlXsIgbda8iz2duQ?usp=sharing) or **install** it locally via `pip install brain_stl` 💨
+
+By default, the model is saved as `brain.stl`, but you can customize the filename along with other options like
+- **Threshold**: Pick a value between 0 and 3 for different tissue types (see GIF left, `2.5`: white matter only) 🧠
+- **Hollowness**: Adjust how hollow the brain is (enables faster printing) 💨
+- **Text**: Add personalized text that works as a support structure 🔤
+- **Smoothing**: Achieve a polished surface via iterative Laplacian smoothing ✨
+- **Mesh Reduction**: Simplify the mesh to reduce the size of `brain.stl` ✂️
+
+![gif](https://github.com/user-attachments/assets/64f10b4f-b136-4e86-8ef4-37f9fe0d8fa7)
+
+## Usage 💻
+To get your first `brain.stl` just run
+```python
+from brain_stl import run_brain_stl
+
+run_brain_stl()  # per default output_folder='.' (current folder)
+```
+and a publicly available brain MRI scan (from [OpenNeuro](https://openneuro.org/)) will be used 🌐
+
+Scan files can be inputted in NifTi (`.nii` or `.nii.gz`) or DICOM (`.dcm` or  [folder](https://pydicom.github.io/pydicom/stable/tutorials/filesets.html)) format
+```python
+from brain_stl import run_brain_stl
+
+run_brain_stl('/path/to/scan.nii.gz')  # or '/path/to/dicom_folder'
+```
+The main arguments of `run_brain_stl` are
+- **`scan_filepath`**: Path to the input scan (if `None`, use scan from `url`). Default: `None`
+- **`output_folder`**: Folder to save the `.stl` file and other outputs. Default: `'.'`
+- **`stl_name`**: Name of the example `.stl` file (without extension). Default: `'brain'`
+
+<details>
+  <summary><b>Click here</b>, to see <b>all</b> remaining <b>arguments</b> 📑</summary>
+
+- **`nifti_name`**: If DICOM produces multiple NifTis, this NifTi filename is used to proceed. Default: `None`
+- **`url`**: URL to download a brain scan if no `scan_filepath` is provided. Default: `OPENNEURO_URL`
+- **`use_cache`**: If `True`, reuses intermediate outputs (e.g., tissue data). Default: `False`
+- **`threshold`**: Threshold tissue value (`0.5`: fluid, `1.5`: gray matter, `2.5`: white matter). Default: `1.5`
+- **`hollow`**: How hollow the brain is (0 to 1). Default: `0`
+- **`in_template_space`**: If `True`, the 3D model is in standardized (template) orientation. Default: `False`
+- **`mesh_reduction`**: Fraction of mesh reduction (0 to 1) for smaller `.stl` file size. Default: `0` (no reduction)
+- **`smooth_iter`**: Number of iterations for Laplacian smoothing. Default: `0` (none)
+- **`smooth_lamb`**: Strength of each Laplacian smoothing step. Default: `0.2`
+- **`text`**: Custom text used as structural support. Default: `None`
+  - **`text2`**: Second line of text. Default: `None`
+  - **`textsize`**: Size (height) of the text. Default: `120`
+  - **`textback`**: Coronal (depth) position of the back of the text. Default: `300`
+  - **`textfront`**: Coronal (depth) position of the front of the text. Default: `330`
+  - **`textlinelength`**: Length of line below the text. Default: `10`
+
+</details>
+
+
+## Command-Line Interface 🖥️
+Process your first brain scan from the terminal by just running
+```bash
+brain-stl
+```
+Without providing any arguments, it downloads a publicly available scan and creates a `brain.stl` of it 🧠
+
+Run `brain-stl --help` (+copy&paste into ChatGPT) to understand the usage of custom settings 💡
+
+## Share Your Brains 🧠🌐
+Use `create_gif.py` to get a GIF of your model and share it on social media with the hashtag `#brain-stl` 🤗

brain_stl-0.0.1/brain_stl/__init__.py

@@ -0,0 +1 @@
+from .main import run_brain_stl

brain_stl-0.0.1/brain_stl/cli.py

@@ -0,0 +1,47 @@
+import argparse
+from brain_stl.main import OPENNEURO_URL, run_brain_stl
+
+
+def run_cli():
+    parser = argparse.ArgumentParser(description='Generate a 3D STL model of the brain from a scan')
+    parser.add_argument('-i', '--scan_filepath', type=str, default=None, help='Path to the input scan (NIfTI or DICOM)')
+    parser.add_argument('-o', '--output_folder', type=str, default='.', help='Folder to save the STL file and other outputs')
+    parser.add_argument('-n', '--stl_name', type=str, default='brain', help='Name of the example STL file (without extension)')
+    parser.add_argument('-ni', '--nifti_name', type=str, help='If DICOM produces multiple NifTis, this NifTi filename is used to proceed')
+    parser.add_argument('-u', '--url', type=str, default=OPENNEURO_URL, help='URL to download from if scan_filepath is not provided')
+    parser.add_argument('-c', '--use_cache', action='store_true', help='Reuses intermediate outputs (e.g., tissue data)')
+    parser.add_argument('-th', '--threshold', type=float, default=1.5, help='Threshold value for brain segmentation (0.5:fluid+gray+white matter, 1.5=gray+white matter, 2.5=white matter)')
+    parser.add_argument('-hl', '--hollow', type=float, default=0.0, help='How hollow the brain is (0 to 1)')
+    parser.add_argument('-s', '--in_template_space', action='store_true', help='If True, the 3D model is in standardized (template) orientation')
+    parser.add_argument('-mr', '--mesh_reduction', type=float, default=0.0, help='Fraction of mesh reduction (0 to 1) for smaller STL file size')
+    parser.add_argument('-si', '--smooth_iter', type=int, default=0, help='Number of iterations for Laplacian smoothing')
+    parser.add_argument('-sl', '--smooth_lamb', type=float, default=0.2, help='Strength of each Laplacian smoothing step')
+    parser.add_argument('-t', '--text', type=str, help='Custom text used as structural support')
+    parser.add_argument('-t2', '--text2', type=str, help='Second line of text')
+    parser.add_argument('-ts', '--textsize', type=int, default=100, help='Size (height) of the text')
+    parser.add_argument('-tb', '--textback', type=int, default=300, help='Coronal (depth) position of the back of the text')
+    parser.add_argument('-tf', '--textfront', type=int, default=330, help='Coronal (depth) position of the front of the text')
+    parser.add_argument('-tl', '--textlinelength', type=int, default=10, help='Length of line below the text')
+    args = parser.parse_args()
+    run_brain_stl(scan_filepath=args.scan_filepath,
+                  output_folder=args.output_folder,
+                  stl_name=args.stl_name,
+                  use_cache=args.use_cache,
+                  hollow=args.hollow,
+                  text=args.text,
+                  text2=args.text2,
+                  textsize=args.textsize,
+                  textback=args.textback,
+                  textfront=args.textfront,
+                  textlinelength=args.textlinelength,
+                  threshold=args.threshold,
+                  in_template_space=args.in_template_space,
+                  mesh_reduction=args.mesh_reduction,
+                  smooth_iter=args.smooth_iter,
+                  smooth_lamb=args.smooth_lamb,
+                  nifti_name=args.nifti_name,
+                  url=args.url)
+
+
+if __name__ == '__main__':
+    run_cli()

brain_stl-0.0.1/brain_stl/main.py

@@ -0,0 +1,136 @@
+import trimesh
+import dcm2niix
+import numpy as np
+import pandas as pd
+import nibabel as nib
+import urllib.request
+import fast_simplification
+from pathlib import Path
+from mcubes import marching_cubes
+from deepbet.utils import dilate
+from niftiview import NiftiImageGrid
+from PIL import Image, ImageDraw, ImageFont
+from deepmriprep.preprocess import AFFINE_TEMPLATE, Preprocess
+OPENNEURO_URL = 'https://openneuro.org/crn/datasets/ds000001/snapshots/1.0.0/files/sub-01:anat:sub-01_T1w.nii.gz'
+OUTPUTS = ['affine', 'rotation', 'p0_large']
+
+
+def run_brain_stl(scan_filepath=None, output_folder='.', stl_name='brain', nifti_name=None, url=OPENNEURO_URL,
+                  use_cache=False, threshold=1.5, hollow=.0, in_template_space=False, mesh_reduction=.0, smooth_iter=0,
+                  smooth_lamb=.2, text=None, text2=None, textsize=120, textback=300, textfront=330, textlinelength=10):
+    assert Path(output_folder).is_dir(), f'Output folder {output_folder} does not exist'
+    if scan_filepath is None:
+        print(f'Instead of a scan from disk, using a scan downloaded from {url}')
+        nifti_filepath = f'{output_folder}/{url.split(":")[-1]}'
+        urllib.request.urlretrieve(url, nifti_filepath)
+    else:
+        assert Path(str(scan_filepath)).exists(), f'Scan filepath {scan_filepath} does not exist'
+        if Path(scan_filepath).is_file() and not scan_filepath.endswith('.dcm'):
+            nifti_filepath = scan_filepath
+        else:
+            nifti_filepath = process_dicom(scan_filepath, output_folder, nifti_name)
+    output_paths = {out: f'{output_folder}/{"tissue.nii.gz" if out == "p0_large" else out+".csv"}' for out in OUTPUTS}
+    if not use_cache or not all([Path(output_paths[output]).is_file() for output in OUTPUTS]):
+        print(f'Calculate and cache (=write to output folder) affine, rotation and tissue of {nifti_filepath}')
+        prep = Preprocess()
+        prep.run(nifti_filepath, output_paths=output_paths, run_all=False)
+    tissue_img = nib.as_closest_canonical(nib.load(output_paths['p0_large']))
+    array = tissue_img.get_fdata(dtype=np.float32)
+    array = array if hollow == 0 else hollow_out_brain(array, hollow)
+    array = array if text is None else add_text(array, text, text2, textsize, textback, textfront, textlinelength)
+    vertices, faces = marching_cubes(array, threshold)
+    if in_template_space:
+        vertices = to_template_space(vertices)
+    else:
+        vertices = to_scanner_space(vertices, array, nifti_filepath, affine_filepath=output_paths['affine'])
+    if mesh_reduction > 0:
+        vertices, faces = fast_simplification.simplify(vertices.tolist(), faces.tolist(), mesh_reduction)
+    mesh = trimesh.Trimesh(vertices=vertices, faces=faces)
+    if smooth_iter > 0:
+        print('Smoothing')
+        mesh = trimesh.smoothing.filter_laplacian(mesh, lamb=smooth_lamb, iterations=smooth_iter)
+    if stl_name is not None:
+        mesh.export(f'{output_folder}/{stl_name}.stl')
+    return mesh
+
+
+def process_dicom(scan_filepath, output_folder, nifti_name):
+    dcm2niix.main([f'-o', output_folder, scan_filepath])
+    nifti_files = sorted(Path.glob(f'{output_folder}/*.ni*'))
+    assert len(nifti_files) > 0, f'Scan filepath {scan_filepath} is no valid DICOM'
+    if len(nifti_files) > 1:
+        im = get_t1w_png(nifti_files)
+        im.save(f'{output_folder}/pick_t1w_image.png')
+        raise RuntimeError(f'The inputted DICOM {scan_filepath} resulted in {len(nifti_files)} Nifti files.'
+                           f'View {output_folder}/pick_t1w_image.png, select the filename'
+                           f'of the appropriate(=T1w) Nifti and pass it via "run_brain_stl(..., nifti_name=*)"')
+    return nifti_files[0] if nifti_name is None else [fp for fp in nifti_files if nifti_name in fp][0]
+
+
+def hollow_out_brain(array, hollow):
+    r = int(.3 * (array.shape[0] * array.shape[1] * array.shape[2]) ** (1 / 3))
+    hollow_mask = dilate(array > 0, n_layer=int((hollow - 1) * r))
+    array[hollow_mask] = 0
+    return array
+
+
+def to_template_space(vertices):
+    vertices = AFFINE_TEMPLATE.affine @ np.hstack([vertices, np.ones_like(vertices[:, :1])]).T
+    return vertices[:3].T
+
+
+def to_scanner_space(vertices, array, nifti_filepath, affine_filepath):
+    affine = pd.read_csv(affine_filepath).values
+    affine = affine[[2, 1, 0, 3]][:, [2, 1, 0, 3]]  # undo pytorch zyx ordering
+    img = nib.as_closest_canonical(nib.load(nifti_filepath))
+    vertices = (2 * vertices / np.array(array.shape)) - 1  # apply pytorch grid scaling [-1;1]
+    vertices = (affine @ np.hstack([vertices, np.ones_like(vertices[:, :1])]).T)[:3]
+    vertices = .5 * np.array(img.get_fdata().shape) * (vertices.T + 1)  # undo pytorch grid scaling [-1;1]
+    vertices = img.affine @ np.hstack([vertices, np.ones_like(vertices[:, :1])]).T
+    return vertices[:3].T
+
+
+def add_text(array, text, text2, size, back=300, front=330, linelength=10):
+    size = size if text2 is None else size // 2
+    textrange = range(back, front)
+    height = np.where(array[:, textrange].mean(axis=(0, 1)) > .2)[0][0]
+    text_array = get_text_array(text, array.shape[0], size)
+    text_left, text_right, text_low, text_up = get_text_bbox(text_array, linelength)
+    fontheight = text_up - text_low
+    array[:, textrange, height - fontheight:height] += text_array[:, None, text_low:text_up]
+    if text2 is None:
+        array[text_left:text_right, textrange, 1:height - fontheight + 2] += 3
+    else:
+        text_array = get_text_array(text2, array.shape[0], size)
+        text_left, text_right, text_low, text_up = get_text_bbox(text_array, linelength)
+        fontheight2 = text_up - text_low
+        array[:, textrange, 1:fontheight2+1] = text_array[:, None, text_low:text_up]
+        array[text_left:text_right, textrange, fontheight2+1:height-fontheight+1] += 3
+        array[text_left:text_right, textrange, 1:2] += 3
+    return array.clip(max=3)
+
+
+def get_text_array(text, width, height):
+    im = Image.new('L', (width, height), color=0)
+    d = ImageDraw.Draw(im)
+    font = ImageFont.load_default(height)
+    d.text((width // 2, 0), text, fill=3, font=font, anchor='mt')
+    return np.array(im).T[::-1, ::-1]
+
+
+def get_text_bbox(array, linelength):
+    text_left, text_right = np.where(array.sum(axis=1))[0][[0, -1]]
+    text_left = max(0, text_left - linelength - 1)
+    text_right = min(text_right + linelength - 1, array.shape[0])
+    text_low, text_up = np.where(array.sum(axis=0))[0][[0, -1]]
+    return text_left, text_right, text_low, text_up
+
+
+def get_t1w_png(nifti_files):
+    ref_im = Image.open(Path(__file__).parent.resolve() / 'data' / 'ref.png')
+    grid_im = NiftiImageGrid(nifti_files).get_image(height=800, layout='sagittal++', fpath=1, fontsize=10)
+    ref_im = ref_im.resize((grid_im.size[0], int(ref_im.size[1] * grid_im.size[0] / ref_im.size[0])))
+    im = Image.new('L', (ref_im.size[0], ref_im.size[1] + grid_im.size[1]))
+    im.paste(ref_im, (0, 0))
+    im.paste(grid_im, (0, ref_im.size[1]))
+    return im

brain_stl-0.0.1/pyproject.toml

@@ -0,0 +1,29 @@
+[tool.poetry]
+name = 'brain-stl'
+version = '0.0.1'
+description = 'Turn your brain MRI into a printable 3D model in seconds 🧠➡️🖨️'
+authors = ['codingfisch <l_fisc17@wwu.de>']
+license = 'MIT'
+readme = 'README.md'
+repository = 'https://github.com/codingfisch/brain_stl'
+classifiers = [
+    'Programming Language :: Python :: 3',
+    'Operating System :: OS Independent',
+    'Intended Audience :: Science/Research'
+]
+
+[tool.poetry.dependencies]
+python = '^3.9'
+niftiview = '*'
+deepmriprep = '*'
+trimesh = '*'
+dcm2niix = '*'
+PyMCubes = '*'
+fast_simplification = '0.1.7'
+
+[tool.poetry.scripts]
+brain-stl = 'brain_stl.cli:run_cli'
+
+[build-system]
+requires = ['poetry-core']
+build-backend = 'poetry.core.masonry.api'