xform_brain: Transform 3D object between template brains

Description

Transform 3D object between template brains

Usage

xform_brain(
  x,
  sample = regtemplate(x),
  reference,
  via = NULL,
  imagedata = is.character(x),
  checkboth = NULL,
  target = NULL,
  Verbose = interactive(),
  ...
)

Value

A transformed version of x

Arguments

x: the 3D object to be transformed
sample: Source template brain (e.g. IS2) that data is currently in. Specified either as character vector or a templatebrain object.
reference: Target template brain (e.g. IS2) that data should be transformed into.
via: (optional) intermediate template brain that the registration sequence must pass through.
imagedata: Whether x should be treated as image data (presently only supported as a file on disk) or 3D object vertices - see details.
checkboth: When TRUE will look for registrations in both directions. See details.
target: When transforming image data, this specifies the target space (defaults to reference when imagedata=TRUE). See Details.
Verbose: Whether to show a message with the sequence of template brains
...: extra arguments to pass to xform and then on to xformpoints or xformimage which will eventually hand off to cmtk.reformatx when using CMTK.

Details

NB the sample, reference and via brains can either be templatebrain objects or a character string containing the short name of the template e.g. "IS2".

xform_brain uses the helper function shortest_bridging_seq to find the shortest path between different template brains based on the set of bridging registrations that the natverse has been informed about (see bridging_graph). You can specify a via argument to ensure that the registrations passes through one or more intermediate templates. Note that when multiple brains are passed to via they should be in order from sample to reference. If you are passing multiple templatebrain objects, they must be wrapped in a list.

When transforming image data (imagedata=TRUE), the target argument should normally be specified. This defines the absolute/voxel dimensions of the target space. This can be calculated from a templatebrain object, so by default it will be set to the value of the reference argument. Alternatively an image file on disk can be specified; this is essential if the reference argument does not specify a templatebrain object but instead just names a template space (i.e. is a string).

The significance of the imagedata and checkboth arguments is that CMTK registrations are not directly invertible although they can be numerically inverted in most cases (unless there are regions where folding occurred). For image data, numerical inversion is much slower.

You can control whether you want to allow inverse registrations manually by setting checkboth explicitly. Otherwise when checkboth=NULL the default is to act as if checkboth=TRUE but issue a warning if an inversion must be used.

Examples

Run this code

## depends on nat.flybrains package and system CMTK installation
if (FALSE) {
## reformat neurons
##
library(nat.flybrains)
# Plot Kenyon cells in their original FCWB template brain
nopen3d()
plot3d(kcs20)
plot3d(FCWB)
# Convert to JFCR2 template brain
kcs20.jfrc2=xform_brain(kcs20, sample = FCWB, reference=JFRC2)
# now plot in the new JFRC2 space
nopen3d()
plot3d(kcs20.jfrc2)
plot3d(JFRC2)
# compare with the untransformed neurons
plot3d(kcs20)
# plot with neuropil sub regions for the left mushroom body
clear3d()
plot3d(kcs20.jfrc2)
# nb "MB.*_L" is a regular expression
plot3d(JFRC2NP.surf, "MB.*_L", alpha=0.3)
# compare with originals - bridging registration is no perfect in peduncle
nopen3d()
plot3d(kcs20)
plot3d(FCWBNP.surf, "MB.*_L", alpha=0.3)

# insist on using a specific intermediate template brain
# this would nor be an improvement in this case
kcs20.jfrc2viais2=xform_brain(kcs20, sample = FCWB, via=IS2, reference=JFRC2)


## reformat image examples
# see ?cmtk.reformatx for details of any additional arguments
# note that for image data a target space defining the dimensions of the
# output image must be specified - this happens by default using the
# reference templatebrain object
xform_brain('in.nrrd', sample=FCWB, ref=JFRC2, output='out.nrrd')
# or you can specify an image file explicitly as target
xform_brain('in.nrrd', sample=FCWB, ref=JFRC2, output='out.nrrd',
            target='JFRC2.nrrd')

# use partial volume interpolation for label field
xform_brain('labels.nrrd', sample=FCWB, ref=JFRC2, output='out.nrrd',
            interpolation='pv')

# use binary mask to restrict (and speed up) reformatting
xform_brain('in.nrrd', sample=FCWB, ref=JFRC2, output='out.nrrd', mask='neuropil.nrrd')
}