Package 'neurotransform'

Description

Returns an adjoint morphism when defined.

Usage

adjoint(object, ...)

## S4 method for signature 'Morphism'
adjoint(object, ...)

## S4 method for signature 'IdentityMorphism'
adjoint(object, ...)

## S4 method for signature 'Affine3DMorphism'
adjoint(object, ...)

## S4 method for signature 'Warp3DMorphism'
adjoint(object, ...)

## S4 method for signature 'VolToSurfMorphism'
adjoint(object, ...)

## S4 method for signature 'SurfToSurfMorphism'
adjoint(object, ...)

Arguments

Details

For invertible morphisms, adjoint() is defined and equals invert(). For other morphisms, adjoint() may not be implemented and will error.

Value

Adjoint morphism or error if not available

Description

Wrap an affine matrix built from components into an Affine3DMorphism

Usage

affine_from_components(source, target, ...)

Arguments

Value

Affine3DMorphism object

Description

Lightweight helpers for building, decomposing, and testing affine transforms without introducing external dependencies or tool-specific semantics.

Description

Represents an affine transformation between volume spaces. The matrix maps target coords -> source coords (pullback semantics).

Usage

Affine3DMorphism(source, target, matrix, cost = 1, method_tag = "anatomical")

Arguments

Value

Affine3DMorphism object

Examples

# Translation by (10, 20, 30)
mat <- diag(4)
mat[1:3, 4] <- c(10, 20, 30)
aff <- Affine3DMorphism("native", "mni", mat)

Description

Represents an affine transformation (rotation, translation, scaling, shear) between volume spaces.

Slots

matrix

4x4 affine transformation matrix (maps target -> source)

Description

Converts an AFNI RAI/DICOM affine matrix to our internal RAS convention by flipping the X and Y axes. Optionally applies AFNI-style deobliquing compensation when source/target image affines are provided. Standard ⁠3dAllineate -1Dmatrix_save⁠ matrices map base/target coordinates to source/input coordinates, which is already the package's pullback direction.

Usage

afni_aff12_to_ras(
  mat_rai,
  source_affine = NULL,
  target_affine = NULL,
  oblique_correction = TRUE
)

Arguments

Value

4x4 affine in RAS coordinates

Examples

mat_rai <- diag(4)
mat_ras <- afni_aff12_to_ras(mat_rai)

Description

Detect whether an affine is oblique (not cardinal axis-aligned)

Usage

afni_is_oblique(affine, threshold_deg = 0.01)

Arguments

Value

Logical

Description

Reads a single affine from a .aff12.1D file and returns it as a 4x4 matrix in AFNI RAI/DICOM coordinates. AFNI axis labels describe the negative end of each axis, so numeric RAI coordinates increase toward Left, Posterior, and Superior (LPS).

Usage

afni_read_aff12(path, row = NULL)

Arguments

Value

4x4 affine matrix (in RAI)

See Also

afni_read_aff12_array for per-volume matrix series

Examples

## Not run: 
mat_rai <- afni_read_aff12("transform.aff12.1D")

## End(Not run)

Description

Reads all matrix rows, returning one 4x4 matrix per row in AFNI RAI/DICOM coordinates. Comment lines are returned in the "comments" attribute.

Usage

afni_read_aff12_array(path)

Arguments

Value

A list of 4x4 matrices in RAI, with a "comments" attribute holding the file's comment lines

See Also

afni_read_aff12 for a single-matrix file

Examples

path <- tempfile(fileext = ".aff12.1D")
afni_write_aff12(list(diag(4), diag(4)), path)
length(afni_read_aff12_array(path))

Description

AFNI-specific coordinate convention handling. AFNI 3dQwarp stores displacement fields in DICOM/LPS convention. These functions handle the LPS <-> RAS conversion for warps and RAI <-> RAS for affines.

Coordinate Systems

• RAI/DICOM (used by AFNI affines and warp displacements): +X=Left, +Y=Posterior, +Z=Superior (numerically LPS)

• RAS (NIfTI/neuroim2): +X=Right, +Y=Anterior, +Z=Superior

LPS to RAS: negate X and Y (Z is the same).

Description

Writes matrices in AFNI's canonical layout: one row of twelve row-major numbers per matrix, optionally preceded by a banner comment. This is the layout ⁠3dAllineate -1Dmatrix_apply⁠ expects.

Usage

afni_write_aff12(x, path, comment = TRUE)

Arguments

Value

Invisibly, path

Examples

path <- tempfile(fileext = ".aff12.1D")
afni_write_aff12(diag(4), path)

Description

S4 class definitions for the neurotransform package. This file defines the morphism class hierarchy. neurotransform is a pure transform kernel; domain and geometry abstractions live in higher-level packages.

Class Hierarchy

Morphism (virtual)
  |-- IdentityMorphism
  |-- Affine3DMorphism
  |-- Warp3DMorphism
  |-- VolToSurfMorphism
  |-- SurfToSurfMorphism

MorphismPath (lightweight list wrapper for composed paths)

Direction Convention

A morphism A -> B maps coordinates in B to coordinates in A (pullback semantics). This is the natural convention for resampling: to get a value at target location, you need to know where to sample from in the source.

Description

Generic function definitions for the neurotransform package. These define the core API for coordinate transforms.

Description

Creates a morphism (or MorphismPath) from an ANTs composite H5 transform file. These files typically contain both a displacement field and an affine transform.

Usage

ants_h5_morphism(
  path,
  source = "source",
  target = "target",
  apply_affine = TRUE
)

Arguments

Value

Warp3DMorphism (if no affine or apply_affine=FALSE), MorphismPath, or Affine3DMorphism for an affine-only H5 file. For an affine-only file, apply_affine=FALSE is an error because there is no displacement field.

Pullback Ordering

When apply_affine=TRUE, the H5 component order is preserved in the returned MorphismPath. Both ITK composite transforms and MorphismPath evaluate the stored components from last to first, so preserving the order reproduces ITK point-transform semantics.

Description

Generic function to apply a 4x4 affine matrix to 3D coordinates.

Usage

apply_affine(coords, affine)

Arguments

Value

Transformed coordinates

Examples

coords <- matrix(c(10, 20, 30), ncol = 3)
affine <- diag(4)
affine[1:3, 4] <- c(5, 10, 15)  # translation
apply_affine(coords, affine)

Description

Apply a resampling plan to a volume

Usage

apply_resampling_plan(
  plan,
  source_data,
  outside = NA_real_,
  modulate = c("none", "jacobian", "sqrt_jacobian")
)

Arguments

Value

Array with target_grid dimensions (and trailing data dim if 4D input)

Description

Applies the transpose of the exact forward operator, including fixed masks and the selected normalization, without renormalizing its transpose. This is an algebraic adjoint, not reverse geometric interpolation or reconstruction. Unsupported source columns receive algebraic zero; details=TRUE identifies them. Missing-data omission is not a fixed linear operator and is unsupported.

Usage

apply_surface_adjoint(
  plan,
  x,
  normalize = c("element", "sum", "none"),
  details = FALSE
)

Arguments

Value

Vector/matrix or a list with values and available.

Description

Geometry, source ROI mass and finite-data mass are distinct. Unsupported or masked outputs are unavailable (NA), while supported numerical zero remains zero. Zero-weight missing inputs never contaminate an output. Omission returns the retained raw weight mass as an attribute, or in the detailed result.

Usage

apply_surface_resampling(
  plan,
  x,
  inverse = FALSE,
  normalize = c("element", "sum", "none"),
  na_policy = c("propagate", "omit", "error"),
  data_type = c("continuous", "label"),
  label_method = c("aggregate", "largest"),
  label_table = NULL,
  unassigned = NA_integer_,
  details = FALSE
)

Arguments

Details

Label keys are never averaged. Aggregate voting sums weights for each key; largest voting selects one source vertex. Ties select the smallest label key for aggregate voting and the smallest source vertex index for largest voting.

Value

Vector/matrix, or a list when details=TRUE. Diagnostics include raw source and finite-data weight mass before normalization and target masking. Adaptive plans also report source_roi_target_area before target masking. effective_target_area is available only for row normalization, and is column specific under omission. With finite continuous data and no target exclusion it gives the area identity described in the surface vignette.

Description

File paths are read with read_transform() and no further arguments. FSL warps need image geometry that a path alone does not carry, so read them with read_transform(..., source_affine, source_dim) and pass the resulting morphisms instead.

Usage

as_morphism_path(...)

Arguments

Value

MorphismPath object

Description

Implements a simple backprojection operator that distributes each surface value into the source volume grid using the same interpolation weights that forward sampling would use.

Usage

backproject_surface_to_volume(
  surface_values,
  morphism,
  grid,
  surface_coords = NULL,
  method = c("linear", "nearest", "ribbon"),
  outside = 0
)

Arguments

Details

This is the transpose/adjoint of the linear sampling operator for sample_volume_on_surface(..., method="linear") when the same surface_coords are used.

Value

3D array (or 4D if multivariate surface_values) in grid geometry

Description

Build a 4x4 affine matrix from components

Usage

build_affine_matrix(
  translation = c(0, 0, 0),
  scales = c(1, 1, 1),
  skews = c(0, 0, 0),
  angles = c(0, 0, 0),
  anchor = c("none", "origin", "centre", "center")
)

Arguments

Value

4x4 numeric matrix

Description

Returns the composition g . f (f applied first, then g). The result is a MorphismPath that can be passed to transform().

Usage

compose(f, g)

## S4 method for signature 'Morphism,Morphism'
compose(f, g)

## S4 method for signature 'MorphismPath,Morphism'
compose(f, g)

## S4 method for signature 'Morphism,MorphismPath'
compose(f, g)

## S4 method for signature 'MorphismPath,MorphismPath'
compose(f, g)

Arguments

Value

MorphismPath representing the composition

Examples

aff1 <- Affine3DMorphism("a", "b", diag(4))
aff2 <- Affine3DMorphism("b", "c", diag(4))
path <- compose(aff1, aff2)  # a -> b -> c

Description

Returns the composition B(A(x)) = BA * x.

Usage

compose_affines(A, B)

Arguments

Value

Composed 4x4 affine matrix

Examples

A <- diag(4); A[1:3, 4] <- c(1, 2, 3)
B <- diag(4); B[1:3, 4] <- c(4, 5, 6)
compose_affines(A, B)

Description

Creates a reproducible hash using digest with serialize=TRUE.

Usage

compute_hash(..., algo = "xxhash64")

Arguments

Value

Character string hash

Examples

compute_hash("hello", "world")
compute_hash(list(a = 1, b = 2))

Description

Convert affine conventions between "generic" (target→source world) and "fsl" (source→target vox)

Usage

convert_affine_convention(
  matrix,
  source_affine,
  target_affine,
  source_dim = NULL,
  target_dim = NULL,
  from = c("generic", "fsl"),
  to = c("generic", "fsl")
)

Arguments

Description

Functions for converting between coordinate conventions used in neuroimaging.

Internal convention: RAS (Right-Anterior-Superior) in millimeters.

Supported conventions

• RAS: Right-Anterior-Superior (internal standard)

• LPS: Left-Posterior-Superior (ANTs/ITK convention)

• tkRAS: FreeSurfer tkregister RAS

• FSL: FSL world coordinates (mm, may need scaling)

Description

Apply affines -> warp -> affines to coordinates (target -> source)

Usage

cpp_path_apply_affine_warp_affine(
  coords,
  affines_pre,
  field,
  dim,
  world_to_vox,
  cubic,
  affines_post
)

Arguments

Value

n x 3 source world coords

Description

Apply arbitrary steps (affine/warp) to coordinates (target -> source)

Usage

cpp_path_apply_steps(coords, steps)

Arguments

Value

n x 3 transformed coords

Description

Decompose a 4x4 affine matrix into components

Usage

decompose_affine_matrix(matrix)

Arguments

Value

list with translation, rotation_matrix, scales, skews, angles

Description

Helpers to materialize morphisms on voxel grids for visualization or export, keeping the core morphism API untouched.

Usage

deformation_field(morphism, grid, with_jacobian = TRUE, log = FALSE)

Arguments

Value

An array with dim = c(grid@dims, 3) and class "DeformationField"

Description

Determines whether a dense FSL warp stores relative displacements or absolute source coordinates, using two kinds of evidence on a regular subsample of non-zero lattice vectors:

1. Field of view (when source_affine and source_dim are given): the reading whose implied source FSL coordinates fall inside the source image (within one voxel) for a clearly larger fraction of samples (by at least 0.25) wins.

2. Jacobian: field values are fitted as $v \approx M x + t$ in reference FSL coordinates, so the implied reference-to-source Jacobian is $M$ (absolute) or $M + I$ (relative). A reading wins when the other implies a volume change at least twice as extreme ($|\log|\det J||$ larger by $\log 2$).

The field-of-view test decides first. If neither is decisive the function stops rather than guess; pass def_type explicitly in that case. Scaled or axis-permuted mappings (e.g. a small or sagittally stored source) can make the Jacobian test ambiguous, which the field-of-view test resolves.

Usage

detect_fnirt_def_type(
  warp_path,
  sample_n = 1000,
  threshold_mm = NULL,
  source_affine = NULL,
  source_dim = NULL
)

Arguments

Value

"relative" or "absolute"

Examples

## Not run: 
def_type <- detect_fnirt_def_type("warp.nii.gz", source_affine = src_affine,
                                  source_dim = src_dim)

## End(Not run)

Description

NIfTI vector fields are classified from the header before the filename: FSL intent codes 2006 (dense field) and 2007–2009 (coefficients) and the ITK vector layout (5D with intent 1007) are definitive. Otherwise filename hints apply, then the layout: a 4D (X, Y, Z, 3) field is FSL's layout (ITK/ANTs cannot read it), and remaining fields default to ANTs. Dense FSL fields need source image geometry, so an FSL result is only usable with source_affine and source_dim.

Usage

detect_transform_type(path, source_affine = NULL, target_affine = NULL)

Arguments

Value

Character scalar naming the detected transform family

Description

Convenience wrapper returning the Dice coefficient from overlap_metrics().

Usage

dice_coefficient(
  x,
  y,
  threshold = 0,
  label = NULL,
  na.rm = TRUE,
  empty = c("one", "zero", "na"),
  check_geometry = TRUE,
  tolerance = sqrt(.Machine$double.eps)
)

Arguments

Value

Numeric scalar Dice coefficient.

Examples

x <- array(c(TRUE, TRUE, FALSE, FALSE), dim = c(2, 2, 1))
y <- array(c(TRUE, FALSE, TRUE, FALSE), dim = c(2, 2, 1))
dice_coefficient(x, y)

Description

Extract affine matrix from data

Usage

extract_affine(x)

## S4 method for signature 'array'
extract_affine(x)

## S4 method for signature 'matrix'
extract_affine(x)

## S4 method for signature 'ANY'
extract_affine(x)

## S4 method for signature 'DenseNeuroVol'
extract_affine(x)

## S4 method for signature 'DenseNeuroVec'
extract_affine(x)

Arguments

Value

4x4 affine matrix

Description

Given a FLIRT matrix (source_FSL -> ref_FSL), returns the internal ref_world -> src_world affine for pullback semantics.

Usage

fsl_flirt_to_internal_affine(
  flirt_mat,
  source_affine,
  ref_affine,
  source_dim = NULL,
  ref_dim = NULL
)

Arguments

Value

4x4 internal affine (ref_world -> src_world)

Examples

## Not run: 
flirt_mat <- as.matrix(read.table("xform.mat"))
src_aff <- diag(4)  # from source image header
ref_aff <- diag(4)  # from reference image header
internal <- fsl_flirt_to_internal_affine(flirt_mat, src_aff, ref_aff)

## End(Not run)

Description

FSL-specific coordinate convention handling. FSL uses scaled voxel coordinates for FLIRT matrices and has specific conventions for FNIRT warp fields (relative vs absolute).

Description

Returns a small factory descriptor for linear transform IO, including canonical format and reader/writer function handles.

Usage

get_linear_factory(fmt, is_array = TRUE)

Arguments

Value

List with format, reader, and writer

Description

Gets a loader function from the registry.

Usage

get_loader(name = NULL)

get_warp_loader(name = NULL)

Arguments

Value

Loader function

Examples

loader <- get_loader("neuroim2")

Description

Get world coordinates for a grid

Usage

grid_coords(grid)

Arguments

Value

Numeric matrix (prod(dims) x 3)

Description

Get grid specification from volume data

Usage

grid_from_data(data)

Arguments

Value

Grid object

Description

Extract Grid from volume or grid-like input

Usage

grid_of(x)

Arguments

Value

Grid

Description

Create a grid specification

Usage

grid_spec(dims, affine)

Arguments

Value

Grid object

Description

Grid: regular coordinate grid specification

Usage

## S4 method for signature 'Grid'
show(object)

Arguments

Slots

dims

Integer: grid dimensions

affine

4x4 voxel-to-world matrix

Description

Returns TRUE if adjoint() is available for this morphism. For linear/invertible morphisms, the adjoint is the inverse.

Usage

has_adjoint(object)

Arguments

Value

Logical

Description

The identity morphism maps a domain to itself. Cost is 0.

Usage

IdentityMorphism(domain)

Arguments

Value

IdentityMorphism object

Examples

id <- IdentityMorphism("my_domain_hash")

Description

The identity morphism maps a domain to itself. Required for categorical structure and useful for composition.

Description

Returns the inverse morphism if available (inverse_type == "exact" or "approximate"). For morphisms with approximate or adjoint inverses, use adjoint() instead.

Usage

invert(object)

## S4 method for signature 'Morphism'
invert(object)

## S4 method for signature 'IdentityMorphism'
invert(object)

## S4 method for signature 'Affine3DMorphism'
invert(object)

## S4 method for signature 'Warp3DMorphism'
invert(object)

Arguments

Value

Inverted morphism

Examples

aff <- Affine3DMorphism("a", "b", diag(4))
inv <- invert(aff)  # b -> a

Description

Invert an affine transformation

Usage

invert_affine(affine)

Arguments

Value

Inverted 4x4 affine matrix

Examples

affine <- diag(4)
affine[1:3, 4] <- c(5, 10, 15)
inv <- invert_affine(affine)

Description

Check if an object is a numeric 4x4 affine matrix

Usage

is_affine_matrix(x)

Arguments

Value

Logical

Description

Check if an object is an Affine3DMorphism

Usage

is_affine_morphism(x)

Arguments

Value

Logical

Description

Returns TRUE only if a geometric inverse is available via invert().

Usage

is_invertible(object)

Arguments

Value

Logical

Examples

aff <- Affine3DMorphism("a", "b", diag(4))
is_invertible(aff)  # TRUE

Description

Check if morphism is linear (affine or identity)

Usage

is_linear_morphism(object)

Arguments

Value

Logical

Description

Returns TRUE if the path is composable, FALSE otherwise.

Usage

is_valid_path(path)

Arguments

Value

Logical

Examples

aff1 <- Affine3DMorphism("a", "b", diag(4))
aff2 <- Affine3DMorphism("b", "c", diag(4))
is_valid_path(list(aff1, aff2))  # TRUE

Description

Check if morphism is a warp field

Usage

is_warp_morphism(object)

Arguments

Value

Logical

Description

Convenience wrapper returning the Jaccard index from overlap_metrics().

Usage

jaccard_index(
  x,
  y,
  threshold = 0,
  label = NULL,
  na.rm = TRUE,
  empty = c("one", "zero", "na"),
  check_geometry = TRUE,
  tolerance = sqrt(.Machine$double.eps)
)

Arguments

Value

Numeric scalar Jaccard index.

Examples

x <- array(c(1, 1, 0, 0), dim = c(2, 2, 1))
y <- array(c(1, 0, 1, 0), dim = c(2, 2, 1))
jaccard_index(x, y)

Description

Compute Jacobian matrices and determinants for morphisms. The Jacobian is the derivative of the coordinate transformation.

Usage

jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'IdentityMorphism,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'Affine3DMorphism,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'Warp3DMorphism,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'MorphismPath,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'VolToSurfMorphism,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'SurfToSurfMorphism,ANY'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

## S4 method for signature 'DeformationField,missing'
jacobian(morphism, coords, mode = c("pullback", "pushforward"))

Arguments

Value

JacobianField object

Semantics

For a morphism with pullback semantics (transform maps target -> source), the pullback Jacobian is d(source)/d(target), evaluated at target coordinates.

Modes

• "pullback": d(source)/d(target) - natural for resampling

• "pushforward": d(target)/d(source) - requires invertible morphism

Examples

aff <- Affine3DMorphism("a", "b", diag(4))
coords <- matrix(c(0, 0, 0, 10, 20, 30), ncol = 3, byrow = TRUE)
J <- jacobian(aff, coords)

Description

Compute Jacobian determinants

Usage

jacobian_det(
  morphism,
  coords,
  log = FALSE,
  mode = c("pullback", "pushforward")
)

## S4 method for signature 'IdentityMorphism'
jacobian_det(
  morphism,
  coords,
  log = FALSE,
  mode = c("pullback", "pushforward")
)

## S4 method for signature 'Affine3DMorphism'
jacobian_det(
  morphism,
  coords,
  log = FALSE,
  mode = c("pullback", "pushforward")
)

## S4 method for signature 'Warp3DMorphism'
jacobian_det(
  morphism,
  coords,
  log = FALSE,
  mode = c("pullback", "pushforward")
)

## S4 method for signature 'MorphismPath'
jacobian_det(
  morphism,
  coords,
  log = FALSE,
  mode = c("pullback", "pushforward")
)

Arguments

Value

Numeric vector of determinants

Examples

aff <- Affine3DMorphism("a", "b", diag(4) * 2)
coords <- matrix(c(0, 0, 0), ncol = 3)
jacobian_det(aff, coords)  # 8 (2^3)
jacobian_det(aff, coords, log = TRUE)  # log(8)

Description

Extract Jacobian determinant volume from a morphism on a grid

Usage

jacobian_det_field(morphism, grid, log = FALSE)

Arguments

Value

Array with grid dimensions containing Jacobian determinants

Description

Jacobian field: collection of 3x3 Jacobian matrices

Extract single Jacobian matrix or subset

Number of Jacobians

Compute determinants

Invert Jacobians (for mode switching)

Usage

## S4 method for signature 'JacobianField'
show(object)

## S4 method for signature 'JacobianField,numeric,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'JacobianField'
length(x)

## S4 method for signature 'JacobianField'
det(x, ...)

## S4 method for signature 'JacobianField,missing'
solve(a, b, ...)

Arguments

Slots

values

Numeric array (n x 3 x 3) of Jacobian matrices

coords

Numeric matrix (n x 3) of coordinate locations

mode

Character: "pullback" or "pushforward"

morphism_hash

Hash of source morphism

Description

List all registered loaders

Usage

list_loaders()

Value

Character vector of registered loader names

Examples

list_loaders()

Description

ANTs and ITK use LPS (Left-Posterior-Superior) convention. This function converts to our internal RAS convention by flipping the first two axes.

Usage

lps_to_ras(coords)

Arguments

Value

Coordinates in RAS convention

Examples

lps <- c(-10, -20, 30)
ras <- lps_to_ras(lps)

Description

Read/write FreeSurfer LTA linear transform files (single or array forms).

Description

Build a resampling plan

Usage

make_resampling_plan(
  morphism,
  source_grid,
  target_grid,
  interpolation = c("linear", "cubic", "nearest"),
  reuse_count = 1L,
  cache = TRUE
)

Arguments

Value

A ResamplingPlan object

Description

Check whether a surface mesh is approximately spherical

Usage

mesh_is_sphere(mesh, tolerance = 1.001)

Arguments

Value

Logical

Description

Set mesh radius for spherical meshes

Usage

mesh_set_radius(mesh, radius = 100)

Arguments

Value

SurfaceMesh object with rescaled coordinates

Description

Constructors and methods for morphism classes. Morphisms represent coordinate transformations with pullback semantics.

Description

Creates a stable hash from morphism properties for identity and caching.

Usage

morphism_hash(object)

Arguments

Value

Character hash string

Description

Returns the morphism kind (identity, affine3d, warp3d, vol2surf, surf2surf).

Usage

morphism_kind(object)

Arguments

Value

Character string indicating kind

Examples

aff <- Affine3DMorphism("a", "b", diag(4))
morphism_kind(aff)  # "affine3d"

Description

A Morphism represents a coordinate transformation between domains. Direction convention: a morphism A -> B maps coordinates in B to coordinates in A (pullback semantics). Data flows opposite: from A to B.

Usage

## S4 method for signature 'Morphism'
show(object)

Arguments

Slots

id

Character identifier

source

Character: source domain hash (opaque string)

target

Character: target domain hash (opaque string)

kind

Character morphism kind (identity, affine3d, warp3d, vol2surf, surf2surf)

params

List: forward params/metadata

inverse_params

List: inverse params/metadata

method_tag

Character: path selection tag (anatomical/functional/etc.)

coverage

Optional mask/metadata for valid region

cost

Numeric: cost/weight for graph traversal

hash

Stable hash of morphism

inverse_type

One of "exact", "approximate", "adjoint", "none"

inverse_quality

Numeric in range 0 to 1, optional confidence for inverse

inverse_method

Description/label for inverse strategy

provenance

List: metadata about the transform origin

cache

Environment for cached data

Description

A lightweight wrapper around a list of morphisms representing a composed path. When passed to transform(), applies the full sequence efficiently. Order convention: path = list(f, g) means f first, then g (like g . f).

Slots

morphisms

List of Morphism objects

source

Source domain hash (from first morphism)

target

Target domain hash (from last morphism)

Description

Compute voxelwise overlap summaries for two images or masks. Inputs may be plain arrays or image objects that can be coerced with as.array(), including neuroim2 volumes.

Usage

overlap_metrics(
  x,
  y,
  threshold = 0,
  labels = NULL,
  na.rm = TRUE,
  empty = c("one", "zero", "na"),
  check_geometry = TRUE,
  tolerance = sqrt(.Machine$double.eps)
)

Arguments

Details

By default, numeric images are converted to foreground masks with value > threshold, and logical images use TRUE as foreground. Supply labels to compute label-wise overlap instead.

Value

A data frame with voxel counts and overlap metrics. sensitivity is intersection / n_x; precision is intersection / n_y.

Examples

x <- array(c(1, 1, 0, 0), dim = c(2, 2, 1))
y <- array(c(1, 0, 1, 0), dim = c(2, 2, 1))
overlap_metrics(x, y)

Description

Converts from our internal RAS convention to ANTs/ITK LPS convention.

Usage

ras_to_lps(coords)

Arguments

Value

Coordinates in LPS convention

Examples

ras <- c(10, 20, 30)
lps <- ras_to_lps(ras)

Description

Converts from scanner RAS to FreeSurfer's tkRAS coordinate system.

Usage

ras_to_tkras(ras, c_ras)

Arguments

Value

Coordinates in tkRAS

Examples

scanner_ras <- c(0.5, -2.3, 1.1)
c_ras <- c(0.5, -2.3, 1.1)
tkras <- ras_to_tkras(scanner_ras, c_ras)

Description

Comment lines (starting with "#") are ignored. If a line contains "affineType:" the value is returned as the detected type.

Usage

read_affine_matrix_txt(file, type = NULL)

Arguments

Value

list(matrix = 4x4, type = character|NULL)

Description

Simple image I/O using neuroim2

Usage

read_image(path)

Arguments

Value

neuroim2 volume (DenseNeuroVol or DenseNeuroVec) or array fallback

Description

Read an affine transform file into an Affine3DMorphism

Usage

read_linear_transform(
  path,
  format = c("generic", "fsl", "afni", "itk", "lta", "x5"),
  source = "source",
  target = "target",
  source_affine = NULL,
  target_affine = NULL,
  source_dim = NULL,
  target_dim = NULL,
  oblique_correction = TRUE,
  invert = FALSE
)

Arguments

Value

Affine3DMorphism

Description

Supports single-file transforms and FSL/MCFLIRT-style indexed files (path.000, path.001, ...).

Usage

read_linear_transform_array(
  path,
  format = c("generic", "fsl", "afni", "itk", "lta", "x5"),
  source = "source",
  target = "target",
  ...
)

Arguments

Value

A LinearTransformArray object

Description

Read transform from file into a Morphism

Usage

read_transform(
  path,
  type = NULL,
  source = NULL,
  target = NULL,
  apply_affine = TRUE,
  ...
)

Arguments

Value

A Morphism or MorphismPath object

Description

Read X5 transform file

Usage

read_x5(path)

Arguments

Value

List of X5Transform objects

Description

Adds a loader function to the registry. Loaders are used to read warp displacement fields from various file formats.

Usage

register_loader(name, loader)

register_warp_loader(name, loader)

Arguments

Value

Invisibly returns the name

Examples

# Register a custom loader
my_loader <- function(path) {
  # Load and return list(array, dim, world_to_vox)
}
register_loader("my_format", my_loader)

Description

The fundamental resampling operation: transform coordinates via morphism, then evaluate sampler at transformed coordinates.

Usage

resample(
  sampler,
  morphism,
  coords,
  modulate = c("none", "jacobian", "sqrt_jacobian")
)

Arguments

Value

Sampled values

Examples

# Create volume and sampler
vol <- array(1:27, dim = c(3, 3, 3))
sampler <- volume_sampler(vol, affine = diag(4))

# Create identity morphism
morph <- IdentityMorphism("test")

# Resample at specific coordinates
coords <- matrix(c(0, 0, 0, 1, 1, 1), ncol = 3, byrow = TRUE)
resample(sampler, morph, coords)

Description

High-level resampling helper

Usage

resample_to(moving, target, transform, method = "linear", modulate = "none")

Arguments

Value

neuroim2 volume (matching target geometry)

Description

Convenience wrapper for common volume-to-volume resampling.

Usage

resample_volume(data, morphism, target, method = "linear", modulate = "none")

Arguments

Value

Array with target dimensions

Description

Plan once, apply many times: precompute target voxel centres and flatten the morphism path so repeated resampling of multiple volumes is cheap while keeping the public API small.

Description

Rebuilds correspondence from the original reference to the original moving mesh, checking both ordered geometry identities. The new source must contain faces for barycentric interpolation. This generally differs from a transpose and does not recover information discarded by downsampling. Masks swap sides.

Usage

reverse_surface_resampling_plan(plan, reference, moving)

Arguments

Value

A new SurfaceResamplingPlan with geometries swapped.

Description

Project volumetric data onto surface vertices.

Usage

sample_volume_on_surface(
  data,
  morphism,
  surface_coords = NULL,
  method = "linear"
)

Arguments

Value

Values at surface vertices

Description

Construct sampled points

Usage

sampled_points(coords)

Arguments

Value

SampledPoints object

Description

Lightweight container for point samples in world coordinates.

Usage

## S4 method for signature 'SampledPoints'
show(object)

Arguments

Slots

coords

Numeric matrix (N x 3)

Description

Samplers encapsulate data + interpolation strategy, enabling elegant composition with morphisms for resampling operations.

Design

A Sampler wraps volumetric or surface data with an interpolation method. The core operation is: given coordinates, return interpolated values.

Resampling through a morphism is then simply:

source_coords <- transform(morphism, target_coords)
values <- sampler(source_coords)

Description

Sampler: data + interpolation encapsulation

Usage

## S4 method for signature 'Sampler'
show(object)

Arguments

Slots

evaluate

Function: (coords) -> values

dims

Integer: data dimensions

vdim

Integer: output dimensionality per point

bounds

List: min/max coordinate bounds

method

Character: interpolation method

outside

Value for out-of-bounds queries

Description

Mirrors the common neuroimaging convention where voxel sizes define the linear part and the image center maps to world origin.

Usage

shape_zoom_affine(shape, zooms, x_flip = TRUE, y_flip = FALSE)

Arguments

Value

4x4 affine matrix

Description

Get source domain of a morphism

Usage

source_of(object)

source_domain(object)

## S4 method for signature 'Morphism'
source_of(object)

## S4 method for signature 'Morphism'
source_domain(object)

## S4 method for signature 'MorphismPath'
source_of(object)

Arguments

Value

Source domain hash (character)

Description

Construct a surface mesh

Usage

surface_mesh(vertices, faces = NULL)

Arguments

Value

SurfaceMesh object

Description

Lightweight surface-to-surface resampling using precomputed sparse triplets. This keeps the core API small while enabling reusable vertex-data transport.

Description

Computes reusable interpolation weights mapping vertex data from a moving mesh onto a reference mesh.

Usage

surface_resampling_plan(
  reference,
  moving,
  method = c("barycentric", "nearest", "adaptive_bary_area"),
  spherical = TRUE,
  radius = 100,
  source_mask = NULL,
  target_mask = NULL,
  outside = NULL,
  source_areas = NULL,
  target_areas = NULL,
  experimental = FALSE
)

Arguments

Details

Spherical barycentric resampling uses the closest point on the rescaled triangular mesh, including edges and vertices (ordinary barycentric, without adaptive area correction). It does not use radial ray intersections. For nonspherical meshes, only interior orthogonal projections are considered, with an explicit policy for uncovered queries. The default is nearest-vertex fallback for nonspherical meshes and an error for spherical meshes.

Value

A SurfaceResamplingPlan object

Description

Create a surface sampler

Usage

surface_sampler(
  vertices,
  data,
  faces = NULL,
  method = c("nearest", "barycentric"),
  projection = c("interior", "closest")
)

Arguments

Value

Sampler object

Description

Supply either positive area values with explicit provenance, or an anatomical mesh with the same ordered faces and vertex identities as the registration geometry. Mesh areas allocate one third of each Euclidean triangle's area to each corner. Registration spheres are never used implicitly as anatomy.

Usage

surface_vertex_areas(
  geometry,
  anatomical = NULL,
  values = NULL,
  units = "mm^2",
  provenance = NULL
)

Arguments

Value

A SurfaceVertexAreas object with values, geometry identity, units and provenance.

Description

Lightweight mesh reference for surface operations.

Usage

## S4 method for signature 'SurfaceMesh'
show(object)

Arguments

Slots

coords

Numeric matrix (V x 3) of vertices

faces

Integer matrix (F x 3) of 0-based triangle indices

Description

Maps between surface meshes via spherical registration.

Usage

SurfToSurfMorphism(
  source,
  target,
  method = c("sphere", "area", "sulc"),
  source_sphere = "",
  target_sphere = "",
  mapping = c("nearest", "barycentric"),
  source_vertices = NULL,
  target_vertices = NULL,
  faces = NULL,
  cost = 1,
  method_tag = "anatomical"
)

Arguments

Value

SurfToSurfMorphism object

Description

Maps between surface meshes (e.g., native to fsaverage via spherical registration).

Slots

method

Registration method ("sphere", "area", "sulc")

source_sphere

Path to source sphere surface

target_sphere

Path to target sphere surface

Description

Get target domain of a morphism

Usage

target_of(object)

target_domain(object)

## S4 method for signature 'Morphism'
target_of(object)

## S4 method for signature 'Morphism'
target_domain(object)

## S4 method for signature 'MorphismPath'
target_of(object)

Arguments

Value

Target domain hash (character)

Description

FreeSurfer's tkregister uses a shifted coordinate system (tkRAS) that differs from scanner RAS by the c_ras offset stored in the surface header.

Usage

tkras_to_ras(tkras, c_ras)

Arguments

Value

Coordinates in scanner RAS

Examples

tkras <- c(0, 0, 0)
c_ras <- c(0.5, -2.3, 1.1)
scanner_ras <- tkras_to_ras(tkras, c_ras)

Description

Applies the coordinate pullback: given coordinates in the target domain, returns corresponding coordinates in the source domain.

Usage

transform(morphism, coords)

## S4 method for signature 'IdentityMorphism'
transform(morphism, coords)

## S4 method for signature 'Affine3DMorphism'
transform(morphism, coords)

## S4 method for signature 'Warp3DMorphism'
transform(morphism, coords)

## S4 method for signature 'VolToSurfMorphism'
transform(morphism, coords)

## S4 method for signature 'SurfToSurfMorphism'
transform(morphism, coords)

## S4 method for signature 'MorphismPath'
transform(morphism, coords)

Arguments

Value

Matrix of coordinates (N x 3) in source domain

Examples

# Create an affine morphism
aff <- Affine3DMorphism("source_hash", "target_hash", diag(4))
coords <- matrix(c(10, 20, 30), ncol = 3)
transform(aff, coords)

Description

Alias for transform() to maintain neurofunctor compatibility.

Usage

transform_coords(object, coords)

## S4 method for signature 'Morphism'
transform_coords(object, coords)

## S4 method for signature 'MorphismPath'
transform_coords(object, coords)

Arguments

Value

Transformed coordinates

Description

Lightweight IO helpers for linear transform backends, including format factories, typed IO conditions, and array-style linear transform IO.

Description

Apply a morphism path to coordinates using optimized warp chain.

Given a path of morphisms from source to target and coordinates in the target domain, returns the corresponding coordinates in the source domain.

Usage

transform_path(path, target_coords)

Arguments

Value

Numeric matrix (N x 3) of source world coords

Pullback Direction

Given a path ⁠[f: A->B, g: B->C]⁠, transform_path applies the pullback:

coords_in_C  --(g pullback)--> coords_in_B --(f pullback)--> coords_in_A

The path is applied from last to first (g then f).

Examples

# Create affine morphisms
aff1 <- Affine3DMorphism("native", "mni", diag(4))
aff2 <- Affine3DMorphism("mni", "template", diag(4))
path <- list(aff1, aff2)

# Transform template coords to native space
template_coords <- matrix(c(0, 0, 0, 10, 20, 30), ncol = 3, byrow = TRUE)
native_coords <- transform_path(path, template_coords)

Description

Construct a transform file-format error condition

Usage

TransformFileError(message)

Arguments

Value

Condition object of class TransformFileError

Description

Construct a transform IO error condition

Usage

TransformIOError(message)

Arguments

Value

Condition object of class TransformIOError

Description

Checks that a path is composable (each morphism's target matches the next's source). Raises an error if the path is invalid.

Usage

validate_path(path)

Arguments

Value

Invisibly returns the path if valid

Examples

aff1 <- Affine3DMorphism("a", "b", diag(4))
aff2 <- Affine3DMorphism("b", "c", diag(4))
validate_path(list(aff1, aff2))  # OK

Description

Reports invalid faces and topology without repairing them. Spherical admission additionally requires origin-based radius spread within tolerance, a closed connected orientable manifold of sphere topology, unambiguous radial face orientations and radial mapping degree one. Input face winding is free. Generic open meshes do not require closed topology or spherical geometry.

Usage

validate_surface_mesh(
  mesh,
  spherical = TRUE,
  error = FALSE,
  radius_tolerance = 1.001
)

Arguments

Value

Diagnostic list with valid, issues (one-based offending indices), topology counts, radius range, radial degree and numerical margins.

Description

Maps from volume domain to surface domain using various sampling strategies.

Usage

VolToSurfMorphism(
  source,
  target,
  method = c("trilinear", "ribbon", "mid_thickness", "nearest"),
  ribbon_inner = "",
  ribbon_outer = "",
  ribbon_inner_coords = NULL,
  ribbon_outer_coords = NULL,
  n_ribbon_samples = 6L,
  mid_coords = NULL,
  cost = 2,
  method_tag = "anatomical"
)

Arguments

Value

VolToSurfMorphism object

Description

Maps volume coordinates to surface vertices. Supports different sampling strategies (ribbon, trilinear point sampling).

Slots

method

Sampling method ("ribbon", "trilinear", "nearest", "mid_thickness")

ribbon_inner

Path to inner (white) surface for ribbon sampling

ribbon_outer

Path to outer (pial) surface for ribbon sampling

n_ribbon_samples

Number of samples along ribbon normal

Description

Create a volume sampler

Usage

volume_sampler(
  data,
  affine = NULL,
  method = c("linear", "nearest", "cubic"),
  outside = NA_real_
)

Arguments

Value

Sampler object

Examples

vol <- array(rnorm(27), dim = c(3, 3, 3))
sampler <- volume_sampler(vol, affine = diag(4))
coords <- matrix(c(1, 1, 1), ncol = 3)
sampler@evaluate(coords)

Description

Builds a Warp3DMorphism directly from a 4D field array and a grid, without requiring an on-disk warp file.

Usage

warp_from_field(
  source,
  target,
  field,
  grid = NULL,
  representation = c("displacements", "deformations"),
  warp_method = c("linear", "cubic"),
  cost = 1.5,
  method_tag = "anatomical",
  id = NULL
)

Arguments

Value

Warp3DMorphism

Description

Pluggable loader system for warp displacement fields. Provides a registry for different file formats (NIfTI via neuroim2, AFNI, FSL, ANTs H5) with morphism-level caching.

Loader Function Contract

A loader function must accept a file path and return a list with:

• array: Numeric vector of displacement values (flattened 3 x X x Y x Z)

• dim: Integer vector c(X, Y, Z)

• world_to_vox: 4x4 matrix mapping world coords to voxel indices

Description

Represents a nonlinear warp field transformation.

Usage

Warp3DMorphism(
  source,
  target,
  warp_path,
  warp_type = c("ants", "ants_h5", "fsl", "fsl_coef", "afni", "freesurfer", "dense"),
  inverse_path = "",
  def_type = NULL,
  warp_method = c("linear", "cubic"),
  cost = 1.5,
  method_tag = "anatomical",
  source_affine = NULL,
  source_dim = NULL,
  target_affine = NULL,
  target_dim = NULL
)

Arguments

Value

Warp3DMorphism object

Examples

warp <- Warp3DMorphism("native", "mni", "path/to/warp.nii.gz")

Description

Represents a nonlinear warp field transformation (e.g., ANTs SyN, FSL FNIRT). Stores metadata; the actual warp field is loaded on demand.

Slots

warp_path

Path to the warp field file

warp_type

Type of warp ("ants", "ants_h5", "fsl", "fsl_coef", "afni", "freesurfer", "dense")

inverse_path

Path to inverse warp (if available)

Description

Write a 4x4 affine matrix to a text file

Usage

write_affine_matrix_txt(matrix, file, type = NULL, comment = TRUE)

Arguments

Value

Invisibly returns the file path

Description

Write image using neuroim2

Usage

write_image(x, path)

Arguments

Description

Write an affine transform to disk

Usage

write_linear_transform(
  x,
  path,
  format = c("generic", "fsl", "afni", "itk", "lta", "x5"),
  source_affine = NULL,
  target_affine = NULL,
  source_dim = NULL,
  target_dim = NULL,
  oblique_correction = TRUE,
  invert = FALSE
)

Arguments

Value

Invisibly returns path

Description

Write a series of linear transforms

Usage

write_linear_transform_array(
  x,
  path,
  format = c("generic", "fsl", "afni", "itk", "lta", "x5"),
  ...
)

Arguments

Value

Invisibly returns written path(s)

Description

Convenience wrapper around write_linear_transform() for affine morphisms and raw 4x4 matrices. For Warp3DMorphism, writes an LPS NIfTI vector field (ANTs-compatible when the output contains displacements).

Usage

write_transform(x, path, type = NULL, ...)

Arguments

Value

Invisibly returns path

Description

Writes a 5D vector image (X, Y, Z, 1, 3), with intent code 1007 and LPS components. Displacement output is compatible with ANTs. Absolute deformation output contains source coordinates and must be explicitly read as such; ANTs expects displacements. Requires RNifti.

Usage

write_warp_field(
  x,
  path,
  representation = c("auto", "displacements", "deformations")
)

Arguments

Value

Invisibly returns path

Description

Write X5 transform file

Usage

write_x5(path, x5_list)

Arguments

Value

Invisibly returns path

Description

Create an X5 domain descriptor

Usage

x5_domain(grid, size, mapping = NULL, coordinates = NULL)

Arguments

Value

An X5Domain object

Description

Read and write X5 transform files for linear and nonlinear transforms.

Description

Create an X5 transform descriptor

Usage

x5_transform(
  type,
  transform,
  subtype = NULL,
  representation = NULL,
  metadata = NULL,
  dimension_kinds = NULL,
  domain = NULL,
  inverse = NULL,
  jacobian = NULL,
  additional_parameters = NULL,
  array_length = 1L
)

Arguments

Value

An X5Transform object