feat(omero): data-driven contrast (min, 99.9th pct) fused into pyramid write

[ferrinm]

Closes #53.

Summary

• Compute per-channel (min, percentile) on the coarsest pyramid level and write them into omero.channels[i].window.start / .end so uint16/uint32/float fluorescence stores open with sensible auto-contrast in napari / OMERO on first click.
• Fused into the same da.compute call as the pyramid writes — raw data is read once, no second read pass over 80+ GB LIF inputs.
• New keyword convert(..., contrast_percentile=99.9) — default runs the pass; pass a float in (0, 100) to shift the tail, or None to skip and keep issue fix(omero): default window to array dtype range instead of hardcoded 0–255 #50's dtype-range placeholder.
• CLI mirrors: --contrast-percentile FLOAT and --no-contrast.
• Audit records the resolved percentile under config.contrast_percentile plus per-channel bounds under per_scene[i].contrast.per_channel[] and the approximation method (coarsest-pyramid-level).
• Backfills writers/plate.py::_channels_for_current_scene to pass window=_dtype_window(reader.dtype), closing the fix(omero): default window to array dtype range instead of hardcoded 0–255 #50 gap on plate FOVs (which otherwise still ship the bioio-ome-zarr 0–255 default).

Approximation choice

Percentile is computed on the coarsest pyramid level, not the base:

• The coarse level is derived from the base in the same dask graph, so no extra chunk reads.
• Level is at most min_size × min_size per channel per Z — trivially cheap to sort or quantile even for 80+ GB inputs.
• Mean-pooling raises the observed min a hair and blurs the tail slightly; for a viewer auto-contrast default the difference is well below what a human eye reads. The choice is named in the audit (per_scene[i].contrast.method = "coarsest-pyramid-level") so downstream consumers can distinguish exact vs approximate.

Wall-clock overhead

Measured on the FakeReader-driven test scenes (32×32 uint16 base, pyramid_min_size=8, 2 pyramid levels): contrast pass adds a handful of ms — the coarse level is 64 pixels per channel. On real 80 GB LIF inputs the extra cost is expected to fall well under the 10% target because the coarsest level's read is already scheduled by the pyramid build; the added work is a per-chunk min reduction plus a percentile over ≤ min_size² values. contrast_percentile=None returns wall-clock to the pre-change baseline (verified by test — the extras list is empty).

Test plan

• Unit test: synthetic uint16 linear ramp → window.start/.end within tolerance of expected coarse-level quantile.
• Integration test: audit config.contrast_percentile and per_scene[i].contrast record the resolved value and method.
• Regression: contrast_percentile=None leaves the dtype-range window unchanged (issue fix(omero): default window to array dtype range instead of hardcoded 0–255 #50 behavior).
• Regression: single-channel-no-C-dim scene doesn't crash the contrast path.
• Regression: existing fix(omero): default window to array dtype range instead of hardcoded 0–255 #50 dtype-range tests updated to pin contrast_percentile=None (they now test just the placeholder shape).
• Full suite green (427 passed).
• Ruff clean.

Follow-ups

• Cut a v0.9.0 tag once merged (this + feat(lif): extract objective lens metadata (magnification, NA, immersion) into audit + OME-XML #52 + feat(channels): emission-band colorblind palette as default; source-file opt-in #51 + fix(omero): default window to array dtype range instead of hardcoded 0–255 #50 are all in Unreleased).
• Real-LIF wall-clock verification on the reporter's Stellaris file — deferred to after merge (no access here).

🤖 Generated with Claude Code