Getting started with ggseg.extra • ggseg.extra

ggseg.extra provides pipelines for creating brain atlas data sets compatible with the ggseg and ggseg3d plotting packages. It supports multiple neuroimaging input formats:

Function	Input	Use case
`create_cortical_from_annotation()`	FreeSurfer `.annot` files	Cortical parcellations (DK, DKT, Yeo networks)
`create_cortical_from_labels()`	Individual `.label` files	Custom region combinations
`create_cortical_from_gifti()`	GIFTI `.label.gii` files	Cortical parcellations in GIFTI format
`create_cortical_from_cifti()`	CIFTI `.dlabel.nii` files	HCP-style cortical parcellations
`create_cortical_from_neuromaps()`	Neuromaps `.func.gii` or `.nii` files	Brain maps and parcellations from neuromaps
`create_subcortical_from_volume()`	Volumetric segmentation	Subcortical structures (thalamus, amygdala)
`create_wholebrain_from_volume()`	Volumetric parcellation with colour table	Combined cortical + subcortical atlases
`create_tract_from_tractography()`	Tractography files (`.trk`, `.tck`)	White matter tracts

All functions produce a ggseg_atlas object that works with both ggseg (2D) and ggseg3d (3D).

What’s inside a ggseg_atlas

Every atlas contains:

Core metadata — region names, hemisphere labels, and the mapping between region names and annotation labels.
Colour palette — extracted from your input files or auto-generated.
3D data — vertex indices for cortical atlases, or meshes for subcortical and tract atlases.
2D geometry (optional) — sf polygon outlines for flat brain plots.

Cortical pipeline

The cortical pipeline reads annotation data and projects inflated mesh triangles directly to 2D polygons via orthographic projection. This completes in seconds and needs no external rendering dependencies:

annot_files <- file.path(
  freesurfer::fs_dir(),
  "subjects",
  "fsaverage5",
  "label",
  c("lh.aparc.annot", "rh.aparc.annot")
)

atlas <- create_cortical_from_annotation(
  input_annot = annot_files,
  output_dir = "my_atlas"
)

Subcortical and tract pipelines

The subcortical and tract pipelines use a steps parameter to control how much of the pipeline runs. Use a low step count for fast 3D-only iteration, then run the full pipeline when you’re ready for 2D geometry.

Post-processing

Raw atlases often contain regions you don’t need (white matter, ventricles, unknown labels) and views that don’t show your structures well. The atlas_region_* and atlas_view_* helpers from ggseg.formats handle cleanup without rebuilding from scratch. See vignette("post-processing") for the full toolkit.

System requirements

Using pre-built atlases requires nothing beyond R. Creating your own atlases may require additional R packages and system tools depending on the pipeline:

Cortical (annotation/label files) — no system tools needed; uses the freesurferformats R package to read files and projects mesh to 2D directly.
Subcortical / whole-brain — FreeSurfer, ImageMagick, and Chrome/Chromium for screenshot-based 2D extraction.
Tract — no system tools; reads tractography files with R packages.

All heavier dependencies (freesurfer, magick, chromote, terra, etc.) are in Suggests and only loaded when needed.

Run setup_sitrep() to check your setup, or see vignette("system-setup") for details.

Tutorials

The package includes step-by-step tutorials that walk through complete atlas creation pipelines:

Cortical atlas — from FreeSurfer annotation files
Label-based atlas — from individual label files
Neuromaps atlas — from neuromaps surface or volume data
Subcortical atlas — from volumetric segmentation
Tract atlas — from tractography data

See also vignette("pipeline-configuration") for controlling verbosity, parallelism, and output directories.