Blender Integration

The Blender extension was built to enable publication level visualization and presentation of simulation results using other 3D modeling software in general, and specifically Blender. It provides a convenient interface for exporting cortical surfaces, field vectors, electrode placements, skin surfaces, and sub-cortical structures in formats compatible with Blender, CAD software, and other 3D visualization tools. Use it when you want a guided workflow from the desktop application, or call the underlying Python scripts directly for batch jobs and automation.

Enable 3D visual exporter in Settings ▸ Extensions to add it to the navigation rail.

Preview and export

Choose the subject, simulation, mode (Cortical regions, Field vectors, Montage visualizer or Sub-cortical) and its settings on the left, then press Run export. The right pane shows the plan, an interactive Scene tab and the live Terminal, which follows the export’s job log. A cortical-regions export queues two jobs, one STL and one PLY; both logs remain available after they finish. To cancel an export, select its job in Jobs and choose Stop. Exports are written under derivatives/ti-toolbox/visual_exports/sub-<id>/.

  • Cortical regions: preview the selected subject’s atlas and click regions to update the same selection used by the export. The whole grey matter surface is always exported; with an empty selection it is the only output.
  • Sub-cortical: preview the selected segmentation volume; clicking a labelled region toggles its export selection. Selected labels are outlined in the full atlas. This is the source segmentation, not a preview of final mesh cleanup.
  • Montage: display the subject’s surfaces and the EEG net recorded with the selected simulation. The montage-only setting hides unused net positions. Markers show electrode positions; configured electrode dimensions are applied when the export is generated.
  • Field vectors: inspect the simulation’s field context. Arrow sampling and geometry are generated by the export itself.

Missing inputs produce a preview message; the preview does not substitute another subject.

Supported Modes

Cortical Regions

This mode exports cortical surface regions defined by anatomical atlases as 3D mesh files. The exporter uses the central cortical surface mesh generated from your simulation and segments it according to the selected atlas labels.

STL Export Sample

STL format export showing cortical surface geometry

PLY Export Sample

PLY format export with color-mapped field data

PLY Export Sample 2

PLY format export showing detailed cortical regions

What is produced:

  • STL files: Binary STL format containing only geometry (no color information). These are lightweight files suitable for CAD software, 3D printing, or any workflow that doesn’t require color mapping.
  • PLY files: PLY format with embedded color information. Each region is color-mapped according to the field values (e.g., TI_max) from the simulation mesh. These files preserve both geometry and field data for visualization in Blender or other 3D tools.

Output structure (under derivatives/ti-toolbox/visual_exports/sub-<id>/<simulation>/):

  • STL: stl/cortical_stls/regions/<region>.stl and stl/cortical_stls/whole_gm.stl.
  • PLY: ply/cortical_plys/regions/<region>.ply and ply/cortical_plys/whole_gm.ply.
  • The app always keeps the intermediate .msh files of the PLY export for audit trails and debugging: ply/meshes/<region>_region.msh and ply/whole_gm.msh.

Field Vectors

This mode exports electric field vectors from each channel’s simulation as arrow clouds in PLY format. The vectors represent the electric field direction and magnitude at sampled points in the brain.

Vector Field Visualization

TI vector field visualization showing electric field directions and magnitudes

Close-up Vector Field Visualization

Close-up view of the vector field, highlighting individual arrow placement and detail

What is produced:

  • CH1, CH2 — the first two channels’ electric fields in V/m (red, blue), optional.
  • TI (mTI for four channels) — the TI_max vector: its length is TI_max over all channels and it points along the direction of maximum modulation (green).
  • TI_sum — the vector sum of all channel fields (E1 + E2 for two channels) (yellow), optional.
  • TI_normal — the TI envelope along the cortical normal, drawn outward (cyan), optional.

For what each field means, see Field definitions.

Vector properties:

  • Each arrow’s direction represents the electric field direction at that point.
  • Arrow length is scaled by the field magnitude (configurable via length scale parameter).
  • Colors can be mapped using RGB mode (fixed colors per vector type: CH1=red, CH2=blue, TI=green, TI_sum=yellow, TI_normal=cyan) or magnitude-based scaling (magscale) to visualize field intensity across a blue-green-red gradient.
  • Vector width and anchor point (tail or head) are customizable for visualization clarity.

TI vs mTI modes:

  • TI mode: Uses 2 channel meshes (CH1 and CH2) to compute standard TI vectors.
  • mTI mode: Uses 4 channel meshes (CH1, CH2, CH3, CH4) to compute multi-channel TI vectors, enabling more complex stimulation patterns.

Sampling options:

  • Configure the number of vectors to sample (default 10,000 in the app, 100,000 in the Python API) or use all nodes for maximum detail.
  • When using the maximum sample count, the script will produce a vector on every node of the given surface mesh. This is an expensive process that requires a large amount of memory and can take multiple hours for all vectors to be produced.
  • Random seed controls reproducibility of sampling patterns.
  • From the Python API, top_percent keeps only the strongest vectors by magnitude (for example top_percent=10).

Montage Visualizer

This mode creates 3D electrode placements on the scalp surface using Blender for visualization. It extracts the scalp and grey-matter surfaces from the subject’s head model and places labelled electrode objects at the positions of the EEG net recorded in the simulation’s documentation/config.json.

Electrode Placement with Sub-cortical Structures

Electrode placement on scalp surface with sub-cortical thalamus ROI visualization

Interactive 3D Electrode Model

Interactive 3D view of GSN-HydroCel-185 electrode placement on scalp surface (GLB format)

What is produced (under derivatives/ti-toolbox/visual_exports/sub-<id>/montage_publication/):

  • <id>_<simulation>_montage_publication.blend: the publication scene with scalp, grey matter, electrode objects and text labels, sensible cameras, lighting conditions and material transparency.
  • <id>_electrodes_<net>.blend and <id>_electrodes_<net>.glb: the electrode placement on the scalp; the GLB (GLTF binary) is for web-based 3D viewers or other applications.
  • scalp.stl and gm.stl: the extracted scalp and grey-matter surfaces, for reference.

Electrode configuration:

  • The EEG net and the montage’s channels come from the selected simulation.
  • Show only montage electrodes places only the montage’s electrodes; otherwise the whole net is placed.
  • Electrode diameter and Electrode height size the electrode cylinders (defaults 10 mm and 6 mm).

Sub-cortical Extraction

This mode extracts sub-cortical structures from NIfTI segmentation files and converts them to 3D mesh formats. It can extract specific anatomical regions by label or export the entire segmentation volume.

What is produced (under derivatives/ti-toolbox/visual_exports/sub-<id>/sub-cortical/):

  • STL files: Binary STL format geometry files suitable for CAD software and 3D printing
  • MSH files: SimNIBS mesh format for compatibility with simulation workflows
  • PLY files: the same mesh coloured by a simulation field (TI_max by default), written when a simulation is selected; its subject-space field volume is written from the simulation’s field mesh first if the simulation did not save it
  • NIfTI files: Copied segmentation files for reference

Segmentation options:

  • Extract specific anatomical labels (e.g., thalamus: 10,49) or export the entire volume
  • Optional cleaning of small disconnected components to reduce mesh complexity
  • Automatic label extraction from FreeSurfer or other segmentation atlases

Input sources:

  • Default: m2m_<subject>/segmentation/labeling.nii.gz (the charm segmentation)
  • Custom: Any NIfTI file containing labeled anatomical regions

This can be incoporated into other visualization to produce images and animations such as:


Rendered examples

Overview of a Blender montage rendering Overview of montage creation and visualization capabilities.
Close-up Blender montage rendering Close-up view of the rendered montage and anatomical surfaces.
Side view of a high-frequency field rendering Side view of a high-frequency field rendering.
Top view of a high-frequency field rendering Top view of the same high-frequency field rendering.
Four-channel high-frequency vector field Dense individual high-frequency vectors for a four-channel simulation.
Four-channel mTI vector field Multi-channel TI vectors derived from a four-channel simulation.

Python API

The blender module exposes typed dataclass configs and runner functions for programmatic use:

from tit.blender import (
    RegionConfig,
    VectorConfig,
    MontageConfig,
    MontageResult,
    run_regions,
    run_vectors,
    run_montage,
)

# Example: export cortical regions as PLY
# Paths (mesh, m2m, output dir) are resolved from the project via PathManager
config = RegionConfig(
    subject_id="001",
    simulation_name="HIPP_L",
    format=RegionConfig.Format.PLY,
    atlas="DK40",
    field_name="TI_max",
)
run_regions(config)

Tips and troubleshooting

  • Environment: Run Python API scripts with simnibs_python inside the TI-Toolbox container. A saved JSON config runs with simnibs_python -m tit.blender config.json.
  • Large vector clouds: Start with a smaller Sample count (count in the Python API), or set top_percent from the Python API, to reduce file sizes before ramping up density.
  • Label extraction: When extracting specific labels, use comma-separated values (e.g., “10,49” for left/right thalamus). Check FreeSurfer’s label lookup table for anatomical region codes.
  • Error logs: The job’s Terminal shows the export’s output; see Where are the logs for the saved log files.


Blender Tutorial: Visualizing PLY Files

This tutorial walks you through importing and visualizing PLY files exported from TI-Toolbox in Blender, including how to display the embedded color attributes.

Step 1: Importing PLY Files

  1. Open Blender and start with the default scene (or create a new project).
  2. Go to File → Import → Stanford (.ply).
  3. Navigate to your exported PLY file location: cortical regions are in derivatives/ti-toolbox/visual_exports/sub-<id>/<simulation>/ply/cortical_plys/ (whole_gm.ply and regions/), field vectors in <simulation>/vectors/, and sub-cortical meshes in sub-<id>/sub-cortical/.
  4. Select your PLY file and click Import Stanford (.ply).

The mesh will appear in your viewport. If the mesh appears very small or very large, you may need to adjust the view or scale the object.

Import PLY file

Step 2: Switching to Material Preview

To see materials and colors properly, switch the viewport shading mode:

  1. In the 3D viewport, locate the viewport shading buttons in the top-right corner (or press Z to open the viewport shading menu).
  2. Select Material Preview mode (or press Z then 2).

Material Preview mode provides a quick preview of how materials will look with basic lighting, making it ideal for checking color attributes.

Material Preview mode

Step 3: Adding a Material

To display the color attributes from your PLY file, you need to create and assign a material:

  1. Select your imported PLY mesh object in the viewport.
  2. In the Material Properties panel (right sidebar, indicated by a sphere icon), click New to create a new material.
  3. The material will be automatically assigned to your selected object.

Adding a material

Step 4: Setting Color to the ‘Col’ Attribute

To use the color data embedded in your PLY file, set it as the material’s base color. Blender 4.4 imports the PLY’s vertex colors as a color attribute named Col (case-sensitive), which is also the mesh’s active color attribute:

  1. With your object still selected, in the Material Properties panel, locate the Base Color field (under the Surface section).
  2. Click on the Base Color field.
  3. Select Color Attribute from the dropdown menu.
  4. In the attribute name field that appears, enter Col (capital C). Leaving the name blank also works, because it then uses the active color attribute.

Your mesh should now display the color-mapped field data from your simulation. The colors represent the field values (e.g., TI_max) that were exported with the mesh.

Setting color attribute - Attribute node

Adding the Attribute node and setting it to 'Col'

Setting color attribute - Connected shader

Final result with color attribute connected to the material

Note: If your PLY file uses a different attribute name for colors, replace Col in step 4 with the appropriate attribute name. You can check available attributes by selecting the mesh and viewing the Geometry Nodes or Mesh Data properties.