> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strandai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mirax ingest

# MIRAX ingest

## Upload contract

A MIRAX slide is a `.mrxs` header plus its same-stem companion directory:

```text theme={"dark"}
slide.mrxs
slide/
  Slidedat.ini
  Index.dat
  Data0000.dat
  ...
```

Upload **one slide per ZIP**, either `slide.mrxs.zip` or `slide.zip`. A common enclosing directory is accepted. Archives containing multiple slides, unrelated files outside the companion directory, unsafe paths, duplicate/case-colliding paths, links, encrypted entries, or incomplete companions are rejected. Finder resource forks and `.DS_Store` entries are path/bounds-validated and discarded without extraction. MIRAX INI index/data references must resolve to the extracted companion files, never arbitrary local paths.

The Python SDK's `client.uploads.upload_file(Path("slide.mrxs"))` creates a deterministic, streaming ZIP64 temporary archive automatically. Missing companions and symlinks produce specific errors; the temporary archive is cleaned up after success or failure. The browser accepts prepared ZIPs and explains why a bare header is insufficient; it does not zip dropped folders.

## Canonical source

Every MIRAX archive requires normalization through quarantine, including organizations with automatic de-identification disabled. Only the validated output becomes the sample's permanent source.

The Python normalizer:

* Bounds archive entries (10,000), decompressed bytes, decoded pixels (100 billion across levels), and total scratch use.
* Reads each native OpenSlide tissue level in bounded 512×512 tiles.
* Writes a lossless DEFLATE-compressed, RGB, tiled pyramidal BigTIFF with the exact native level dimensions.
* Copies no original metadata, associated images, label/macro pixels, INI bytes, or ICC profile.
* Generates only a minimal Aperio `MPP` header and standard per-level X/Y resolution tags in centimeters. OpenSlide exposes native `openslide.mpp-x` and `openslide.mpp-y`; existing dimensions, preprocessing, inference and segmentation readers need no MIRAX-specific changes.
* Requires finite, positive, isotropic native MPP (up to 100 µm/px). Anisotropic sources fail closed because the existing product and Aperio MPP representation are isotropic.
* Reopens the output independently with OpenSlide, checks dimensions/MPP/absence of associated images, exercises reads at three positions per level, and compares independently decoded TIFF tile patches exactly against source tissue pixels.

TIFF readers infer downsample factors from the integer pyramid dimensions, so lower-level factors can differ slightly from MIRAX's exact powers of two at rounded edges. Dimensions and level-0 calibration are preserved. Pixel-equality validation uses decoded TIFF tile coordinates, not interpolated `read_region` locations.

The permanent object is a single `.tiff` with `image/tiff` content type. Sample `gcsPath`, filename, byte size, permanent generation and SHA-256 identify this canonical object, not the archive. The original archive hash is retained separately for repeat SDK upload deduplication. Quarantine deletion remains after successful validation, permanent upload and DB repoint. This removes format-defined metadata/associated-image surfaces; it does not inspect or remove identifiers burned into tissue pixels or filenames.

## Scratch and deployment

The deid Cloud Run Job requires the accompanying Terraform configuration: **8 vCPU, 32 GiB RAM, 28 GiB RAM-backed `/tmp`**. No separate GPU or inference changes are needed. This PR does not deploy or apply infrastructure.

The downloaded archive is removed after successful extraction, before transcoding. Extracted companions are removed after output validation, before upload. Quarantine retains the immutable original generation if conversion fails. The normalizer rejects extraction or output growth beyond its 28 GiB scratch budget rather than relying on the container OOM killer. The remaining 4 GiB is reserved for Node, native decoders and bounded tile buffers. Sources beyond these limits need a larger disk-backed normalization runner; increasing ZIP limits alone is unsafe.

## Local verification

Synthetic security, metadata and lossless-transcode tests:

```sh theme={"dark"}
python -m unittest discover -s platform/src/jobs/__tests__ -p 'test_mirax*.py' -v
python -m unittest discover -s platform/src/jobs/__tests__ -p test_wsi_deid.py -v
```

Opt-in real archive → deid → unchanged production lazy-tiler integration:

```sh theme={"dark"}
MIRAX_REAL_SLIDE=/authorized/scratch/slide.mrxs \
  python -m unittest discover -s platform/src/jobs/__tests__ -p test_mirax_real.py -v
```

This test uses the source's sibling directory, writes temporary data beside it, requires no GCS/database/GPU, supplies **no MPP override**, and checks that preprocessing decodes 224×224 model patches at the correct native scale. Do not commit source slides or record them in UI proof.

### Real-fixture results

All four authorized Human Brain Cancer MIRAX fixtures were downloaded with complete companions and opened with OpenSlide. Every fixture has dimensions **125112×297800**, **nine native levels**, and **0.1725 µm/px on both axes**. All four full-resolution lossless BigTIFF conversions passed independent dimension, calibration, tissue-pixel and associated-image checks.

| Blinded fixture | Canonical bytes | Retained model-grid positions | Canonical SHA-256 prefix |
| - | -: | -: | - |
| A | 7,205,996,135 | 21,622 | `5b2540e9f429` |
| B | 11,947,848,176 | 35,970 | `325f7d1988cf` |
| C | 8,337,286,978 | 25,433 | `61fb60b4e413` |
| D | 18,598,496,881 | 62,267 | `66e7f472a74f` |

For each canonical file, the unchanged `read-wsi-dimensions.py` returned the exact native dimensions/MPP. The unchanged `preprocess.tile_wsi_lazy` selected level 1 and decoded a `[4, 3, 224, 224]` patch batch without an MPP override. These CPU-only local checks used `bg_mode="rgb_legacy"`, not the model-backed tissue mask. Fixture A also passed the complete ZIP → sidecar de-identification → lazy-preprocessing integration test; its independently repeated conversion produced the same canonical SHA-256.

No real slide pixels, source metadata, or specimen names are committed or included in UI evidence. GCS promotion/dispatch is covered by PGlite/orchestrator integration tests, not a deployed cloud run.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.