Skip to content

Add a renderer-agnostic graphical annotation model #53

Description

@PierreRaybaut

Is your feature request related to a problem? Please describe.

BaseObj.annotations currently provides a versioned JSON container without shared graphical semantics. DataLab Desktop stores serialized PlotPy items there, while other consumers cannot interpret, transform, or render them portably.

Describe the solution you'd like

Introduce a canonical, typed, renderer-agnostic annotation model in sigima.objects, together with a versioned JSON Schema, a typed API parallel to the existing free-form API, lossless preservation of unknown payloads, exact geometric transformations, PlotPy and Matplotlib renderers, and an explicit migration path for known historical PlotPy items.

Acceptance criteria:

  • Point, segment, oriented rectangle, circle, oriented ellipse, polyline, polygon, text, axis/crosshair cursor, and axis range primitives are modeled.
  • Shared fields cover stable identifiers, visibility, locking, z-order, calibrated axis coordinates, structured style, labels, metadata, and named JSON extensions.
  • A versioned Draft 2020-12 JSON Schema is published and included in Sigima distributions.
  • Existing get_annotations() / set_annotations() behavior and the historical 1.0 container remain compatible.
  • A parallel typed API preserves opaque and future entries by default.
  • Canonical annotations survive object copies, .h5sig / .h5ima persistence, and .dlabann round-trips.
  • Supported image geometry operations transform canonical annotations exactly; arbitrary rotation follows an explicit reset policy when exact representation is not safe.
  • PlotPy renders every canonical primitive and explicitly migrates known historical PlotPy types while preserving unknown types.
  • Matplotlib renders every canonical primitive in read-only form.
  • sigima.viz exposes show_annotations=True consistently across both backends.
  • Focused tests, the full test suite, Ruff, strict documentation, and distribution checks pass.

Describe alternatives you've considered

W3C Web Annotation is useful as an exchange envelope but does not define enough scientific geometry. OME ROI is image/XML-oriented. SVG provides a useful geometry and style vocabulary but not calibrated scientific coordinate systems. These standards may inform future import/export adapters, but none is suitable as the internal v1 model.

Additional context

Out of scope for this first delivery: Qt or React editors, DataLab Desktop/Web/Kernel integration, Plotly, W3C or OME import/export, collaboration, edit history, and links to analysis results.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions