transform2world: Convert a transformation to the world (RAS) coordinate space.

In freesurferformats: Read and Write 'FreeSurfer' Neuroimaging File Formats

Convert a transformation to the world (RAS) coordinate space.

Description

Transformation files often store their matrix in voxel coordinates, which means that the matrix alone cannot be used to transform world coordinates (e.g. the coordinates of a brain surface vertex, or a peak coordinate from another study): the geometry of the volumes the matrix relates is required as well. This function converts such a transformation into one that operates on world coordinates.

The result depends on the format the transformation was read from, because the formats disagree about their world space, which is why this is not a pure matrix operation:

• For an FSL matrix ('fslmat'), the world space is the one FSL uses: unit voxel axes with a flipped first axis, see fsl.scaled.voxel.matrix. Both MRtrix3 and FreeSurfer implement exactly this, and the result is a transformation between FSL world coordinates. The src and dst entries of the result have the frame 'fsl'.

• For an LTA of type 0 (VOX2VOX), the world space is the RAS space of the two volume geometries: the result is ⁠vox2ras_dst \%*\% matrix \%*\% solve(vox2ras_src)⁠. The descriptors have the frame 'scanner'.

Usage

transform2world(tf, src = NULL, dst = NULL)

Arguments

tf	an fs.transform instance with a matrix in voxel coordinates (space_in and space_out are 'voxel'). A transformation that already operates on world coordinates is returned unchanged.
src	NULL or the volume the transformation maps from (the ⁠-in⁠ image of FSL, the src volume of an LTA). Required for FSL matrices, since their files do not record the volumes.
dst	NULL or the volume the transformation maps to (the -ref image of FSL, the dst volume of an LTA). Required for FSL matrices.

Value

an fs.transform instance whose matrix operates on world coordinates.

See Also

Other header coordinate space: invert.fs.transform(), is.fs.transform(), mghheader.is.ras.valid(), mghheader.ras2vox(), mghheader.ras2vox.tkreg(), mghheader.scanner2tkreg(), mghheader.tkreg2scanner(), mghheader.vox2ras(), mghheader.vox2ras.tkreg(), print.fs.transform(), read.fs.transform(), read.fs.transform.dat(), read.fs.transform.fslmat(), read.fs.transform.itk(), read.fs.transform.lta(), read.fs.transform.xfm(), sm0to1(), sm1to0(), summary.fs.transform(), transform2lps(), transform2ras(), transform2voxel(), write.fs.transform(), write.fs.transform.dat(), write.fs.transform.fslmat(), write.fs.transform.itk(), write.fs.transform.lta(), write.fs.transform.xfm()

Examples

# Read an LTA file, which records both volumes it relates, and convert it to world coordinates.
lta_file <- system.file("extdata", "talairach.lta", package = "freesurferformats", mustWork = TRUE)
tf <- read.fs.transform(lta_file)
tf_world <- transform2world(tf)
tf_world$space_in
tf_world$matrix

freesurferformats documentation built on Sept. 25, 2026, 1:07 a.m.