Skip to contents

Create brain atlas from white matter tracts

Source: R/atlas_tracts.R
create_tract_from_tractography.Rd

[Experimental]

Turn tractography streamlines into a brain atlas where each tract is rendered as a 3D tube. The function computes a centerline from the streamlines and generates a tube mesh around it.

You can provide tract data in several formats: TRK files from TrackVis, TCK files from MRtrix, or coordinate matrices directly in R. The function reads the streamlines, extracts a representative centerline (by averaging or selecting the medoid), and builds a tube mesh for 3D rendering.

For tracts with many streamlines, set tube_radius = "density" to make the tube thicker where more streamlines pass through.

Usage

create_tract_from_tractography(
  input_tracts,
  verbose = get_verbose(),
  ...,
  input_aseg = NULL,
  input_lut = NULL,
  atlas_name = NULL,
  output_dir = NULL,
  tube_opts = list(),
  slabs = NULL,
  vertex_size_limits = NULL,
  steps = NULL,
  min_coverage = NULL,
  cleanup = NULL,
  skip_existing = NULL,
  coord_space = c("infer", "voxel", "mm")
)

Arguments

input_tracts

Paths to tractography files (.trk or .tck), or a named list of coordinate matrices where each matrix has N rows and 3 columns (x, y, z).

verbose

How much to print: 0 silent, 1 progress (the default), 2 adds FreeSurfer's own output. TRUE and FALSE mean 1 and 0. Falls back to options("ggseg.extra.verbose"), then GGSEG_EXTRA_VERBOSE.

...

Not used. Present so that a mistyped or misplaced argument is reported against this function rather than silently ignored; anything passed here is an error. Geometry is shaped after the build: see atlas_polish(), or atlas_simplify(), atlas_smooth() and atlas_dilate() individually.

input_aseg

Path to a segmentation volume (.mgz, .nii) used to draw cortex outlines in 2D views. Required unless steps = 1; the build stops before reading any tract when it is missing.

input_lut

Path to a color lookup table (LUT) file, or a data.frame with a region column (or a FreeSurfer-style label column) plus colour columns (R, G, B or hex). Rows must be in the same order as input_tracts. Use this to provide tract names and colours. If NULL, names are derived from filenames or list names, and colours will be auto-generated.

atlas_name

Name for the atlas. If NULL, derived from the input filename. It also names the folder of intermediate files inside output_dir, so it must be a single name without path separators.

output_dir

Where to put the intermediate files. Defaults to tempdir(), from options("ggseg.extra.output_dir") or GGSEG_EXTRA_OUTPUT_DIR.

tube_opts

Named list controlling how a bundle of streamlines becomes a 3D tube mesh, with these entries and defaults:

  • centerline_method ("mean") and n_points (50): how one centerline is derived from many streamlines, and how many points it is resampled to. All tracts are resampled to the same length so the tubes are consistent.

  • tube_radius (5) and tube_segments (8): the thickness of the tube drawn along that centerline, and how many segments go around its circumference. tube_radius also takes "density", to scale thickness by how many streamlines pass through each point.

Unknown entries error.

slabs

A data.frame specifying projection slabs. If NULL, a default set of tract slabs is derived from the volume dimensions.

vertex_size_limits

Numeric vector of length 2 setting minimum and maximum vertex count for polygons. Polygons outside this range are filtered out. Default NULL applies no limits.

steps

Which pipeline steps to run. Default NULL runs all steps. Steps are:

  • 1: Read tractography and create tube meshes

  • 2: Create projection snapshots

  • 3: Extract contours

  • 4: Build the atlas

Use steps = 1 for a 3D-only atlas. Geometry is shaped after the build, not during it: see atlas_polish().

min_coverage

Smallest share of core labels that must end up with 2D geometry, between 0 and 1. A build that falls below it warns and names the labels that have no shape; the warning fires whatever verbose is set to, because a region that cannot be drawn is data loss rather than progress chatter. The build itself still returns, so a long pipeline is never thrown away over a threshold. Use 0 to turn the check off. Defaults to 0.8, or to options("ggseg.extra.min_coverage"), then GGSEG_EXTRA_MIN_COVERAGE.

cleanup

Remove the intermediate files afterwards. Default TRUE, from options("ggseg.extra.cleanup") or GGSEG_EXTRA_CLEANUP.

The intermediate files live in a folder named after the atlas inside output_dir, and the whole folder is removed. A build therefore refuses to start if that folder already holds files it did not write, since removing it would take them too. Choose another output_dir or atlas_name, or pass FALSE to build there and keep everything.

skip_existing

Reuse a step's intermediate files when they already exist, instead of running the step. Default FALSE, from options("ggseg.extra.skip_existing") or GGSEG_EXTRA_SKIP_EXISTING.

A cache records which ggseg.extra wrote it, not what it was built from, so reuse cannot tell that the volume or lookup table has changed. Reuse is therefore asked for rather than assumed, and is reported when it happens. To continue an interrupted build, either pass TRUE or leave the finished steps out of steps.

coord_space

The space the streamline coordinates are in, when input_tracts is a list of coordinate matrices. One of "infer" (the default), "voxel" for voxel indices, or "mm" for RAS world millimetres. Inference is a heuristic: it cannot always tell, and a wrong guess does not error – it places the tract in the wrong space and produces a plausible-looking atlas. Declare the space when you know it. Whichever applies is reported at verbose >= 1.

Tractography files need no declaration: .trk and .tck files are always read into RAS world millimetres, and "voxel" is an error for them.

Value

A ggseg_atlas object with type "tract", containing region metadata, tube meshes for 3D rendering, colours, and optionally sf geometry for 2D projection plots. A run that stops before the final step returns NULL, invisibly.

See also

atlas_polish() to simplify and round off the result, which most builds want next.

Other atlas creation: create_cerebellar_from_annotation(), create_cerebellar_from_gifti(), create_cerebellar_from_volume(), create_cortical_from_annotation(), create_cortical_from_cifti(), create_cortical_from_gifti(), create_cortical_from_labels(), create_cortical_from_neuromaps(), create_subcortical_from_volume(), create_tract_from_volume(), create_wholebrain_from_volume()

Examples

if (FALSE) { # \dontrun{
# From TRK files (names derived from filenames)
atlas <- create_tract_from_tractography(
  input_tracts = c("cst_left.trk", "cst_right.trk"),
  input_aseg = "aparc+aseg.mgz"
)

# With custom names and colours via LUT
atlas <- create_tract_from_tractography(
  input_tracts = c("cst_left.trk", "cst_right.trk"),
  input_aseg = "aparc+aseg.mgz",
  input_lut = "tract_colors.txt"
)

# A 3D-only atlas from coordinate matrices, which needs no segmentation.
# Declare their space rather than letting it be inferred
atlas <- create_tract_from_tractography(
  input_tracts = list(cst_left = cst_left_points),
  coord_space = "mm",
  steps = 1
)

# View with ggseg3d
ggseg3d::ggseg3d(atlas = atlas)
} # }