Enhancement: carry MPP/magnification through convert --to dzi (needs opentile-go read-back)

[cornish]

Summary (enhancement)

convert --to dzi loses the source MPP and magnification:

source:      mpp=0.499  magnification=20
dzi output:  mpp=0      magnification=0

The DZI writer emits no MPP/mag, and standard Deep Zoom XML
(<Image><Size Width Height/></Image>) has no slot for them — so this is a
format limitation, not a defect. Filing as an enhancement to carry scale
metadata through a DZI conversion (e.g. a custom <Image> attribute or a
metadata sidecar written alongside the .dzi).

IMPORTANT prerequisite

Any such enhancement is only useful if opentile-go's DZI reader reads the
metadata back — otherwise info on the output still shows mpp=0/mag=0 and the
round-trip gains nothing. So before (or alongside) adding the write side:

• Confirm opentile-go can read MPP/magnification from a DZI (custom attribute
  or sidecar). If it can't, this needs a coordinated opentile-go read-side change
  (file an opentile-go issue; read-side is implemented upstream) that agrees on
  the exact attribute/sidecar name and format with the wsitools writer.

Found by

The automated CLI matrix audit (scripts/qa/audit.sh, cross-container scale-metadata check).

[cornish]

Design decision (deferred — considering later)

Explored where to carry the WSI metadata in a DZI output. Conclusion: use a scan-properties.xml sidecar next to the .dzi, not attributes in the .dzi manifest.

Why not in the .dzi itself: the .dzi is a standard Microsoft Deep Zoom manifest with a strict schema (<Image Format Overlap TileSize xmlns><Size Width Height/></Image> — the spec even reproduces its XSD). Adding MicronsPerPixel/ObjectiveMagnification there makes it non-conformant DZI (a validating parser could reject it; interop is the whole reason to emit standard DZI), needs namespace gymnastics, and gains nothing on the read side. The SZI designers hit exactly this and deliberately kept the .dzi standard, putting metadata in a separate scan-properties.xml. A DZI-on-disk is basically an unzipped SZI, so the same sidecar fits naturally.

Write side is ready: internal/szi.WriteScanProperties(w, md, imgW, imgH) already emits the full spec-mandatory field set (ImageWidth/Height/MicronsPerPixel{,X,Y}) plus the identity/mag/serial/time optionals (added in the #26 follow-up). The convert --to dzi driver (cmd/wsitools/convert_dzi.go) can call it to write scan-properties.xml alongside the .dzi.

The real blocker (why deferred): opentile-go's DZI reader currently reads neither a sidecar nor manifest metadata for a bare DZI (formats/dzi/tiler.go:24: "There is no scan-properties.xml and no associated_images/ in a bare [DZI]"). So wherever we put the fields, info on a DZI still shows mpp=0 until opentile's DZI reader is extended. Writing it now would be write-only (easy to forget), so hold.

When we pick this up: one coordinated change — teach opentile-go's DZI reader to read a scan-properties.xml sidecar (it can reuse its existing SZI scan-properties.xml parser, which already maps VendorName/ObjectiveMagnification/MicronsPerPixel* etc.), then wire the wsitools writer side. Read-side lands upstream in opentile-go.