plexora 0.0.1__py3-none-any.whl

plexora/plugins/roi/server/geojson.py

@@ -0,0 +1,267 @@
+"""Annotations as a file somebody else can open.
+
+GeoJSON, because polygons are polygons: Shapely, GeoPandas, QGIS, SpatialData's
+own shapes reader and every JavaScript geometry library already read it, and the
+alternative is inventing a polygon format that only Plexora can open.
+
+The one honest caveat, stated in the file itself rather than assumed: GeoJSON is
+a GEOGRAPHIC format. Its positions are longitude/latitude on the WGS-84 datum
+unless a document says otherwise, and these are image pixels with y increasing
+downward -- which is not a coordinate reference system at all. So the export
+carries an explicit `coordinate_space` and never claims a CRS. A reader that
+treats these as degrees gets nonsense either way; one that reads the metadata
+gets the truth.
+
+Plexora-specific material lives under a `plexora` foreign member. Foreign
+members are the part of the GeoJSON spec meant for exactly this: a strict reader
+ignores it and still gets valid geometry, and Plexora gets its categories back.
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime, timezone
+
+from plexora.plugins.roi.server import schema
+from plexora.plugins.roi.server.geometry import validate_geometry
+
+MIME_TYPE = "application/geo+json"
+
+#: Features in one imported document. An import is parsed, validated and applied
+#: in one request, so this is the ceiling on how long that request can take.
+MAX_IMPORT_FEATURES = 50_000
+
+#: Where an imported feature carrying no category information at all is filed.
+#: It has to go somewhere -- dropping the shape because some intermediate tool
+#: stripped its properties would lose real annotation -- and since a project no
+#: longer has a reserved catch-all, one named for how these arrived is at least
+#: honest about what it holds. Created only if such a feature actually turns up.
+IMPORTED_LABEL = "Imported"
+
+
+def export_document(state, datasource, plugin_version, image_key=schema.DEFAULT_IMAGE,
+                    image_id=None):
+    """A FeatureCollection holding everything needed to reconstruct the project.
+
+    Category metadata is written twice on purpose: once in the foreign member
+    (so a Plexora import restores the categories themselves -- colours, order,
+    visibility) and once flattened onto each feature's properties (so a reader
+    that ignores foreign members still knows what each region is). The
+    duplication is a few bytes and the alternative is an export that is either
+    lossy for Plexora or opaque to everyone else.
+
+    `image_id` is the value this project's cells carry in their image-id column,
+    and it is written for the same reason and in both of the same places. An
+    AnnData can hold cells from a dozen slides; a file of polygons that does not
+    say which one it was drawn on is a file whose regions can be applied to the
+    wrong slide without anything looking wrong. It is passed in rather than read
+    from `state` because it is a fact about the project record, which can change
+    after these shapes were drawn -- resolving it at export time is what keeps a
+    stored copy from going quietly stale. None is a real answer: a single-image
+    project has no such column, and the key is then absent rather than null.
+    """
+    entry = state["images"].get(image_key) or schema.empty_image()
+    categories = {c["id"]: c for c in state["categories"]}
+
+    features = []
+    for feature in entry["features"]:
+        category = categories.get(feature["category_id"]) or schema.placeholder_category()
+        features.append({
+            "type": "Feature",
+            "id": feature["id"],
+            "geometry": feature["geometry"],
+            "properties": {
+                "name": feature.get("name") or "",
+                "category_id": feature["category_id"],
+                "category": category["label"],
+                "category_color": category["color"],
+                "locked": feature.get("locked", False),
+                "created_at": feature.get("created_at"),
+                "updated_at": feature.get("updated_at"),
+                "source_roi_id": feature.get("source_roi_id"),
+                # Per feature as well as per document, so concatenating two
+                # projects' exports into one collection -- which is what anyone
+                # comparing slides does -- keeps each shape bound to its image.
+                **({"image_id": image_id} if image_id is not None else {}),
+                **({"notes": feature["notes"]} if feature.get("notes") else {}),
+            },
+        })
+
+    return {
+        "type": "FeatureCollection",
+        "plexora": {
+            "schema_version": schema.SCHEMA_VERSION,
+            "plugin_version": plugin_version,
+            "datasource": datasource,
+            **({"image_id": image_id} if image_id is not None else {}),
+            "exported_at": _now(),
+            "coordinate_space": entry["coordinate_space"],
+            "categories": state["categories"],
+        },
+        "features": features,
+    }
+
+
+def validate_document(document, image_size=None):
+    """Check an incoming document, returning what is wrong with it.
+
+    Returns (errors, warnings). Errors mean it cannot be imported at all;
+    warnings mean it can, but the user should be asked first -- which today is
+    exactly one thing, and the important one.
+    """
+    errors, warnings = [], {}
+
+    if not isinstance(document, dict):
+        return ["that file does not contain a GeoJSON object"], warnings
+    if document.get("type") != "FeatureCollection":
+        errors.append("expected a GeoJSON FeatureCollection")
+
+    meta = document.get("plexora")
+    if not isinstance(meta, dict):
+        # v1 imports Plexora's own exports only. A bare GeoJSON from elsewhere
+        # is readable geometry in an unknown coordinate space -- pixels of some
+        # image, microns, or degrees -- and importing it would mean guessing
+        # which. That guess is the one this whole module exists to avoid.
+        errors.append(
+            "this file was not exported by Plexora (no 'plexora' metadata), so "
+            "there is no way to tell what its coordinates mean"
+        )
+    else:
+        version = meta.get("schema_version")
+        if not isinstance(version, int) or isinstance(version, bool):
+            errors.append("the file's Plexora metadata has no schema version")
+        elif version > schema.SCHEMA_VERSION:
+            errors.append(
+                f"the file was written by a newer version of Plexora "
+                f"(schema {version}, this build reads {schema.SCHEMA_VERSION})"
+            )
+
+    features = document.get("features")
+    if not isinstance(features, list):
+        errors.append("the file has no features list")
+    elif len(features) > MAX_IMPORT_FEATURES:
+        errors.append(f"the file holds more than {MAX_IMPORT_FEATURES} regions")
+
+    if errors:
+        return errors, warnings
+
+    stored = (meta.get("coordinate_space") or {}) if isinstance(meta, dict) else {}
+    stored_size = (stored.get("width"), stored.get("height"))
+    if image_size and all(image_size) and all(stored_size) and tuple(image_size) != stored_size:
+        # Not an error: importing anyway is a legitimate thing to want when the
+        # two images really are the same field of view at different scales. It
+        # is just never the thing to do by default, because the geometry will
+        # land somewhere plausible and wrong.
+        warnings["dimension_mismatch"] = {
+            "found": list(stored_size),
+            "expected": list(image_size),
+        }
+
+    return errors, warnings
+
+
+def import_features(state, document, image_key=schema.DEFAULT_IMAGE):
+    """Add a document's regions to `state`, returning (new_state, report).
+
+    Nothing is ever overwritten. Every imported region is given a fresh id with
+    its original kept in `source_roi_id`, because an id collision here is not a
+    conflict to resolve -- the two regions are simply different regions that
+    happen to have been numbered the same in two projects, and picking one would
+    destroy the other. Importing the same file twice therefore duplicates its
+    regions, which is visible and undoable; the alternative silently is not.
+
+    Categories are matched first by id (a Plexora export carries the same ids)
+    and then by label, so importing Tumor into a project that already has one
+    lands in the existing category rather than creating "Tumor" twice.
+    """
+    by_id = {c["id"]: c for c in state["categories"]}
+    by_label = {c["label"].casefold(): c for c in state["categories"]}
+
+    new_categories, new_features = [], []
+    remap = {}
+
+    meta = document.get("plexora") or {}
+    for raw in meta.get("categories") or []:
+        if not isinstance(raw, dict):
+            continue
+        category = schema.normalize_category(raw)
+        match = by_id.get(category["id"]) or by_label.get(category["label"].casefold())
+        if match is not None:
+            remap[category["id"]] = match["id"]
+            continue
+        new_categories.append(category)
+        by_id[category["id"]] = category
+        by_label[category["label"].casefold()] = category
+        remap[category["id"]] = category["id"]
+
+    for raw in document.get("features") or []:
+        if not isinstance(raw, dict):
+            raise ValueError("every entry in 'features' must be an object")
+        properties = raw.get("properties") if isinstance(raw.get("properties"), dict) else {}
+
+        category_id = _resolve_category(properties, remap, by_id, by_label, new_categories)
+        new_features.append({
+            "id": new_id("r"),
+            "category_id": category_id,
+            "name": schema.clean_text(properties.get("name")),
+            "locked": bool(properties.get("locked", False)),
+            "geometry": validate_geometry(raw.get("geometry")),
+            "flags": schema.normalize_flags(raw.get("flags")),
+            # The id it had where it came from. Kept because it is the only
+            # thread back to the source project once ids are regenerated, and
+            # somebody reconciling two exports will want it.
+            "source_roi_id": schema.clean_text(raw.get("id")) or None,
+            "notes": schema.clean_text(properties.get("notes"), schema.MAX_NOTE_LENGTH),
+        })
+
+    return {
+        "op": "roi.bulk_create",
+        "image": image_key,
+        "categories": new_categories,
+        "features": [f for f in new_features],
+    }, {
+        "imported": len(new_features),
+        "created_categories": len(new_categories),
+    }
+
+
+def _resolve_category(properties, remap, by_id, by_label, new_categories):
+    """Which category an imported feature belongs in.
+
+    Falls back through: the id the export used, then the label it printed, then
+    IMPORTED_LABEL. The label fallback is what makes a feature survive a
+    document whose foreign member was stripped by some intermediate tool, and
+    the last step is what makes it survive losing its properties entirely.
+
+    Every path ends at a category that exists or is created here, since there is
+    no reserved one to point at.
+    """
+    source_id = properties.get("category_id")
+    if isinstance(source_id, str) and source_id in remap:
+        return remap[source_id]
+    if isinstance(source_id, str) and source_id in by_id:
+        return source_id
+
+    label = schema.clean_text(properties.get("category")) or IMPORTED_LABEL
+    match = by_label.get(label.casefold())
+    if match is not None:
+        return match["id"]
+
+    category = schema.normalize_category({
+        "id": new_id("c"),
+        "label": label,
+        "color": properties.get("category_color"),
+        "sort_order": len(by_id),
+    })
+    new_categories.append(category)
+    by_id[category["id"]] = category
+    by_label[label.casefold()] = category
+    return category["id"]
+
+
+def new_id(prefix):
+    return f"{prefix}-{uuid.uuid4()}"
+
+
+def _now():
+    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")

plexora/plugins/roi/server/geometry.py

@@ -0,0 +1,181 @@
+"""What counts as a storable ROI geometry.
+
+Every geometry that reaches the store passes through `validate_geometry`,
+whether it came from the drawing tools, an import, or a request somebody wrote
+by hand. The client validates too -- it has to, since it decides what to do
+about a bad shape while the user is still holding the mouse -- but the client's
+answer is advice and this one is the rule.
+
+Two things are deliberately NOT done here:
+
+**No repair.** A self-intersecting polygon is stored as drawn, flagged rather
+than corrected. `make_valid` and friends change topology, and a bow-tie silently
+becoming two triangles is a different annotation from the one the user drew.
+The flag is what surfaces it; the user decides.
+
+**No projection, no scaling, no clamping.** Coordinates are full-resolution
+image pixels and are stored exactly as given. A shape that hangs off the edge of
+the image is a real thing to have drawn (a region continuing past the tissue
+edge), and quietly trimming it would lose that.
+
+The one normalization that does happen is closing rings. GeoJSON requires the
+first and last position of a ring to be identical; [A,B,C] and [A,B,C,A] denote
+the same polygon to every geometry library there is, so accepting both and
+storing one is not a repair -- it just means nothing downstream has to handle
+two spellings of the same shape.
+"""
+
+from __future__ import annotations
+
+import math
+
+POLYGON = "Polygon"
+MULTI_POLYGON = "MultiPolygon"
+GEOMETRY_TYPES = (POLYGON, MULTI_POLYGON)
+
+#: Vertices in one feature, across every ring. A hand-drawn region is a few
+#: hundred points and a simplified freehand trace a few thousand; an imported
+#: tissue contour can legitimately be tens of thousands. Past this, a request is
+#: a mistake or an attempt to make the server chew on something -- and a feature
+#: that big is unusable in the editor anyway, since it is one undo step and one
+#: Path2D rebuild per drag frame.
+MAX_VERTICES = 100_000
+
+#: Rings in one polygon (the outer ring plus interior holes), and polygons in
+#: one MultiPolygon. Both only ever arrive from an import; the editor authors a
+#: single ring.
+MAX_RINGS = 1_000
+MAX_POLYGONS = 1_000
+
+#: The smallest closed ring that encloses anything: three distinct corners plus
+#: the repeated first point.
+MIN_RING_POSITIONS = 4
+
+
+def validate_geometry(geometry, *, max_vertices=MAX_VERTICES):
+    """Return a normalized copy of `geometry`, or raise ValueError.
+
+    Normalized means: type is one of GEOMETRY_TYPES, every position is a pair of
+    finite floats, and every ring is explicitly closed.
+    """
+    if not isinstance(geometry, dict):
+        raise ValueError("geometry must be an object")
+
+    kind = geometry.get("type")
+    if kind not in GEOMETRY_TYPES:
+        raise ValueError(
+            f"unsupported geometry type {kind!r}: expected one of {list(GEOMETRY_TYPES)}"
+        )
+
+    coordinates = geometry.get("coordinates")
+    budget = _Budget(max_vertices)
+
+    if kind == POLYGON:
+        normalized = _polygon(coordinates, budget)
+    else:
+        if not isinstance(coordinates, list) or not coordinates:
+            raise ValueError("MultiPolygon coordinates must be a non-empty list of polygons")
+        if len(coordinates) > MAX_POLYGONS:
+            raise ValueError(f"MultiPolygon has more than {MAX_POLYGONS} polygons")
+        normalized = [_polygon(part, budget) for part in coordinates]
+
+    return {"type": kind, "coordinates": normalized}
+
+
+class _Budget:
+    """Vertex allowance for one feature, shared across all its rings.
+
+    Counted for the whole geometry rather than per ring: a thousand rings of a
+    hundred points each is the same amount of work as one ring of a hundred
+    thousand, and only a per-feature total sees both.
+    """
+
+    def __init__(self, limit):
+        self.limit = limit
+        self.used = 0
+
+    def spend(self, count):
+        self.used += count
+        if self.used > self.limit:
+            raise ValueError(f"geometry has more than {self.limit} vertices")
+
+
+def _polygon(rings, budget):
+    if not isinstance(rings, list) or not rings:
+        raise ValueError("polygon coordinates must be a non-empty list of rings")
+    if len(rings) > MAX_RINGS:
+        raise ValueError(f"polygon has more than {MAX_RINGS} rings")
+    return [_ring(ring, budget) for ring in rings]
+
+
+def _ring(ring, budget):
+    if not isinstance(ring, list):
+        raise ValueError("a ring must be a list of positions")
+    budget.spend(len(ring))
+
+    points = [_position(p) for p in ring]
+    points = close_ring(points)
+
+    if len(points) < MIN_RING_POSITIONS:
+        raise ValueError(
+            "a ring needs at least three distinct positions "
+            f"(got {len(points) - 1 if points else 0})"
+        )
+    # Three points that happen to be the same point are four positions once
+    # closed, and enclose nothing. Counted on the open ring so the deliberate
+    # closing duplicate is not mistaken for a degenerate one.
+    if len({(x, y) for x, y in points[:-1]}) < 3:
+        raise ValueError("a ring needs at least three distinct positions")
+    return points
+
+
+def _position(position):
+    if not isinstance(position, (list, tuple)) or len(position) < 2:
+        raise ValueError("a position must be a [x, y] pair")
+    x, y = position[0], position[1]
+    # bool is an int; a JSON `true` reaching a coordinate is a malformed payload
+    # rather than the number 1.
+    for value in (x, y):
+        if isinstance(value, bool) or not isinstance(value, (int, float)):
+            raise ValueError(f"coordinate {value!r} is not a number")
+        if not math.isfinite(value):
+            # NaN and Infinity survive json.loads by default, so this is the
+            # check that keeps them out of the store -- and out of every
+            # consumer that would otherwise get them back as invalid JSON.
+            raise ValueError("coordinates must be finite numbers")
+    return [float(x), float(y)]
+
+
+def close_ring(points):
+    """A ring whose last position repeats its first."""
+    if not points:
+        return points
+    if points[0] != points[-1]:
+        return [*points, list(points[0])]
+    return points
+
+
+def geometry_bounds(geometry):
+    """(min_x, min_y, max_x, max_y) over every position, or None if empty."""
+    xs, ys = [], []
+    for ring in iter_rings(geometry):
+        for x, y in ring:
+            xs.append(x)
+            ys.append(y)
+    if not xs:
+        return None
+    return (min(xs), min(ys), max(xs), max(ys))
+
+
+def iter_rings(geometry):
+    """Every ring in a Polygon or MultiPolygon, outer and interior alike."""
+    coordinates = (geometry or {}).get("coordinates") or []
+    if (geometry or {}).get("type") == MULTI_POLYGON:
+        for polygon in coordinates:
+            yield from polygon
+    else:
+        yield from coordinates
+
+
+def vertex_count(geometry):
+    return sum(len(ring) for ring in iter_rings(geometry))

plexora/plugins/roi/server/mapping.py

@@ -0,0 +1,169 @@
+"""Which cells fall inside which regions.
+
+The one place the annotation engine meets the cell table, and it stays a thin
+one on purpose: this module answers "for each point, which ROIs contain it" and
+turns that into two label columns. It reads no files and writes none -- the
+callers in `adapters.py` do that -- so the containment rules can be tested
+against hand-built geometry rather than against an .h5ad.
+
+Two rules worth stating, because both are choices and neither is recoverable
+from the code at a glance:
+
+**A cell in several ROIs belongs to all of them.** Regions overlap on purpose --
+a tumour nest inside a stromal region is not a mistake to be resolved by picking
+one -- so the labels are joined with `_` rather than one winning. Names are
+joined in document order, which is the order the GeoJSON export writes and the
+panel lists, so two exports of the same project agree. Categories are joined the
+same way but deduplicated: a cell inside two Tumor regions is `Tumor`, not
+`Tumor_Tumor`, because the question the category column answers is "what kind of
+place is this cell in".
+
+**A cell in a hole is outside.** Interior rings are honoured, which is the whole
+reason this goes through shapely rather than a hand-rolled ray cast: a donut
+region drawn around a necrotic core means the core is not in it.
+"""
+
+from __future__ import annotations
+
+#: Between the ROIs a cell falls in. Underscore rather than a comma or a pipe
+#: because these land in a column that gets read back as a category level, and
+#: a separator that survives a CSV round trip without quoting is worth more
+#: here than one that reads well in a sentence.
+JOINER = "_"
+
+#: What a cell in no region gets. An empty string rather than a word like
+#: "None" or "Background": those are labels a user might legitimately give a
+#: category, and a value that cannot be told apart from a real answer is worse
+#: than a blank. Callers turn this into NA where the format has one.
+UNASSIGNED = ""
+
+
+def assign(features, categories, xs, ys):
+    """(category_label, roi_name) for each point, in point order.
+
+    `features` is the ROI list for one image, in document order; `categories`
+    is the project's category list. Points are full-resolution image pixels --
+    the same space ROI geometry is stored in, so nothing is transformed here.
+
+    Returns two lists as long as `xs`. A point in no region gets UNASSIGNED in
+    both, never a partial answer in one.
+    """
+    count = len(xs)
+    if len(ys) != count:
+        raise ValueError("x and y must be the same length")
+    names = [UNASSIGNED] * count
+    labels = [UNASSIGNED] * count
+    if not count or not features:
+        return labels, names
+
+    import numpy as np
+    import shapely
+    from shapely import geometry as sgeom
+
+    by_id = {c["id"]: c for c in categories}
+    polygons = [_shapely(feature["geometry"], sgeom) for feature in features]
+
+    # One vectorised containment query rather than a Python loop over cells: a
+    # real slide is 10^5-10^6 cells against 10^1-10^3 regions, and the loop
+    # version of this is minutes. `within` is strict about the boundary, which
+    # is the same predicate a point-in-polygon test would give and is not worth
+    # softening -- a centroid exactly on a hand-drawn edge is a coin flip
+    # whatever rule is picked.
+    tree = shapely.STRtree(polygons)
+    points = shapely.points(np.asarray(xs, dtype="float64"),
+                            np.asarray(ys, dtype="float64"))
+    point_index, polygon_index = tree.query(points, predicate="within")
+
+    # Sorted by polygon index within each point, so the joined order is
+    # document order and not whatever order the index happened to return.
+    order = np.lexsort((polygon_index, point_index))
+    hits = {}
+    for position in order:
+        hits.setdefault(int(point_index[position]), []).append(int(polygon_index[position]))
+
+    for row, matched in hits.items():
+        matched_names = []
+        matched_labels = []
+        for index in matched:
+            feature = features[index]
+            category = by_id.get(feature.get("category_id")) or {}
+            matched_names.append(feature.get("name") or "")
+            label = category.get("label") or ""
+            # Deduplicated in first-seen order. See the module docstring: the
+            # category column says what KIND of place a cell is in, and
+            # repeating it once per overlapping region says nothing extra.
+            if label not in matched_labels:
+                matched_labels.append(label)
+        names[row] = JOINER.join(matched_names)
+        labels[row] = JOINER.join(matched_labels)
+
+    return labels, names
+
+
+def current_image_id(dataset):
+    """The image-id value this project's cells carry, or None.
+
+    None is a real answer and not a failure: "this table covers one image"
+    (DataSpec.single_image) and "there is no table at all" both land here, and
+    in both cases every row the project can see belongs to this image.
+
+    Deliberately the same rule gating applies in `resolve_current_image_id` --
+    the two plugins have to mean the same thing by "which image is this
+    project", or the same .h5ad gets gates filed under one name and ROIs under
+    another. It is read off the loaded frame rather than the file because the
+    frame is already narrowed by the project's registration subset, which is
+    exactly the scoping the question needs.
+
+    Raises ValueError when the column holds more than one value within this
+    project's own rows. Refusing to guess is the entire point of asking which
+    column it is: writing ROI columns against the wrong image is not a
+    cosmetic error, it annotates somebody else's cells.
+    """
+    if dataset.schema is None or not dataset.table.available:
+        return None
+    column = dataset.schema.image_id
+    if not column:
+        return None
+
+    # The registration subset first, and without reading anything. For an
+    # AnnData or SpatialData project narrowed to one image at import, the value
+    # the user picked IS the answer -- and it is the only place the answer
+    # reliably survives, because the adapter emits a table of its own columns
+    # and need not carry the obs column the subset was taken on.
+    source = dataset.table.source
+    subset = dict((source.subset if source else None) or {})
+    if subset.get("column") == column and subset.get("value") is not None:
+        return str(subset["value"])
+
+    frame = dataset.table.frame()
+    if frame is None or column not in frame.columns:
+        return None
+    values = [value for value in frame[column].unique().to_list() if value is not None]
+    if not values:
+        return None
+    if len(values) > 1:
+        raise ValueError(
+            f"column {column!r} holds {len(values)} different image ids within "
+            f"this project's own cells, so Plexora cannot tell which image "
+            f"these regions belong to"
+        )
+    return str(values[0])
+
+
+def _shapely(geometry, sgeom):
+    """A stored geometry as a shapely object, holes and all.
+
+    The same conversion `adapters.save_to_spatialdata` does. Kept as its own
+    copy rather than imported from there because that module is the file-writing
+    one and this module deliberately touches no files -- the tests for each
+    should be able to run without the other's dependencies.
+    """
+    if (geometry or {}).get("type") == "MultiPolygon":
+        return sgeom.MultiPolygon(
+            [_polygon(part, sgeom) for part in geometry["coordinates"]])
+    return _polygon((geometry or {}).get("coordinates") or [], sgeom)
+
+
+def _polygon(rings, sgeom):
+    outer, *holes = rings
+    return sgeom.Polygon(outer, holes)