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', check_for_reflections=False, max_scaling=3.0, align_to_reference=False, qt_emitter=None, valis_obj=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.
check_for_reflections (bool, optional) – Determine if alignments are improved by relfecting/mirroring/flipping images. Optional because it requires re-detecting features in each version of the images and then re-matching features, and so can be time consuming and not always necessary.
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:
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
- 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:
- 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:
- 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:
- reflection_M
Transformation to reflect the image in the x and/or y axis, before padding. Will be the first transformation performed
- Type:
ndarray
- 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
- 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:
- 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
- distance_metric_name
Name of distance metric used to determine the dis/similarity between each pair of images
- Type:
- 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:
- img_obj_dict
Dictionary of ZImage objects. Created to conveniently access ZIimages. Key = ZImage.name, value= ZImage
- Type:
- 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
- reference_img_idx
Index of ZImage that corresponds to reference_img_f, after the img_obj_list has been sorted.
- Type:
- 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.