Instruments
===========

Overview
--------

This section documents the imaging instruments and their acquired data formats that are processed
by the image portal workflows. For each instrument, we provide technical background on how the
microscope operates, detailed descriptions of the image data it produces (data formats, dimensions,
coordinate systems, metadata), and processing considerations specific to that instrument.

This documentation currently covers spatial gene expression and microscopy instruments. As the
image portal evolves, additional microscope platforms will be added here, including their respective
data specifications and workflow integration details.


10x Genomics Xenium Analyzer
-----------------------------

The `Xenium Analyzer <https://www.10xgenomics.com/platforms/xenium>`_ is an in situ spatial
gene and protein expression imaging instrument from 10x Genomics. It performs cyclic fluorescence
imaging of tissue sections to decode RNA transcripts and, optionally, cell segmentation stain
markers at sub-cellular resolution. The instrument captures images across multiple Z-slices using
four spectral channels (Near UV, Blue, Green, Red).

Reference: `Understanding Xenium Outputs <https://www.10xgenomics.com/support/software/xenium-onboard-analysis/latest/analysis/xoa-output-understanding-outputs>`_

Morphology Images
-----------------

The Xenium Onboard Analysis (XOA) pipeline outputs two categories of tissue morphology image:

``morphology.ome.tif``
~~~~~~~~~~~~~~~~~~~~~~

A 3D Z-stack of the DAPI-stained tissue in OME-TIFF format. Produced from all DAPI imaging
cycles with a 3 µm Z-step size (sub-sampled from the raw 0.75 µm acquisition step). Used
primarily for nucleus segmentation and assessment of segmentation quality. Pixel size is
0.2125 µm in X and Y.

``morphology_focus/``
~~~~~~~~~~~~~~~~~~~~~

A set of 2D autofocus projection images, one per stain channel, stored as multi-file OME-TIFF.
These are the primary morphology images of interest for downstream image portal ingestion.

The focus images are generated by:

1. Selecting the best in-focus Z-slice per 16×16 pixel patch across all channels.
2. Building a global focus map from those per-patch selections.
3. Sampling seven Z-slices around the focus map and applying deconvolution, background
   subtraction, masking, and spectral crosstalk correction.
4. Stitching FOV tiles into a single 2D projection per channel.

Reference: `Image Processing Algorithms <https://www.10xgenomics.com/support/software/xenium-onboard-analysis/latest/algorithms-overview/image-processing>`_

Image properties:

* Format: multi-file OME-TIFF with full-resolution and downsampled pyramid levels
* Bit depth: 16-bit unsigned integer (``uint16``)
* Physical pixel size: 0.2125 µm × 0.2125 µm
* Coordinate origin: top-left corner (image coordinate system, same as transcript X/Y locations)
* Dimension order: XYZCT (SizeZ=1, SizeT=1 per focus file)

Assay variants and channel layout
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The number of channels in ``morphology_focus/`` depends on the assay workflow used.

**RNA-only (DAPI only)**

A single channel is produced — the DAPI nuclear stain acquired at cycle 1.

.. code-block:: text

   morphology_focus/
   └── ch0000_dapi.ome.tif   (DAPI, Near UV, Nuclear)

Example OME-XML metadata (single-channel)::

   <Pixels SizeC="1" SizeX="28435" SizeY="91698" SizeZ="1" Type="uint16"
           PhysicalSizeX="0.2125" PhysicalSizeXUnit="µm" ...>
       <Channel ID="Channel:0:0" Name="DAPI" .../>
   </Pixels>

Channel annotation keys present in ``StructuredAnnotations``:

.. list-table::
   :header-rows: 1
   :widths: 25 75

   * - Key
     - Description
   * - Cycle
     - Imaging cycle index (0 for RNA-only DAPI)
   * - Channel
     - Spectral channel name (Near UV / Blue / Green / Red)
   * - Long name
     - Human-readable stain name
   * - Purpose
     - Biological role (Nuclear / Boundary / Interior - RNA / Interior - Protein)
   * - Observed min/max
     - Pixel intensity range observed in the image
   * - Suggested LUT min/max
     - Recommended display lookup table range

**Multimodal cell segmentation (DAPI + 3 stains)**

Four channels are produced when the Multi-Tissue Stain Mix Cell Segmentation Staining workflow
is used. Each channel maps to a distinct biological purpose used for multimodal cell
segmentation.

.. code-block:: text

   morphology_focus/
   ├── ch0000_dapi.ome.tif                        (DAPI,               Near UV, Nuclear)
   ├── ch0001_atp1a1_e-cadherin_cd45.ome.tif      (ATP1A1/CD45/E-Cad,  Red,     Boundary)
   ├── ch0002_18s.ome.tif                         (18S rRNA,           Green,   Interior - RNA)
   └── ch0003_alphasma_vimentin.ome.tif           (alphaSMA/Vimentin,  Blue,    Interior - Protein)

Example OME-XML metadata (multi-channel)::

   <Pixels SizeC="4" SizeX="39848" SizeY="74707" SizeZ="1" Type="uint16"
           PhysicalSizeX="0.2125" PhysicalSizeXUnit="µm" ...>
       <Channel ID="Channel:0:0" Name="DAPI" .../>
       <Channel ID="Channel:0:1" Name="ATP1A1/CD45/E-Cadherin" .../>
       <Channel ID="Channel:0:2" Name="18S" .../>
       <Channel ID="Channel:0:3" Name="alphaSMA/Vimentin" .../>
   </Pixels>

The per-channel ``StructuredAnnotations`` include a ``Pixel value offset`` key (in addition to
the keys listed above) used to correct for any applied pixel value shift during processing.