Generate 3D‑printable brain surfaces (cortical, subcortical, brainstem, etc.) in T1, MNI, or target subject space, color them from parametric volumes, or generate distinct multi-material slab components – all from the command line.

The core is pure‑Python (trimesh, nibabel, scikit-image) while heavy lifting is delegated to familiar neuro‑tools (FreeSurfer, FSL, ANTs, MRtrix3). Every CLI writes a timestamped JSON run‑log for provenance and supports structured console logging via -v/--verbose.

# 1. Clone
git clone [https://github.com/claudebajada/process_brain_for_printing.git](https://github.com/claudebajada/process_brain_for_printing.git)
cd process_brain_for_printing

# 2. Editable install + entry‑points
pip install -e .

Python ≥3.8 recommended. All Python dependencies (see requirements.txt) are pulled in automatically. VTK is required for handling some subcortical/ventricular meshes.

Depending on the sub‑command and features you use, you may need some (or all) of:

CLIs abort early with a helpful message if a required binary is missing for the requested operation.

Run any command with -h/--help for a full argument reference.

Using a preset for pial surfaces, brainstem, cerebellum, and corpus callosum in T1 space:

brain_for_printing_cortical_surfaces preset \
  --subjects_dir /path/to/bids/derivatives \
  --subject_id sub-01 \
  --name pial_brain \
  --space T1 \
  --output_dir ./models_t1_preset \
  --split_outputs \
  -v

Custom selection including cortical, ASEG, and 5ttgen-derived (VTK) subcortical structures in T1 space:

brain_for_printing_cortical_surfaces custom \
  --subjects_dir /path/to/bids/derivatives \
  --subject_id sub-01 \
  --cortical-surfaces lh-pial rh-pial \
  --cbm-bs-cc brainstem cerebellum \
  --subcortical-gray L_Thal R_Thal all # 'all' for all available SGM, or specific names
  --space T1 \
  --output_dir ./models_t1_custom \
  --work_dir /path/to/work_directory_for_5ttgen # Optional: specify base for 5ttgen temp/persistent files
  --split_outputs \
  -v

Flags of note for brain_for_printing_cortical_surfaces:

• Mode: preset --name <preset_name> or custom
• --cortical-surfaces: e.g., pial, lh-white, rh-mid (for custom mode)
• --cbm-bs-cc: e.g., brainstem, cerebellum, corpus_callosum (for custom mode)
• --subcortical-gray: e.g., L_Hipp, R_Amyg, all (for custom mode, requires 5ttgen data)
• --ventricular-system: e.g., 3rd-Ventricle, all (for custom mode, requires 5ttgen data)
• --space T1|MNI|sub-XX: Target output space.
• --split_outputs: Export each generated mesh as a separate file.
• --no-fill-structures / --no-smooth-structures: Selectively skip hole filling or smoothing for ASEG structures.
• --work_dir: Base directory for intermediate files, especially for 5ttgen processing.
• --no_clean: Keep temporary folders.
• -v: Verbose logging.

Generate 5mm thick axial slabs of different brain materials for sub-01, outputting STLs in AC-PC space:

brain_for_printing_multi_material_slabs \
  --subjects_dir /path/to/bids/derivatives \
  --subject_id sub-01 \
  --output_dir ./multi_material_slabs_sub-01 \
  --slab_thickness 5.0 \
  --slab_orientation axial \
  --voxel_resolution 0.5 \
  --voxel2mesh_threshold 0.5 \
  -v

Flags of note for brain_for_printing_multi_material_slabs:

• --slab_thickness: Thickness of each slab in mm.
• --slab_orientation: axial, coronal, or sagittal (relative to AC-PC space).
• --voxel_resolution: Resolution for the intermediate AC-PC grid.
• --voxel2mesh_threshold: Threshold for voxel2mesh when creating STLs from AC-PC material volumes.
• --voxel2mesh_blocky: Use -blocky option for voxel2mesh for voxel-faced meshes.
• --skip_outer_csf: Optionally skip the outermost CSF layer.
• --work_dir: Specify a directory for intermediate files.
• --no_clean: Keep the work directory.
• -v: Verbose logging.

Color a "pial_brain" preset in MNI space, sampling from the white matter surface:

brain_for_printing_color preset \
  --subjects_dir /path/to/bids/derivatives \
  --subject_id sub-01 \
  --preset pial_brain \
  --space MNI \
  --color_in target \
  --param_map /path/to/tstat_in_MNI.nii.gz \
  --color_sampling_surf white \
  --num_colors 9 \
  --output_dir ./coloured_models_mni \
  -v

Color in source T1 space, then warp surfaces to target subject sub-02:

brain_for_printing_color preset \
  --subjects_dir /path/to/bids/derivatives \
  --subject_id sub-01 \
  --preset mid_brain \
  --space sub-02 \
  --color_in source \
  --param_map /path/to/tstat_in_T1_sub-01.nii.gz \
  --color_sampling_surf mid \
  --num_colors 6 \
  --output_dir ./coloured_models_sub02_from_sub01 \
  -v

Flags of note for brain_for_printing_color preset:

• --preset <name>: e.g., pial_brain, white_brain, mid_brain.
• --space T1|MNI|sub-XX: Space for final surface generation.
• --color_in source|target: Space in which coloring is performed (source is subject's T1, target is the final --space).
• --param_map <path_to_nifti>: Parameter map for coloring.
• --color_sampling_surf white|pial|mid: Cortical surface type used to sample colors for other cortical surfaces.
• --num_colors <N>: Number of discrete color bins.
• --param_threshold <value>: Optional threshold for parameter map.

brain_for_printing_color direct \
  --in_mesh ./input_brain.obj \
  --param_map ./perfusion_map.nii.gz \
  --out_obj ./brain_coloured.obj \
  --num_colors 7

• Real‑time logging is controlled by -v/--verbose.
• Every run writes a JSON log (*_log_<timestamp>.json) capturing inputs, parameters, steps, warnings, and outputs.
• Temporary folders are auto‑removed unless you pass --no_clean.

The project includes a suite of unit and integration tests using pytest.

• Run tests with pytest in the root directory.
• Test coverage reports can be generated (see pytest.ini).
• Current tests cover core utilities, argument parsing, and some workflow logic, with ongoing efforts to expand coverage, especially with diverse dummy data.

• Enhanced Test Coverage: Continue expanding unit and integration tests with more diverse dummy datasets and edge cases.
• General Mesh Boolean Operations CLI: Potentially add a dedicated CLI tool for more general boolean operations on meshes.
• Configuration for External Tools: Explore options for specifying paths to external tool binaries if not in PATH.

MIT © Claude J. Bajada and contributors

• Neuroimaging software: FSL, FreeSurfer, ANTs, MRtrix3.
• Python libraries: numpy, nibabel, scipy, scikit‑image, trimesh, vtk.