Files
faunosteo/docs/ANNOTATION-RENDERING.md
T

7.8 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); so do the PDF writer (R4) and the curation pipeline's review drawings (R5). The TypeScript renderer (packages/anatomy/src/render) it replaced was deleted at R5.7.

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).

The editor canvas is inlined in the page, where #id resolves against the whole document. Since V1-2.2 (owner decision 2026-10-29) the core writes fv.<view id>. in front of every id of the drawing and of every local reference to it (href, xlink:href, url(#…)), so each view resolves its gradients, clip paths and <use> targets in its own drawing only, never in another view's or in the page, and the composer refuses a canvas that would keep a reference outside its scope. A drawing whose reference names an id it does not define is refused by the reader (dangling_reference); a url( spelt any other way than url(#id) with optional quotes and spaces is removed by the reader, so the cleaning refuses the file as active content and the verdict as a removal. A url( glued to a longer name (xurl(#a)) is no reference: the reader removes the attribute holding it, whatever the attribute (2026-10-30), so the canvas and the PDF view accept the same references as the reader; the canvas still refuses a composed view over 4 MiB (too_large), its scope prefix lengthening every id and reference. The annotation layer carries no id. The PDF view keeps the drawing's ids: it is rasterised as a document of its own. The R3 canvas goldens stay frozen; the tests apply this declared change to them (withIdsScopedPerView, with_ids_scoped_per_view).

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. The PDF view keeps the drawing's ids, so osteo-halo is reserved (V1-2.2, owner brief 2026-10-30): the reader refuses a drawing holding it in any letter case (reserved_id) and both composers refuse such a tree, so the halo the markers name is always the engine's.

Both forms append the layer as the root's last child, so it inherits the root's visibility. A root visibility other than visible is refused by the reader (root_visibility) and by both composers: a drawing could otherwise hide every marker while its own children set visible back. The root's class, style, transform, filter, mask and clip-path are removed by the reader; opacity and display on the root act on the drawing and the markers alike. Still open (RUST.md §12.10): stroke-opacity, stroke-dasharray and stroke-width on the root reach the markers, which do not set them, and a view without view_box takes its frame from the drawing.

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).