Reduce an atlas's vertex count

Drops vertices from region geometry while keeping its topology, so an atlas costs less to store and to draw.

Usage

atlas_simplify(
  atlas,
  keep = 0.05,
  close_gaps = TRUE,
  labels = NULL,
  exclude = NULL
)

Arguments

atlas

A ggseg_atlas object with 2D geometry.

keep

Proportion of vertices to retain, between 0 and 1. Lower is smaller and blockier; near 1 is an effective no-op. A target rather than a promise: a ring is never taken below the handful of vertices that holds its shape, so an atlas of many small rings lands above what was asked - keep = 0.05 on a tract atlas came back at 0.18. atlas_polish() has measured figures.

close_gaps

Whether to hand back any sliver the simplification opens between neighbouring regions. Simplification is topology-aware, so on geometry straight out of a pipeline, whose neighbours share their boundary vertex for vertex, it opens none and this does nothing. It earns its keep on geometry that has been reshaped since - rounded off by atlas_smooth(), or traced region by region from separate masks - where the rings no longer agree and the shared edge comes apart. With TRUE, the default, area that no longer belongs to any region but borders two of them is given back to one of them.

labels, exclude

Which labels to simplify, or which to leave alone: a regular expression, or a function that takes the atlas and returns one. Pass context_pattern, without calling it, to select the atlas's context. Give at most one.

Value

The ggseg_atlas, in the representation it arrived in.

Details

This is about size, not shape. The silhouette an atlas draws behind its structures usually carries the bulk of the vertices, so it is the part worth simplifying; tiny deep structures have few to spare. Use labels or exclude to say which.

See also

atlas_smooth() to round shapes off, and atlas_dilate() to grow or shrink them. Simplify first and smooth afterwards, so the smoothing has the last word on the outline.

Other atlas geometry: atlas_dilate(), atlas_polish(), atlas_smooth(), count_vertices()

Examples

dk <- ggseg.formats::dk()
sum(count_vertices(dk))
#> [1] 5391

simplified <- atlas_simplify(dk, keep = 0.2)
sum(count_vertices(simplified))
#> [1] 2346

if (FALSE) { # \dontrun{
# Simplify the backdrop only, sparing the structures.
atlas_simplify(dk, keep = 0.5, labels = context_pattern)
} # }