Files
faunosteo/docs/ANNOTATION-RENDERING.md
T

5.5 KiB
Raw Blame History

Annotation rendering contract

Status: source of truth since Step 5. Replaces ANATOMY-SVG-CONVENTION.md (the legacy data-anno-* attributes authored inside the SVG files). Rewritten at R3 (2026-10-14) to describe the code exactly, before the renderer moved to Rust; nothing in the rendering changed with this rewrite.

The drawing of a sheet is a plain SVG asset with no annotation element. The application draws the markers itself from the canonical document (docs/development/ANATOMICAL_SHEET_MODEL.md). One layer renderer turns the annotations of one view into a <g data-layer="annotations" data-view-id="…"> appended last to the view's <svg>, above the drawing. Since R3 the editor canvas gets the whole view (sanitised drawing + layer) from the Rust core (crates/core/src/anatomy); the PDF engine and the curation pipeline still use the TypeScript renderer (packages/anatomy/src/render) until R4 and R5, with the same output.

Elements emitted per annotation

The element follows the geometry type, not the annotation kind, except for a trigger.

Annotation Elements
detail_trigger, any geometry one dashed shape: fill and stroke = the colour, fill-opacity 0.06, stroke-width 2, stroke-dasharray 8,4, pointer-events all, style cursor:pointer, class detail-zone
point or zone with a circle a transparent hitbox (the geometry's r, fill transparent, pointer-events all, style cursor:pointer) then a visible twin on top (radius max(2, r − 12), the colour, fill-opacity 0.65 on the main view / 0.5 on a detail view, stroke #000 1.5, pointer-events none)
point or zone with a polygon or a path one filled shape: fill and stroke = the colour, fill-opacity 0.3, stroke-width 2, pointer-events all, style cursor:pointer

Annotations without geometry draw nothing. Annotations follow the document order of the view. Coordinates are printed as JavaScript prints numbers, never rounded; a path's d is copied as written. Each element has one <title> child, "name FR / name EN" (native tooltip), and the attributes below. Owner decision 2026-10-15: until then an unnamed trigger carried the French view name in both attributes and its title read "FR / FR"; the editor canvas (Rust core) now follows the language of each attribute. The PDF engine's TypeScript renderer keeps the old form until R4, where it is invisible: the highlight drops every data-* attribute and a raster never shows a title.

Attributes (the application's read contract)

Attribute Value
data-anno-id annotation id (stable, the report's annotationId)
data-anno-kind point, zone or detail_trigger
data-anno-lateral unpaired, bilateral, left or right
data-anno-opens-view opens_view_id of a trigger
data-anno-name-fr, data-anno-name-en the annotation's name in each language; a trigger without a name carries the opened view's name in each language (French in -fr, English in -en; an empty language takes the other one). Display only: never an identifier, never persisted
data-anno-zone finding_zone_id, when present
data-anno-region vertebral_region_code, when present
data-state current on every element of an annotation of the active observation

Click handling walks up to the nearest [data-anno-id] and hands the annotation id to the core's click rule (zone.click, R2). Behaviour never depends on a label, an element id or a class. The canvas sets and removes data-state in place when the active observation changes (no rebuild), for the annotation ids of every zone of that observation, whatever their view; the custom tooltip reads the two name attributes (none on a trigger).

Colours

annotations[].color gives the colour of one annotation; otherwise the colour of its category (categories[].color); otherwise #888888 (no colour, or an unknown category). Colours are document data, written by the curation changeset, never by the renderer.

Views

A view renders on its view_box when set (the head view is the crop 60 100 500 380 of the main drawing). Otherwise the canvas keeps the asset's own viewBox, and falls back to 0 0 100 100 when the asset has none; the PDF engine keeps whatever the asset has. A detail view with its own svg_asset_id renders that asset, otherwise the first asset up its parent chain. The root's width and height are removed; its other attributes are kept (after sanitising).

Styling and states

The application stylesheet: .svg-canvas [data-state='current'] fills the selected markers with the accent colour at 0.85, every [data-anno-id] shows a pointer cursor and brightens on hover.

PDF highlight

The engine composes the observation's zones of one view: the markers of the other annotations are dropped (not hidden), every data-* attribute is removed, the kept elements get fill #b85a3f at 0.85 and, on the main view, the osteo-halo filter (two Gaussian blurs merged with the source), added to the first <defs> of the drawing or to a new <defs> placed first.

Checking the look

pnpm import:equine writes draft/review/app-main.svg and app-head.svg (the curation pipeline's rendering, byte goldens until R5). Rasterise them with ImageMagick next to the legacy files (strip the <title> elements first, ImageMagick's own SVG renderer drops shapes that carry one) to compare markers and framing. The editor canvas itself is compared in Chromium with scripts/visual-canvas.mjs (capture before and after, pixel comparison).