Serial non-rigid registration

Functions

Classes and functions to perform serial non-rigid registration of a set of images

valis.serial_non_rigid.register_images(src, non_rigid_reg_class=<class 'valis.non_rigid_registrars.OpticalFlowWarper'>, non_rigid_reg_params=None, dst_dir=None, reference_img_f=None, moving_to_fixed_xy=None, mask=None, name=None, align_to_reference=False, img_params=None, compose_transforms=True, qt_emitter=None)[source]
Parameters:

  • src (SerialRigidRegistrar, str) – Either a SerialRigidRegistrar object that was used to optimally align a series of images, or a string indicating where the images to be aligned are located. If src is a string, the images should be named such that they are read in the correct order, i.e. each starting with a number.

  • non_rigid_reg_class (NonRigidRegistrar) – Uninstantiated NonRigidRegistrar class that will be used to calculate the deformation fields between images. By default this is an OpticalFlowWarper that uses the OpenCV implementation of DeepFlow.

  • non_rigid_reg_params (dictionary, optional) – Dictionary containing parameters {name: value} to be used to initialize the NonRigidRegistrar. In the case where simple ITK is used by the, params should be a SimpleITK.ParameterMap. Note that numeric values nedd to be converted to strings.

  • dst_dir (str, optional) – Top directory where aliged images should be save. SerialNonRigidRegistrar will be in this folder, and aligned images in the “registered_images” sub-directory. If None, the images will not be written to file

  • reference_img_f (str, optional) – Filename of image that will be treated as the center of the stack. If None, the index of the middle image will be returned.

  • moving_to_fixed_xy (dict of list, or bool) –

    If moving_to_fixed_xy is a dict of list, then Key = image name, value = list of matched keypoints between each moving image and the fixed image. Each element in the list contains 2 arrays:

    1. Rigid registered xy in moving/current/from image

    2. Rigid registered xy in fixed/next/to image

    To deterime which pairs of images will be aligned, use warp_tools.get_alignment_indices. Can use get_imgs_from_dir to see the order inwhich the images will be read, which will correspond to the indices retuned by warp_tools.get_alignment_indices.

    If src is a SerialRigidRegistrar and moving_to_fixed_xy is True, then the matching features in the SerialRigidRegistrar will be used. If False, then matching features will not be used.

  • mask (ndarray, bool, optional) –

    Mask used in non-rigid alignments.

    If an ndarray, it must have the same size as the other images.

    If True, then the overlap_mask in the SerialRigidRegistrar will be used.

    If False or None, no mask will be used.

  • name (optional) – Optional name for this SerialNonRigidRegistrar

  • align_to_reference (bool, optional) – Whether or not images should be aligne to a reference image specified by reference_img_f. Will be set to True if reference_img_f is provided.

  • img_params (dict, optional) – Dictionary of parameters to be used for each particular image. Useful if images to be registered haven’t been processed. Will be passed to non_rigid_reg_class init and register functions. key = file name, value= dictionary of keyword arguments and values

  • qt_emitter (PySide2.QtCore.Signal, optional) – Used to emit signals that update the GUI’s progress bars

Returns:

nr_reg – SerialNonRigidRegistrar that has registeredt the images in src

Return type:

SerialNonRigidRegistrar

Classes

NonRigidZImage

class valis.serial_non_rigid.NonRigidZImage(reg_obj, image, name, stack_idx, moving_xy=None, fixed_xy=None, mask=None)[source]

Class that store info about an image, including both rigid and non-rigid registration parameters

image

Original, unwarped image with shape (P, Q)

Type:

ndarray

name

Name of image.

Type:

str

stack_idx

Position of image in the stack

Type:

int

moving_xy

(V, 2) array containing points in the moving image that correspond to those in the fixed image. If these are provided, non_rigid_reg_class should be a subclass of non_rigid_registrars.NonRigidRegistrarXY

Type:

ndarray, optional

fixed_xy

(V, 2) array containing points in the fixed image that correspond to those in the moving image

Type:

ndarray, optional

bk_dxdy

(2, N, M) numpy array of pixel displacements in the x and y directions from the reference image. dx = bk_dxdy[0], and dy=bk_dxdy[1]. Used to warp images

Type:

ndarray

fwd_dxdy

Inversion of bk_dxdy. dx = fwd_dxdy[0], and dy=fwd_dxdy[1]. Used to warp points

Type:

ndarray

warped_grid

Image showing deformation applied to a regular grid.

Type:

ndarray

__init__(reg_obj, image, name, stack_idx, moving_xy=None, fixed_xy=None, mask=None)[source]
Parameters:

  • image (ndarray) – Original, unwarped image with shape (P, Q)

  • name (str) – Name of image.

  • stack_idx (int) – Position of image in the stack

  • moving_xy (ndarray, optional) – (V, 2) array containing points in the moving image that correspond to those in the fixed image. If these are provided, non_rigid_reg_class should be a subclass of non_rigid_registrars.NonRigidRegistrarXY

  • fixed_xy (ndarray, optional) – (V, 2) array containing points in the fixed image that correspond to those in the moving image

  • mask (ndarray, optional) – Mask covering area to be registered.

SerialNonRigidRegistrar

class valis.serial_non_rigid.SerialNonRigidRegistrar(src, reference_img_f=None, moving_to_fixed_xy=None, mask=None, name=None, align_to_reference=False, compose_transforms=True)[source]

Class that performs serial non-rigid registration, based on results SerialRigidRegistrar

A SerialNonRigidRegistrar finds the deformation fields that will non-rigidly align a series of images, using the rigid registration parameters found by a SerialRigidRegistrar object. There are two types of non-rigid registration methods:

#. Images are aligned towards a reference image, which may or may not be at the center of the stack. In this case, the image directly “above” the reference image is aligned to the reference image, after which the image 2 steps above the reference image is aligned to the 1st (now aligned) image above the reference image, and so on. The process is similar when aligning images “below” the reference image.

#. All images are aligned simultaneously, and so a reference image is not # required. An example is the SimpleElastix groupwise registration.

Similar to SerialRigidRegistrar, SerialNonRigidRegistrar creates a list and dictionary of NonRigidZImage objects each of which contains information related to the non-rigid registration, including the original rigid transformation matrices, and the calculated deformation fields.

name

Optional name of this SerialNonRigidRegistrar

Type:

str, optional

from_rigid_reg

Whether or not the images are from a SerialRigidRegistrar

Type:

bool

ref_image_name

Name of mage that is being treated as the “center” of the stack. For example, this may be associated with an H+E image that is the 2nd image in a stack of 7 images.

Type:

str

size

Number of images to align

Type:

int

shape

Shape of each image to register. Must be the same for all images

Type:

tuple of int

non_rigid_obj_dict

Dictionary, where each key is the name of a NonRigidZImage, and the value is the assocatiated NonRigidZImage

Type:

dict

non_rigid_reg_params

Dictionary containing parameters {name: value} to be used to initialize the NonRigidRegistrar. In the case where simple ITK is used by the, params should be a SimpleITK.ParameterMap. Note that numeric values nedd to be converted to strings.

Type:

dictionary

mask

Mask used in non-rigid alignments, with shape (P, Q).

Type:

ndarray

mask_bbox_xywh

Bounding box of mask (top left x, top left y, width, height)

Type:

ndarray

summary

Pandas dataframe containing the median distance between matched features before and after registration.

Type:

Dataframe

__init__(src, reference_img_f=None, moving_to_fixed_xy=None, mask=None, name=None, align_to_reference=False, compose_transforms=True)[source]
Parameters:

src (SerialRigidRegistrar, str, dict) –

A SerialRigidRegistrar object that was used to optimally align a series of images.

If a string, it should indicating where the images to be aligned are located. If src is a string, the images should be named such that they are read in the correct order, i.e. each starting with a number.

If a dictionary, it should contain the following key, value pairs:

”img_list” : list of images to register “img_f_list” : list of filenames of each image “name_list” : list of image names. If not provided, will come from file names “mask_list” list of masks for each image

reference_img_fstr, optional

Filename of image that will be treated as the center of the stack. If None, the index of the middle image will be returned.

moving_to_fixed_xydict of list, or bool

If moving_to_fixed_xy is a dict of list, then Key = image name, value = list of matched keypoints between each moving image and the fixed image. Each element in the list contains 2 arrays:

  1. Rigid registered xy in moving/current/from image

  2. Rigid registered xy in fixed/next/to image

To deterime which pairs of images will be aligned, use get_alignment_indices. Can use get_imgs_from_dir to see the order inwhich the images will be read, which will correspond to the indices retuned by get_alignment_indices.

If src is a SerialRigidRegistrar and moving_to_fixed_xy is True, then the matching features in the SerialRigidRegistrar will be used. If False, then matching features will not be used.

maskndarray, bool, optional

Mask used for all non-rigid alignments.

If an ndarray, it must have the same size as the other images.

If True, then the overlap_mask in the SerialRigidRegistrar will be used.

If False or None, no mask will be used.

nameoptional

Optional name for this SerialNonRigidRegistrar

align_to_referencebool, optional

Whether or not images should be aligned to a reference image specified by reference_img_f.

img_paramsdict, optional

Dictionary of parameters to be used for each particular image. Useful if images to be registered haven’t been processed. Will be passed to non_rigid_reg_class init and register functions. key = file name, value= dictionary of keyword arguments and values

register(non_rigid_reg_class, non_rigid_reg_params, img_params=None)[source]

Non-rigidly align images, either as a group or serially

Images will be registered serially if non_rigid_reg_class is a subclass of NonRigidRegistrarGroupwise, then groupwise registration will be conductedd. If non_rigid_reg_class is a subclass of NonRigidRegistrar then images will be aligned serially.

Parameters:

  • non_rigid_reg_class (NonRigidRegistrar, NonRigidRegistrarGroupwise) – Uninstantiated NonRigidRegistrar or NonRigidRegistrarGroupwise class that will be used to calculate the deformation fields between images

  • non_rigid_reg_params (dictionary, optional) – Dictionary containing parameters {name: value} to be used to initialize the NonRigidRegistrar. In the case where simple ITK is used by the, params should be a SimpleITK.ParameterMap. Note that numeric values nedd to be converted to strings.

  • img_params (dict, optional) – Dictionary of parameters to be used for each particular image. Useful if images to be registered haven’t been processed. Will be passed to non_rigid_reg_class init and register functions. key = file name, value= dictionary of keyword arguments and values

summarize()[source]

Summarize alignment error

Returns:

summary_df – Pandas dataframe containin the registration error of the alignment between each image and the previous one in the stack.

Return type:

Dataframe