Registration

Functions

Classes and functions to register a collection of images

valis.registration.init_jvm(jar=None, mem_gb=10)[source]

Initialize JVM for BioFormats

valis.registration.kill_jvm()[source]

Kill JVM for BioFormats

valis.registration.load_registrar(src_f)[source]

Load a Valis object

Parameters

src_f (string) – Path to pickled Valis object

Returns

registrar – Valis object used for registration

Return type

Valis

Valis

class valis.registration.Valis(src_dir, dst_dir, series=None, name=None, img_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', match_filter_method='RANSAC', imgs_ordered=False, non_rigid_registrar_cls=<class 'valis.non_rigid_registrars.OpticalFlowWarper'>, non_rigid_reg_params={}, compose_non_rigid=True, img_list=None, reference_img_f=None, align_to_reference=False, do_rigid=True, crop=None, create_masks=True, resolution_xyu=None, slide_dims_dict_wh=None, max_image_dim_px=850, max_processed_image_dim_px=850, max_non_rigid_registartion_dim_px=850, thumbnail_size=500, norm_method='img_stats', 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.

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

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

Type

str

src_dir

Path to directory containing the slides that will be registered.

Type

str

dst_dir

Path to where the results should be saved.

Type

str

original_img_list

List of images converted from the slides in src_dir

Type

list of ndarray

slide_dims_dict_wh

Dictionary of slide dimensions. Only needed if dimensions not available in the slide/image’s metadata.

resolution_xyu

Physical size per pixel and the unit.

Type

tuple

image_type

Type of image, i.e. “brightfield” or “fluorescence”

Type

str

series

Slide series to that was read.

Type

int

size

Number of images to align

Type

int

aligned_img_shape_rc

Shape (row, col) of aligned images

Type

tuple of int

aligned_slide_shape_rc

Shape (row, col) of the aligned slides

Type

tuple of int

slide_dict

Dictionary of Slide objects, each of which contains information about a slide, and methods to warp it.

Type

dict of Slide

brightfield_procsseing_fxn_str

Name of function used to process brightfield images.

Type

str

if_procsseing_fxn_str

Name of function used to process fluorescence images.

Type

str

max_image_dim_px

Maximum width or height of images that will be saved. This limit is mostly to keep memory in check.

Type

int

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

int

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

str

reference_img_idx

Index of slide that corresponds to reference_img_f, after the img_obj_list has been sorted during rigid registration.

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

crop

How to crop the registered images.

Type

str, optional

rigid_registrar

SerialRigidRegistrar object that performs the rigid registration.

Type

SerialRigidRegistrar

rigid_reg_kwargs

Dictionary of keyward arguments passed to serial_rigid.register_images.

Type

dict

feature_descriptor_str

Name of feature descriptor.

Type

str

feature_detector_str

Name of feature detector.

Type

str

transform_str

Name of rigid transform

Type

str

similarity_metric

Name of similarity metric used to order slides.

Type

str

match_filter_method

Name of method used to filter out poor feature matches.

Type

str

non_rigid_registrar

SerialNonRigidRegistrar object that performs serial non-rigid registration.

Type

SerialNonRigidRegistrar

non_rigid_reg_kwargs

Dictionary of keyward arguments passed to serial_non_rigid.register_images.

Type

dict

non_rigid_registrar_cls

Uninstantiated NonRigidRegistrar class that will be used by non_rigid_registrar to calculate the deformation fields between images.

Type

NonRigidRegistrar

non_rigid_reg_class_str

Name of the of class non_rigid_registrar_cls belongs to.

Type

str

thumbnail_size

Maximum width or height of thumbnails that show results

Type

int

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

bool

norm_method

Name of method used to normalize the processed images

Type

str

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

start_time

The time at which registation was initiated.

Type

float

end_rigid_time

The time at which rigid registation was completed.

Type

float

end_non_rigid_time

The time at which non-rigid registation was completed.

Type

float

qt_emitter

Used to emit signals that update the GUI’s progress bars

Type

PySide2.QtCore.Signal

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, img_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', match_filter_method='RANSAC', imgs_ordered=False, non_rigid_registrar_cls=<class 'valis.non_rigid_registrars.OpticalFlowWarper'>, non_rigid_reg_params={}, compose_non_rigid=True, img_list=None, reference_img_f=None, align_to_reference=False, do_rigid=True, crop=None, create_masks=True, resolution_xyu=None, slide_dims_dict_wh=None, max_image_dim_px=850, max_processed_image_dim_px=850, max_non_rigid_registartion_dim_px=850, thumbnail_size=500, norm_method='img_stats', 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.

img_typestr, optional

The type of image, either “brightfield”, “fluorescence”, or “multi”. If None, VALIS will guess img_type of each image, based on the number of channels and datatype. Will assume that RGB = “brightfield”, otherwise img_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.

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.

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_registartion_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 “histo_match” for histogram matching, “img_stats” for normalizing by image statistics. See preprocessing.match_histograms and preprocessing.norm_khan for details.

_non_rigid_bboxlist

Bounding box of area in which non-rigid registration was conducted

_full_displacement_shape_rctuple

Shape of full displacement field. Would be larger than _non_rigid_bbox if non-rigid registration only performed in a masked region

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.

Parameters

src_f (str) – Path to the slide

Returns

slide_obj – Slide associated with src_f

Return type

Slide

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'}, reader_cls=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

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

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, perceputally_uniform_channel_colors=False, drop_duplicates=True, tile_wh=None, interp_method='bicubic', compression='lzw')[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…

  • perceputally_uniform_channel_colors (bool, optional) – Whether or not to add perceptually uniform 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.

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)[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.

src_f

Path to slide.

Type

str

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

val_obj

The “parent” object that registers all of the slide.

Type

Valis

reader

Object that can read slides and collect metadata.

Type

SlideReader

original_xml

Xml string created by bio-formats

Type

str

img_type

Whether the image is “brightfield” or “fluorescence”

Type

str

is_rgb

Whether or not the slide is RGB.

Type

bool

slide_shape_rc

Dimensions of the largest resolution in the slide, in the form of (row, col).

Type

tuple of int

series

Slide series to be read

Type

int

slide_dimensions_wh

Dimensions of all images in the pyramid (width, height).

Type

ndarray

resolution

Physical size of each pixel.

Type

float

units

Physical unit of each pixel.

Type

str

name

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

Type

str

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

stack_idx

Position of image in sorted Z-stack

Type

int

processed_img_f

Path to thumbnail of the processed image.

Type

str

rigid_reg_img_f

Path to thumbnail of rigidly aligned image.

Type

str

non_rigid_reg_img_f

Path to thumbnail of non-rigidly aligned image.

Type

str

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.

Type

tuple of int

aligned_slide_shape_rc

Shape (row, col) of aligned slide, based on the dimensions in the 0th level of they pyramid. In

Type

tuple of int

reg_img_shape_rc

Shape (row, col) of the registered image

Type

tuple of int

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_f

Path to file containing bk_dxdy, if saved

Type

str

_fwd_dxdy_f

Path to file containing fwd_dxdy, if saved

Type

str

_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

bool

fixed_slide

Slide object to which this one was aligned.

Type

Slide

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

crop

Crop method

Type

str

bg_px_pos_rc

Position of pixel that has the background color

Type

tuple

bg_color

Color of background pixels

Type

list, optional

__init__(src_f, image, val_obj, reader)[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.

slide2image(level, series=None, xywh=None)[source]

Convert slide to image

Parameters
  • level (int) – Pyramid level

  • series (int, optional) – Series number. Defaults to 0

  • xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

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
  • level (int) – Pyramid level

  • series (int, optional) – Series number. Defaults to 0

  • xywh (tuple of int, optional) – The region to be sliced from the slide. If None, then the entire slide will be converted. Otherwise xywh is the (top left x, top left y, width, height) of the region to be sliced.

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, perceputally_uniform_channel_colors=False, interp_method='bicubic', tile_wh=None, compression='lzw')[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 initialzing 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.

  • src_f (str, optional) – Path of slide to be warped. If None (the deffault), 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.

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')[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.

  • crop (bool, str) –

    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.