plexora 0.0.1__py3-none-any.whl

plexora/plugins/roi/server/schema.py

@@ -0,0 +1,323 @@
+"""The shape of stored ROI state, and what a valid piece of it looks like.
+
+One versioned JSON document per datasource holds everything: the categories, the
+features grouped by image, and the revision the conflict check turns on.
+
+    {
+      "schema_version": 1,
+      "revision": 42,
+      "categories": [ {id, label, color, visible, locked, sort_order}, ... ],
+      "images": {
+        "default": {
+          "coordinate_space": {"type": "image_pixels", "width": W, "height": H},
+          "features": [ {id, category_id, name, locked, geometry, ...}, ... ]
+        }
+      },
+      "settings": {"destination": "rois"}
+    }
+
+Two structural decisions worth stating, because both are cheap now and
+expensive later:
+
+**Categories are project-level, features are image-level.** A user who defines
+Tumor/Stroma/Necrosis on one image expects those same choices on the next one;
+what they do not expect is the first image's shapes to follow them there. The
+`images` map is keyed by image identity for that reason, even though a Plexora
+project holds exactly one image today and the only key ever written is
+`"default"`. Every operation carries the key it applies to, so adding a second
+image later adds entries rather than changing the format.
+
+**`coordinate_space` is stored, not assumed.** It is what catches the dangerous
+case: the same datasource name now pointing at a different image. Geometry drawn
+on a 92,164 x 76,510 slide looks perfectly plausible on a 101,212 x 84,039 one,
+and nothing about the numbers themselves says otherwise -- so the dimensions
+travel with the annotations and are checked on load.
+"""
+
+from __future__ import annotations
+
+import re
+
+from plexora.plugins.roi.server.geometry import validate_geometry
+
+SCHEMA_VERSION = 1
+
+#: The image key used while a project holds one image. See the module docstring.
+DEFAULT_IMAGE = "default"
+
+#: A project starts with NO categories. The names a pathologist works in are
+#: theirs to choose, and a built-in "Uncategorized" that cannot be renamed or
+#: deleted is a label nobody asked for sitting permanently at the top of their
+#: list -- and one that quietly collects shapes they meant to file properly.
+#: The panel asks for the first category instead: one interaction, once, at the
+#: point where the user already knows what they are about to draw.
+#:
+#: Nothing is special-cased any more, so a document written by an earlier build
+#: keeps whatever "uncategorized" it has and that category behaves like every
+#: other one -- renameable, recolourable, deletable.
+DEFAULT_COLOR = "#8b93a6"
+
+#: What a category with a blank name is called, so the list never has a row the
+#: user cannot see or click.
+UNTITLED_LABEL = "Untitled"
+
+#: Ids are generated by the client (crypto.randomUUID with a short prefix) so a
+#: shape appears the instant it is drawn rather than after a round trip. They are
+#: validated rather than trusted: they end up in DOM attributes and selectors.
+ID_PATTERN = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$")
+
+#: Free text the user typed. Length-capped and stripped of control characters
+#: here; rendered with textContent, never innerHTML, on the client.
+MAX_LABEL_LENGTH = 200
+MAX_NOTE_LENGTH = 4_000
+_CONTROL_CHARS = re.compile(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]")
+
+COLOR_PATTERN = re.compile(r"^#[0-9a-fA-F]{6}$")
+
+#: Ceilings on one project's annotations. Generous -- these exist to stop a
+#: runaway client or a malformed import, not to tell a pathologist how many
+#: regions their slide has.
+MAX_CATEGORIES = 1_000
+MAX_FEATURES = 100_000
+
+FEATURE_FIELDS = (
+    "id", "category_id", "name", "locked", "created_at", "updated_at",
+    "geometry", "flags", "source_roi_id", "notes",
+)
+
+
+def default_state(width=None, height=None):
+    """The state of a project nobody has annotated yet.
+
+    Returned rather than written: a project with no ROIs should not acquire a
+    stored blob just because somebody opened the panel, and revision 0 is what
+    makes the first save from any client a well-formed first write.
+
+    No categories, deliberately -- see DEFAULT_COLOR above.
+    """
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "revision": 0,
+        "categories": [],
+        "images": {DEFAULT_IMAGE: empty_image(width, height)},
+        "settings": default_settings(),
+    }
+
+
+def default_settings():
+    """Project-level preferences that are not annotations.
+
+    One entry so far: `destination`, the name of the place inside the source
+    file that this project last exported to -- the key under `uns/plexora` for
+    an AnnData, the shapes element for a SpatialData store.
+
+    Blank means nobody has exported yet, and the panel fills in the default for
+    whichever kind of file the project came from. Storing a name here rather
+    than a per-kind default means the schema never has to know what the project
+    was imported from.
+    """
+    return {"destination": ""}
+
+
+def normalize_settings(raw):
+    return {"destination": clean_text((raw or {}).get("destination"))}
+
+
+def element_name(value, default):
+    """A name the user typed for a place inside their own file.
+
+    Both destinations need the same rule and neither can afford a looser one:
+    the AnnData key becomes a group under `uns/plexora`, the SpatialData
+    element becomes a directory inside the store. A path is not a name.
+
+    Blank means "whatever you were going to call it" -- somebody pressing save
+    with an empty field has not made a mistake -- so it becomes the default
+    rather than an error. Stripped first, so that holds for whitespace too.
+    """
+    value = clean_text(value)
+    if not value:
+        return default
+    if "/" in value or "\\" in value or value.startswith("."):
+        raise ValueError(f"invalid name {value!r}: it cannot be a path")
+    return value
+
+
+def placeholder_category():
+    """Stand-in for a category a feature names but the document no longer holds.
+
+    Only ever used on the way OUT -- an export or a native save filling in a
+    label and a colour beside each shape -- so that one dangling reference costs
+    a blank label rather than a KeyError halfway through writing somebody's
+    file. Nothing reads it back in, and it is never added to a project.
+    """
+    return {
+        "id": "",
+        "label": "",
+        "color": DEFAULT_COLOR,
+        "visible": True,
+        "locked": False,
+        "sort_order": 0,
+    }
+
+
+def empty_image(width=None, height=None):
+    return {"coordinate_space": coordinate_space(width, height), "features": []}
+
+
+def coordinate_space(width=None, height=None):
+    """How to read the numbers in a geometry.
+
+    Spelled out rather than implied because "image pixels" is one of several
+    things a viewer could plausibly have stored -- screen pixels, viewport
+    fractions, coordinates at whatever pyramid level was on screen -- and a
+    consumer reading this file in five years has no way to tell which.
+    """
+    return {
+        "type": "image_pixels",
+        "width": int(width) if width else None,
+        "height": int(height) if height else None,
+        "origin": "top-left",
+        "axis_order": "xy",
+    }
+
+
+def normalize_state(raw, width=None, height=None):
+    """Coerce a loaded document into the current shape.
+
+    Tolerant on the way in and strict on the way out: a document written by an
+    older build is upgraded, and anything unrecognisable is replaced rather than
+    allowed to half-load. Losing annotations to a corrupt blob is bad; drawing a
+    project's regions from a half-parsed one is worse, because it looks fine.
+    """
+    if not isinstance(raw, dict):
+        return default_state(width, height)
+
+    version = raw.get("schema_version")
+    if version is not None and not isinstance(version, bool) and isinstance(version, int):
+        if version > SCHEMA_VERSION:
+            raise ValueError(
+                f"these ROI annotations were written by a newer version of Plexora "
+                f"(schema {version}, this build reads {SCHEMA_VERSION})"
+            )
+
+    categories = [normalize_category(c) for c in raw.get("categories") or []
+                  if isinstance(c, dict) and c.get("id")]
+
+    images = {}
+    for key, entry in (raw.get("images") or {}).items():
+        if not isinstance(entry, dict):
+            continue
+        stored = entry.get("coordinate_space") or {}
+        images[str(key)] = {
+            "coordinate_space": {
+                **coordinate_space(stored.get("width"), stored.get("height")),
+                **{k: v for k, v in stored.items() if k in ("type", "origin", "axis_order")},
+            },
+            "features": [normalize_feature(f) for f in entry.get("features") or []
+                         if isinstance(f, dict) and f.get("id")],
+        }
+    if DEFAULT_IMAGE not in images:
+        images[DEFAULT_IMAGE] = empty_image(width, height)
+
+    revision = raw.get("revision")
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "revision": int(revision) if isinstance(revision, int) and not isinstance(revision, bool) else 0,
+        "categories": categories,
+        "images": images,
+        "settings": normalize_settings(raw.get("settings")),
+    }
+
+
+def normalize_category(raw):
+    """One category, with every field present and of the right type."""
+    return {
+        "id": validate_id(raw.get("id"), "category id"),
+        "label": clean_text(raw.get("label")) or UNTITLED_LABEL,
+        "color": color(raw.get("color")),
+        "visible": bool(raw.get("visible", True)),
+        "locked": bool(raw.get("locked", False)),
+        "sort_order": as_int(raw.get("sort_order"), 0),
+    }
+
+
+def normalize_feature(raw):
+    """One ROI, with its geometry validated and unknown fields dropped."""
+    feature = {
+        "id": validate_id(raw.get("id"), "ROI id"),
+        # Required, with nothing to fall back to: there is no catch-all category
+        # to file a shape under any more, and inventing one here would put it
+        # somewhere the user never chose.
+        "category_id": validate_id(raw.get("category_id"), "category id"),
+        "name": clean_text(raw.get("name")),
+        "locked": bool(raw.get("locked", False)),
+        "created_at": clean_text(raw.get("created_at")) or None,
+        "updated_at": clean_text(raw.get("updated_at")) or None,
+        "geometry": validate_geometry(raw.get("geometry")),
+        "flags": normalize_flags(raw.get("flags")),
+        "source_roi_id": clean_text(raw.get("source_roi_id")) or None,
+    }
+    notes = clean_text(raw.get("notes"), MAX_NOTE_LENGTH)
+    if notes:
+        feature["notes"] = notes
+    return feature
+
+
+def normalize_flags(raw):
+    """Advisory marks the editor put on a shape.
+
+    `self_intersecting` is computed on the client, where the shape is being
+    drawn, and recorded rather than acted on -- the server neither verifies nor
+    repairs it. It exists so the outline can be drawn differently and the user
+    can see there is something to look at.
+    """
+    raw = raw if isinstance(raw, dict) else {}
+    return {"self_intersecting": bool(raw.get("self_intersecting", False))}
+
+
+def validate_id(value, what):
+    if not isinstance(value, str) or not ID_PATTERN.match(value):
+        raise ValueError(f"invalid {what}: {value!r}")
+    return value
+
+
+def clean_text(value, limit=MAX_LABEL_LENGTH):
+    """User-typed text, made safe to store and hand back.
+
+    Control characters go (they serve no purpose in a label and make a mess of
+    every downstream format), and length is capped. Nothing is HTML-escaped
+    here: escaping at the store would double-escape on every round trip, and the
+    place that has to be careful is the one that puts it in the DOM.
+    """
+    if value is None:
+        return ""
+    if not isinstance(value, str):
+        value = str(value)
+    return _CONTROL_CHARS.sub("", value).strip()[:limit]
+
+
+def color(value):
+    if isinstance(value, str) and COLOR_PATTERN.match(value):
+        return value.lower()
+    return DEFAULT_COLOR
+
+
+def as_int(value, fallback):
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return fallback
+    return int(value)
+
+
+def image_entry(state, image_key):
+    """The entry for one image, or a ValueError naming what was asked for."""
+    entry = (state.get("images") or {}).get(image_key)
+    if entry is None:
+        raise ValueError(f"unknown image {image_key!r}")
+    return entry
+
+
+def find(items, item_id):
+    for index, item in enumerate(items):
+        if item.get("id") == item_id:
+            return index, item
+    return -1, None