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