ioimage 0.1.2__py3-none-any.whl

ioimage/__init__.py

@@ -0,0 +1,43 @@
+"""ioimage: read and write microscopy images (TIFF, OME-TIFF, OME-Zarr) with one API.
+
+Lazy region reads, pyramids, sharding, and a format-independent metadata model that keeps the
+original metadata blocks verbatim (see `docs/design.md`).
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version(__name__)
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0.0.0+unknown"
+
+from .errors import FormatError, MetadataDropped
+from .image import (
+    Image,
+    convert,
+    create_memmap,
+    open,  # noqa: A004 - `ioimage.open` mirrors the builtin on purpose
+    read,
+    write,
+)
+from .metadata import Acquisition, Channel, ImageMetadata, MetadataError, Objective, RawBlocks
+
+__all__ = (
+    "Acquisition",
+    "Channel",
+    "FormatError",
+    "Image",
+    "ImageMetadata",
+    "MetadataDropped",
+    "MetadataError",
+    "Objective",
+    "RawBlocks",
+    "__version__",
+    "convert",
+    "create_memmap",
+    "open",
+    "read",
+    "write",
+)

ioimage/_omexml.py

@@ -0,0 +1,504 @@
+"""OME-XML: parse the subset ioimage models and generate OME-XML for OME-TIFF and OME-Zarr.
+
+Only the standard library is used (`xml.etree.ElementTree`). The original OME-XML of a source
+file is always kept verbatim in `ImageMetadata.raw.ome_xml`; this module extracts structured
+fields from it and writes new OME-XML (schema 2016-06) whose element order follows the schema:
+Instrument before Image, then StructuredAnnotations; inside Image: AcquisitionDate, Description,
+InstrumentRef, ObjectiveSettings, Pixels (Channel*, TiffData*, Plane*), AnnotationRef*.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+import xml.etree.ElementTree as ET
+from typing import Any
+
+import numpy as np
+
+from .metadata import (
+    OME_UNITS,
+    Acquisition,
+    Channel,
+    ImageMetadata,
+    Objective,
+    normalize_length_unit,
+    normalize_time_unit,
+)
+
+OME_NS = "http://www.openmicroscopy.org/Schemas/OME/2016-06"
+XSI_NS = "http://www.w3.org/2001/XMLSchema-instance"
+SCHEMA_LOCATION = f"{OME_NS} {OME_NS}/ome.xsd"
+IOIMAGE_NAMESPACE = "ioimage"
+
+_IMMERSIONS = {"oil", "water", "waterdipping", "air", "multi", "glycerol", "other"}
+_IMMERSION_SPELLING = {
+    "oil": "Oil",
+    "water": "Water",
+    "waterdipping": "WaterDipping",
+    "air": "Air",
+    "multi": "Multi",
+    "glycerol": "Glycerol",
+    "other": "Other",
+}
+
+_OME_PIXEL_TYPES: dict[str, str] = {
+    "int8": "int8",
+    "int16": "int16",
+    "int32": "int32",
+    "uint8": "uint8",
+    "uint16": "uint16",
+    "uint32": "uint32",
+    "float32": "float",
+    "float64": "double",
+    "complex64": "complex",
+    "complex128": "double-complex",
+    "bool": "bit",
+}
+_NUMPY_FROM_OME: dict[str, str] = {v: k for k, v in _OME_PIXEL_TYPES.items()}
+
+
+def _q(tag: str) -> str:
+    return f"{{{OME_NS}}}{tag}"
+
+
+def _strip_ns(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _float(value: str | None) -> float | None:
+    if value is None or value == "":
+        return None
+    try:
+        return float(value)
+    except ValueError:
+        return None
+
+
+def ome_color_to_hex(value: str | None) -> str | None:
+    """OME `Color` (signed 32-bit RGBA integer) -> 'RRGGBBAA'."""
+    if value is None:
+        return None
+    try:
+        i = int(value)
+    except ValueError:
+        return None
+    return f"{i & 0xFFFFFFFF:08X}"
+
+
+def hex_to_ome_color(color: str) -> int:
+    """'RRGGBBAA' -> OME signed 32-bit integer."""
+    u = int(color, 16)
+    return u - (1 << 32) if u >= 1 << 31 else u
+
+
+# -- parsing -----------------------------------------------------------------------------------
+
+
+def parse_ome_xml(xml: str, series: int = 0) -> dict[str, Any]:
+    """Extract the fields of the `series`-th Image of an OME-XML document.
+
+    Returns a dict with keys usable as `ImageMetadata` fields (`spacing`, `spacing_unit`, `origin`,
+    `time_interval`, `time_unit`, `timestamps`, `channels`, `objective`, `acquisition`,
+    `significant_bits`, `name`) plus `dimension_order`, `sizes` (dict letter -> int), `dtype`,
+    `n_images`, and `annotations` (dict of ioimage MapAnnotations, keyed without the prefix).
+    """
+    root = ET.fromstring(xml)  # noqa: S314 - local files written by microscopes and by ioimage; defusedxml would be a new dependency
+    images = [el for el in root if _strip_ns(el.tag) == "Image"]
+    if not images:
+        raise ValueError("OME-XML without an Image element")
+    if series >= len(images):
+        raise ValueError(f"OME-XML has {len(images)} Image elements, series {series} requested")
+    image = images[series]
+    out: dict[str, Any] = {"n_images": len(images), "name": image.get("Name")}
+
+    pixels = next((el for el in image if _strip_ns(el.tag) == "Pixels"), None)
+    if pixels is None:
+        raise ValueError("OME-XML Image without Pixels")
+    out["dimension_order"] = pixels.get("DimensionOrder", "XYZCT")
+    out["sizes"] = {a: int(pixels.get(f"Size{a}", 1)) for a in "XYZCT"}
+    out["dtype"] = _NUMPY_FROM_OME.get(pixels.get("Type", ""))
+    bits = pixels.get("SignificantBits")
+    out["significant_bits"] = int(bits) if bits else None
+
+    # spacing on the space axes present (z, y, x order), all or nothing
+    phys = {a: _float(pixels.get(f"PhysicalSize{a}")) for a in "XYZ"}
+    units = {a: pixels.get(f"PhysicalSize{a}Unit", "µm") for a in "XYZ"}
+    has_z = out["sizes"]["Z"] > 1
+    needed = "ZYX" if has_z else "YX"
+    if all(phys[a] is not None for a in needed):
+        unit0 = normalize_length_unit(units[needed[0]])
+        spacing = []
+        for a in needed:
+            u = normalize_length_unit(units[a])
+            v = phys[a]
+            if v is None:  # pragma: no cover - excluded by the `all(...)` test above
+                continue
+            if u != unit0:
+                v = _convert_length(v, u, unit0)
+            spacing.append(v)
+        out["spacing"] = tuple(spacing)
+        out["spacing_unit"] = unit0
+    else:
+        out["spacing"] = None
+        out["spacing_unit"] = None
+
+    ti = _float(pixels.get("TimeIncrement"))
+    out["time_interval"] = ti
+    out["time_unit"] = normalize_time_unit(pixels.get("TimeIncrementUnit", "s")) if ti is not None else None
+
+    channels: list[Channel] = []
+    for ch in (el for el in pixels if _strip_ns(el.tag) == "Channel"):
+        ex, em = _float(ch.get("ExcitationWavelength")), _float(ch.get("EmissionWavelength"))
+        wunit = ch.get("EmissionWavelengthUnit") or ch.get("ExcitationWavelengthUnit") or ("nm" if ex or em else None)
+        channels.append(
+            Channel(
+                name=ch.get("Name"),
+                color=ome_color_to_hex(ch.get("Color")),
+                excitation_wavelength=ex,
+                emission_wavelength=em,
+                wavelength_unit=normalize_length_unit(wunit) if wunit else None,
+                fluorophore=ch.get("Fluor"),
+            )
+        )
+    out["channels"] = tuple(channels)
+
+    # planes: origin from the first plane's position, timestamps from DeltaT of the first (z, c) per t
+    planes = [el for el in pixels if _strip_ns(el.tag) == "Plane"]
+    origin = None
+    timestamps: dict[int, float] = {}
+    exposure = None
+    exposure_unit = None
+    delta_unit = None
+    for pl in planes:
+        if origin is None:
+            pos = [_float(pl.get(f"Position{a}")) for a in ("Z", "Y", "X")]
+            if has_z and all(p is not None for p in pos):
+                punit = normalize_length_unit(pl.get("PositionXUnit", "µm"))
+                origin = (tuple(float(p) for p in pos if p is not None), punit)
+            elif not has_z and all(p is not None for p in pos[1:]):
+                punit = normalize_length_unit(pl.get("PositionXUnit", "µm"))
+                origin = (tuple(float(p) for p in pos[1:] if p is not None), punit)
+        t = int(pl.get("TheT", 0))
+        dt = _float(pl.get("DeltaT"))
+        if dt is not None and t not in timestamps and int(pl.get("TheZ", 0)) == 0 and int(pl.get("TheC", 0)) == 0:
+            timestamps[t] = dt
+            delta_unit = pl.get("DeltaTUnit", "s")
+        if exposure is None and pl.get("ExposureTime") is not None:
+            exposure = _float(pl.get("ExposureTime"))
+            exposure_unit = pl.get("ExposureTimeUnit", "s")
+    if origin is not None and out["spacing"] is not None:
+        values, punit = origin
+        if punit != out["spacing_unit"]:
+            values = tuple(_convert_length(v, punit, out["spacing_unit"]) for v in values)
+        out["origin"] = values
+    else:
+        out["origin"] = None
+    if timestamps and len(timestamps) == out["sizes"]["T"]:
+        out["timestamps"] = tuple(timestamps[t] for t in range(out["sizes"]["T"]))
+        if out["time_unit"] is None:
+            out["time_unit"] = normalize_time_unit(delta_unit or "s")
+    else:
+        out["timestamps"] = None
+
+    # instrument / objective
+    objective = None
+    acquisition_fields: dict[str, Any] = {}
+    settings: list[tuple[str, str]] = []
+    obj_settings = next((el for el in image if _strip_ns(el.tag) == "ObjectiveSettings"), None)
+    instrument_ref = next((el for el in image if _strip_ns(el.tag) == "InstrumentRef"), None)
+    instruments = [el for el in root if _strip_ns(el.tag) == "Instrument"]
+    instrument = None
+    if instrument_ref is not None:
+        instrument = next((i for i in instruments if i.get("ID") == instrument_ref.get("ID")), None)
+    if instrument is None and len(instruments) == 1:
+        instrument = instruments[0]
+    if instrument is not None:
+        micro = next((el for el in instrument if _strip_ns(el.tag) == "Microscope"), None)
+        if micro is not None:
+            parts = [micro.get("Manufacturer"), micro.get("Model")]
+            acquisition_fields["instrument"] = " ".join(p for p in parts if p) or None
+            if micro.get("Type"):
+                settings.append(("Microscope.Type", str(micro.get("Type"))))
+        det = next((el for el in instrument if _strip_ns(el.tag) == "Detector"), None)
+        if det is not None:
+            parts = [det.get("Manufacturer"), det.get("Model")]
+            acquisition_fields["detector"] = " ".join(p for p in parts if p) or None
+        objectives = [el for el in instrument if _strip_ns(el.tag) == "Objective"]
+        obj_el = None
+        if obj_settings is not None:
+            obj_el = next((o for o in objectives if o.get("ID") == obj_settings.get("ID")), None)
+        if obj_el is None and len(objectives) == 1:
+            obj_el = objectives[0]
+        if obj_el is not None:
+            wd = _float(obj_el.get("WorkingDistance"))
+            objective = Objective(
+                magnification=_float(obj_el.get("NominalMagnification")),
+                numerical_aperture=_float(obj_el.get("LensNA")),
+                immersion=obj_el.get("Immersion"),
+                refractive_index=_float(obj_settings.get("RefractiveIndex")) if obj_settings is not None else None,
+                working_distance=wd,
+                working_distance_unit=normalize_length_unit(obj_el.get("WorkingDistanceUnit", "µm")) if wd else None,
+                model=obj_el.get("Model"),
+                manufacturer=obj_el.get("Manufacturer"),
+            )
+    elif obj_settings is not None and obj_settings.get("RefractiveIndex"):
+        objective = Objective(refractive_index=_float(obj_settings.get("RefractiveIndex")))
+    out["objective"] = objective
+    date = next((el.text for el in image if _strip_ns(el.tag) == "AcquisitionDate"), None)
+    acquisition_fields["date"] = date
+    acquisition_fields["exposure_time"] = exposure
+    acquisition_fields["exposure_time_unit"] = normalize_time_unit(exposure_unit) if exposure is not None else None
+
+    # structured annotations written by ioimage (and the software name when present)
+    annotations: dict[str, Any] = {}
+    sa = next((el for el in root if _strip_ns(el.tag) == "StructuredAnnotations"), None)
+    if sa is not None:
+        for ann in sa:
+            if _strip_ns(ann.tag) != "MapAnnotation":
+                continue
+            if ann.get("Namespace") != IOIMAGE_NAMESPACE:
+                continue
+            key = (ann.get("ID") or "").rsplit(":", 1)[-1]
+            value_el = next((el for el in ann if _strip_ns(el.tag) == "Value"), None)
+            if value_el is None:
+                continue
+            pairs = {m.get("K"): (m.text or "") for m in value_el if _strip_ns(m.tag) == "M"}
+            if "json" in pairs:
+                try:
+                    annotations[key] = json.loads(pairs["json"])
+                except json.JSONDecodeError:
+                    annotations[key] = pairs["json"]
+            elif "text" in pairs:
+                annotations[key] = pairs["text"]
+            else:
+                annotations[key] = pairs
+    out["annotations"] = annotations
+    if "acquisition_settings" in annotations and isinstance(annotations["acquisition_settings"], dict):
+        acq = annotations["acquisition_settings"]
+        acquisition_fields.setdefault("software", acq.get("software"))
+        if acq.get("instrument") and not acquisition_fields.get("instrument"):
+            acquisition_fields["instrument"] = acq["instrument"]
+        if acq.get("detector") and not acquisition_fields.get("detector"):
+            acquisition_fields["detector"] = acq["detector"]
+        settings.extend((str(k), str(v)) for k, v in (acq.get("settings") or []))
+    acquisition = Acquisition(settings=tuple(settings), **acquisition_fields)
+    out["acquisition"] = None if acquisition.is_empty() else acquisition
+    return out
+
+
+_LENGTH_IN_METERS: dict[str, float] = {
+    "angstrom": 1e-10,
+    "nanometer": 1e-9,
+    "micrometer": 1e-6,
+    "millimeter": 1e-3,
+    "centimeter": 1e-2,
+    "meter": 1.0,
+    "inch": 0.0254,
+}
+
+
+def _convert_length(value: float, unit_from: str | None, unit_to: str | None) -> float:
+    if unit_from == unit_to or unit_from is None or unit_to is None:
+        return value
+    if unit_from not in _LENGTH_IN_METERS or unit_to not in _LENGTH_IN_METERS:
+        raise ValueError(f"cannot convert {unit_from} to {unit_to}")
+    return value * _LENGTH_IN_METERS[unit_from] / _LENGTH_IN_METERS[unit_to]
+
+
+# -- generation --------------------------------------------------------------------------------
+
+
+def build_ome_xml(
+    meta: ImageMetadata,
+    *,
+    file_name: str | None = None,
+    tiff_data: bool = True,
+    extra_annotations: dict[str, Any] | None = None,
+) -> tuple[str, list[str]]:
+    """Generate OME-XML for `meta`.
+
+    Returns the XML string and the list of structured fields that OME-XML could not hold
+    (currently none; raw blocks and the frame keys go to `MapAnnotation`s in the `ioimage` namespace).
+    With `tiff_data=True` a single `<TiffData IFD="0" PlaneCount="n"/>` describes an OME-TIFF whose
+    pages are ordered t, c, z (DimensionOrder XYZCT); with False, `<MetadataOnly/>` is written (OME-Zarr).
+    """
+    dropped: list[str] = []
+    ET.register_namespace("", OME_NS)
+    ET.register_namespace("xsi", XSI_NS)
+    root = ET.Element(_q("OME"), {f"{{{XSI_NS}}}schemaLocation": SCHEMA_LOCATION, "UUID": f"urn:uuid:{uuid.uuid4()}"})
+
+    sizes = dict.fromkeys("XYZCT", 1)
+    for a, n in zip(meta.axes, meta.shape, strict=True):
+        sizes[a.upper()] = n
+
+    # Instrument (before Image)
+    instrument_id = None
+    objective_id = None
+    if meta.objective is not None or (
+        meta.acquisition is not None and (meta.acquisition.instrument or meta.acquisition.detector)
+    ):
+        instrument_id = "Instrument:0"
+        inst = ET.SubElement(root, _q("Instrument"), {"ID": instrument_id})
+        if meta.acquisition is not None and meta.acquisition.instrument:
+            ET.SubElement(inst, _q("Microscope"), {"Model": meta.acquisition.instrument})
+        if meta.acquisition is not None and meta.acquisition.detector:
+            ET.SubElement(inst, _q("Detector"), {"ID": "Detector:0", "Model": meta.acquisition.detector})
+        if meta.objective is not None:
+            objective_id = "Objective:0"
+            attrs: dict[str, str] = {"ID": objective_id}
+            o = meta.objective
+            if o.manufacturer:
+                attrs["Manufacturer"] = o.manufacturer
+            if o.model:
+                attrs["Model"] = o.model
+            if o.numerical_aperture is not None:
+                attrs["LensNA"] = repr(float(o.numerical_aperture))
+            if o.magnification is not None:
+                attrs["NominalMagnification"] = repr(float(o.magnification))
+            if o.immersion:
+                key = o.immersion.replace(" ", "").replace("-", "").lower()
+                attrs["Immersion"] = _IMMERSION_SPELLING.get(key, "Other")
+            if o.working_distance is not None:
+                attrs["WorkingDistance"] = repr(float(o.working_distance))
+                attrs["WorkingDistanceUnit"] = OME_UNITS.get(o.working_distance_unit or "micrometer", "µm")
+            ET.SubElement(inst, _q("Objective"), attrs)
+
+    image = ET.SubElement(root, _q("Image"), {"ID": "Image:0", "Name": meta.name or (file_name or "image")})
+    if meta.acquisition is not None and meta.acquisition.date:
+        ET.SubElement(image, _q("AcquisitionDate")).text = meta.acquisition.date
+    if instrument_id is not None:
+        ET.SubElement(image, _q("InstrumentRef"), {"ID": instrument_id})
+    if meta.objective is not None:
+        os_attrs = {"ID": objective_id or "Objective:0"}
+        if meta.objective.refractive_index is not None:
+            os_attrs["RefractiveIndex"] = repr(float(meta.objective.refractive_index))
+        ET.SubElement(image, _q("ObjectiveSettings"), os_attrs)
+
+    pixels_attrs: dict[str, str] = {
+        "ID": "Pixels:0",
+        "DimensionOrder": "XYZCT",
+        "Type": _OME_PIXEL_TYPES[np.dtype(meta.dtype).name],
+        "BigEndian": "false",
+        "Interleaved": "false",
+    }
+    for a in "XYZCT":
+        pixels_attrs[f"Size{a}"] = str(sizes[a])
+    if meta.significant_bits is not None:
+        pixels_attrs["SignificantBits"] = str(meta.significant_bits)
+    if meta.spacing is not None:
+        unit = OME_UNITS[meta.spacing_unit or "micrometer"]
+        for a in meta.space_axes:
+            s = meta.spacing_of(a)
+            if s is None:  # pragma: no cover - spacing is complete or None
+                continue
+            pixels_attrs[f"PhysicalSize{a.upper()}"] = repr(float(s))
+            pixels_attrs[f"PhysicalSize{a.upper()}Unit"] = unit
+    if meta.time_interval is not None:
+        pixels_attrs["TimeIncrement"] = repr(float(meta.time_interval))
+        pixels_attrs["TimeIncrementUnit"] = OME_UNITS[meta.time_unit or "second"]
+    pixels = ET.SubElement(image, _q("Pixels"), pixels_attrs)
+
+    n_c = sizes["C"]
+    channels = meta.channels or tuple(Channel() for _ in range(n_c))
+    for i, ch in enumerate(channels):
+        ch_attrs: dict[str, str] = {"ID": f"Channel:0:{i}", "SamplesPerPixel": "1"}
+        if ch.name:
+            ch_attrs["Name"] = ch.name
+        if ch.color:
+            ch_attrs["Color"] = str(hex_to_ome_color(ch.color))
+        if ch.fluorophore:
+            ch_attrs["Fluor"] = ch.fluorophore
+        wunit = OME_UNITS.get(ch.wavelength_unit or "nanometer", "nm")
+        if ch.excitation_wavelength is not None:
+            ch_attrs["ExcitationWavelength"] = repr(float(ch.excitation_wavelength))
+            ch_attrs["ExcitationWavelengthUnit"] = wunit
+        if ch.emission_wavelength is not None:
+            ch_attrs["EmissionWavelength"] = repr(float(ch.emission_wavelength))
+            ch_attrs["EmissionWavelengthUnit"] = wunit
+        ET.SubElement(pixels, _q("Channel"), ch_attrs)
+
+    n_planes = sizes["Z"] * sizes["C"] * sizes["T"]
+    if tiff_data:
+        ET.SubElement(pixels, _q("TiffData"), {"IFD": "0", "PlaneCount": str(n_planes)})
+    else:
+        ET.SubElement(pixels, _q("MetadataOnly"))
+
+    want_planes = (
+        meta.origin is not None
+        or meta.timestamps is not None
+        or (meta.acquisition is not None and meta.acquisition.exposure_time is not None)
+    )
+    if want_planes:
+        if n_planes > 65536:
+            dropped.append("origin/timestamps (too many planes for OME Plane elements)")
+        else:
+            unit = OME_UNITS[meta.spacing_unit or "micrometer"]
+            tunit = OME_UNITS[meta.time_unit or "second"]
+            for t in range(sizes["T"]):
+                for c in range(sizes["C"]):
+                    for z in range(sizes["Z"]):
+                        pl: dict[str, str] = {"TheZ": str(z), "TheC": str(c), "TheT": str(t)}
+                        if meta.origin is not None:
+                            for a, o in zip(meta.space_axes, meta.origin, strict=True):
+                                pl[f"Position{a.upper()}"] = repr(float(o))
+                                pl[f"Position{a.upper()}Unit"] = unit
+                        if meta.timestamps is not None:
+                            pl["DeltaT"] = repr(float(meta.timestamps[t]))
+                            pl["DeltaTUnit"] = tunit
+                        if meta.acquisition is not None and meta.acquisition.exposure_time is not None:
+                            pl["ExposureTime"] = repr(float(meta.acquisition.exposure_time))
+                            pl["ExposureTimeUnit"] = OME_UNITS[meta.acquisition.exposure_time_unit or "second"]
+                        ET.SubElement(pixels, _q("Plane"), pl)
+
+    # ioimage annotations: frame keys, raw blocks, dropped fields, provenance, acquisition extras
+    annotations: dict[str, Any] = {}
+    frame = {
+        "coordinate_frame": meta.coordinate_frame,
+        "axis_order": meta.space_axes,
+        "axes": meta.axes,
+        "source_shape": meta.source_shape,
+        "crop_offset": meta.crop_offset,
+    }
+    annotations["frame"] = frame
+    if meta.acquisition is not None and (meta.acquisition.software or meta.acquisition.settings):
+        annotations["acquisition_settings"] = {
+            "software": meta.acquisition.software,
+            "settings": [list(p) for p in meta.acquisition.settings],
+        }
+    if meta.raw.imagej is not None:
+        annotations["imagej"] = meta.raw.imagej
+    if meta.raw.tiff_tags is not None:
+        annotations["tiff_tags"] = meta.raw.tiff_tags
+    if meta.raw.vendor is not None:
+        annotations["vendor"] = meta.raw.vendor
+    if meta.raw.ngff is not None:
+        annotations["ngff"] = meta.raw.ngff
+    if meta.raw.extra is not None:
+        annotations["extra"] = meta.raw.extra
+    if meta.raw.ome_xml is not None:
+        annotations["original_ome_xml"] = meta.raw.ome_xml
+    if meta.dropped_fields or dropped:
+        annotations["dropped_fields"] = list(meta.dropped_fields) + dropped
+    if meta.provenance:
+        annotations["provenance"] = list(meta.provenance)
+    if meta.kind is not None:
+        annotations["kind"] = meta.kind
+    if extra_annotations:
+        annotations.update(extra_annotations)
+
+    sa = ET.SubElement(root, _q("StructuredAnnotations"))
+    for key, value in annotations.items():
+        ann_id = f"Annotation:{IOIMAGE_NAMESPACE}:{key}"
+        ann = ET.SubElement(sa, _q("MapAnnotation"), {"ID": ann_id, "Namespace": IOIMAGE_NAMESPACE})
+        val = ET.SubElement(ann, _q("Value"))
+        if isinstance(value, str):
+            ET.SubElement(val, _q("M"), {"K": "text"}).text = value
+        else:
+            ET.SubElement(val, _q("M"), {"K": "json"}).text = json.dumps(value, ensure_ascii=False)
+        ET.SubElement(image, _q("AnnotationRef"), {"ID": ann_id})
+    if len(sa) == 0:
+        root.remove(sa)
+
+    xml = ET.tostring(root, encoding="unicode")
+    return '<?xml version="1.0" encoding="UTF-8"?>' + xml, dropped