Registration
Functions
Classes and functions to register a collection of images
Classes
Valis
- class valis.registration.Valis(src_dir, dst_dir, series=None, name=None, image_type=None, feature_detector_cls=<class 'valis.feature_detectors.VggFD'>, transformer_cls=<class 'skimage.transform._geometric.SimilarityTransform'>, affine_optimizer_cls=None, similarity_metric='n_matches', matcher=<valis.feature_matcher.Matcher object>, imgs_ordered=False, non_rigid_registrar_cls=<class 'valis.non_rigid_registrars.OpticalFlowWarper'>, non_rigid_reg_params={}, compose_non_rigid=False, img_list=None, reference_img_f=None, align_to_reference=False, do_rigid=True, crop=None, create_masks=True, denoise_rigid=True, check_for_reflections=False, resolution_xyu=None, slide_dims_dict_wh=None, max_image_dim_px=850, max_processed_image_dim_px=850, max_non_rigid_registration_dim_px=850, thumbnail_size=500, norm_method='img_stats', micro_rigid_registrar_cls=None, micro_rigid_registrar_params={}, qt_emitter=None)[source]
Reads, registers, and saves a series of slides/images
Implements the registration pipeline described in “VALIS: Virtual Alignment of pathoLogy Image Series” by Gatenbee et al. This pipeline will read images and whole slide images (WSI) using pyvips, bioformats, or openslide, and so should work with a wide variety of formats. VALIS can perform both rigid and non-rigid registration. The registered slides can be saved as ome.tiff slides that can be used in downstream analyses. The ome.tiff format is opensource and widely supported, being readable in several different programming languages (Python, Java, Matlab, etc…) and software, such as QuPath or HALO.
The pipeline is fully automated and goes as follows:
1. Images/slides are converted to numpy arrays. As WSI are often too large to fit into memory, these images are usually lower resolution images from different pyramid levels.
2. Images are processed to single channel images. They are then normalized to make them look as similar as possible.
Image features are detected and then matched between all pairs of image.
4. If the order of images is unknown, they will be optimally ordered based on their feature similarity
5. Rigid registration is performed serially, with each image being rigidly aligned to the previous image in the stack.
6. Non-rigid registration is then performed either by 1) aliging each image towards the center of the stack, composing the deformation fields along the way, or 2) using groupwise registration that non-rigidly aligns the images to a common frame of reference.
7. Error is measured by calculating the distance between registered matched features.
The transformations found by VALIS can then be used to warp the full resolution slides. It is also possible to merge non-RGB registered slides to create a highly multiplexed image. These aligned and/or merged slides can then be saved as ome.tiff images using pyvips.
In addition to warping images and slides, VALIS can also warp point data, such as cell centoids or ROI coordinates.
- name_dict
Key=full path to image, value = name used to look up Slide in Valis.slide_dict
- Type:
dictionary
- slide_dims_dict_wh
Dictionary of slide dimensions. Only needed if dimensions not available in the slide/image’s metadata.
- slide_dict
Dictionary of Slide objects, each of which contains information about a slide, and methods to warp it.
- max_image_dim_px
Maximum width or height of images that will be saved. This limit is mostly to keep memory in check.
- Type:
- max_processed_image_dim_px
Maximum width or height of processed images. An important parameter, as it determines the size of of the image in which features will be detected and displacement fields computed.
- Type:
- reference_img_f
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.
- Type:
- reference_img_idx
Index of slide that corresponds to reference_img_f, after the img_obj_list has been sorted during rigid registration.
- 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:
- rigid_registrar
SerialRigidRegistrar object that performs the rigid registration.
- Type:
- rigid_reg_kwargs
Dictionary of keyward arguments passed to serial_rigid.register_images.
- Type:
- non_rigid_registrar
SerialNonRigidRegistrar object that performs serial non-rigid registration.
- Type:
- non_rigid_reg_kwargs
Dictionary of keyward arguments passed to serial_non_rigid.register_images.
- Type:
- non_rigid_registrar_cls
Uninstantiated NonRigidRegistrar class that will be used by non_rigid_registrar to calculate the deformation fields between images.
- Type:
- original_overlap_img
Image showing how original images overlap before registration. Created by merging coloring the inverted greyscale copies of each image, and then merging those images.
- Type:
ndarray
- rigid_overlap_img
Image showing how images overlap after rigid registration.
- Type:
ndarray
- non_rigid_overlap_img
Image showing how images overlap after rigid + non-rigid registration.
- Type:
ndarray
- has_rounds
Whether or not the contents of src_dir contain subdirectories that have single images spread across multiple files. An example would be .ndpis images.
- Type:
- target_processing_stats
Array of processed images’ stats used to normalize all images
- Type:
ndarray
- summary_df
Pandas dataframe containing information about the results, such as the error, shape of aligned slides, time to completion, etc…
- Type:
pd.Dataframe
- qt_emitter
Used to emit signals that update the GUI’s progress bars
- Type:
PySide2.QtCore.Signal
- _full_displacement_shape_rc
Shape of full displacement field. Would be larger than _non_rigid_bbox if non-rigid registration only performed in a masked region
- Type:
- _dup_names_dict
Dictionary describing which images would have been assigned duplicate names. Key= duplicated name, value=list of paths to images which would have been assigned the same name
- Type:
dictionary
- _empty_slides
Dictionary of Slide objects that have empty images. Ignored during registration but added back at the end
- Type:
dictionary
Examples
Basic example using default parameters
>>> from valis import registration, data >>> slide_src_dir = data.dcis_src_dir >>> results_dst_dir = "./slide_registration_example" >>> registered_slide_dst_dir = "./slide_registration_example/registered_slides"
Perform registration
>>> rigid_registrar, non_rigid_registrar, error_df = registrar.register()
View results in “./slide_registration_example”. If they look good, warp and save the slides as ome.tiff
>>> registrar.warp_and_save_slides(registered_slide_dst_dir)
This example shows how to register CyCIF images and then merge to create a high dimensional ome.tiff slide
>>> registrar = registration.Valis(slide_src_dir, results_dst_dir) >>> rigid_registrar, non_rigid_registrar, error_df = registrar.register()
Create function to get marker names from each slides’ filename
>>> def cnames_from_filename(src_f): ... f = valtils.get_name(src_f) ... return ["DAPI"] + f.split(" ")[1:4] ... >>> channel_name_dict = {f:cnames_from_filename(f) for f in registrar.original_img_list} >>> merged_img, channel_names, ome_xml = registrar.warp_and_merge_slides(merged_slide_dst_f, channel_name_dict=channel_name_dict)
View ome.tiff, located at merged_slide_dst_f
- __init__(src_dir, dst_dir, series=None, name=None, image_type=None, feature_detector_cls=<class 'valis.feature_detectors.VggFD'>, transformer_cls=<class 'skimage.transform._geometric.SimilarityTransform'>, affine_optimizer_cls=None, similarity_metric='n_matches', matcher=<valis.feature_matcher.Matcher object>, imgs_ordered=False, non_rigid_registrar_cls=<class 'valis.non_rigid_registrars.OpticalFlowWarper'>, non_rigid_reg_params={}, compose_non_rigid=False, img_list=None, reference_img_f=None, align_to_reference=False, do_rigid=True, crop=None, create_masks=True, denoise_rigid=True, check_for_reflections=False, resolution_xyu=None, slide_dims_dict_wh=None, max_image_dim_px=850, max_processed_image_dim_px=850, max_non_rigid_registration_dim_px=850, thumbnail_size=500, norm_method='img_stats', micro_rigid_registrar_cls=None, micro_rigid_registrar_params={}, qt_emitter=None)[source]
- src_dir: str
Path to directory containing the slides that will be registered.
- dst_dirstr
Path to where the results should be saved.
- namestr, optional
Descriptive name of registrar, such as the sample’s name
- seriesint, optional
Slide series to that was read. If None, series will be set to 0.
- image_typestr, optional
The type of image, either “brightfield”, “fluorescence”, or “multi”. If None, VALIS will guess image_type of each image, based on the number of channels and datatype. Will assume that RGB = “brightfield”, otherwise image_type will be set to “fluorescence”.
- feature_detector_clsFeatureDD, optional
Uninstantiated FeatureDD object that detects and computes image features. Default is VggFD. The available feature_detectors are found in the feature_detectors module. If a desired feature detector is not available, one can be created by subclassing feature_detectors.FeatureDD.
- transformer_clsscikit-image Transform class, optional
Uninstantiated scikit-image transformer used to find transformation matrix that will warp each image to the target image. Default is SimilarityTransform
- affine_optimizer_clsAffineOptimzer class, optional
Uninstantiated AffineOptimzer that will minimize a cost function to find the optimal affine transformations. If a desired affine optimization is not available, one can be created by subclassing affine_optimizer.AffineOptimizer.
- similarity_metricstr, optional
Metric used to calculate similarity between images, which is in turn used to build the distance matrix used to sort the images. Can be “n_matches”, or a string to used as distance in spatial.distance.cdist. “n_matches” is the number of matching features between image pairs.
- match_filter_method: str, optional
“GMS” will use filter_matches_gms() to remove poor matches. This uses the Grid-based Motion Statistics (GMS) or RANSAC.
- imgs_orderedbool, optional
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. Default is False.
- 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 the reference.
- align_to_referencebool, optional
If False, images will be non-rigidly aligned serially towards the reference image. If True, images will be non-rigidly aligned directly to the reference image. If reference_img_f is None, then the reference image will be the one in the middle of the stack.
- non_rigid_registrar_clsNonRigidRegistrar, optional
Uninstantiated NonRigidRegistrar class that will be used to calculate the deformation fields between images. See the non_rigid_registrars module for a desciption of available methods. If a desired non-rigid registration method is not available, one can be implemented by subclassing.NonRigidRegistrar. If None, then only rigid registration will be performed
- non_rigid_reg_params: dictionary, optional
Dictionary containing key, value pairs to be used to initialize non_rigid_registrar_cls. 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. See the NonRigidRegistrar classes in non_rigid_registrars for the available non-rigid registration methods and arguments.
- compose_non_rigidbool, optional
Whether or not to compose non-rigid transformations. If True, then an image is non-rigidly warped before aligning to the adjacent non-rigidly aligned image. This allows the transformations to accumulate, which may bring distant features together but could also result in un-wanted deformations, particularly around the edges. If False, the image not warped before being aaligned to the adjacent non-rigidly aligned image. This can reduce unwanted deformations, but may not bring distant features together.
- img_listlist, dictionary, optional
List of images to be registered. However, it can also be a dictionary, in which case the key: value pairs are full_path_to_image: name_of_image, where name_of_image is the key that can be used to access the image from Valis.slide_dict.
- do_rigid: bool, dictionary, optional
Whether or not to perform rigid registration. If False, rigid registration will be skipped.
If do_rigid is a dictionary, it should contain inverse transformation matrices to rigidly align images to the specificed by reference_img_f. M will be estimated for images that are not in the dictionary. Each key is the filename of the image associated with the transformation matrix, and value is a dictionary containing the following values:
- M(required) a 3x3 inverse transformation matrix as a numpy array.
Found by determining how to align fixed to moving. If M was found by determining how to align moving to fixed, then M will need to be inverted first.
- transformation_src_shape_rc(optional) shape (row, col) of image used to find the rigid transformation.
If not provided, then it is assumed to be the shape of the level 0 slide
- transformation_dst_shape_rc(optional) shape of registered image.
If not provided, this is assumed to be the shape of the level 0 reference slide.
- crop: str, optional
How to crop the registered images. “overlap” will crop to include only areas where all images overlapped. “reference” crops to the area that overlaps with a reference image, defined by reference_img_f. This option can be used even if reference_img_f is None because the reference image will be set as the one at the center of the stack.
If both crop and reference_img_f are None, crop will be set to “overlap”. If crop is None, but reference_img_f is defined, then crop will be set to “reference”.
- create_masksbool, optional
Whether or not to create and apply masks for registration. Can help focus alignment on the tissue, but can sometimes mask too much if there is a lot of variation in the image.
- denoise_rigidbool, optional
Whether or not to denoise processed images before rigid registion. Note that un-denoised images are used in the non-rigid registration
- check_for_reflectionsbool, 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.
- resolution_xyu: tuple, optional
Physical size per pixel and the unit. If None (the default), these values will be determined for each slide using the slides’ metadata. If provided, this physical pixel sizes will be used for all of the slides. This option is available in case one cannot easily access to the original slides, but does have the information on pixel’s physical units.
- slide_dims_dict_whdict, optional
Key= slide/image file name, value= dimensions = [(width, height), (width, height), …] for each level. If None (the default), the slide dimensions will be pulled from the slides’ metadata. If provided, those values will be overwritten. This option is available in case one cannot easily access to the original slides, but does have the information on the slide dimensions.
- max_image_dim_pxint, optional
Maximum width or height of images that will be saved. This limit is mostly to keep memory in check.
- max_processed_image_dim_pxint, optional
Maximum width or height of processed images. An important parameter, as it determines the size of of the image in which features will be detected and displacement fields computed.
- max_non_rigid_registration_dim_pxint, optional
Maximum width or height of images used for non-rigid registration. Larger values may yeild more accurate results, at the expense of speed and memory. There is also a practical limit, as the specified size may be too large to fit in memory.
- mask_dictdictionary
Dictionary where key = overlap type (all, overlap, or reference), and value = (mask, mask_bbox_xywh)
- thumbnail_sizeint, optional
Maximum width or height of thumbnails that show results
- norm_methodstr
Name of method used to normalize the processed images. Options are None when normalization is not desired, “histo_match” for histogram matching and “img_stats” for normalizing by image statistics. See preprocessing.match_histograms and preprocessing.norm_khan for details.
- iter_orderlist of tuples
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.
- micro_rigid_registrar_clsMicroRigidRegistrar, optional
Class used to perform higher resolution rigid registration. If None, this step is skipped.
- micro_rigid_registrar_paramsdictionary
Dictionary of keyword arguments used intialize the MicroRigidRegistrar
- qt_emitterPySide2.QtCore.Signal, optional
Used to emit signals that update the GUI’s progress bars
- get_slide(src_f)[source]
Get Slide
Get the Slide associated with src_f. Slide store registration parameters and other metadata about the slide associated with src_f. Slide can also:
Convert the slide to a numpy array (Slide.slide2image)
Convert the slide to a pyvips.Image (Slide.slide2vips)
Warp the slide (Slide.warp_slide)
Save the warped slide as an ome.tiff (Slide.warp_and_save_slide)
Warp an image of the slide (Slide.warp_img)
Warp points (Slide.warp_xy)
Warp points in one slide to their position in another unwarped slide (Slide.warp_xy_from_to)
Access slide ome-xml (Slide.original_xml)
See Slide for more details.
- register(brightfield_processing_cls=<class 'valis.preprocessing.ColorfulStandardizer'>, brightfield_processing_kwargs={'c': 0.2, 'h': 0}, if_processing_cls=<class 'valis.preprocessing.ChannelGetter'>, if_processing_kwargs={'adaptive_eq': True, 'channel': 'dapi'}, processor_dict=None, reader_cls=None, reader_dict=None)[source]
Register a collection of images
This function will convert the slides to images, pre-process and normalize them, and then conduct rigid registration. Non-rigid registration will then be performed if the non_rigid_registrar_cls argument used to initialize the Valis object was not None.
In addition to the objects returned, the desination directory (i.e. dst_dir) will contain thumbnails so that one can visualize the results: converted image thumbnails will be in “images/”; processed images in “processed/”; rigidly aligned images in “rigid_registration/”; non-rigidly aligned images in “non_rigid_registration/”; non-rigid deformation field images (i.e. warped grids colored by the direction and magntidue) of the deformation) will be in “”deformation_fields/”. The size of these thumbnails is determined by the thumbnail_size argument used to initialze this object.
One can get a sense of how well the registration worked by looking in the “overlaps/”, which shows how the images overlap before registration, after rigid registration, and after non-rigid registration. Each image is created by coloring an inverted greyscale version of the processed images, and then blending those images.
The “data/” directory will contain a pickled copy of this registrar, which can be later be opened (unpickled) and used to warp slides and/or point data.
“data/” will also contain the summary_df saved as a csv file.
- Parameters:
brightfield_processing_cls (preprocessing.ImageProcesser) – preprocessing.ImageProcesser used to pre-process brightfield images to make them look as similar as possible.
brightfield_processing_kwargs (dict) – Dictionary of keyward arguments to be passed to brightfield_processing_cls
if_processing_cls (preprocessing.ImageProcesser) – preprocessing.ImageProcesser used to pre-process immunofluorescent images to make them look as similar as possible.
if_processing_kwargs (dict) – Dictionary of keyward arguments to be passed to if_processing_cls
processor_dict (dict, optional) – Each key should be the filename of the image, and the value either a subclassed preprocessing.ImageProcessor, or a list, where the 1st element is the processor, and the second element a dictionary of keyword arguments passed to the processor. If None, then a default processor will be used for each image based on the inferred modality.
reader_cls (SlideReader, optional) – Uninstantiated SlideReader class that will convert the slide to an image, and also collect metadata. If None (the default), the appropriate SlideReader will be found by slide_io.get_slide_reader. This option is provided in case the slides cannot be opened by a current SlideReader class. In this case, the user should create a subclass of SlideReader. See slide_io.SlideReader for details.
reader_dict (dict, optional) – Dictionary specifying which readers to use for individual images. The keys should be the image’s filename, and the values the instantiated slide_io.SlideReader to use to read that file. Valis will try to find an appropritate reader for any omitted files, or will use reader_cls as the default.
- Returns:
rigid_registrar (SerialRigidRegistrar) – SerialRigidRegistrar object that performed the rigid registration. This object can be pickled if so desired
non_rigid_registrar (SerialNonRigidRegistrar) – SerialNonRigidRegistrar object that performed serial non-rigid registration. This object can be pickled if so desired.
summary_df (Dataframe) – summary_df contains various information about the registration.
The “from” column is the name of the image, while the “to” column name of the image it was aligned to. “from” is analagous to “moving” or “current”, while “to” is analgous to “fixed” or “previous”.
Columns begining with “original” refer to error measurements of the unregistered images. Those beginning with “rigid” or “non_rigid” refer to measurements related to rigid or non-rigid registration, respectively.
Columns beginning with “mean” are averages of error measurements. In the case of errors based on feature distances (i.e. those ending in “D”), the mean is weighted by the number of feature matches between “from” and “to”.
Columns endining in “D” indicate the median distance between matched features in “from” and “to”.
Columns ending in “TRE” indicate the target registration error between “from” and “to”.
Columns ending in “mattesMI” contain measurements of the Mattes mutual information between “from” and “to”.
”processed_img_shape” indicates the shape (row, column) of the processed image actually used to conduct the registration
”shape” is the shape of the slide at full resolution
”aligned_shape” is the shape of the registered full resolution slide
”physical_units” are the names of the pixels physcial unit, e.g. u’µm’
”resolution” is the physical unit per pixel
”name” is the name assigned to the Valis instance
”rigid_time_minutes” is the total number of minutes it took to convert the images and then rigidly align them.
”non_rigid_time_minutes” is the total number of minutes it took to convert the images, and then perform rigid -> non-rigid registration.
- warp_and_merge_slides(dst_f=None, level=0, non_rigid=True, crop=True, channel_name_dict=None, src_f_list=None, colormap='auto', drop_duplicates=True, tile_wh=None, interp_method='bicubic', compression='lzw', Q=100, pyramid=True)[source]
Warp and merge registered slides
- Parameters:
dst_f (str, optional) – Path to were the warped slide will be saved. If None, then the slides will be merged but not saved.
level (int, optional) – Pyramid level to be warped. Default is 0, which means the highest resolution image will be warped and saved.
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied. Default is True
crop (bool, str) – How to crop the registered images. If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initialzing the Valis object.
channel_name_dict (dict of lists, optional.) – key = slide file name, value = list of channel names for that slide. If None, the the channel names found in each slide will be used.
src_f_list (list of str, optionaal) – List of paths to slide to be warped. If None (the default), Valis.original_img_list will be used. Otherwise, the paths to which src_f_list points to should be an alternative copy of the slides, such as ones that have undergone processing (e.g. stain segmentation), had a mask applied, etc…
colormap (list) – List of RGB colors (0-255) to use for channel colors
drop_duplicates (bool, optional) – Whether or not to drop duplicate channels that might be found in multiple slides. For example, if DAPI is in multiple slides, then the only the DAPI channel in the first slide will be kept.
tile_wh (int, optional) – Tile width and height used to save image
interp_method (str) – Interpolation method used when warping slide. Default is “bicubic”
compression (str) – Compression method used to save ome.tiff . Default is lzw, but can also be jpeg or jp2k. See pyips for more details.
Q (int) – Q factor for lossy compression
pyramid (bool) – Whether or not to save an image pyramid.
- Returns:
merged_slide (pyvips.Image) – Image with all channels merged. If drop_duplicates is True, then this will only contain unique channels.
all_channel_names (list of str) – Name of each channel in the image
ome_xml (str) – OME-XML string containing the slide’s metadata
Slide
- class valis.registration.Slide(src_f, image, val_obj, reader, name=None)[source]
Stores registration info and warps slides/points
Slide is a class that stores registration parameters and other metadata about a slide. Once registration has been completed, Slide is also able warp the slide and/or points using the same registration parameters. Warped slides can be saved as ome.tiff images with valid ome-xml.
- image
Image to registered. Taken from a level in the image pyramid. However, image may be resized to fit within the max_image_dim_px argument specified when creating a Valis object.
- Type:
ndarray
- reader
Object that can read slides and collect metadata.
- Type:
- slide_shape_rc
Dimensions of the largest resolution in the slide, in the form of (row, col).
- slide_dimensions_wh
Dimensions of all images in the pyramid (width, height).
- Type:
ndarray
- processed_img
Image used to perform registration
- Type:
ndarray
- rigid_reg_mask
Mask of convex hulls covering tissue in unregistered image. Could be used to mask processed_img before rigid registration
- Type:
ndarray
- non_rigid_reg_mask
Created by combining rigidly warped rigid_reg_mask in all other slides.
- Type:
ndarray
- processed_img_shape_rc
Shape (row, col) of the processed image used to find the transformation parameters. Maximum dimension will be less or equal to the max_processed_image_dim_px specified when creating a Valis object. As such, this may be smaller than the image’s shape.
- aligned_slide_shape_rc
Shape (row, col) of aligned slide, based on the dimensions in the 0th level of they pyramid. In
- M
Rigid transformation matrix that aligns image to the previous image in the stack. Found using the processed copy of image.
- Type:
ndarray
- bk_dxdy
(2, N, M) numpy array of pixel displacements in the x and y directions. dx = bk_dxdy[0], and dy=bk_dxdy[1]. Used to warp images. Found using the rigidly aligned version of the processed image.
- Type:
ndarray
- fwd_dxdy
Inverse of bk_dxdy. Used to warp points.
- Type:
ndarray
- _bk_dxdy_np
bk_dxdy as a numpy array. Only not None if bk_dxdy becomes associated with a file
- Type:
ndarray
- _fwd_dxdy_np
fwd_dxdy as a numpy array. Only not None if fwd_dxdy becomes associated with a file
- Type:
ndarray
- stored_dxdy
Whether or not the non-rigid displacements are saved in a file Should only occur if image is very large.
- Type:
- xy_matched_to_prev
Coordinates (x, y) of features in image that had matches in the previous image. Will have shape (N, 2)
- Type:
ndarray
- xy_in_prev
Coordinates (x, y) of features in the previous that had matches to those in image. Will have shape (N, 2)
- Type:
ndarray
- xy_matched_to_prev_in_bbox
Subset of xy_matched_to_prev that were within overlap_mask_bbox_xywh. Will either have shape (N, 2) or (M, 2), with M < N.
- Type:
ndarray
- xy_in_prev_in_bbox
Subset of xy_in_prev that were within overlap_mask_bbox_xywh. Will either have shape (N, 2) or (M, 2), with M < N.
- Type:
ndarray
- __init__(src_f, image, val_obj, reader, name=None)[source]
- Parameters:
src_f (str) – Path to slide.
image (ndarray) – Image to registered. Taken from a level in the image pyramid. However, image may be resized to fit within the max_image_dim_px argument specified when creating a Valis object.
val_obj (Valis) – The “parent” object that registers all of the slide.
reader (SlideReader) – Object that can read slides and collect metadata.
name (str, optional) – Name of slide. If None, it will be src_f with the extension removed
- slide2image(level, series=None, xywh=None)[source]
Convert slide to image
- Parameters:
- Returns:
img – An image of the slide or the region defined by xywh
- Return type:
ndarray
- slide2vips(level, series=None, xywh=None)[source]
Convert slide to pyvips.Image
- Parameters:
- Returns:
vips_slide – An of the slide or the region defined by xywh
- Return type:
pyvips.Image
- warp_and_save_slide(dst_f, level=0, non_rigid=True, crop=True, src_f=None, channel_names=None, colormap='auto', interp_method='bicubic', tile_wh=None, compression='lzw', Q=100, pyramid=True, reader=None)[source]
Warp and save a slide
Slides will be saved in the ome.tiff format.
- Parameters:
dst_f (str) – Path to were the warped slide will be saved.
level (int) – Pyramid level to be warped
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied. Default is True
crop (bool, str) – How to crop the registered images. If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initializing the Valis object.
channel_names (list, optional) – List of channel names. If None, then Slide.reader will attempt to find the channel names associated with src_f.
colormap (dict, optional) – Dictionary of channel colors, where the key is the channel name, and the value the color as rgb255. If None (default), the channel colors from current_ome_xml_str will be used, if available. If None, and there are no channel colors in the current_ome_xml_str, then no colors will be added
src_f (str, optional) – Path of slide to be warped. If None (the default), Slide.src_f will be used. Otherwise, the file to which src_f points to should be an alternative copy of the slide, such as one that has undergone processing (e.g. stain segmentation), has a mask applied, etc…
interp_method (str) – Interpolation method used when warping slide. Default is “bicubic”
tile_wh (int, optional) – Tile width and height used to save image
compression (str) – Compression method used to save ome.tiff . Default is lzw, but can also be jpeg or jp2k. See pyips for more details.
Q (int) – Q factor for lossy compression
pyramid (bool) – Whether or not to save an image pyramid.
- warp_geojson(geojson_f, M=None, slide_level=0, pt_level=0, non_rigid=True, crop=True)[source]
Warp geometry using registration parameters
Warps geometries to their location in the registered slide/image
- Parameters:
geojson_f (str) – Path to geojson file containing the annotation geometries. Assumes coordinates are in pixels.
slide_level (int, tuple, optional) – Pyramid level of the slide. Used to scale transformation matrices. Can also be the shape of the warped image (row, col) into which the points should be warped. Default is 0.
pt_level (int, tuple, optional) – Pyramid level from which the points origingated. For example, if xy are from the centroids of cell segmentation performed on the full resolution image, this should be 0. Alternatively, the value can be a tuple of the image’s shape (row, col) from which the points came. For example, if xy are bounding box coordinates from an analysis on a lower resolution image, then pt_level is that lower resolution image’s shape (row, col). Default is 0.
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied. Default is True.
Apply crop to warped points by shifting points to the mask’s origin. Note that this can result in negative coordinates, but might be useful if wanting to draw the coordinates on the registered slide, such as annotation coordinates.
If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initialzing the Valis object.
- warp_geojson_from_to(geojson_f, to_slide_obj, src_slide_level=0, src_pt_level=0, dst_slide_level=0, non_rigid=True)[source]
Warp geoms in geojson file from annotation slide to another unwarped slide
Takes a set of geometries found in this annotation slide, and warps them to their position in the unwarped “to” slide.
- Parameters:
geojson_f (str) – Path to geojson file containing the annotation geometries. Assumes coordinates are in pixels.
to_slide_obj (Slide) – Slide to which the points will be warped. I.e. xy will be warped from this Slide to their position in the unwarped slide associated with to_slide_obj.
src_pt_level (int, tuple, optional) – Pyramid level of the slide/image in which xy originated. For example, if xy are from the centroids of cell segmentation performed on the unwarped full resolution image, this should be 0. Alternatively, the value can be a tuple of the image’s shape (row, col) from which the points came. For example, if xy are bounding box coordinates from an analysis on a lower resolution image, then pt_level is that lower resolution image’s shape (row, col).
dst_slide_level (int, tuple, optional) – Pyramid level of the slide/image in to xy will be warped. Similar to src_pt_level, if dst_slide_level is an int then the points will be warped to that pyramid level. If dst_slide_level is the “to” image’s shape (row, col), then the points will be warped to their location in an image with that same shape.
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied.
- Returns:
warped_geojson – Dictionry of warped geojson geometries
- Return type:
- warp_img(img=None, non_rigid=True, crop=True, interp_method='bicubic')[source]
Warp an image using the registration parameters
- imgndarray, optional
The image to be warped. If None, then Slide.image will be warped.
- non_rigidbool
Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied.
- crop: bool, str
How to crop the registered images. If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initialzing the Valis object.
- interp_methodstr
Interpolation method used when warping slide. Default is “bicubic”
- Returns:
warped_img – Warped copy of img
- Return type:
ndarray
- warp_slide(level, non_rigid=True, crop=True, src_f=None, interp_method='bicubic', reader=None)[source]
Warp a slide using registration parameters
- Parameters:
level (int) – Pyramid level to be warped
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied. Default is True
crop (bool, str) – How to crop the registered images. If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initialzing the Valis object.
src_f (str, optional) – Path of slide to be warped. If None (the default), Slide.src_f will be used. Otherwise, the file to which src_f points to should be an alternative copy of the slide, such as one that has undergone processing (e.g. stain segmentation), has a mask applied, etc…
interp_method (str) – Interpolation method used when warping slide. Default is “bicubic”
- warp_xy(xy, M=None, slide_level=0, pt_level=0, non_rigid=True, crop=True)[source]
Warp points using registration parameters
Warps xy to their location in the registered slide/image
- Parameters:
xy (ndarray) – (N, 2) array of points to be warped. Must be x,y coordinates
slide_level (int, tuple, optional) – Pyramid level of the slide. Used to scale transformation matrices. Can also be the shape of the warped image (row, col) into which the points should be warped. Default is 0.
pt_level (int, tuple, optional) – Pyramid level from which the points origingated. For example, if xy are from the centroids of cell segmentation performed on the full resolution image, this should be 0. Alternatively, the value can be a tuple of the image’s shape (row, col) from which the points came. For example, if xy are bounding box coordinates from an analysis on a lower resolution image, then pt_level is that lower resolution image’s shape (row, col). Default is 0.
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied. Default is True.
Apply crop to warped points by shifting points to the mask’s origin. Note that this can result in negative coordinates, but might be useful if wanting to draw the coordinates on the registered slide, such as annotation coordinates.
If True, then the same crop used when initializing the Valis object will be used. If False, the image will not be cropped. If “overlap”, the warped slide will be cropped to include only areas where all images overlapped. “reference” crops to the area that overlaps with the reference image, defined by reference_img_f when initialzing the Valis object.
- warp_xy_from_to(xy, to_slide_obj, src_slide_level=0, src_pt_level=0, dst_slide_level=0, non_rigid=True)[source]
Warp points from this slide to another unwarped slide
Takes a set of points found in this unwarped slide, and warps them to their position in the unwarped “to” slide.
- Parameters:
xy (ndarray) – (N, 2) array of points to be warped. Must be x,y coordinates
to_slide_obj (Slide) – Slide to which the points will be warped. I.e. xy will be warped from this Slide to their position in the unwarped slide associated with to_slide_obj.
src_pt_level (int, tuple, optional) – Pyramid level of the slide/image in which xy originated. For example, if xy are from the centroids of cell segmentation performed on the unwarped full resolution image, this should be 0. Alternatively, the value can be a tuple of the image’s shape (row, col) from which the points came. For example, if xy are bounding box coordinates from an analysis on a lower resolution image, then pt_level is that lower resolution image’s shape (row, col).
dst_slide_level (int, tuple, optional) – Pyramid level of the slide/image in to xy will be warped. Similar to src_pt_level, if dst_slide_level is an int then the points will be warped to that pyramid level. If dst_slide_level is the “to” image’s shape (row, col), then the points will be warped to their location in an image with that same shape.
non_rigid (bool, optional) – Whether or not to conduct non-rigid warping. If False, then only a rigid transformation will be applied.