---
title: "Getting started with ggseg.extra"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting started with ggseg.extra}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r}
#| label: setup
#| include: false
library(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:

```{r}
#| label: cortical-example
#| eval: false
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](https://surfer.nmr.mgh.harvard.edu/),
  [ImageMagick](https://imagemagick.org/), 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](tutorial-cortical-atlas.html) --- from FreeSurfer annotation files
- [Label-based atlas](tutorial-label-atlas.html) --- from individual label files
- [Neuromaps atlas](tutorial-neuromaps-atlas.html) --- from neuromaps surface or volume data
- [Subcortical atlas](tutorial-subcortical-atlas.html) --- from volumetric segmentation
- [Tract atlas](tutorial-tract-atlas.html) --- from tractography data

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