Skip to content

Tractography and connectomes

View as Markdown

Streamlines and connectomes load with loadMeshes, like surfaces. NiiVue looks at the file type and builds tubes for streamlines, or spheres and cylinders for a connectome’s nodes and edges. They share the mesh options (opacity, visible, shaderType), and each kind adds its own set of display options.

Streamlines

NiiVue reads TCK, TRK, TRX, TT (DSI-Studio), VTK line and binary AFNI .niml.tract files (bundle IDs as dps:tract). Each streamline becomes a tube; tractOptions in the load options sets how:

await nv.loadMeshes([
{
url: '/meshes/tract.IFOF_R.trk',
tractOptions: { fiberRadius: 0.5, fiberSides: 7 },
},
])

Change them later with setTractOptions(meshIndex, options), which rebuilds the tubes:

  • fiberRadius (mm, default 0.5) and fiberSides (default 7) set the tube shape. Fewer sides draw faster.
  • decimation shows every Nth streamline (1 shows all), and minLength hides streamlines shorter than that many millimeters. Both help with large tractograms.
  • colorBy chooses the coloring: '' (the default) colors each segment by its local direction, 'global' by the start-to-end direction of the whole streamline, and 'fixed' uses fixedColor (RGBA, 0 to 255; it defaults to the mesh color).

Scalars

Per-vertex and per-streamline values color streamlines through a colormap. Load MRtrix TSF files (one value per vertex) and plain text files (one value per streamline) as layers of the tract; each is named after its file without the extension. TRX files carry both kinds inside, under the names stored in the file (the demo’s dpsv.trx has z and DataSetID). Select a scalar with colorBy: 'dpv:<name>' (per vertex) or 'dps:<name>' (per streamline). colormap, colormapNegative, calMin and calMax then map the values to colors; when you switch scalars, the range resets to fit the new data.

Groups

TRX files can group streamlines, for example by bundle. getTractGroups(meshIndex) returns the group names, and groupColors shows only the listed groups, each in its own RGBA color (0 to 255). Set it to null to show everything again:

const [first] = nv.getTractGroups(0)
await nv.setTractOptions(0, { groupColors: { [first]: [230, 25, 75, 255] } })
await nv.setTractOptions(0, { groupColors: null })

To show some groups but keep the current colorBy coloring (direction or a scalar), use visibleGroups instead. null shows every group:

await nv.setTractOptions(0, { visibleGroups: ['AF_L', 'AF_R'] })
await nv.setTractOptions(0, { visibleGroups: null })

If both are set, a streamline must be in visibleGroups and in groupColors to be shown.

See Tract groups.

Connectomes

A connectome is a set of named nodes (positions in mm with a color value and a size value) and weighted edges between them. NiiVue reads them from JCON, a JSON format; the file can also carry display options. Nodes become spheres and edges become cylinders:

await nv.loadMeshes([{ url: '/meshes/connectome.jcon' }])
await nv.setConnectomeOptions(0, { nodeScale: 4, edgeMin: 3 })

The options split into nodes and edges:

  • Nodes: nodeColormap, nodeColormapNegative, nodeMinColor, nodeMaxColor and nodeScale (sphere size multiplier, default 3).
  • Edges: edgeColormap, edgeColormapNegative, edgeMin (edges weaker than this are hidden), edgeMax and edgeScale (cylinder size multiplier, default 1).

The Connectome example shows a dense and a sparse connectome over a clipped volume.

Examples

Surfaces and their layers are covered in Meshes and layers.