Given one or more 3D coordinates, look up the atlas region(s) at each location. Supports exact voxel lookup (`radius = 0`), fuzzy search (`radius > 0`) that returns all regions within a sphere of given radius in millimetres, and a nearest-label mode (`nearest = TRUE`) that returns the single closest labelled region within `radius` together with its distance. Multiple atlases can be queried simultaneously.
Arguments
- coords
Numeric vector of length 3 (single point) or an N x 3 matrix of world coordinates.
- atlas
A single atlas object (class `"atlas"`) or a named list of atlas objects.
- radius
Numeric scalar giving the search radius in millimetres. `0` (default) performs an exact voxel lookup; values greater than zero return every region whose labelled voxels fall within `radius` mm of the query coordinate.
- from_space
Character string identifying the coordinate space of the input coordinates (default `"MNI152"`).
- nearest
Logical. If `TRUE`, return exactly one row per point and atlas: the region containing the point if there is one, otherwise the nearest labelled voxel within `radius` mm, with its distance in a `distance` column. Default `FALSE` keeps the exact/fuzzy behaviour.
Value
A tibble with columns:
- point
Integer index of the query coordinate (row number).
- x, y, z
The input world coordinates.
- atlas_name
Name of the atlas.
- id
Integer region ID (`NA` for background or out-of-bounds).
- label
Region label string (`NA` for background/OOB).
- hemi
Hemisphere designation (`NA` if unavailable).
- network
Network label (`NA` if unavailable).
- distance
Only when `nearest = TRUE`: distance in mm from the query coordinate to the centre of the reported region's nearest voxel; `0` when the point lies in a labelled voxel, `NA` when no labelled voxel is within `radius`.
Any further per-region columns from roi_metadata follow.
Details
World coordinates are converted to voxel grid positions via
coord_to_grid and rounded to the nearest integer.
When `radius > 0`, candidate voxel centres in a local grid neighbourhood
are tested in world coordinates to find all labelled atlas voxels within
`radius` mm.
With `nearest = TRUE`, the voxel containing the point (the voxel whose grid position is nearest to it) is checked first; if it is labelled, that region is returned with distance `0`. Otherwise every labelled voxel whose centre lies within `radius` mm of the point is considered and the closest one wins. Distances are Euclidean, in the atlas's world coordinates. Ties (voxel centres equidistant from the point, to within 1e-6 mm) are broken deterministically in favour of the smallest region id, so the result does not depend on voxel scan order. With `radius = 0` only the containing voxel is considered.
If the atlas carries a coordinate-space annotation
(`atlas$atlas_ref$coord_space`) that differs from `from_space`, the input
coordinates are transformed automatically via
transform_coords.
An atlas whose `coord_space` is `NA`, empty or `"Unknown"` has no single
coordinate space to transform into. This is the case for
merge_atlases composites whose parents declare different
spaces, and for atlases built without a space annotation. Such atlases are
queried directly in their own world coordinates: the input coordinates are
assumed to be in the atlas's space, no transform is applied, and a warning
of class `"neuroatlas_unknown_coord_space"` says so. Check that the input
coordinates match the atlas grid before relying on the result.
Examples
if (FALSE) { # \dontrun{
atlas <- get_schaefer_atlas(parcels = "200", networks = "7")
query_point(c(24, -10, 5), atlas)
# Multiple points
pts <- rbind(c(24, -10, 5), c(-30, 20, 50))
query_point(pts, atlas)
# Fuzzy search within 5 mm
query_point(c(24, -10, 5), atlas, radius = 5)
# Nearest labelled region within 4 mm, with its distance
query_point(c(24, -10, 5), atlas, radius = 4, nearest = TRUE)
# Query multiple atlases at once
atlases <- list(schaefer = atlas, aseg = get_aseg_atlas())
query_point(c(24, -10, 5), atlases)
} # }