cellxgene/README-visium.md

Cellxgene Visium Beta

How it works

1. Launch cellxgene as normal.
2. If the loaded dataset has spatial information available, the image data will be loaded on startup.
3. On the toolbar, next to the Zoom icon, a Toggle image button will now appear. Click on it and the image will be added as an underlay.
4. You can now use any cellxgene functionality and the image will still be present. If you pan and zoom, the image will also be panned and zoomed.
5. If you want to hide the image, you can click on Toggle image again

In order for the image to be displayed with the correct size and alignment, the H5AD needs to have a few requirements. See the following section to learn more.

h5ad requirements

1. The spatial embedding layer should be contained in obsm and be named X_spatial. Other layers can exist, but only this one will have the spatial feature enabled.
2. A spatial dict needs to be defined in the uns dictionary.
3. Inside the spatial dict, an images dict must be defined.
4. The images dict must contain a hires key, which should reference an image encoded as an RGB matrix (i.e., a three-dimensional matrix of size height x width x 3 where the final dimension has the RGB values for each pixel)
5. The images dict must contain a scalefactors dict. This should in turn contain a tissue_hires_scalef key, which should reference a floating point number.

Moreover, in order to have the image correctly aligned with the dots, the following must be true:

1. tissue_hires_scalef should represent the ratio between the embedding layer X_spatial and the image matrix. In particular, if you multiply X_spatial by tissue_hires_scalef, you should obtain an array of points that ovelap the tissue image if you plot them in a plane.