Files
faunosteo/docs/ANNOTATION-RENDERING.md
T
bchanot 96b99784b5 fix(anatomy): V1-2.2 refuse markers too small on the phone preview
Owner decision 2026-11-01: the scale bypass (viewBox blown up, drawing
scaled back) is closed by the visible size, 4 CSS px on the editor at
320 x 568 (equine junctions 4.97 px), verdict marker_too_small. A frame
is usable only where browsers draw it faithfully: edges within 2^20,
span from 1 unit, aspect 100, offset 256 spans; measured in 3 engines.
2026-11-01 01:28:48 +01:00

9.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, stroke none, pointer-events visibleFill, style cursor:pointer; the R3 form kept for the seed review drawings has no stroke and pointer-events all) 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; visiblePainted in the editor canvas, see below)
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, in the PDF view and the review drawings. The editor canvas paints and hits them in three passes, each in document order (« the visible wins », owner decision 2026-11-01, V1-2.2): every point hitbox, then every filled shape (zones and triggers), then every visible twin, which captures on what it paints (pointer-events visiblePainted). A tap on a point's visible disc selects that point even where a zone or another point's hitbox lies under it; a zone keeps every pixel no visible disc covers, the hitbox ring of a point included; a hitbox ring keeps what neither covers. Until then each annotation's elements followed one another, so a zone painted after a vertebral junction took part of its disc. Visible consequence: a selected point's hitbox, filled by the canvas stylesheet, sits under a neighbouring zone, which tints the part it covers. 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 frame (anatomy::frame::view_frame, V1-2.2 owner brief 2026-10-30): its view_box when set (the head view is the crop 60 100 500 380 of the main drawing), otherwise the asset's own viewBox read as a browser reads it (four numbers, positive width and height) and written back in JavaScript number printing (0,0,10,10 becomes 0 0 10 10). Without a usable frame the canvas falls back to 0 0 100 100 and the PDF view carries no viewBox. A detail view with its own svg_asset_id renders that asset, otherwise the first asset up its parent chain. The root's width, height and preserveAspectRatio are removed (the default xMidYMid meet shows the whole frame, which a slice would crop where the box is not the frame's); its other attributes are kept (after sanitising). The verdict and the preview refuse an annotation not entirely inside this same frame (verification.validation.out_of_frame), so a drawing whose viewBox moved away from the annotations is refused, never drawn without its markers. Since the owner brief of 2026-11-01 a frame is usable only within the range browsers draw faithfully (edges within 2²⁰, spans from 1 unit, aspect at most 100, farthest edge at most 256 smaller spans; otherwise no usable frame), and every annotation must show at least 4 CSS px on the smallest preview, the editor at 320 × 568 (verification.validation.marker_too_small): a frame blown up with its drawing scaled back keeps the drawing and shrinks every marker, refused.

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), in a <defs> of the engine placed after the drawing's group, before the layer. 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.

The composition root is the engine's (V1-2.2, owner brief 2026-10-30, RUST.md §12.12): xmlns, xmlns:xlink and the frame only. The drawing's root becomes a <g> holding its other attributes and its children; the layer (and the halo's <defs>) are that group's siblings, so no property the drawing sets, inherited (stroke-*, fill*, visibility…) or acting on a whole group (opacity, display), reaches a marker: a root opacity="0" or display="none" hides the drawing alone. A root visibility other than visible stays refused by the reader (root_visibility) and by both composers. The R3 trees stay frozen; the tests apply this declared change (withIsolatedLayer, withDeclaredHitboxes, with_isolated_layer).

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