skrt.registration module

Classes and functions relating to image registration.

This module defines the following classes:

Registration : Class for handling image registration.
DeformationField : Class representing a deformation field.
Grid : Class representing a grid.
Jacobian : Class representing a Jacobian determinant.
RegistrationEngine : Base class for interfacing to a registration engine.
Elastix: Class interfacing to elastix registration engine.
Matlab: Class interfacing to MATLAB-based registration engine.
NiftyReg: Class interfacing to NiftyReg registration engine.

This module defines the following functions:

add_engine() : Decorator for adding RegistrationEngine subclasses to skrt.registartion.engines dictionary.
adjust_parameters() : Modify contents of a registration parameter file.
get_data_dir() : Return path to data directory within the scikit-rt package.
get_default_pfiles() : Get list of default parameter files.
get_default_pfiles_dir() : Return path to directory containing default parameter files for specified engine.
get_engine_cls() : Get registration-engine class, given engine name or software directory.
get_engine_name : Get registration-engine name, given engine name or software directory.
get_engines : Obtain list of names of available registration engines.
get_image_transform_parameters() : Define Elastix registration-independent parameters for transforms to the space of a specified image.
get_jacobian_colormap() : Return custom colour map, for highlighting features of Jacobian determinant.
get_parameters : Obtain parameter dictionary from default parameter file.
read_parameters() : Get dictionary of parameters from a registration parameter file.
set_elastix_dir() : Perform environment setup for using elastix software.
set_engine_dir() : Perform environment setup for using registration software.
shift_translation_parameters() : Add offsets to the translation parameters in a registration parameter file.
write_parameters() : Write dictionary of parameters to a registration parameter file.

class skrt.registration.DeformationField(path='', load=True, signs=None, image=None, **kwargs)

Bases: PathData

Class representing a deformation field.

__init__(path='', load=True, signs=None, image=None, **kwargs)

Initialise from a deformation-field source.

pathstr/array/Nifti1Image, default= “”: Data source. Possibilities are the same as for skrt.image.Image, but should correspond to arrays of dimension 4. Otherwise, it can be loaded later with the load() method.
loadbool, default=True: If True, the deformation-field data will be immediately loaded.
signstuple, default=None: Three element tuple of ints, indicating the signs to be applied to the (x, y, z) components of the deformation field, allowing for different conventions. If None, components are taken to be as read from source.
imageskrt.image.Image, default=None: Image object to be associated with the deformation field.
kwargsdict: Dictionary of keyword-value pairs, passed to the skrt.image.Image constructor when creating a representation of the deformation field.

convert_spacing(spacing, scale_in_mm): Convert grid spacing in mm or voxels to list containing grid spacing in voxels in each dimension.

get_displacement_image(displacement='3d')

Get skrt.dose.ImageOverlay object representing point displacements.

Parameter:

displacementstr, default=”3d”: Point displacement to be represented: - ‘x’: displacement along x-axis; - ‘y’: displacement along y-axis; - ‘z’: displacement along z-axis; - ‘3d’: magnitude of 3d displacement.

get_slice(view, sl=None, idx=None, pos=None, scale_in_mm=True): Get voxel positions and displacement vectors on a 2D slice.

load(force=False)

Load deformation-field data from source. If already loaded and <force> is False, nothing will happen.

Parameters:

forcebool, default=True: If True, the deformation-field data will be reloaded from source even if it has previously been loaded.

plot(view='x-y', sl=None, idx=None, pos=None, df_plot_type='quiver', include_image=False, df_opacity=None, df_spacing=30, ax=None, gs=None, figsize=None, zoom=None, zoom_centre=None, show=True, save_as=None, scale_in_mm=True, title=None, colorbar=False, xlabel=None, ylabel=None, no_xlabel=False, no_ylabel=False, xticks=None, yticks=None, no_xticks=False, no_yticks=False, no_xtick_labels=False, no_ytick_labels=False, annotate_slice=False, major_ticks=None, minor_ticks=None, ticks_all_sides=False, no_axis_labels=False, mask=None, mask_threshold=0.5, masked=True, invert_mask=False, mask_color='black', **mpl_kwargs)

Plot deformation field.

For explanation of parameters, see documentation for skrt.better_viewer.BetterViewer.

view(include_image=False, **kwargs)

View the deformation field.

Parameters:

include_imagebool, default=True: If True, the image associated with the deformation field will be displayed as underlay.

Any **kwargs will be passed to BetterViewer initialisation.

class skrt.registration.Elastix(**kwargs)

Bases: RegistrationEngine

Class interfacing to elastix registration engine.

__init__(**kwargs)

Create RegistrationEngine instance.

Parameters: path : str/pathlib.Path, default=None

Path to directory containing registration-engine software.

force : bool, default=False If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

log_level: str/int/None, default=None: Severity level for event logging. If the value is None, log_level is set to the value of skrt.core.Defaults().log_level.

adjust_parameters(infile, outfile, params)

Modify contents of a registration parameter file.

Parameters:

infilestr/patlib.Path: Path to a registration parameter file.
outfilestr/pathlib.Path: Path to output file.
paramsdict: Dictionary of parameter names and new values.

define_translation(dxdydz, fixed_image=None)

Define translation parameters to be passed to registration engine.

Parameters:

dxdydztuple/list: Three-element tuple or list, giving translations in order (dx, dy, dz). Translations correspond to the amounts added in mapping a point from fixed image to moving image.
fixed_imageskrt.image.Image, default=None: Image towards which moving image is to be warped.

exes = ['elastix', 'transformix']

get_def_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing deformation field.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_dose_params(): Get default parameters to be used when transforming dose.

get_jac_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing Jacobian determinant.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_registration_cmd(fixed_path, moving_path, fixed_mask_path, moving_mask_path, pfile, outdir, tfile=None)

Get registration-engine command for performing image registration.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
fixed_mask_pathstr: Path to mask for fixed image.
moving_mask_pathstr: Path to mask for moving image.
pfilestr: Path to registration paramter file.
outdirstr: Path to directory for registration output.
tfilestr, default=None: Path to registration transform file from previous registration step. If None, no previous registration step is it be considered.

get_roi_params(): Get default parameters to be used when transforming ROI mask.

get_transform_cmd(fixed_path, moving_path, outdir, tfile, params=None)

Get registration-engine command for applying registration transform.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
outdirstr: Path to directory for transform output.
tfilestr: Path to registration transform file to be applied.
params: dict, default=None: Dictionary of parameter-value pairs defining modifications to the registration transform file prior to running the transform command. The original transform file is left unaltered.

static get_transform_strategies()

Get list of available strategies for applying registration transform.

Possible strategies are:

“pull”: transform applied to pull image or mask from the reference frame of the moving image to the reference frame of the fixed image;
“push”: transform applied to push points from the reference frame of the fixed image to the reference frame of the moving image.

read_parameters(infile)

Get dictionary of parameters from a registration parameter file.

Parameter: infile: str/pathlib.Path

Path to registration parameter file.

set_exe_paths(path)

Set path(s)s to registration-engine executable(s).

Parameter:

pathstr/pathlib.Path: Path to directory containing registration-engine executable(s).

shift_translation_parameters(infile, dx=0, dy=0, dz=0, outfile=None)

Add offsets to the translation parameters in a registration transform file.

Parameters:

infile: str: Path to input transform file.
dx, dy, dz: int, default=0: Amounts by which to increase translation parameters, along x, y, z directions.
outfile: str, default=None: Path to output parameter file. If None, overwrite input parameter file.

transform_log = 'transformix.log'

transform_points_implemented = True

write_parameters(outfile, params)

Write dictionary of parameters to a registration parameter file.

Parameters:

outfile: str/pathlib.Path: Path to output file.
params: dict: Dictionary of parameters to be written to file.

class skrt.registration.Grid(*args, color='green', **kwargs)

Bases: ImageOverlay

Class representating a grid.

This is the same as the ImageOverlay class, but sets different attribute values at instantiation.

__init__(*args, color='green', **kwargs): Perform ImageOverlay initialisation, then overwrite selected attribute values.

class skrt.registration.Jacobian(*args, **kwargs)

Bases: ImageOverlay

Class for representing a Jacobian determinant.

This is the same as the ImageOverlay class, but sets different attribute values at instantiation.

__init__(*args, **kwargs): Perform ImageOverlay initialisation, then overwrite selected attribute values.

class skrt.registration.Matlab(path=None, force=False, log_level=None)

Bases: RegistrationEngine

Class interfacing to MATLAB registration engine.

adjust_parameters(infile, outfile, params)

Modify contents of a registration parameter file.

Parameters:

infilestr/patlib.Path: Path to a registration parameter file.
outfilestr/pathlib.Path: Path to output file.
paramsdict: Dictionary of parameter names and new values.

define_translation(dxdydz, fixed_image=None)

Define translation parameters to be passed to registration engine.

Parameters:

dxdydztuple/list: Three-element tuple or list, giving translations in order (dx, dy, dz). Translations correspond to the amounts added in mapping a point from fixed image to moving image.
fixed_imageskrt.image.Image, default=None: Image towards which moving image is to be warped.

exes = ['mskrt.matlabreg']

get_def_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing deformation field.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_jac_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing Jacobian determinant.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_registration_cmd(fixed_path, moving_path, fixed_mask_path, moving_mask_path, pfile, outdir, tfile=None)

Get registration-engine command for performing image registration.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
fixed_mask_pathstr: Path to mask for fixed image.
moving_mask_pathstr: Path to mask for moving image.
pfilestr: Path to registration paramter file.
outdirstr: Path to directory for registration output.
tfilestr, default=None: Path to registration transform file from previous registration step. If None, no previous registration step is it be considered.

get_roi_params(): Get default parameters to be used when transforming ROI mask.

get_transform_cmd(fixed_path, moving_path, outdir, tfile, params=None)

Get registration-engine command for applying registration transform.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
outdirstr: Path to directory for transform output.
tfilestr: Path to registration transform file to be applied.
params: dict, default=None: Dictionary of parameter-value pairs defining modifications to the registration transform file prior to running the transform command. The original transform file is left unaltered.

static get_transform_strategies()

Get list of available strategies for applying registration transform.

Possible strategies are:

“pull”: transform applied to pull image or mask from the reference frame of the moving image to the reference frame of the fixed image;
“push”: transform applied to push points from the reference frame of the fixed image to the reference frame of the moving image.

read_affine(infile)

Read affine matrix from file.

Parameter: infile: str/pathlib.Path

Path to file from which to read affine matrix.

read_parameters(infile)

Get dictionary of parameters from a registration parameter file.

Parameter: infile: str/pathlib.Path

Path to registration parameter file.

recursive_transform = True

set_exe_env(path=None, force=False)

Set environment variables for running MATLAB registration.

MATLAB registration can be run using compiled or uncompiled MATLAB code. In both cases, the environment setup can be performed before or after starting the Python session that runs scikit-rt.

To run compiled MATLAB code:

To set environment from scikit-rt:
1. Set skrt.registration.Defaults().matlab_runtime to be the path to the MATLAB runtime installation directory.
2. When creating a skrt.registration.Matlab() instance, pass as the <path> parameter the path to the directory that contains the compiled MATLAB application.
To set environment prior to starting Python:
1. Set platform dependent environment variable for MATLAB runtime: https://uk.mathworks.com/help/compiler/mcr-path-settings-for-run-time-deployment.html
2. Add to PATH variable the path to the directory that contains the compiled MATLAB application.
3. After starting Python and importing scikit-rt, set: skrt.registration.Defaults().matlab_runtime = True

To run uncompiled MATLAB code:

To set environment from scikit-rt:
1. Set skrt.registration.Defaults().matlab_app to be the path to the directory that contains the MATLAB executable.
2. When creating a skrt.registration.Matlab() instance, pass as the <path> parameter the path to the directory that contains the uncompiled MATLAB registration package directory (+mskrt).
To set environment prior to starting Python:
1. Add to PATH variable the path to the directory that contains the MATLAB executable.
2. Add to MATLABPATH variable the path to the directory that contains the uncompiled MATLAB registration package directory (+mskrt).

Parameters:

pathstr/pathlib.Path, default=None: If skrt.registration.Defaults().matlab_runtime evaluates to True, this is the path to the directory containing the compiled MATLAB application for image registration. Otherwise, this is the path to the directory that contains the MATLAB executable. Ignored if set to None.
forcebool, default=False: If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

shift_translation_parameters(infile, dx=0, dy=0, dz=0, outfile=None)

Add offsets to the translation parameters in a registration transform file.

Parameters:

infile: str: Path to input transform file.
dx, dy, dz: int, default=0: Amounts by which to increase translation parameters, along x, y, z directions.
outfile: str, default=None: Path to output parameter file. If None, overwrite input parameter file.

write_affine(affine, outfile)

Write affine matrix fo file.

Parameter: outfile: str/pathlib.Path

Path to file to which to write affine matrix.

write_parameters(outfile, params)

Write dictionary of parameters to a registration parameter file.

Parameters:

outfile: str/pathlib.Path: Path to output file.
params: dict: Dictionary of parameters to be written to file.

class skrt.registration.NiftyReg(**kwargs)

Bases: RegistrationEngine

Class interfacing to NiftyReg registration engine.

__init__(**kwargs)

Create RegistrationEngine instance.

Parameters: path : str/pathlib.Path, default=None

Path to directory containing registration-engine software.

force : bool, default=False If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

log_level: str/int/None, default=None: Severity level for event logging. If the value is None, log_level is set to the value of skrt.core.Defaults().log_level.

adjust_parameters(infile, outfile, params)

Modify contents of a registration parameter file.

Parameters:

infilestr/patlib.Path: Path to a registration parameter file.
outfilestr/pathlib.Path: Path to output file.
paramsdict: Dictionary of parameter names and new values.

def_signs = (-1, -1, 1)

define_translation(dxdydz, fixed_image=None)

Define translation parameters to be passed to registration engine.

Parameters:

dxdydztuple/list: Three-element tuple or list, giving translations in order (dx, dy, dz). Translations correspond to the amounts added in mapping a point from fixed image to moving image.
fixed_imageskrt.image.Image, default=None: Image towards which moving image is to be warped.

exes = ['reg_aladin', 'reg_f3d', 'reg_jacobian', 'reg_resample', 'reg_transform']

get_def_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing deformation field.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_jac_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing Jacobian determinant.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_registration_cmd(fixed_path, moving_path, fixed_mask_path, moving_mask_path, pfile, outdir, tfile=None)

Get registration-engine command for performing image registration.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
fixed_mask_pathstr: Path to mask for fixed image.
moving_mask_pathstr: Path to mask for moving image.
pfilestr: Path to registration paramter file.
outdirstr: Path to directory for registration output.
tfilestr, default=None: Path to registration transform file from previous registration step. If None, no previous registration step is it be considered.

get_roi_params(): Get default parameters to be used when transforming ROI mask.

get_transform_cmd(fixed_path, moving_path, outdir, tfile, params=None)

Get registration-engine command for applying registration transform.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
outdirstr: Path to directory for transform output.
tfilestr: Path to registration transform file to be applied.
params: dict, default=None: Dictionary of parameter-value pairs defining modifications to the registration transform file prior to running the transform command. The original transform file is left unaltered.

static get_transform_strategies()

Get list of available strategies for applying registration transform.

Possible strategies are:

“pull”: transform applied to pull image or mask from the reference frame of the moving image to the reference frame of the fixed image;
“push”: transform applied to push points from the reference frame of the fixed image to the reference frame of the moving image.

read_affine(infile)

Read affine matrix from file.

Parameter: infile: str/pathlib.Path

Path to file from which to read affine matrix.

read_parameters(infile)

Get dictionary of parameters from a registration parameter file.

Parameter: infile: str/pathlib.Path

Path to registration parameter file.

set_exe_paths(path)

Set path(s)s to registration-engine executable(s).

Parameter:

pathstr/pathlib.Path: Path to directory containing registration-engine executable(s).

shift_translation_parameters(infile, dx=0, dy=0, dz=0, outfile=None)

Add offsets to the translation parameters in a registration transform file.

Parameters:

infile: str: Path to input transform file.
dx, dy, dz: int, default=0: Amounts by which to increase translation parameters, along x, y, z directions.
outfile: str, default=None: Path to output parameter file. If None, overwrite input parameter file.

write_affine(affine, outfile)

Write affine matrix fo file.

Parameter: outfile: str/pathlib.Path

Path to file to which to write affine matrix.

write_parameters(outfile, params)

Write dictionary of parameters to a registration parameter file.

Parameters:

outfile: str/pathlib.Path: Path to output file.
params: dict: Dictionary of parameters to be written to file.

class skrt.registration.Registration(path, fixed=None, moving=None, fixed_mask=None, moving_mask=None, pfiles=None, auto=False, overwrite=False, tfiles=None, initial_alignment=None, initial_transform_name=None, capture_output=False, log_level=None, keep_tmp_dir=False, engine=None, engine_dir=None)

Bases: Data

Class for handling image registration.

__init__(path, fixed=None, moving=None, fixed_mask=None, moving_mask=None, pfiles=None, auto=False, overwrite=False, tfiles=None, initial_alignment=None, initial_transform_name=None, capture_output=False, log_level=None, keep_tmp_dir=False, engine=None, engine_dir=None)

Load data for an image registration, and run the registration if auto_seg=True.

Parameters:

pathstr

Path to directory where the data for this image registration is stored. Can either be a non-existing directory, in which case registration will be performed from scratch, or a directory already containing a fixed and moving image and optionally some registration steps. The path shouldn’t contain spaces. It the path does contain spaces, these will be replaced with underscores.

fixedImage/str, default=None

Image object representing the fixed image, or a source from which an Image object can be initialised. Must be set if the directory at <path> does not already contain a fixed image file called “fixed.nii.gz”.

movingImage/str, default=None

Image object representing the fixed image, or a source from which an Image object can be initialised. Must be set if the directory at <path> does not already contain a moving image file called “moving.nii.gz”.

fixed_maskImage/str, default=None

Image object representing a mask to be applied to the fixed image, or a source from which an Image object can be initialised. If None and an image file ‘fixed_mask.nii.gz’ exists at <path> then this will be used. Setting a mask is optional.

moving_maskImage/str, default=None

Image object representing a mask to be applied to the moving image, or a source from which an Image object can be initialised. If None and an image file ‘moving_mask.nii.gz’ exists at <path> then this will be used. Setting a mask is optional.

pfilesstr/list/dict, default=None

Path(s) to parameter file(s) to be used in each step of the registration. If a list of more than one path, the parameter files will be used to apply registrations in series, which the output of each step being used as an initial transformation for the following step. If None, the Registration will be initialised with no registration steps and no registration will be performed. If a dict, the keys will be taken as names for the registration steps and the values should be the path to the parameter file for that step; otherwise, the name of the step will be taken from the parameter filename.

autobool, default=True

If True, the registration will be performed immediately for all steps.

overwritebool, default=False

If True and <path> already contains files, these will be deleted, meaning that no prior registration results will be loaded.

tfilesdict, default=None

Dictionary of pre-defined transforms, where a key is a registration step and the associated value is the path to a pre-defined registration transform. Transformations are performed, in the order given in the dictionary, before any registration step is performed.

initial_alignmenttuple/dict/str, default=None

Alignment to be performed before any registration steps are run. This can be any of the following: - a tuple indicating the amounts (dx, dy, dz) by which

a point in the fixed image must be translated to align with the corresponding point in the moving image;

a dictionary specifying parameters and values to be passed to skrt.image.get_translation_to_align(), which defines a translation for aligning fixed and moving image;
one of the strings “_top_”, “_centre_”, “_bottom_”, in which case skrt.image.get_translation_to align() is called to define a translationg such that fixed and moving image have their (x, y) centres aligned, and have z positions aligned at image top, centre or bottom;
a string specifying the name of an ROI associated with both fixed and moving image, with ROI centroids to be aligned;
a tuple of strings specifying names of an ROI associated with the fixed image and an ROI associated with the moving image, with ROI centroids to be aligned;
a tuple specifying ROI name and relative position along z-axis on which to align (0 most-inferior slice of ROI, 1 most-superior slice), with the same ROI name and relative position used for fixed and moving image;
a tuple of tuples specifying ROI name and relative position along z-axis on which to align, with one tuple for the fixed image and one tuple for the moving image.

The result of the initial alignment is stored as the first entry of <self.tfiles”, with key <initial_alignment_name>. If <initial_alignment> is set to None, no initial alignment is performed.

initial_transform_namestr, default=None

Name to be used in registration steps for transform corresponding to <initial_alignment>. If None, the name ‘initial_alignment’ is used.

capture_outputbool, default=False

If True, capture to stdout messages from performing registration and transformation. This suppresses informational messages to screen, but doesn’t suppress error messages.

log_level: str/int/None, default=None

Severity level for event logging. If the value is None, log_level is set to the value of skrt.core.Defaults().log_level.

keep_tmp_dir: bool, default=False

If True, don’t delete directory self._tmp_dir used when performing transformations. Otherwise, delete this directory after use.

engine: str, default=None

Name of the registration engine to use for image registration. This should be a key of the dictionary skrt.registration.engines. If None, the first key found to be a substring of <engine_dir> is used, or if there’s no match then the value of Defaults().registration_engine is used.

engine_dir: str/pathlib.Path, default=None

Path to directory containing software for registration engine.

add_default_pfile(filename, params=None)

Add a default parameter file. For options, run Registration.list_default_pfiles(). You can also inspect the contents of a default parameter file by running get_default_params(name).

Parameters:

filenamestr: Name of the default parameter file to add (with or without the .txt extension).
paramsdict, default=None: Dictionary of parameter names and replacement values with which the input parameter file will be modified.

add_file(file, name=None, params=None, ftype='p')

Add a single file of type <ftype> to the list of registration steps. This file can optionally be modified by providing a dict of parameter names and new values in <params>.

Parameters:

filestr/dict/tuple/list: Path to the parameter file to copy into the registration directory. Can also be a dict containing parameters and values, which will be used to create a parameter file from scratch. In this case, the <name> argument must also be provided. For a transform file (<ftype> of ‘t’), can also be a three element tuple or list, specifying the x, y, z components of a translation.
namestr, default=None: Name for this step of the registration. If None, a name will be taken from the parameter file name.
paramsdict, default=None: Dictionary of parameter names and replacement values with which the input parameter file will be modified.
ftypestr, default=’p’: String indicating whether the file to be added is a parameter file (‘p’) or a transform file (‘t’).

add_files(files, ftype='p')

Add multiple files of type <ftype> to the list of registration steps, then write list of registration steps to a file.

The valid values for <ftype? are: - ‘p’: parameter file; - ‘t’: transform file.

add_pfile(file, name=None, params=None): Alias for add_file() with ftype=’p’.

adjust_file(step, params, ftype='p', reset=True)

Adjust parameters in a parameter or transform file for a given step.

Parameters:

stepstr/int: Name or number of step for which the parameter file should be adjusted.
paramsdict: Dict of parameter names and desired parameter values. Any parameters matching those in the existing file will be overwritten with the new values. Any parameters not in the existing file will be added. Parameters in the existing file but not in <params> will remain unchanged.
ftypestr, default=’p’: String indicating whether the file to be added is a parameter file (‘p’) or a transform file (‘t’).
resetbool, default=True: If True, and the step can be rerun (that is, it has a parameter file assigne), this will remove existing registration transforms.

adjust_pfile(step, params, reset=True): Alias for adjust_file() with ftype=’p’.

clear(): Remove all registration steps and their output directories.

ensure_registered(step): If a step has not already been registered, perform registration for this step and any preceding steps. Return True if registration had already been performed.

get_comparison(step=-1, force=False, **kwargs)

Return a pandas DataFrame comparing fixed image and transformed moving image after step.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which mutual information is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.
**kwargs: Keyword arguments passed to skrt.image.Image.get_comparison() See this method’s documentation for options.

get_correlation_quality(step=-1, force=False)

Calculate quality of correlation between transformed moving image after step and fixed image.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which correlation quality is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.

get_default_params(filename): Get the contents of a default parameter file as a dict. Note that this does not affect the current Registration object and is only for informative purposes.

get_deformation_field(step=-1, force=False): Generate deformation field for a given registration step.

get_fidelity(step=-1, force=False)

Calculate fidelity with which transformed moving image after step matches fixed image.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which fidelity is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.

get_foreground_comparison(step=-1, force=False, **kwargs)

Return a pandas DataFrame comparing the foregrounds of fixed image and transformed moving image after step.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which mutual information is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.
**kwargs: Keyword arguments passed to skrt.image.Image.get_foreground_comparison() See this method’s documentation for options.

get_input_parameters(step): Get dict of input parameters for a given step.

get_jacobian(step=-1, force=False, moving_to_fixed=False)

Generate Jacobian determinant for a given registration step (or return existing Jacobian object, unless force=True).

If the registration engine used is unable to generate the Jacobian determinant, None will be returned.

Positive values in the Jacobian determinant represent: - moving_to_fixed=False: scaling from fixed image to moving image; - moving_to_fixed=True: scaling from moving image to fixed image.

get_mutual_information(step=-1, force=False, **kwargs)

For fixed image and transformed moving image after step, calculate mutual information or a variant. after step.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which mutual information is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.
**kwargs: Keyword arguments passed to skrt.image.Image.get_mutual_information() See this method’s documentation for options.

get_quality(step=-1, force=False, metrics=None)

Evaluate quality relative to fixed image of transformed moving image after step.

For information on quality metrics, see documentation of skrt.image.Image.get_quality().

Parameters: step : int/str/list, default=None

Name or number of the registration step after which relative structure content is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.
metrics: list, default=None: List of strings specifying quality metrics to be evaluated. If None, all defined quality metrics are evaluated.

get_registration_cmd(step, use_previous_tfile=True): Get registration command for a given step.

get_relative_structural_content(step=-1, force=False)

Quantify structural content relative to fixed image of transformed moving image after step.

Parameters: step : int/str/list, default=None

Name or number of the registration step after which relative structure content is to be calculated. Available steps are listed in self.steps.

forcebool, default=False: If True, transformation of the moving image will be forced, even if the image was transformed previously.

get_step_name(step): Convert <step> to a string containing a step name. If <step> is already a string, use this; otherwise if <step> is an integer, obtain the corresponding step name. Check that step has a parameter file and/or a transform file assigned.

get_step_number(step): Convert <step> to an int containing the number of a given step. If <step> is an int, check it corresponds to a step number, ensure it is positive, and return it. Otherwise if it’s a string, return the index of that step name in self.steps.

get_tfile(dir_path)

Return path to transform file in directory <dir_path>.

The transform file may be named either ‘TransformParameters.0.txt’ (e.g. Elastix or NiftyReg affine) or ‘TransformParameters.0.nii’ (e.g. NiftyReg deformable). If both exist in the directory, the latter should be used.

get_transform_parameters(step): Get dict of output transform parameters for a given step.

get_transformed_grid(step=-1, force=False, spacing=(30, 30, 30), thickness=(2, 2, 2), voxel_units=False, color='green')

Obtain transformed grid.

A three-dimensional grid is defined in the space of the moving image, and is transformed by applying the result of a registration step.

Parameters:

stepint, default=-1: Registration step for which transformed grid is to be obtained.
forcebool, default=False: If False, return any previously calculated transformed grid. If True, disregard any previous calculations.
spacingtuple, default=(30, 30, 30): Spacing along (x, y, z) directions of grid lines. If voxel_units is True, values are taken to be in numbers of voxels. Otherwise, values are taken to be in the same units as the voxel dimensions of the moving image.
thicknesstuple, default=(2, 2, 2): Thickness along (x, y, z) directions of grid lines. If voxel_units is True, values are taken to be in numbers of voxels. Otherwise, values are taken to be in the same units as the voxel dimensions of the moving image.
voxel_unitsbool, default=False: If True, values for spacing and thickness are taken to be in numbers of voxels. If False, values for spacing and thickness are taken to be in the same units as the voxel dimensions of the moving image.
colortuple/str, default=’green’: Colour to use for grid lines. The colour may be specified in any of the forms recognised by matplotlib: https://matplotlib.org/stable/tutorials/colors/colors.html

get_transformed_image(step=-1, force=False): Get the transformed moving image for a given step, by default the final step. If force=True, the transform will be applied even if there is already a resultant image in the output directory for that step.

is_registered(step): Check whether a registration step has already been performed (i.e. has a valid output transform file).

list_default_pfiles(): List the available default parameter files. Note that this does not affect the current Registration object and is only for informative purposes.

load_existing_input_images(): Attempt to load images from fixed.nii.gz and moving.nii.gz from inside self.path. Print a warning if not found.

load_files(): Attempt to load registration steps from a registration step file.

make_tmp_dir(): Create temporary directory.

manually_adjust_translation(step=None, reapply_transformation=True)

Open BetterViewer and manually adjust the translation between the fixed image and the result of a registration. If the “write translation” button is clicked, the manual translation will be added to the translation in the output transform file.

Parameters:

stepint/str, default=None: Name, number, or list of the step which should have its translation modified. This must be provided if the registration has more than one step. If the tfile for the chosen step does not contain a translation, the function will immediately return None.
reapply_transformationbool, default=True: If True, upon saving a translation, the transformed moving image will be produced according to the new translation parameters.

print_log(step=-1): Print registration output log for a given step (by default, the last step).

register(step=None, force=False, use_previous_tfile=True, ensure_transformed_moving=True)

Run a registration. By default the registration will be run for all steps in self.steps, but can optionally be run for just one step by setting <step> to a step name or number. Note that if use_previous_tfile=True, any prior steps that have not yet been run will be run.

Parameters:

stepint/str/list, default=None: Name, number, or list of the step(s) for which the registration should be performed. By default, registration will be performed for all steps in series, using the previous steps’s output transform as input for the next. Available steps are listed in self.steps.
forcebool, default=None: If False and a registration has already been performed for the given step(s), the registration will not be re-run.
use_previous_tfilebool, default=True: If True, each step will use the transform file from the previous step as an initial transform.
ensure_transformed_movingbool, default=True: Ensure that a transformed moving image is created for each registration step. This may mean forcing the image creation for a step with a pre-defined transform file.

register_step(step, force=False, use_previous_tfile=True, ensure_transformed_moving=True)

Run a single registration step, if it has a parameter file assigned. Note that if use_previous_tfile=True, any prior steps that have not yet been run will be run.

Parameters:

stepint/str/list, default=None: Name or number of the step for which the registration should be performed. Available steps are listed in self.steps.
forcebool, default=None: If False and a registration has already been performed for the given step, the registration will not be re-run. Ignored if the step has no parameter file assigned (in which case the step must have a pre-defined transform file). Note that setting force=True will only force rerunning of the chosen step, not of any preceding steps needed for the input transform file. To enforce rerunning of multiple steps, call self.register(step, force=True) where <steps> is a list of steps to run.
use_previous_tfilebool, default=True: If True, this step will use the transform file from the previous step as an initial transform, unless it is the first step. Note that this will cause any prior steps that have not yet been run to be run.
ensure_transformed_movingbool, default=True: Ensure that a transformed moving image is created for the registration step. This may mean forcing the image creation for a step with a pre-defined transform file.

rm_tmp_dir(): Delete temporary directory and its contents.

run_transformix_on_all(is_jac, outdir, tfile, image=None, step=-1, force=False)

Create a Jacobian determinant or deformation field file, and return either a Jacobian or DeformationField object initialised from the output file.

This was first implemented by running transformix for an elastix transform file. Creation of Jacobian or DeformationField object now depends on the registration engine used.

set_fixed_image(im): Assign a fixed image.

set_fixed_mask(im): Assign a fixed-image mask.

set_image(im, category, force=True)

Assign a fixed or moving image.

Parameters:

imImage/str: The Image object to set, or a path that can be used to intialise an Image object.
categorystr: Category of image: “fixed”, “moving”, “fixed_mask”, “moving_mask”, “moving_grid”.
forcebool, default=True: If True, the image file within self.path will be overwritten by this image even if it already exists.

set_moving_grid(im): Assign a grid in the reference system of the moving image.

set_moving_image(im): Assign a moving image.

set_moving_mask(im): Assign a moving-image mask.

transform(to_transform, **kwargs)

Call one of the transform functions, depending on the type of to_transform. Functions called depending on type are:

Image:: transform_image(to_transform, `**`kwargs)
str:: transform_data(to_transform, `**`kwargs)
StructureSet:: transform_structure_set(to_transform, `**`kwargs)
ROI:: transform_roi(to_transform, `**`kwargs)

transform_data(path, step=-1, params=None, recurse=True): Transform a nifti file or point cloud at a given path for a given step, ensuring that the step has been run. Return the path to the transformed file inside self._tmp_dir.

transform_image(im, step=-1, outfile=None, params=None, rois=None)

Transform an image using the output transform from a given registration step (by default, the final step). If the registration step has not yet been performed, the step and all preceding steps will be run. Either return the transformed image or write it to a file.

Parameters:

imImage/str: Image to be transformed. Can be either an Image object or a path that can be used to initialise an Image object.
stepint/str, default=-1: Name or number of step for which to apply the transform; by default, the final step will be used.
outfilestr, default=None: If None, the transformed Image object will be returned; otherwise, it will be written to the path specified in <outfile>.
paramsdict, default=None: Optional list of parameters to temporarily overwrite in the transform file before applying the transform. Should be a dict, where keys are parameter names and desired values are values. Note that strings in the parameter file, need to include quotes, so you will need to use double quotes.

transform_moving_image(step=-1): Transform the moving image using the output of a registration step and set it to self.transformed_images[step].

transform_roi(roi, step=-1, outfile=None, params=None, transform_points=False, require_contours=False, recurse=True)

Transform a single ROI using the output transform from a given registration step (by default, the final step). If the registration step has not yet been performed, the step and all preceding steps will be run. Either return the transformed ROI or write it to a file.

Parameters:

roiROI/str: ROI to be transformed. Can be either an ROI object or a path that can be used to initialise an ROI object.
stepint/str, default=-1: Name or number of step for which to apply the transform; by default, the final step will be used.
outfilestr, default=None: If None, the transformed ROI object will be returned; otherwise, it will be written to the path specified in <outfile>. If outfile has no suffix, it will be treated as the path to a directory.
paramsdict, default=None: Optional list of parameters to temporarily overwrite in the transform file before applying the transform. Should be a dict, where keys are parameter names and desired values are values. Note that strings in the parameter file, need to include quotes, so you will need to use double quotes. By default, “ResampleInterpolator” will be set to “FinalNearestNeighborInterpolator”.
transform_pointsbool, default=False: If False, the transform is applied to pull the ROI mask from the reference frame of the moving image to the reference frame of the fixed image. If True, the transform is applied to push ROI contour points from the reference frame of the fixed image to the reference frame of the moving image.
require_contoursbool, default=False: If the transformed ROI doesn’t have contours defined: return the ROI if <require_contours> is False; return None if <require_contours> is True. A transformed ROI won’t have contours defined if, for example, it’s transformed as a mask, and the non-zero regions of the transformed mask are outside the fixed image.
recursebool, default=True: If True, and registration engine stores single-step transforms (engine property recursive_transform set to True), apply transforms step by step for all steps up to the one requested. if False, only apply transform relating to the current step.

transform_structure_set(structure_set, step=-1, outfile=None, params=None, transform_points=False, recurse=True)

Transform a structure set using the output transform from a given registration step (by default, the final step). If the registration step has not yet been performed, the step and all preceding steps will be run. Either return the transformed ROI or write it to a file.

Parameters:

structure_setStructureSet/str: StructureSet to be transformed. Can be either a StructureSet object or a path that can be used to initialise a StructureSet.
stepint/str, default=-1: Name or number of step for which to apply the transform; by default, the final step will be used.
outfilestr/pathlib.Path, default=None: If None, the transformed StructureSet object will be returned; otherwise, it will be written to the path specified in <outfile>. If outfile has no suffix, it will be treated as the path to a directory.
paramsdict, default=None: Optional list of parameters to temporarily overwrite in the transform file before applying the transform. Should be a dict, where keys are parameter names and desired values are values. Note that strings in the parameter file, need to include quotes, so you will need to use double quotes. By default, “ResampleInterpolator” will be set to “FinalNearestNeighborInterpolator”.
transform_pointsbool, default=False: If False, the transform is applied to pull ROI masks from the reference frame of the moving image to the reference frame of the fixed image. If True, the transform is applied to push ROI contour points from the reference frame of the fixed image to the reference frame of the moving image.
recursebool, default=True: If True, and registration engine stores single-step transforms (engine property recursive_transform set to True), apply transforms step by step for all steps up to the one requested. if False, only apply transform relating to the current step.

view_init(**kwargs): Interactively view initial fixed and moving images.

view_result(step=-1, compare_with_fixed=True, **kwargs)

Interactively view transformed image, optionally side-by-side with fixed image.

Parameters:

stepint/str, default=-1: Name or number of step for which to view the result. By default, the result of the final step will be shown.
compare_with_fixedbool, default=True: If True, the result will be displayed in comparison with the fixed image.
`**`kwargs :: Optional keyword arguments to pass to BetterViewer.

write_steps(): Write list of registration steps to a file at self.path/registration_steps.txt.

class skrt.registration.RegistrationEngine(path=None, force=False, log_level=None)

Bases: object

Base class for interfacing to a registration engine.

Some methods are effectively virtual: they will raise a NotImplementedError exception if called, and should be overridden in subclasses.

This class defines the following variables and methods:

Class variables: transform_points_implemented (bool): Indicate whether registration engine

implements mapping of points from fixed image to moving images.

recursive_transform (bool): Indicate whether a transform for a: registration step other than the first requires the transform output from the preceding step.
def_signs (tuple/None): Indicate signs to be applied to: (x, y, z) components of deformation field.

Methods: __init__(): Create RegistrationEngine instance. adjust_parameters():

Modify contents of a registration parameter file.

define_translation(): Define translation parameters to be passed: to registration engine.

get_default_pfiles(): Get list of default parameter files. get_default_pfiles_dir(): Return path to directory containing

default parameter files.

get_def_cmd(): Get registration-engine command for computing: deformation field.
get_dose_params(): Get default parameters to be used when: transforming dose.
get_jac_cmd(): Get registration-engine command for computing: Jacobian determinant.
get_registration_cmd(): Get registration-engine command for: performing image registration.
get_roi_params(): Get default parameters to be used when: transforming ROI mask.
get_transform_cmd(): Get registration-engine command for: applying registration transform.
read_parameters(): Get dictionary of parameters from a: registration parameter file.
set_exe_env(): Set environment variables for running: registration-engine software.

set_exe_paths(): Set path(s)s to registration-engine executable(s). shift_translation_parameters(): Add offsets to the translation parameters

in a registration transform file.

write_parameters(): Write dictionary of parameters to a: registration parameter file.

Static method: get_transform_strategies(): Get list of available strategies

for applying registration transform.

__init__(path=None, force=False, log_level=None)

Create RegistrationEngine instance.

Parameters: path : str/pathlib.Path, default=None

Path to directory containing registration-engine software.

force : bool, default=False If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

log_level: str/int/None, default=None: Severity level for event logging. If the value is None, log_level is set to the value of skrt.core.Defaults().log_level.

adjust_parameters(infile, outfile, params)

Modify contents of a registration parameter file.

Parameters:

infilestr/patlib.Path: Path to a registration parameter file.
outfilestr/pathlib.Path: Path to output file.
paramsdict: Dictionary of parameter names and new values.

def_signs = None

define_translation(dxdydz, fixed_image=None)

Define translation parameters to be passed to registration engine.

Parameters:

dxdydztuple/list: Three-element tuple or list, giving translations in order (dx, dy, dz). Translations correspond to the amounts added in mapping a point from fixed image to moving image.
fixed_imageskrt.image.Image, default=None: Image towards which moving image is to be warped.

exes = []

get_def_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing deformation field.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_default_pfiles(basename_only=True)

Get list of default parameter files.

Parameter:

basename_onlybool, default=True: If True, return list of filenames only. If False, return list of paths, as pathlib.Path objects.

get_default_pfiles_dir(): Return path to directory containing default parameter files.

get_dose_params(): Get default parameters to be used when transforming dose.

get_jac_cmd(fixed_path, outdir, tfile)

Get registration-engine command for computing Jacobian determinant.

Parameters:

fixed_pathstr: Path to fixed image.
outdirstr: Path to directory for output deformation field.
tfilestr: Path to registration transform file for which deformation field is to be computed.

get_registration_cmd(fixed_path, moving_path, fixed_mask_path, moving_mask_path, pfile, outdir, tfile=None)

Get registration-engine command for performing image registration.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
fixed_mask_pathstr: Path to mask for fixed image.
moving_mask_pathstr: Path to mask for moving image.
pfilestr: Path to registration paramter file.
outdirstr: Path to directory for registration output.
tfilestr, default=None: Path to registration transform file from previous registration step. If None, no previous registration step is it be considered.

get_roi_params(): Get default parameters to be used when transforming ROI mask.

get_transform_cmd(fixed_path, moving_path, outdir, tfile, params=None)

Get registration-engine command for applying registration transform.

Parameters:

fixed_pathstr: Path to fixed image.
moving_pathstr: Path to moving image.
outdirstr: Path to directory for transform output.
tfilestr: Path to registration transform file to be applied.
params: dict, default=None: Dictionary of parameter-value pairs defining modifications to the registration transform file prior to running the transform command. The original transform file is left unaltered.

get_transform_log(): Get name of transform log file.

static get_transform_strategies()

Get list of available strategies for applying registration transform.

Possible strategies are:

“pull”: transform applied to pull image or mask from the reference frame of the moving image to the reference frame of the fixed image;
“push”: transform applied to push points from the reference frame of the fixed image to the reference frame of the moving image.

is_available(path=None, force=False, defaults=None)

Check whether registration engine is available.

The environment setup can optionally be modified before checking.

Parameters:

pathstr/pathlib.Path, default=None: Path to set as directory containing registration-engine software.
forcebool, default=False: If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.
defaultsdict, default=None: Dictionary of key-value pairs with which to update skrt.core.Defaults().

read_parameters(infile)

Get dictionary of parameters from a registration parameter file.

Parameter: infile: str/pathlib.Path

Path to registration parameter file.

recursive_transform = False

set_exe_env(path=None, force=False)

Set environment variables for running registration-engine software.

Parameters:

pathstr/pathlib.Path, default=None: Path to directory containing registration-engine software.

force : bool, default=False If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

set_exe_paths(path)

Set path(s)s to registration-engine executable(s).

Parameter:

pathstr/pathlib.Path: Path to directory containing registration-engine executable(s).

shift_translation_parameters(infile, dx=0, dy=0, dz=0, outfile=None)

Add offsets to the translation parameters in a registration transform file.

Parameters:

infile: str: Path to input transform file.
dx, dy, dz: int, default=0: Amounts by which to increase translation parameters, along x, y, z directions.
outfile: str, default=None: Path to output parameter file. If None, overwrite input parameter file.

transform_points_implemented = False

write_parameters(outfile, params)

Write dictionary of parameters to a registration parameter file.

Parameters:

outfile: str/pathlib.Path: Path to output file.
params: dict: Dictionary of parameters to be written to file.

skrt.registration.add_engine(cls): Decorator for adding skrt.registration.RegistrationEngine subclasses to the skrt.registartion.engines dictionary.

skrt.registration.adjust_parameters(infile, outfile, params, engine=None)

Modify contents of a registration parameter file.

Parameters:

infilestr: Path to a registration parameter file.
outfilestr: Path to output file.
paramsdict: Dictionary of parameter names and new values.
engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.

skrt.registration.get_data_dir(): Return path to data directory within the scikit-rt package.

skrt.registration.get_default_pfiles(pattern='*.txt', engine=None, basename_only=False)

Get list of default parameter files.

Parameter:

basename_onlybool, default=False: If True, return list of filenames only. If False, return list of paths, as pathlib.Path objects.
engine: str, default=None: Name of registration engine for which path to directory containing default parameter files is required. If None, use value set for skrt.core.Default().registration_engine.
pattern: str, default=”*.txt”: Glob-style pattern for filtering on file names.

skrt.registration.get_default_pfiles_dir(engine=None)

Return path to directory containing default parameter files for specified engine.

Parameter: engine: str, default=None

Name of registration engine for which path to directory containing default parameter files is required. If None, use value set for skrt.core.Default().registration_engine.

skrt.registration.get_engine_cls(engine=None, engine_dir=None)

Get registration-engine class, given engine name or software directory.

Parameters:

engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.
engine_dir: pathlib.Path/str, default=None: Path to directory containing registration-engine software. It’s assumed that the registration engine is a key of the dictionary skrt.registration.engines, that the directory path includes this key, and that directory path doesn’t include any other keys of skrt.registration.engines.

skrt.registration.get_engine_name(engine=None, engine_dir=None)

Get registration-engine name, given engine name or software directory.

Parameters:

engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.
engine_dir: pathlib.Path/str, default=None: Path to directory containing registration-engine software. It’s assumed that the registration engine is a key of the dictionary skrt.registration.engines, that the directory path includes this key, and that directory path doesn’t include any other keys of skrt.registration.engines.

skrt.registration.get_engines(engine_dirs=None, force=False, defaults=None, verbose=False, no_exception=False)

Obtain list of names of available registration engines.

The environment setup can optionally be modified before checking.

Parameters:

engine_dirsdict, default=None: Dictionary where each key is the name of a registration engine, and the associated value is the path to be set as the directory containing the registration-engine software. This can be left as the default of None if all setup has been performed before calling this function.
forcebool, default=False: If False, modify environment based on <engine_dirs> only if registration software can’t be located in the existing environment. If True, modify environment based on <engine_dirs> in all cases.
defaultsdict, default=None: Dictionary of key-value pairs with which to update skrt.core.Defaults().
verbosebool, default=False: If True, print a message indicating available registration engines.
no_exception: bool, default=False: If False, raise an exception if no registration engine is available.

skrt.registration.get_image_transform_parameters(im)

Define Elastix registration-independent parameters for transforms to the space of a specified image.

Parameter:

imskrt.image.Image: Image object representing a fixed image in the context of registration.

skrt.registration.get_jacobian_colormap(col_per_band=100, sat_values=None)

Return custom colour map, for highlighting features of Jacobian determinant.

Following image registration, the Jacobian determinant of the registration transformation reflects the characteristics of the deformation field. A positive value, x, in the Jacobian determinant indicates a volume scaling by x in going from the fixed image to the moving image. A negative value indicates folding.

The colour map defined here is designed to cover the range -1 to 2, highlighting the following:

regions of no volume change (value equal to 1);
regions of small and large expansion (values greater than 1 by a small or large amount);
regions of small and large expansion (non-negative values less than 1 by a small or large amount);
regions of folding (negative values).

The colour map is as follows: - x < 0 (band 0): yellow, increasing linearly in opacity,

from 0 at x ==0 to 1 at saturation value;

0 <= x < 1 (band 1): blue, increasing in opacity as 1/x, from 0 at x == 1 to 1 at saturation value;
x == 1: transparent;
x > 1 (band 2): red, increasing linearly in opacity, from 0 at x == 1 to 1 at saturation value;

Parameters:

col_per_bandint, default=1000: Number of colours (anchor points) per band in the colour map.
sat_valuesdict, default=None: Dictionary of saturation values for the colour bands. The saturation value is the (unsigned) distance along the x scale from the band threshold. If None, use dictionary {0: 1, 1: 0.5, 2: 1}.

skrt.registration.get_parameters(pattern=None, engine=None, idx=0, params=None)

Obtain parameter dictionary from default parameter file.

Parameter: pattern: str, default=None

Glob-style pattern for identifying default parameter file(s).

engine: str, default=None: Name of registration engine for which a default parameter file is to be read. If None, use value set for skrt.core.Default().registration_engine.
idx: int, default=0: Index of parameter file to be read, from sorted list of those matching <pattern>. To avoid ambiguity, it’s usually best to choose <pattern> so that only one file is matched. A list of matching files can be obtained using get_default_pfiles().
params: dict, default=None: Dictionary of parameter-value pairs, with which to update dictionary read from file. Ignored if None.

skrt.registration.read_parameters(infile, engine=None)

Get dictionary of parameters from a registration parameter file.

Parameters: infile: str, pathlib.Path

Path fo registration parameter file.

engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.

skrt.registration.set_elastix_dir(path, force=True)

Perform environment setup for using elastix software.

Function deprecated - use set_engine_dir()

Parameters:

pathstr/pathlib.Path, default=None: Path to directory containing elastix software.
forcebool, default=True: If False, modify environment based on <path> only if elastix software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

skrt.registration.set_engine_dir(path, engine=None, force=True)

Perform environment setup for using registration software.

pathstr/pathlib.Path, default=None: Path to directory containing registration software.
enginestr, default=None: Name identifying the registration engine for which environment setup is to be performed. This should correspond to a key of the dictionary skrt.registration.engines.
forcebool, default=True: If False, modify environment based on <path> only if registration software can’t be located in the existing environment. If True, modify environment based on <path> in all cases.

skrt.registration.shift_translation_parameters(infile, dx=0, dy=0, dz=0, outfile=None, engine=None)

Add offsets to the translation parameters in a registration transform file.

Parameters:

infile: str: Path to input parameter file.
dx, dy, dz: int, default=0: Amounts by which to increase translation parameters, along x, y, z directions.
outfile: str, default=None: Path to output parameter file. If None, overwrite input parameter file.
engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.

skrt.registration.write_parameters(outfile, params, engine=None)

Write dictionary of parameters to a registration parameter file.

Parameters:

outfile: str: Path to output file.
params: dict: Dictionary of parameters to be written to file.
engine: str, default=None: String identifying registration engine, corresponding to a key of the dictionary skrt.registration.engines.