This page documents a way to register whole slide images in Fiji and analyze their result in QuPath. This workflow allows to register slides with transformations which are more complex than affine transform. Reasonably, if the sample is not too deformed, registration at the cellular level can be achieved on the whole slide area.
In this documentation, a demo dataset is used where a fluorescent WSI image is registered to a RGB DAB image. The demo dataset can be [downloaded here](https://perdu.com/).
= Installation
== ImageJ / Fiji
* Enable the [bigdataviewer-playground](https://imagej.github.io/Bigdataviewer_Playground) update site, then restart Fiji.
* To enable automated registrations capabilities, install elastix:
** Download the [latest release of elastix for your OS](https://github.com/SuperElastix/elastix/releases/tag/5.0.1). This documentation has been tested for elastix 5.0.1.
** Unzip it
** For windows users, you also need to install [Visual C++ redistributable](https://support.microsoft.com/en-us/topic/the-latest-supported-visual-c-downloads-2647da03-1eea-4433-9aff-95f26a218cc0), you'll most probably need `vc_redist.x64.exe`
** Check, in a command line that elastix can run:
*** On windows launch a command console `cmd.exe`, go to the elastix folder, then type `elastix.exe --help`. Check that you got some useful help message and not errors.
*** Not tested on mac and linux, but you probably need to type either `elastix --help` or `.\elastix --help` to check proper functioning as well
** Indicate `elastix` and `transformix` executable location in Fiji:
*** Execute {nav Plugins › BIOP › Set and Check Wrappers} then indicate the proper location of executable files {F18020664, size=full}
*** This should show up in the ImageJ console : `[INFO] Transformix -> set :-) Elastix -> set :-)`
== QuPath
Install the [latest QuPath version](https://qupath.github.io/)
Install the latest release of [QuPath biop extensions](https://github.com/BIOP/qupath-biop-extensions/releases). (TODO make the proper release):
* Download the latest release
* Extract zip
* Put jars in folder TODO
When you start QuPath, you should specify the location of your common extension folder:
* TODO
When QuPath is restarted, a BIOP menu should appear on top of the QuPath window:
{F18022329, size=full}
= Usage
== Create your QuPath project
Create first a QuPath project containing all the slides that you want to register. If you do not have files, here is a demo dataset that you can download for testing : TODO, add zenodo link.
{F18022361, size=full}
WARNING: Only the Bio-Formats image server is supported on the FIJI side.
If your image can't be loaded in QuPath using the `Bio-Formats builder`, you can convert your slides in `ome.tiff` format. Several options are available, for instance by using [bfconvert with Kheops](https://c4science.ch/w/bioimaging_and_optics_platform_biop/image-processing/imagej_tools/ijp-kheops/), or [bioformatsf2raw](https://c4science.ch/w/bioimaging_and_optics_platform_biop/image-processing/qupath/ome-tiff-conversion/) for a fast conversion.
WARNING: All files need to be properly calibrated (microns, millimeters, etc, but not pixels!). Check on the image tab of QuPath that you have a proper physical unit specified, and not pixels!
{F18022412, size=full}
Save your project, and your are done for now on the QuPath side.
NOTE: You can let QuPath open while performing the registration on Fiji.
== Registration in Fiji
=== Open your QuPath project
In Fiji, open your QuPath project using {nav Plugins › BigDataViewer › Playground › BDVDataset › Open [QuPath Project] }. You can also directly type `QuPath` in Fiji's search bar to avoid struggling in Fiji's menu hierarchy.
* Fill in your qpproj file
* Let the default options but make sure to select **MILLIMETER** in the `physical units of the dataset` field
{F18022564, size=full}
NOTE: the `physical units of the dataset` field actually indicates how you want to import your dataset. Bio-Formats takes care of converting the unit of the acquisition into the millimeter. But this can be achieved only if the image is correctly calibrated initially.
NOTE: this WSI registration workflow hides many registration parameters by making use of the proper calibration in physical units, and by assuming it targets a cellular resolution level (do not expect registration precision at 50 nm resolution, unless you manually correct it with BigWarp).
After you have opened your Project, a window called `BDV Sources` should pop-up. If you double click on the `Sources` node, you should be able to browse the hierarchy and see the "sources" contained in your QuPath project. Note that the fluorescent channels have been splitted into separated sources. In the demo file, you get a window like this:
{F18022649, size=full}
* `DAB.tif-ch0` is the RGB DAB image
* `TileScan_001_Merging001-ch0` is the DAPI fluorescent channel
* `TileScan_001_Merging001-ch1` is the other fluorescent channel (which one is it?? TODO)
For the WSI registration, we fill choose the DAB image as the fixed reference image, and we will choose the DAPI channel as the reference moving image, which will be registered to the DAB image.
=== Coarse manual pre-registration
This workflow works if the images are approximately pre-aligned in the world coordinate space. To check if this is the case, you will need to display the two slides you want to align in a BigDataViewer window. To do this:
* select the slides that you want to align in the tree view. For this, you may find convenient to expand {nav SpimData 0> QuPathEntryEntity}, and select, using `ctrl+click`, the two entities you want to align:
{F18022728, size=full}
* With these selected, right-click and select `BDV - Show Sources (new BDV Window)`
{F18022737, size=full}
* Select the options as below:
{F18022742, size=full}
* For the demo dataset, you will get something like this:
{F18022750, size=full}
You can hover with your mouse on the right part of the panel to see a blue arrow that you can click:
{F18022760, size=full}
With this right panel you can activate or deactivate sources. You notice that the fluorescent image, while of the correct size, is shifted in XY to the DAB image. This needs to be corrected before going further. If your images are already approximately aligned, you can skip the part below and go to the wizard section.
NOTE: Navigating within BigDataViewer requires a bit of experience. In 2D, the minimal commands to know are written below.
- **hold and drag right-click**: Pan;
- **mouse wheel (or up / down key)**: zoom in and out;
- **`shift` modifier key**: zoom in or out faster,
- **`ctrl` modifier key**: more precise zoom.
- You'll soon notice that holding ***`left-click`*** rotates the view. To go back to the default rotation, click ***`shift+Z`***
== Analysis in QuPath