Serial rigid registration

Functions

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

valis.serial_rigid.register_images(img_dir, dst_dir=None, name='registrar', feature_detector=<valis.feature_detectors.VggFD object>, matcher=<valis.feature_matcher.Matcher object>, transformer=<EuclideanTransform(matrix=     [[ 1.,  0.,  0.],      [ 0.,  1.,  0.],      [ 0.,  0.,  1.]])>, affine_optimizer=None, imgs_ordered=False, reference_img_f=None, similarity_metric='n_matches', max_scaling=3.0, align_to_reference=False, qt_emitter=None)[source]

Rigidly align collection of images

Parameters
  • img_dir (str) – Path to directory containing the images that the user would like to be registered. These images need to be single channel, uint8 images

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

  • name (str, optional) – Descriptive name of registrar, such as the sample’s name

  • feature_detector (FeatureDD) – FeatureDD object that detects and computes image features.

  • matcher (Matcher) – Matcher object that will be used to match image features

  • transformer (scikit-image Transform object) – Transformer used to find transformation matrix that will warp each image to the target image.

  • affine_optimizer (AffineOptimzer object) – Object that will minimize a cost function to find the optimal affine transoformations

  • imgs_ordered (bool) – Boolean defining whether or not the order of images in img_dir are already in the correct order. If True, then each filename should begin with the number that indicates its position in the z-stack. If False, then the images will be sorted by ordering a feature distance matix.

  • 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 the reference.

  • similarity_metric (str) – Metric used to calculate similarity between images, which is in turn used to build the distance matrix used to sort the images.

  • summary (Dataframe) – Pandas dataframe containing the median distance between matched features before and after registration.

  • align_to_reference (bool, optional) – Whether or not images should be aligned to a reference image specified by reference_img_f.

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

Returns

registrar – SerialRigidRegistrar object contains general information about the alginments, but also a list of Z-images. Each ZImage contains the warp information for an image in the stack, including the transformation matrices calculated at each step, keypoint poisions, image descriptors, and matches with other images. See attributes from Zimage for more information.

Return type

SerialRigidRegistrar

Classes

ZImage

class valis.serial_rigid.ZImage(image, img_f, img_id, name)[source]

Class store info about an image, including the rigid registration parameters

image

Greyscale image that will be used for feature detection. This images should be greyscale and may need to have undergone preprocessing to make them look as similar as possible.

Type

ndarray

full_img_f

full path to the image

Type

str

img_id

ID of the image, based on its ordering processed_src_dir

Type

int

name

Name of the image. Usually img_f but with the extension removed.

Type

str

desc

(N, M) array of N desciptors for each keypoint, each of which has M features

Type

ndarray

kp_pos_xy

(N, 2) array of position for each keypoint

Type

ndarray

match_dict

Dictionary of image matches. Key= img_obj this ZImage is being compared to, value= MatchInfo containing information about the comparison, such as the position of matches, features for each match, number of matches, etc… The MatchInfo objects in this dictionary contain only the info for matches that were considered “good”.

Type

dict

unfiltered_match_dict

Dictionary of image matches. Key= img_obj this ZImage is being compared to, value= MatchInfo containing inoformation about the comparison, such as the position of matches, features for each match, number of matches, etc… The MatchInfo objects in this dictionary contain info for all matches that were cross-checked.

Type

dict

stack_idx

Position of image in sorted Z-stack

Type

int

fixed_obj

ZImage to which this ZImage was aligned, i.e. this is the “moving” image, and fixed_obj is the “fixed” image. This is set during the align_to_prev method of the SerialRigidRegistrar. The fixed_obj will either be immediately above or immediately below this ZImage in the image stack.

Type

ZImage

T

Transformation matrix that translates the image such that it is in a padded image that has the same shape as all other images

Type

ndarray

to_prev_A

Transformation matrix that warps image to align with the previous image

Type

ndarray

optimal_M

Transformation matrix found by minimizing a cost function. Used as final optional step to refine alignment

Type

ndarray

crop_T

Transformation matrix used to crop image after registration

Type

ndarray

M

Final transformation matrix that aligns image in the Z-stack.

Type

ndarray

M_inv

Inverse of final transformation matrix that aligns image in the Z-stack.

Type

ndarray

registered_img

image after being warped

Type

ndarray

padded_shape_rc

Shape of padded image. All other images will have this shape

Type

tuple

registered_shape_rc = tuple

Shape of aligned image. All other aligned images will have this shape

__init__(image, img_f, img_id, name)[source]

Class that stores information about an image

Parameters
  • image (ndarray) – Greyscale image that will be used for feature detection. This images should be single channel uint8 images, and may need to have undergone preprocessing and/or normalization to make them look as similar as possible.

  • img_f (str) – full path to image

  • img_id (int) – ID of the image, based on its ordering in the image source directory

  • name (str) – Name of the image. Usually img_f but with the extension removed.

SerialRigidRegistrar

class valis.serial_rigid.SerialRigidRegistrar(img_dir, imgs_ordered=False, reference_img_f=None, name=None, align_to_reference=False)[source]

Class that performs serial rigid registration

Registration is conducted by first detecting features in all images. Features are then matched between images, which are then used to construct a distance matrix, D. D is then sorted such that the most similar images are adjcent to one another. The rigid transformation matrics are then found to align each image with the previous image. Optionally, optimization can be performed to improve the alignments, although the “optimized” matrix will be discarded if it increases the distances between matched features.

SerialRigidRegistrar creates a list and dictionary of ZImage objects, each of which contains information related to feature matching and the rigid registration matrices.

img_dir

Path to directory containing the images that will be registered. The images in this folder should be single channel uint8 images. For the best registration results, they have undergone some sort of pre-processing and normalization. The preprocessing module contains methods for this, but the user may want/need to use other methods.

Type

str

aleady_sorted

Whether or not the order of images already known. If True, the file names should start with ascending numbers, with the first image file having the smallest number, and the last image file having the largest number. If False (the default), the order of images will be determined by ordering a distance matrix.

Type

bool, optional

name

Descriptive name of registrar, such as the sample’s name

Type

str

img_file_list

List of full paths to single channel uint8 images

Type

list

size

Number of images to align

Type

int

distance_metric_name

Name of distance metric used to determine the dis/similarity between each pair of images

Type

str

distance_metric_type

Name of the type of metric used to determine the dis/similarity between each pair of images. Despite the name, it could be “similarity” if the Matcher object compares image feautres using a similarity metric. In that case, similarities are converted to distances.

Type

str

img_obj_list

List of ZImage objects. Initially unordered, but eventually be sorted

Type

list

img_obj_dict

Dictionary of ZImage objects. Created to conveniently access ZIimages. Key = ZImage.name, value= ZImage

Type

dict

optimal_Z

Ordered linkage matrix for distance_mat

Type

ndarray

unsorted_distance_mat

Distance matrix with shape (N, N), where each element is the disimilariy betweewn each pair of the N images. The order of rows and columns reflects the order in which the images were read. This matrix is used to order the images the Z-stack.

Type

ndarray

distance_mat

unsorted_distance_mat reorderd such that the most similar images are adjacent to one another

Type

ndarray

unsorted_similarity_mat

Similar to unsorted_distance_mat, except the elements are image similarity

Type

ndarray

similarity_mat

Similar to distance_mat, except the elements are image similarity

Type

ndarray

features

Name of feature detector and descriptor used

Type

str

transform_type

Name of scikit-image transformer class that was used

Type

str

reference_img_f

Filename of image that will be treated as the center of the stack.

Type

str

reference_img_idx

Index of ZImage that corresponds to reference_img_f, after the img_obj_list has been sorted.

Type

int

align_to_reference

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.

Type

bool, optional

iter_order

Each element of iter_order contains a tuple of stack indices. The first value is the index of the moving/current/from image, while the second value is the index of the moving/next/to image.

Type

list of tuples

summary_df

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

Type

Dataframe

__init__(img_dir, imgs_ordered=False, reference_img_f=None, name=None, align_to_reference=False)[source]

Class that performs serial rigid registration

Parameters
  • img_dir (str) – Path to directory containing the images that will be registered. The images in this folder should be single channel uint8 images. For the best registration results, they have undergone some sort of pre-processing and normalization. The preprocessing module contains methods for this, but the user may want/need to use other methods.

  • imgs_ordered (bool) – Whether or not the order of images already known. If True, the file names should start with ascending numbers, with the first image file having the smallest number, and the last image file having the largest number. If False (the default), the order of images will be determined by sorting a distance matrix.

  • 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 the reference.

  • name (str, optional) – Descriptive name of registrar, such as the sample’s name

  • 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.

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