Registration module

OXASL - Registration for ASL data

Copyright (c) 2008-2020 Univerisity of Oxford

class oxasl.reg.Options(**kwargs)[source]

OptionCategory which contains options for registration of ASL data to structural image

groups(parser)[source]
Parameters:parser – OptionParser instance
Returns:Sequence of OptionGroup instances for this category of options
oxasl.reg.change_space(wsp, img, target_space, source_space=None, **kwargs)[source]

Convert an image to a different space

Note that while the source space can be determined from the image, this may not be correct if images (e.g. ASL and calibration) share the same voxel->world transformation but still need registration to one another

Parameters:
  • wsp – Workspace object
  • img – Image
  • target_space – Either an Image in the target space, or the name of the target space
  • src_space – If specified, explicit indication of source image space
oxasl.reg.get_img_space(wsp, img)[source]

Find out what image space an image is in

Note that this only compares the voxel->world transformation matrix to the reference image for each space. It is quite possible for two images to be in the same space but not be registered to one another. In this case, the returned space may not be accurate when determining whether a registration is required.

Parameters:
  • wsp – Workspace object
  • img – Image
Returns:

Name of image space for img, e.g. asl, struc

oxasl.reg.get_ref_imgs(wsp, use_quantification_wsp=None)[source]

Get the images that define the various processing ‘spaces’ and are used for registration to/from these spaces. The built in spaces are ‘asl’ (aka ‘native’) ‘struc’ and ‘std’ (MNI).

Note that the ‘custom’ space requires a user-specified reference image and transformation from structural space

aslref defines the ‘asl’ space

  • aslref : User-supplied registration reference image
  • aslref_method : Method for choosing registration reference image
  • asldata : Raw ASL data
  • calib : Calibration image
  • aslref : Registration reference image in ASL space
  • strucref : Registration reference image in structural space
  • stdref : Registration reference image in standard space
oxasl.reg.get_transform_params(mat)[source]

Get motion parameters from a Flirt motion correction matrix

This is done under the assumption that the matrix may contain rotation, translation and possibly minor scaling but no reflection, shear etc. So the output could be incorrect for some extreme correction matrices, but this probably indicates an error in the registration process. We wrap the whole thing in a try block so if anything goes horribly wrong it does not at least stop the pipeline running

See http://en.wikipedia.org/wiki/Rotation_matrix for details of the rotation calculation.

Returns:Tuple of magnitude of translation, angle and rotation axis
oxasl.reg.main()[source]

Entry point for command line tool

oxasl.reg.reg_asl2calib(wsp)[source]

Register calibration image to ASL space

Note that this might already have been done as part of motion correction

oxasl.reg.reg_asl2custom(wsp)[source]

Register custom output image to ASL space, via structural.

If no output_custom_mat (struc -> custom) has been provided, then FLIRT will be used to generate this. The transformation from ASL space is the concatenation of asl2struc and struc2custom.

oxasl.reg.reg_asl2struc(wsp, flirt=True, bbr=False, name='initial')[source]

Registration of ASL images to structural image

Parameters:
  • flirt – If provided, sets whether to use FLIRT registration
  • bbr – If provided, sets whether to use BBR registration
  • aslref : Registration reference image in ASL space
  • struc : Structural image
  • asl2struc : ASL->structural transformation matrix
  • struc2asl : Structural->ASL transformation matrix
  • regto : aslref image transformed to structural space
oxasl.reg.reg_bbr(wsp)[source]

Perform BBR registration

Parameters:
  • reg_img – Data to register, e.g. PWI or calibration image. Normally would be brain extracted
  • struc_img – Structural image
  • struc_brain_img – Brain-extracted structural image

Optional keyword arguments:

Parameters:
  • inweight
  • init – Initial transform matrix

Optional keyword arguments for fieldmap distortion correction:

Parameters:
  • fmap – Fieldmap image
  • fmapmag – Fieldmap magnitude image
  • fmapmagbrain – Fieldmap magnitude image - brain extracted
  • pedir – Phase encoding direction (x, -x, y, -y, z, -z)
  • echospacing – Echo spacing

:return Tuple of registered image, transform matrix

oxasl.reg.reg_flirt(wsp, img, ref, initial_transform=None)[source]

Register low resolution ASL or calibration data to a high resolution structural image using Flirt rigid-body registration

The brain extracted structural image is used as the reference image. If this is not supplied, BET will be run on the whole head structural image.

Parameters:
  • reg_img – Data to register, e.g. PWI or calibration image. Normally would be brain extracted
  • struc_brain_img – Brain-extracted structural image

Optional keyword arguments:

Parameters:
  • inweight
  • init – Initial transform matrix
  • schedule – FLIRT transform schedule file (default: xyztrans.sch”)
  • dof – FLIRT degrees of freedom

:return Tuple of registered image, transform matrix

oxasl.reg.reg_struc2std(wsp, **kwargs)[source]

Determine structural -> standard space registration

  • structural.struc : Structural image
  • fslanat : Path to existing FSLANAT data
  • reg.struc2std : Structural->MNI transformation matrix - either warp image or FLIRT matrix
  • reg.std2struc : MNI->structural transformation - either warp image or FLIRT matrix
oxasl.reg.transform(wsp, img, trans, ref, use_flirt=False, interp='trilinear', paddingsize=1, premat=None, postmat=None, mask=False, mask_thresh=0.5)[source]

Transform an image

Parameters:
  • wsp – Workspace, used for logging only
  • img – Image to transform
  • trans – Transformation matrix or warp image
  • ref – Reference image
  • use_flirt – Use flirt to apply the transformation which must be a matrix
  • interp – Interpolation method
  • paddingsize – Padding size in pixels
  • premat – If trans is a warp, this can be set to a pre-warp affine transformation matrix
Returns:

Transformed Image object