Release notes for Valis 1.2.0

[cdgatenbee]

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

---

This discussion was created from the release Release notes for Valis 1.2.0.

[simomounir]

Thanks for all these updates and improvements. It will certainly come handy in a handful of computations I am trying to run.

I have a question though. Did the visualization for displacement fields change in the latest release? It used to be a triangular mesh grid, but now it is dots (I assume same color coding meaning for direction and amplitude).

[cdgatenbee]

Hi @simomounir,
Yes, you're correct that I changed how the displacement fields are visualized, I just forgot to include it in the release notes. I changed this because it seemed a bit easier to to see the larger displacements (color coded arrows, angle=color, size = magnitude), and ignore the small ones (which appear more like dots, but are actually tiny gray arrows). Hope this doesn't cause you any trouble. If you'd like to re-create the version with the triangular mesh, you can use viz.color_displacement_tri_grid(bk_dx=slide_obj.bk_dxdy[0], bk_dy=slide_obj.bk_dxdy[1], img=slide_obj.warp_img()).

Best,
-Chandler