Search Support
Contact us
10x Genomics Support/Xenium Explorer/Tutorials/

Image Alignment in Xenium Explorer

The Xenium In Situ workflow is non-destructive, which enables post-Xenium Analyzer staining and imaging on the same tissue section. Starting in Xenium Explorer v1.2, Hematoxylin & Eosin (H&E) images can be imported and aligned to the original DAPI-stained image.

At this time, immunofluorescence (IF) images aligned with community-developed tools can be viewed in Xenium Explorer (see Getting Started tutorial Advanced section). In a future software release, Xenium Explorer will provide a supported workflow to align IF images directly with Xenium data.

Xenium Explorer provides three methods for viewing post-Xenium H&E images:

The image format must be a pyramidal, tiled OME-TIFF to be compatible with Xenium Explorer. If you need to convert the image file, start with the image file conversion tutorial.

Once the H&E image is in an ome.tif format, you can open the dataset in Xenium Explorer (see Getting Started tutorial for guidance) and proceed to import and alignment options.

To follow along with example steps for either aligning the image in Xenium Explorer or using an existing image alignment file, you can download the Xenium Onboard Analysis output bundle and unaligned H&E image from this public dataset (either Rep 1 or Rep 2).

  • These files are in TIFF format and need to be converted to OME-TIFF before they can be opened in Xenium Explorer (see file conversion tutorial). The example screenshots below show an H&E TIFF file that was converted to OME-TIFF with Tifffile.
# Example curl command to download files # Input Files curl -O https://cf.10xgenomics.com/samples/xenium/1.0.1/Xenium_FFPE_Human_Breast_Cancer_Rep1/Xenium_FFPE_Human_Breast_Cancer_Rep1_he_image.tif # Output Files curl -O https://cf.10xgenomics.com/samples/xenium/1.0.1/Xenium_FFPE_Human_Breast_Cancer_Rep1/Xenium_FFPE_Human_Breast_Cancer_Rep1_outs.zip

To follow the steps for adding an image that has been aligned with a community-developed tool, download the supplemental aligned H&E image files from this public dataset: FFPE Human Breast with Custom Add-on Panel.

# Example curl commands to download file # Input Files curl -O https://cf.10xgenomics.com/samples/xenium/1.0.2/Xenium_V1_FFPE_Human_Breast_IDC_With_Addon/Xenium_V1_FFPE_Human_Breast_IDC_With_Addon_he_image.ome.tif # Output Files curl -O https://s3-us-west-2.amazonaws.com/10x.files/samples/xenium/1.0.2/Xenium_V1_FFPE_Human_Breast_IDC_With_Addon/Xenium_V1_FFPE_Human_Breast_IDC_With_Addon_outs.zip

In the Image menu, click on "Add image" and select the OME-TIFF image file by clicking "Import Image". Select the H&E image on your computer or shared network drive.

You should see a preview of the image. Verify the selected image is correct. You can reselect another image or edit the image name in the dialog box to change how it is displayed in the UI. Click "Continue" to view the image alignment options.

While not required, if the imported image is much larger than the Xenium DAPI image, you may want to use community-developed tools to crop it to approximately the same size and reimport it before aligning for an improved viewing experience (i.e., ImageJ/Fiji).

There are three image alignment options. The sections below describe and demonstrate when to use each option.

After adding the image, select "No, image is not aligned" to align the image in Xenium Explorer (see algorithm section).

The UI instructions will guide you through the image alignment process. For each step, you can reopen the specific instructions/guidance in the UI by clicking the blue ? at the top of the window.

Please wait for images to load, it may take a few seconds depending on image size.

Use the buttons to rotate or flip (vertically or horizontally) the H&E image to match the DAPI image orientation. Click "Continue to Keypoint Placement" to go to the next step.

Follow the guidance in the wizard for placing keypoints on landmarks on the DAPI and H&E images:

  • Zoom in to the edge of a nuclei on the Xenium DAPI image.
  • Place at least 6-8 keypoints on each image.
  • Space keypoints around the entire capture area.
  • Focus on edges and other visually distinctive areas.
  • Add more keypoints in specific regions of interest for a more precise alignment in those regions.
  • 25-30 keypoints may be required to achieve a satisfactory alignment depending on image quality and keypoint accuracy.

For each landmark, zoom in until you can see the nuclei edges in both images to place the keypoints. You can "Undo last" keypoint or "Clear all" keypoints using the arrow and trash can buttons for each image.

Once you are satisfied with the keypoint placements, click "Check Alignment".

Wait for the H&E image and red nuclei outlines to load. Check that the image is properly aligned by verifying that the red nuclei boundaries, based on the DAPI segmentation results, fit around the nuclei in the imported image.

Zoom in to check the nuclei alignment across the image area. Here are examples of poor vs. good alignment of the nuclei outlines:

Click "Back To Keypoints" to adjust as needed. If satisfied, click "Alignment Complete".

The aligned H&E image will be listed in the Image menu under the DAPI image. Use the sliders to adjust the opacity, brightness, and contrast of each image layer.

The options in the Cells and Transcripts menus, as well as selections, can now be used for the H&E image. The cell and nuclei outlines shown in the Cells menu will be based on the DAPI image segmentation results.

To remove an aligned image, click the three dots next to the image name in the Image menu and select "Remove image".

To share the image alignment with a colleague or view the alignment later, download the alignment CSV file (transformation matrix).

The file contains affine transformation values and is saved as <H&E image name>_imagealignment.csv. The image alignment file is a 3x3 transformation matrix, where the last row is [0,0,1]. It captures the translation, scaling, rotation, and reflection applied to the imported image (see algorithm section). This file can be used to align the post-Xenium image to the Xenium dataset in other instances of Xenium Explorer or community-developed tools.

Select an H&E image that has already been aligned for example in Xenium Explorer in a previous session or by a colleague. After verifying the preview image is correct, select "Yes, use an existing alignment file".

Click "Upload" and upload the alignment CSV file (see above for step to download this file from Xenium Explorer alignment).

Choose this option if you have an image that was aligned with community-developed software (e.g., H&E to Xenium DAPI Image Registration with Fiji Analysis Guide). Make sure the image format is OME-TIFF.

  1. Download the "Supplemental: Post-Xenium H&E image (TIFF)" file for either Tissue sample 1 or 2. They are already in OME-TIFF format.
  2. Add the image to Xenium Explorer.
  3. Select "Yes, skip alignment".
  1. Wait for the image to load and be added to the Image menu.

Once the image alignment is complete, you can come back to the file anytime or share the alignment with colleagues by sharing the image alignment CSV file.

  • The imported H&E image will be saved to your Recent Files and Saved Views by default.
  • To export the image alignment file, click the dots next to the H&E image name and click "Download Image Alignment File".

The manual alignment process finds the best similarity transform, in a least-squares sense, that aligns corresponding pairs of keypoints chosen from two images. That transform is then used for display purposes to overlay one image onto the other. This transform is able to account for differences in translation, scale, rotation, and reflection between two images. The algorithm used by Xenium Explorer is a version of the algorithm presented in (Horn, 1987), with minor changes to work in two dimensions instead of three.

Our use of this transform assumes that translation, scaling, rotation, and reflection (equally applied to both axes), can account for the differences between the two images. Data may not align perfectly where the tissue is different between the two images, for instance due to changes in tissue morphology after the Xenium run. As a least-squares solution, adding more (correct) keypoint pairs helps to minimize error due to keypoint placement and refine the overall solution.

  • Horn, B. Closed-form solution of absolute orientation using unit quaternions. J. Opt. Soc. Am. A. 4, 629-642: 1987. PDF available from the author’s website (search for "absolute orientation").