Release notes for Valis 1.2.0

Major improvements to rigid registration by using more modern feature detectors and matchers. More specifically, Disk and DeDoDe feature detectors outperform BRISK and VGG (previous defaults). Different combinations of feature detectors, image sizes, and colorspaces (RGB or grayscale) were benchmarked using the ANHIR dataset. These results indicate that using the DISK feature detector on grayscale images both increases accuracy (i.e. lower TRE) and increase the correlation between VALIS' estimated error and the true error. However, using RGB does have somewhat higher accuracy and slightly faster runtimes. If you'd like to use RGB images, set the rgb=True when initializing Disk or DeDoDe feature detectors, pass that to the LightGlueMatcher, and then have that be the feature matcher used by Valis. That is:

  from valis import registration, feature_detectors, feature_matcher
  slide_src_dir = "/path/to/slides"
  results_dst_dir = "./slide_registration_example"
  registered_slide_dst_dir = "./slide_registration_example/registered_slides"

  fd = feature_detectors.DiskFD(rgb=True, num_features=2000)
  matcher = feature_matcher.LightGlueMatcher(fd)
  registrar = registration.Valis(slide_src_dir, results_dst_dir, matcher=matcher)
  rigid_registrar, non_rigid_registrar, error_df = registrar.register()

This improved rigid registration should also lead to fewer unwanted non-rigid deformations, and thus better results overall. Below are more details on these and other changes, as well as describing several bug fixes:

• Set default feature detector and matcher to be DISK and LightGlueMatcher, used on grayscale images with a maximum dimension of 512 pixels.
• Added DISK and DeDoDe feature detectors (see feature_detectors.DiskFD and feature_detectors.DeDoDeFD), as implemented in Kornia. These feature detectors can also work with RGB images instead of the processed grayscale images. This can be accomplished by setting rgb=True when initializing the feature detector. Do note these feature detectors are not rotation invariant, but the rotation angle can be estimated using features matched with a rotation invariant feature detector, such as BRISK. This is automatically done when using feature_matcher.LightGlueMatcher(see below).
• Added LightGlueMatcher feature matcher (see feature_matcher.LightGlueMatcher), which is intended to be used with the DiskFD and DeDoDeFD feature detectors.
• Feature matchers now instantiated with feature detectors.
• Instantiated feature detectors and matchers can be passed into Valis.register. This makes it possible to set the number of features to detect, whether RGB features should be used, etc... For example, Valis(matcher=feature_matcher.LightGlueMatcher(feature_detectors.DiskFD(rgb=True, num_features=2000))) will use the LightGlueMatcher to match 2000 RGB Disk features for each image pair.
• Using USAC_MAGSAC to remove outliers in matched feature, replacing RANSAC.
• Default image size for non-rigid registration has been doubled from 1024 to 2048.
• Added RAFT non-rigid registration method (see non_rigid_registrars.RAFTWarper), as implemented in torchvision. RAFT can also be used with RGB images by setting rgb=True when initializing non_rigid_registrars.RAFTWarper. Can use RAFT by passing non_rigid_registrars.RAFTWarper()to thenon_rigid_registrar_clswhen initializing theValisobject, e.g.Valis(non_rigid_registrar_cls=non_rigid_registrars.RAFTWarper())`.
• Can now use different feature detectors for image sorting and image matching. This is useful when the preferred feature detector is not rotation invariant, as the features matched during sorting can be used to estimate an initial rotation.
• Fix to avoid trying to access a negative level of an image pyramid GitHub issue 141
• Now possible to re-register a subset of images in src_dir. Previously, an error would occur if an attempt at registration was made, followed subsequent attempts using only a subset of images in src_dir.
• Now using the autocrop option when reading images with OpenSlide (via libvips). Only reads in the specimen area, as opposed to the entire slide, facilitating higher resolution registration.
• Avoid bug when searching for a file that has special characters in the name GitHub issue 170
• Test examples in Docker container by mounting a Docker volume that contains example data and scripts. Makes Docker testing more robust, and should avoid issues like those reported in GitHub issues 139 and 176
• Now requires pillow ≥ 10.3 GitHub issue 180
• Reads in formats readable by BioFormats without unnecessarily launching the JVM when calling slide_io.get_slide_reader`.
• Switched from Poetry to UV for Python package management

v1.1.0

• Rigid registration now performed after detecting the tissue and slicing it from the image. This allows higher resolution images to be used for rigid registration, improving accuracy. Implementing this enhancement involved making several changes to VALIS' defaults (see below). Please note that this behavior can be disabled by setting crop_for_rigid_reg=False when initializing the Valis object.
• A new masking method was developed to better detect the tissue and pickup less noise (preprocessing.create_tissue_mask_with_jc_dist)
• Added several new pre-processing methods, including preprocessing.OD, preprocessing.JCDist, preprocessing.ColorDeconvolver, and preprocessing.ColorDeconvolver.
• preprocessing.OD has replaced preprocessing.ColorfulStandardizer as the default RGB pre-processing method. Testing indicates that this method tends to perform better across a range of challenging images, as measured by median number of feature matches and mean TRE. To get results similar to previous versions of VALIS, one can set brightfield_processing_cls=preprocessing.ColorfulStandardizer when calling Valis.register.
• The default image size for rigid registration has been increased from 850 to 1024, (i.e. Valis(max_processed_image_dim_px=1024)).
• Image denoising for rigid registration is no longer the default behavior. This can be turned back on by setting Valis(denoise_rigid=False).
• Reduced memory usage to help enable aligning a large number of images Github issue 105. VALIS has now be tested aligning 556 serially sliced images.
• Passing radians to np.cos and np.sin when determining how much to pad images, as noted in Github issue 103. These images get cropped, so this should not affect registration accuracy.
• Can now read ome.tiff that do not have a SUBIFD, reported in Github issue 101
• Improved saving of non-pyarmid images, related to Github issue 101
• Better compatibility with non-uint8 RGB images.
• Updated code to ensure merged images have channels in the same order as when sorted or specified.
• Dockerfile now compatible with Python 3.12

1.0.4

• Added checks and unit tests to verify reference image is not being warped. Can confirm no transformations were being applied to the reference image, but values may have differed slightly due to interpolation effects, as the reference image was being padded and cropped. To avoid these interpolation effects, the original reference image is returned when "warping" the reference slide with crop="reference", which occurs regardless of the align_to_reference setting. This avoids unnecessary computation and potential interpolation errors. There are still checks to make sure that the warped image would have been the same as the unwarped image.
• Merge channels based on the position of each slide in the stack. This will be the same as the original order when imgs_ordered=True.
• Can provide colormaps for each slide when calling Valis.warp_and_save_slides
• Added pyramid argument to Valis.warp_and_save_slides
• Ignore setting series=0 message when there is only 1 series
• Updated openCV version in project.toml, as suggested in Github issue 76
• Added slide_io.check_xml_img_match to determine if there are mismatches between the xml metadata and the image that was read. If there are mismatches, the metadata will be updated based on the image (instead of the xml) and warning messages will be printed to let the user know about the mismatch.
• If a single channel image does not have channel names in the metadata, the channel name will be set to the image's name.
• Added denoise_rigid as an argument to initialize the Valis object. Determines whether or not to denoise the processed images prior to rigid registration. Had been fixed as True in previous versions, but this makes it optional (default remains True).
• Fixed issue where merged images were being interpreted as RGB and saved with extra channels (reported in Github issue 76 )

v1.0.3

• Can specify which slide readers to use for each image by passing a dictionary to the reader_dict argument in Valis.register. The keys, value pairs are image filename and instantiated SlideReader to use to read that file. Valis will try to find an appropriate reader for any omitted files. Can be especially useful in cases where one needs different series for different images, as the series argument is set when the SlideReader is created.
• Each Slide is assigned aSlideReader, ensuring that the same series will always be read.
• Added traceback messages to critical try/except blocks to help with debugging.
• Micro-registration can now use multiple image processors, and so should be able to perform multi-modal registration
• Now possible to save the images as non-pyarmid WSI by setting pyramid=False when calling the various slide saving methods (requested in github issue 56).
• Tested the slide_io.CziJpgxrReader with more jpegxr compressed czi images, including 3 RGB (2 mosaic, 1 not mosaic), 1 multichannel non-RGB (mosaic), 1 single channel (mosaic). Related to github issue 76.
• Added checks to make sure all channel names are in the colormap, addressing github issues 78 and 86.
• Setting colormap=None to the various save functions will not add any color channels, and so the slide viewer's default colormaps will be used.
• Updated slide_io.get_slide_reader to give preference to reading images with libvips/openslide. Should be faster since image will not need to be constructed from tiles.
• JVM will only be initialized if bioformats is needed to read the image.
• Updated slide_io.VipsSlideReader to use the ome-types pacakge to extract metadata, instead of Bio-formats. Should avoid having to launch JVM unless Bio-formats is really needed.
• Added checks to ensure that channels in merged image are in the correct order when imgs_ordered=True, addressing the comment github issue 56.
• Added tests for images with minimal ome-xml (i.e. no channel names, units, etc...)
• Removed usage of imghdr, which is being deprecated
• Replaced joblib with pqdm. May resolve issue posted on image.sc
• Removed interpolation and numba packages as dependencies
• Updated ome-types' parser to "lxml"
• Merged github pull request 95

v1.0.2

pypi fix

v1.0.0rc15

Version 1.0.0rc15 (May 10, 2023)

#. Added import for :code:aicspylibczi.CziFile in :code:slide_io (found in github issue 44). Also added :code:aicspylibczi to the poetry lock file.
#. Added :code:src_f argument in :code:Slide.warp_and_save_slide. Previously would end up using the :code:Slide.src_f, and preventing one from being able to warp and save other images using the same transformations (github issue 49).
#. Various bug fixes to allow the initial non-rigid registration to work with larger images (which may be :code:pyvips.Image objects).
#. Fixed bug where errors that occurred while reading images would prevent Python from shutting down.
#. Updated documentation for :code:valis.preprocessing
#. Added more tests
#. Fixed many typos in the documentation.