Title: Interactive 3D Brain Atlas Visualization
Version: 2.0.0
Description: Plot brain atlases as interactive 3D meshes using 'Three.js' via 'htmlwidgets', or render publication-quality static images through 'rgl' and 'rayshader'. A pipe-friendly API lets you map data onto brain regions, control camera angles, toggle region edges, overlay glass brains, and snapshot or ray-trace the result. Additional atlases are available through the 'ggsegverse' r-universe. Mowinckel & Vidal-Piñeiro (2020) <doi:10.1177/2515245920928009>.
License: MIT + file LICENSE
URL: https://github.com/ggsegverse/ggseg3d, https://ggsegverse.github.io/ggseg3d/
BugReports: https://github.com/ggsegverse/ggseg3d/issues
Depends: R (≥ 4.1)
Imports: cli, dplyr, ggseg.formats, htmlwidgets, knitr, lifecycle, rlang, scales, tidyr, webshot2
Suggests: png, rayshader, rgl, rmarkdown, shiny, spelling, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/Needs/website: ggsegverse/ggseg.docs
Config/testthat/edition: 3
Config/testthat/parallel: true
Encoding: UTF-8
Language: en-US
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-02-20 18:32:40 UTC; athanasm
Author: Athanasia Mo Mowinckel ORCID iD [aut, cre], Didac Vidal-Piñeiro ORCID iD [aut]
Maintainer: Athanasia Mo Mowinckel <a.m.mowinckel@psykologi.uio.no>
Repository: CRAN
Date/Publication: 2026-02-20 18:50:02 UTC

ggseg3d: Plot brain segmentations in 3D

Description

Plotting results from analyses done on data derived from brain segmentations is a common need, but may be quite laborious. Results from such analyses are usually easier to interpret if the plot can mimmick the shape and position in the brain it represents.

Details

This package contains data from various brain parcellations, with convenient functions to inspect the results directly on a brain-plot using interactive 3D mesh visualizations powered by Three.js via htmlwidgets.

The package uses 'ggseg_atlas' objects from ggseg.formats that contain 3D vertex mappings.

Author(s)

Maintainer: Athanasia Mo Mowinckel a.m.mowinckel@psykologi.uio.no (ORCID)

Authors:

See Also

Useful links:

Add glass brain to ggseg3d plot

Description

Adds a translucent brain surface to a ggseg3d plot for anatomical reference. Particularly useful for subcortical and tract visualizations where spatial context helps interpretation. Works with both htmlwidget ('ggseg3d') and rgl ('ggsegray') objects.

Usage

add_glassbrain(
  p,
  hemisphere = c("left", "right"),
  surface = "pial",
  colour = "#CCCCCC",
  opacity = 0.3,
  brain_meshes = NULL
)

Arguments

p

A 'ggseg3d' widget or 'ggsegray' rgl object.

hemisphere

Character vector. Hemispheres to add: "left", "right", or both.

surface

Character. Surface type: "inflated", "white", or "pial".

colour

Character. Colour for the glass brain surface (hex or named).

opacity

Numeric. Transparency of the glass brain (0-1).

brain_meshes

Optional user-supplied brain meshes. See [ggseg.formats::get_brain_mesh()] for format details.

Value

The input object (modified), for piping.

Examples

## Not run: 
ggseg3d(atlas = aseg()) |>
  add_glassbrain("left", opacity = 0.2)

ggsegray(atlas = aseg()) |>
  add_glassbrain(opacity = 0.15) |>
  pan_camera("right lateral")

## End(Not run)

Apply colour palette

Description

Processes colour mapping for ggseg_atlas objects using vertex-based colouring.

Usage

apply_colour_palette(atlas_data, colour, palette, na_colour)

Arguments

atlas_data

Atlas data frame with vertices column

colour

Column name for colour values

palette

Colour palette specification

na_colour

Colour for NA values

Value

List with data, fill column name, palette, and colour metadata

Apply colour palette and build legend data

Description

Shared pipeline step for all atlas types: applies colour palette to atlas data and builds the legend data structure.

Usage

apply_colours_and_legend(atlas_data, colour_by, palette, na_colour, label_by)

Arguments

atlas_data

Prepared atlas data frame

colour_by

Column name for colour values

palette

Colour palette specification

na_colour

Colour for NA values

label_by

Column name for labels

Value

List with 'atlas_data' and 'legend_data'

Build centerline data for tract atlases

Description

Extracts centerline data from a tract atlas, applies native coordinate offsets, and assembles the tube generation parameters.

Usage

build_centerline_data(atlas, tube_radius = NULL, tube_segments = NULL)

Arguments

atlas

A 'tract_atlas' object

tube_radius

Optional radius override

tube_segments

Optional segment count override

Value

List with centerlines, tube_radius, tube_segments, or NULL

Build continuous legend

Description

Creates a continuous colorbar legend specification for numeric data.

Usage

build_continuous_legend(palette, pal_colours, colour_col, data_min, data_max)

Arguments

palette

Original palette specification

pal_colours

Processed palette colours

colour_col

Name of the colour column (used as title)

data_min

Minimum data value

data_max

Maximum data value

Value

List with continuous legend specification

Build mesh list for cortical atlases

Description

Creates mesh data structures for cortical ggseg_atlas objects using shared brain meshes with vertex-based colouring.

Usage

build_cortical_meshes(
  atlas_data,
  hemisphere,
  surface,
  na_colour,
  edge_by,
  brain_meshes = NULL,
  text_by = NULL,
  label_by = "region"
)

Arguments

atlas_data

Prepared atlas data frame

hemisphere

Hemispheres to include

surface

Surface type

na_colour

Colour for NA values

edge_by

Column for edge grouping (or NULL)

brain_meshes

Optional user-supplied brain meshes

Value

List of mesh data structures

Build discrete legend

Description

Creates a discrete legend specification for categorical data.

Usage

build_discrete_legend(data, fill_col, label_col)

Arguments

data

Atlas data

fill_col

Name of the fill column

label_col

Name of the label column

Value

List with discrete legend specification or NULL if too many categories

Build legend data structure

Description

Creates the appropriate legend data structure based on whether the colour variable is numeric (continuous colorbar) or categorical (discrete legend).

Usage

build_legend_data(
  is_numeric,
  data_min,
  data_max,
  palette,
  pal_colours,
  colour_col,
  label_col,
  fill_col,
  data
)

Arguments

is_numeric

Whether the colour variable is numeric

data_min

Minimum data value (for continuous)

data_max

Maximum data value (for continuous)

palette

Original palette specification

pal_colours

Processed palette colours

colour_col

Name of the colour column

label_col

Name of the label column

fill_col

Name of the fill column

data

Atlas data

Value

List with legend specification or NULL

Build mesh list for subcortical atlases

Description

Creates mesh data structures for subcortical atlases with per-region mesh data using face-based colouring (each structure is a separate mesh).

Usage

build_subcortical_meshes(
  atlas_data,
  na_colour,
  text_by = NULL,
  label_by = "region"
)

Arguments

atlas_data

Prepared atlas data frame with label, colour, and mesh columns

na_colour

Colour for NA values

Value

List of mesh data structures

Build mesh list for tract atlases

Description

Creates mesh data structures for tract atlases with per-vertex colouring. Supports palette colours (uniform per tract) or orientation-based RGB colours computed from centerline tangent vectors.

Usage

build_tract_meshes(
  atlas_data,
  na_colour,
  color_by = "colour",
  atlas_centerlines = NULL,
  text_by = NULL,
  label_by = "region"
)

Arguments

atlas_data

Prepared atlas data frame with label, colour, and mesh columns

na_colour

Colour for NA values

color_by

How to colour tracts: "colour" (use colour column), "orientation" (direction-based RGB from tangents)

Value

List of mesh data structures

Map camera preset name to position vector

Description

Converts a camera preset string to an xyz position vector matching the same presets used in the Three.js viewer.

Usage

camera_preset_to_position(preset)

Arguments

preset

Character string naming the camera preset.

Value

Numeric vector of length 3 (x, y, z).

Compute parallel transport frames along curve

Description

Compute parallel transport frames along curve

Usage

compute_parallel_transp_fr(curve)

Create ggseg3d htmlwidget

Description

Creates the final htmlwidget object with default options and sizing policy.

Usage

create_ggseg3d_widget(meshes, legend_data)

Arguments

meshes

List of mesh data structures

legend_data

Legend specification (or NULL)

Value

An htmlwidget object of class "ggseg3d"

Cross product of two 3D vectors

Description

Cross product of two 3D vectors

Usage

cross_product(a, b)

Merge user data with mesh atlas data

Description

Merge user data with mesh atlas data

Usage

data_merge_mesh(.data, atlas_data)

Arguments

.data

User-provided data frame

atlas_data

Atlas data frame

Value

Merged data frame

Generate tube mesh from centerline

Description

Creates a 3D tube mesh around a centerline path using parallel transport frames for smooth geometry without twisting artifacts.

Usage

generate_tube_mesh(centerline, radius = 0.5, segments = 8)

Arguments

centerline

Matrix with N rows and 3 columns (x, y, z coordinates)

radius

Tube radius. Either a single value or vector of length N.

segments

Number of segments around tube circumference.

Value

List with vertices (data.frame), faces (data.frame), and metadata

Plot 3D brain parcellations

Description

'ggseg3d' creates and returns an interactive Three.js brain mesh visualization. Dispatches to atlas-type-specific methods via [prepare_brain_meshes()].

Usage

ggseg3d(
  .data = NULL,
  atlas = dk(),
  label_by = "region",
  text_by = NULL,
  colour_by = "colour",
  palette = NULL,
  na_colour = "darkgrey",
  na_alpha = 1,
  ...,
  label = deprecated(),
  text = deprecated(),
  colour = deprecated()
)

Arguments

.data

A data.frame to use for plot aesthetics. Must include a column called "region" corresponding to regions.

atlas

A 'ggseg_atlas' object containing 3D vertex mappings, or a string naming an atlas function (deprecated).

label_by

String. Column name used as hover label for each region.

text_by

String. Column name for extra hover text shown below the region label.

colour_by

String. Column name mapped to mesh colours.

palette

String. Vector of colour names or HEX colours. Can also be a named numeric vector, with colours as names, and breakpoint for that colour as the value

na_colour

String. Either name, hex of RGB for colour of NA in colour.

na_alpha

Numeric. A number between 0 and 1 to control transparency of NA-regions.

...

Type-specific arguments passed to the atlas method. See section **Type-specific arguments** below.

label, text, colour

'r lifecycle::badge("deprecated")' Use 'label_by', 'text_by', and 'colour_by' instead.

Value

an htmlwidget object for interactive 3D brain visualization

Type-specific arguments

Cortical atlases ('cortical_atlas'):

'surface'

Surface type: '"LCBC"' (default, alias for inflated), '"inflated"', '"semi-inflated"', '"white"', '"pial"'.

'hemisphere'

Character vector of hemispheres: '"right"', '"left"'.

'edge_by'

Column name for region boundary edges.

'brain_meshes'

Custom brain mesh data.

Tract atlases ('tract_atlas'):

'tract_color'

'"palette"' (default) or '"orientation"' (direction-based RGB).

'tube_radius'

Tube radius (numeric, default 5).

'tube_segments'

Tube segment count (integer, default 8).

Author(s)

Athanasia Mowinckel and Didac Piñeiro

See Also

[pan_camera()] for camera position, [set_background()] for background colour, [set_legend()] for legend visibility

Examples

## Not run: 
ggseg3d()
ggseg3d(hemisphere = "left") |> pan_camera("left lateral")
ggseg3d() |> set_legend(FALSE)
ggseg3d() |> set_background("black")

## End(Not run)

Shiny bindings for ggseg3d

Description

Output and render functions for using ggseg3d within Shiny applications and interactive R Markdown documents.

Usage

ggseg3dOutput(outputId, width = "100%", height = "400px")

renderGgseg3d(expr, env = parent.frame(), quoted = FALSE)

Arguments

outputId

output variable to read from

width, height

Must be a valid CSS unit (like '100%', '400px', 'auto') or a number, which will be coerced to a string and have 'px' appended.

expr

An expression that generates a ggseg3d

env

The environment in which to evaluate expr.

quoted

Is expr a quoted expression (with quote())? This is useful if you want to save an expression in a variable.

Render brain atlas with rgl

Description

Creates an rgl 3D scene from a brain atlas. Uses the same atlas preparation pipeline as [ggseg3d()] but outputs to rgl instead of htmlwidgets. The resulting scene can be piped into [pan_camera()], [add_glassbrain()], and [set_background()], then rendered with rayshader's 'render_highquality()' or captured with 'rgl::snapshot3d()'.

Usage

ggsegray(
  .data = NULL,
  atlas = dk(),
  label_by = "region",
  text_by = NULL,
  colour_by = "colour",
  palette = NULL,
  na_colour = "darkgrey",
  na_alpha = 1,
  material = list(),
  ...,
  label = deprecated(),
  text = deprecated(),
  colour = deprecated()
)

Arguments

.data

A data.frame to use for plot aesthetics. Must include a column called "region" corresponding to regions.

atlas

A 'ggseg_atlas' object containing 3D vertex mappings, or a string naming an atlas function (deprecated).

label_by

String. Column name used as hover label for each region.

text_by

String. Column name for extra hover text shown below the region label.

colour_by

String. Column name mapped to mesh colours.

palette

String. Vector of colour names or HEX colours. Can also be a named numeric vector, with colours as names, and breakpoint for that colour as the value

na_colour

String. Either name, hex of RGB for colour of NA in colour.

na_alpha

Numeric. A number between 0 and 1 to control transparency of NA-regions.

material

Named list of rgl material properties passed to [rgl::tmesh3d()]. Controls how the mesh surface is shaded.

...

Type-specific arguments passed to the atlas method. See section **Type-specific arguments** below.

label, text, colour

'r lifecycle::badge("deprecated")' Use 'label_by', 'text_by', and 'colour_by' instead.

Value

An object of class 'ggsegray' (invisibly), which wraps the rgl device ID. Pipe into [pan_camera()], [add_glassbrain()], or [set_background()] to modify the scene.

Material properties

Useful material list entries:

'specular'

'"black"' (matte) or '"white"' (glossy).

'shininess'

Specular exponent. Higher = tighter highlights.

'lit'

'FALSE' disables lighting.

'alpha'

Transparency, 0 (invisible) to 1 (opaque).

'smooth'

'TRUE' for Gouraud shading, 'FALSE' for flat.

See [rgl::material3d()] for the full list.

Type-specific arguments

Cortical atlases ('cortical_atlas'):

'surface'

Surface type: '"LCBC"' (default, alias for inflated), '"inflated"', '"semi-inflated"', '"white"', '"pial"'.

'hemisphere'

Character vector of hemispheres: '"right"', '"left"'.

'edge_by'

Column name for region boundary edges.

'brain_meshes'

Custom brain mesh data.

Tract atlases ('tract_atlas'):

'tract_color'

'"palette"' (default) or '"orientation"' (direction-based RGB).

'tube_radius'

Tube radius (numeric, default 5).

'tube_segments'

Tube segment count (integer, default 8).

Examples

## Not run: 
ggsegray(hemisphere = "left") |>
  pan_camera("left lateral")

ggsegray(atlas = aseg()) |>
  add_glassbrain(opacity = 0.15) |>
  pan_camera("right lateral") |>
  set_background("black")

## End(Not run)

Compute rgl rotation matrix to look at the origin from a given position

Description

Builds a 4x4 rotation matrix suitable for 'rgl::view3d(userMatrix = ...)' that orients the scene as if the camera is at 'eye' looking toward the origin with z pointing up.

Usage

look_at_origin(eye)

Arguments

eye

Numeric vector of length 3 (x, y, z) — camera position.

Value

A 4x4 rotation matrix.

Convert mesh entry to rgl mesh3d object

Description

Converts the internal mesh_entry list structure (as built by [make_mesh_entry()]) into an [rgl::tmesh3d()] object for rgl rendering.

Usage

mesh_entry_to_mesh3d(mesh_entry, ...)

Arguments

mesh_entry

A mesh entry list with vertices, faces, colors, colorMode, and opacity.

...

Material properties merged into the 'material' list of [rgl::tmesh3d()]. Overrides defaults ('specular = "black"', 'shininess = 128'). See [rgl::material3d()] for all options.

Value

An rgl 'mesh3d' object

Pan camera position of ggseg3d plot

Description

Sets the camera position for a ggseg3d widget or ggsegray rgl scene to standard anatomical views or custom positions.

Usage

pan_camera(p, camera)

Arguments

p

A 'ggseg3d' widget or 'ggsegray' rgl object.

camera

string, list, or numeric vector. Camera position preset name, custom eye position list, or 'c(x, y, z)' for rgl.

Available camera presets:

  • 'left lateral' or 'left_lateral'

  • 'left medial' or 'left_medial'

  • 'right lateral' or 'right_lateral'

  • 'right medial' or 'right_medial'

  • 'left superior' or 'left_superior'

  • 'right superior' or 'right_superior'

  • 'left inferior' or 'left_inferior'

  • 'right inferior' or 'right_inferior'

  • 'left anterior' or 'left_anterior'

  • 'right anterior' or 'right_anterior'

  • 'left posterior' or 'left_posterior'

  • 'right posterior' or 'right_posterior'

Value

The input object (modified), for piping.

Examples

## Not run: 
ggseg3d() |> pan_camera("right lateral")

ggsegray(atlas = dk(), hemisphere = "left") |>
  pan_camera("left lateral")

## End(Not run)

Position hemisphere vertices for anatomical display

Description

Offsets hemisphere vertices so left is at negative x and right at positive x, with medial surfaces adjacent at the midline. Used by [add_glassbrain()] for anatomical context.

Usage

position_hemisphere(vertices, hemisphere)

Arguments

vertices

data.frame with x, y, z columns

hemisphere

"left" or "right"

Value

data.frame with adjusted x coordinates

Prepare atlas data

Description

Extracts and prepares data from a ggseg_atlas object for rendering. Joins vertices with core region info and palette colours.

Usage

prepare_atlas_data(atlas, .data)

Arguments

atlas

A ggseg_atlas object

.data

Optional user data to merge

Value

Prepared data frame with hemi, region, label, colour, and vertices

Prepare brain meshes and legend data

Description

S3 generic that dispatches to atlas-type-specific preparation methods. Builds mesh data structures and legend data from a 'ggseg_atlas'.

Usage

prepare_brain_meshes(atlas, ...)

## S3 method for class 'cortical_atlas'
prepare_brain_meshes(
  atlas,
  .data = NULL,
  surface = "LCBC",
  hemisphere = c("right", "left"),
  label_by = "region",
  text_by = NULL,
  colour_by = "colour",
  palette = NULL,
  na_colour = "darkgrey",
  na_alpha = 1,
  edge_by = NULL,
  brain_meshes = NULL,
  ...
)

## S3 method for class 'subcortical_atlas'
prepare_brain_meshes(
  atlas,
  .data = NULL,
  label_by = "region",
  text_by = NULL,
  colour_by = "colour",
  palette = NULL,
  na_colour = "darkgrey",
  na_alpha = 1,
  ...
)

## S3 method for class 'tract_atlas'
prepare_brain_meshes(
  atlas,
  .data = NULL,
  label_by = "region",
  text_by = NULL,
  colour_by = "colour",
  palette = NULL,
  na_colour = "darkgrey",
  na_alpha = 1,
  tract_color = c("palette", "orientation"),
  tube_radius = 2,
  tube_segments = 10,
  ...
)

Arguments

atlas

A 'ggseg_atlas' object

...

Type-specific arguments passed to methods

.data

Optional user data to merge

surface

Surface type: '"inflated"' (default), '"semi-inflated"', '"white"', '"pial"'. Use '"LCBC"' as alias for '"inflated"'.

hemisphere

Character vector of hemispheres: '"right"', '"left"'.

label_by

Column name for region hover labels

text_by

Column name for extra hover text

colour_by

Column name for colour values

palette

Colour palette specification

na_colour

Colour for NA values

na_alpha

Transparency for NA regions

edge_by

Column name for region boundary edge grouping

brain_meshes

Optional user-supplied brain meshes

tract_color

'"palette"' (default) or '"orientation"' (direction-based RGB colouring)

tube_radius

Numeric tube radius (default 5 when 'NULL').

tube_segments

Integer tube segment count (default 8 when 'NULL').

Value

List with 'meshes' (list of mesh entries) and 'legend_data'

Prepare mesh-based atlas data

Description

Extracts and prepares data from a mesh-based ggseg_atlas object (subcortical/tract) for rendering. Joins meshes with core region info and palette colours.

Usage

prepare_mesh_atlas_data(atlas, .data)

Arguments

atlas

A mesh-based ggseg_atlas object

.data

Optional user data to merge

Value

Prepared data frame with hemi, region, label, colour, and mesh

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

ggseg.formats

aseg, dk, tracula

Resolve brain surface mesh

Description

Resolves and prepares a brain surface mesh for rendering. Delegates to [ggseg.formats::get_brain_mesh()] for inflated surfaces, provides pial, white, and semi-inflated surfaces from ggseg3d internal data, corrects 0-based face indices, and centers inflated/semi-inflated meshes on pial centroids.

Usage

resolve_brain_mesh(
  hemisphere = c("lh", "rh"),
  surface = c("inflated", "semi-inflated", "white", "pial"),
  brain_meshes = NULL
)

Arguments

hemisphere

'"lh"' or '"rh"'

surface

Surface type: '"inflated"', '"semi-inflated"', '"white"', '"pial"'

brain_meshes

Optional user-supplied mesh data. Passed through to [ggseg.formats::get_brain_mesh()] for format details.

Value

list with vertices (data.frame with x, y, z) and faces (data.frame with i, j, k), or NULL if mesh not found

Rotate vector around axis by angle (Rodrigues' formula)

Description

Rotate vector around axis by angle (Rodrigues' formula)

Usage

rotate_vector(v, axis, angle)

Set background color of ggseg3d plot

Description

Changes the background color of a ggseg3d widget or ggsegray rgl scene.

Usage

set_background(p, colour = "#ffffff")

Arguments

p

A 'ggseg3d' widget or 'ggsegray' rgl object.

colour

string. Background color (hex or named color)

Value

The input object (modified), for piping.

Examples

## Not run: 
ggseg3d() |> set_background("black")

ggsegray(atlas = dk()) |> set_background("black")

## End(Not run)

Set widget dimensions

Description

Changes the width and height of a ggseg3d widget.

Usage

set_dimensions(p, width = NULL, height = NULL)

Arguments

p

ggseg3d widget object

width

numeric. Widget width in pixels (NULL for default)

height

numeric. Widget height in pixels (NULL for default)

Value

ggseg3d widget object with updated dimensions

Examples

## Not run: 
ggseg3d() |>
  set_dimensions(width = 800, height = 600)

## End(Not run)

Set region boundary edges

Description

Adds coloured outlines around brain regions. This is useful for highlighting region boundaries in figures. Works with both htmlwidget ('ggseg3d') and rgl ('ggsegray') objects. For rgl, edges must have been computed at creation time via 'edge_by'.

Usage

set_edges(p, colour = "black", width = 1)

Arguments

p

A 'ggseg3d' widget or 'ggsegray' rgl object.

colour

string. Edge colour (hex or named color). Set to NULL to hide edges.

width

numeric. Width of edge lines (default: 1). Note: line width > 1 may not render on all systems due to WebGL limitations.

Value

The input object (modified), for piping.

Lifecycle

'r lifecycle::badge("experimental")'

Examples

## Not run: 
ggseg3d(hemisphere = "left", edge_by = "region") |>
  set_edges("black") |>
  pan_camera("left lateral")

ggsegray(hemisphere = "left", edge_by = "region") |>
  set_edges("red", width = 2) |>
  pan_camera("left lateral")

## End(Not run)

Enable flat shading for ggseg3d plot

Description

Disables lighting effects to show colors exactly as specified. Useful for screenshots where accurate color reproduction is needed, such as atlas creation pipelines that extract contours from images.

Usage

set_flat_shading(p, flat = TRUE)

Arguments

p

ggseg3d widget object

flat

logical. Enable flat shading (default: TRUE)

Value

ggseg3d widget object with updated shading

Examples

## Not run: 
ggseg3d() |>
  set_flat_shading()

## End(Not run)

Set legend visibility

Description

For htmlwidget output, toggles legend visibility. For rgl output, draws or removes the legend overlay.

Usage

set_legend(p, show = TRUE)

Arguments

p

A ggseg3d or ggsegray object

show

logical. Whether to show the legend (default: TRUE)

Value

The input object, modified

Examples

## Not run: 
ggseg3d() |> set_legend(FALSE)
ggsegray(hemisphere = "left") |> set_legend()

## End(Not run)

Enable orthographic camera for ggseg3d plot

Description

Uses orthographic projection instead of perspective. This eliminates perspective distortion and ensures consistent sizing across all views.

Usage

set_orthographic(p, ortho = TRUE, frustum_size = 220)

Arguments

p

ggseg3d widget object

ortho

logical. Enable orthographic mode (default: TRUE)

frustum_size

numeric. Size of the orthographic frustum. Controls how much of the scene is visible. Default 220 works well for brain meshes. Use the same value across all views for consistent sizing.

Value

ggseg3d widget object with updated camera mode

Examples

## Not run: 
ggseg3d() |>
  set_orthographic()

## End(Not run)

Set hemisphere positioning mode

Description

Repositions meshes in a ggseg3d widget to either anatomical or centered mode. This modifies the x-coordinates of all meshes in the widget.

Usage

set_positioning(p, positioning = c("anatomical", "centered"))

Arguments

p

ggseg3d widget object

positioning

How to position hemispheres: - "anatomical": Offset so medial surfaces are adjacent at midline. Left at negative x, right at positive x. Best for displaying both hemispheres together. - "centered": Center each hemisphere at the origin. Best for single-hemisphere snapshots where consistent sizing is needed.

Value

ggseg3d widget object with repositioned meshes

Examples

## Not run: 
# View both hemispheres anatomically positioned
ggseg3d(hemisphere = c("left", "right")) |>
  set_positioning("anatomical") |>
  pan_camera("left lateral")

# Atlas creation: centered (default) for consistent sizing
ggseg3d(hemisphere = "left") |>
  set_orthographic() |>
  pan_camera("left lateral") |>
  snapshot_brain("left_lateral.png")

## End(Not run)

Save ggseg3d widget as image

Description

Takes a screenshot of a ggseg3d widget and saves it as a PNG image. Requires a Chrome-based browser to be installed.

Usage

snapshot_brain(p, file, width = 600, height = 500, delay = 1, zoom = 2, ...)

Arguments

p

ggseg3d widget object

file

string. Output file path (should end in .png)

width

numeric. Image width in pixels (default: 600)

height

numeric. Image height in pixels (default: 500)

delay

numeric. Seconds to wait for widget to render before capture (default: 1)

zoom

numeric. Zoom factor for higher resolution (default: 2)

...

Additional arguments passed to webshot2::webshot

Value

The file path (invisibly)

Examples

## Not run: 
ggseg3d() |>
  pan_camera("left lateral") |>
  snapshot_brain("brain.png")

## End(Not run)

Convert tangent vectors to orientation RGB colours

Description

Computes direction-based RGB colours from centerline tangent vectors. Standard tractography colouring: R = left-right (x), G = anterior-posterior (y), B = superior-inferior (z).

Usage

tangents_to_colors(mesh_data)

Arguments

mesh_data

Mesh data with vertices data.frame and metadata list

Value

Character vector of hex colours (one per mesh vertex)

Update background in Shiny

Description

Sends a message to update the background color of a ggseg3d widget in a Shiny app.

Usage

updateGgseg3dBackground(session, outputId, colour)

Arguments

session

The Shiny session object

outputId

The output ID of the ggseg3d widget

colour

Background color (hex or named color)

Update camera in Shiny

Description

Sends a message to update the camera position of a ggseg3d widget in a Shiny app.

Usage

updateGgseg3dCamera(session, outputId, camera)

Arguments

session

The Shiny session object

outputId

The output ID of the ggseg3d widget

camera

Camera position preset or custom position

Map atlas vertex indices to mesh colors

Description

Given a ggseg_atlas with vertices column and a brain mesh, creates a color vector for each mesh vertex based on which region it belongs to.

Usage

vertices_to_colors(atlas_data, n_vertices, na_colour = "#CCCCCC")

Arguments

atlas_data

Data frame with region, colour, and vertices columns

n_vertices

Number of vertices in the mesh

na_colour

Color for vertices not in any region

Value

Character vector of colors, one per mesh vertex

Map atlas vertex indices to region labels

Description

Given a ggseg_atlas with vertices column and a brain mesh, creates a label vector for each mesh vertex based on which region it belongs to.

Usage

vertices_to_labels(atlas_data, n_vertices, na_label = NA_character_)

Arguments

atlas_data

Data frame with region and vertices columns

n_vertices

Number of vertices in the mesh

na_label

Label for vertices not in any region

Value

Character vector of labels, one per mesh vertex

Map vertices to text values for hover display

Description

Assigns text values to mesh vertices based on a column in atlas data. Used for per-vertex hover text in the Three.js tooltip.

Usage

vertices_to_text(atlas_data, n_vertices, text_col)

Arguments

atlas_data

Data frame with vertices list column

n_vertices

Number of vertices in the mesh

text_col

Name of the column containing text values

Value

Character vector of text values, one per mesh vertex