Files
faunosteo/docs/ANNOTATION-RENDERING.md
T

23 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). In the editor the press machine (press.ts, U2) lists the elements under the pointer (elementsFromPoint), reads the nearest [data-anno-id] of each and decides one action for the whole press. 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).

Deselection (D6b, R1): a press that begins outside any [data-anno-id] element and ends as a click deselects the current annotation, in the editor and in its read-only twin; the catalogue reader does not. The hit areas themselves are unchanged. A drag, a pan, a zoom or a press with a second finger never deselects.

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. A zone or a trigger drawn as a polygon or a path must also fill a disc of 4 CSS px on that preview, under the nonzero rule the layer fills with (it writes no fill-rule, and none reaches it), its stroke left out (verification.validation.marker_interior_too_small, owner brief 2026-11-01): an outline drawn forth and back, the same loop twice in opposite directions, or a near-flat shape on a diagonal fills no point a tap can reach, refused. The measure is conservative (a disc crossing no edge, curves cut into chords whose deviation is taken off) and refuses in doubt; a point painted over a zone takes the taps on its disc, which the measure does not count (known limitation, RUST.md §12.14).

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.

Editor overlay (V1-2.6)

The draft editor (admin, tab Annotations and the crop rectangle of tab Views) puts a second <svg> over the core's composed view, inside the same transformed container, with the composed root's own viewBox and preserveAspectRatio (the attribute text, read with Number, never viewBox.baseVal). It draws no annotation: the markers stay the core's (view.canvas) and the drawing is never modified. The overlay holds numbers only, drawn from the editor's state: the selection outline (dashed), the vertex circles, the tracing in progress, the pending or dragged outline, the hollow cross of a corrected position and the crop rectangle. It is aria-hidden and never takes the pointer. It sets pointer-events: none on its own shapes; the pointer is read on the canvas box and mapped to drawing units through the overlay's getScreenCTM().inverse(). No overlay shape carries data-anno-id, so click targeting still reads the core's markers only.

Handles live in a third <svg> of their own (the handle layer), above the overlay in the same transformed container, with the same viewBox and preserveAspectRatio. It is not aria-hidden: each handle is a focusable role="button" (tabindex="0") named after what it moves (« Point {nom} » for a point, « Accès {nom} » for a link circle), with a visible focus ring. The layer's root sets pointer-events: none; each handle's hit shape turns it back on (pointer-events: auto, painted shapes only) with a transparent fill and carries data-handle (the JSON of its handle reference), which the press machine reads through elementsFromPoint. Handle sizes are constant in CSS px under zoom: the layer divides them by the drawing's px per unit (the box size over the frame, times the zoom). The device size is read once per handle layer from (any-pointer: coarse):

Device Vertex « + » « − » bubble Hit radius
Coarse (finger) 18 px 24 px 44 × 36 px 22 px
Fine (mouse, pen) 12 px 16 px 28 × 22 px 10 px

The point handle covers the selected point's own circle (at least the hit radius), so the whole marker can be held. A chosen vertex is drawn bigger, filled and ringed, never by colour alone.

A selected polygon (zone, or a link traced as a polygon) gets its handles in the same layer, in this order: one « + » at the midpoint of each segment (wrapping from the last vertex to the first), then one vertex handle per vertex, then the « − » bubble of the chosen vertex, a rounded rectangle drawn just above that vertex. Each is a role="button" with tabindex="0", so Tab and Shift+Tab walk them in document order. They sit in one <g role="group"> named « Sommets de {nom} »; each name carries the shape's display name in the current locale: « Sommet {n} de {nom} », « Ajouter un sommet après le sommet {n} de {nom} », « Retirer le sommet {n} de {nom} ». A « + » is not drawn while its segment is shorter than two hit radii on screen at the current zoom (R-9); Insert or the « + » key on a vertex still reaches it. The « − » bubble is aria-disabled and greyed while the polygon has three vertices. Above 40 vertices (HANDLE_CAP, T18) the layer draws no handle at all: the overlay keeps the selection outline. No handle covers the polygon's interior: a press inside it still reads the core's markers, so an annotation drawn on top is the one a click reaches. A path, or an annotation without geometry, gets no handle. The pending shape of a resumed creation gets the same handles (see the creation marks below).

Marks of a gesture in progress, drawn by the overlay:

  • the old place: grey dashes of the stored shape while a drag, a move mode, a size change or a keyboard series shows a preview;
  • the preview itself: the selection outline at its new place or size;
  • the refused place: red dashes of the shape the core refused, while the refusal message is shown (the shape stays where it was);
  • the move-mode target: the shape the mode moves (the selection, or the chosen vertex) keeps its handles; a drag anywhere on the drawing moves it;
  • a redraw (« Redessiner », or « Remplacer par un polygone » on a path): the stored outline in grey dashes stays until the new tracing closes, without vertices or handles; the new tracing is drawn as any tracing.

The loupe (U2 Task 8, board 13): while a finger drags a handle (a vertex, the point) or the move mode's target, a 120 px disc sits 90 px above the finger, clamped inside the canvas box, and shows the place under the finger at twice its size on screen. It is a sibling of the transformed container inside the canvas box, aria-hidden, inert and pointer-events: none, so it never takes a press and is never a hit target. Its content is a copy of the core's drawing taken once when the drag starts, with every data-anno-id removed (the copy is a picture, never a marker), then the preview outline and its vertices on top (accent, solid), as the overlay draws them. The copy is never rebuilt during the drag: per move, the disc's place, the copy's offset and the outline change (transforms and numbers only). The loupe goes away on the drop, on a cancel (a second finger, a lost capture, a document change) and at the end of the press. A mouse or pen drag shows no loupe.

The edit strip (U2 Task 14) stays under the shell's top bar from 1 024 px: it is sticky at top: var(--shell-top-bar-height), opaque, with a z-index of 5 (above the drawing, under the loupe, the menus, the bar and the dialogs), and no ancestor sets an overflow other than visible. The bar's height (3.5 rem plus the safe-area inset) and the strip's (--edit-strip-height) are CSS variables of styles/index.css, which also feed a scroll-margin-top on every focusable of the drawing place (links, buttons, fields, tabindex elements, rows through data-focus-key, handles through data-focus-target, the canvas box) except the strip's own commands and a dialog's controls, from 1 024 px and only while the place is not hidden, so a focus or a scrollIntoView never lands under either. It is a margin, not a page scroll-padding: the padding made the page jump when the focus went to the sticky bar or strip themselves, which is also why the strip's commands carry none. A vertex chosen from the keyboard (Delete, Backspace, Insert, « + ») takes the focus with a scroll, so the margin applies; one chosen by a pointer or a finger takes it without a scroll. Below 1 024 px the strip is not sticky.

The drawing column (U2 Task 17: the view chips, the tools and the canvas box, the add row, the message line; data-drawing-column) is pinned under the strip from 1 024 px wide and 40.25 rem (644 px) high: sticky at --edit-pinned-top (bar + strip + 0.75 rem, the strip's gap), aligned to the start of its grid row, so no part of it ever passes under the strip or the bar while the side panel scrolls past; the side panel still passes under the strip. A bottom margin of −3 rem lets the pinned travel run into the page's bottom space (the workspace's gap and the main area's padding), else the end of the page pushed the column's top under the strip at 1 180 × 820. So that the column always fits the window, the canvas box (data-canvas-box) is capped in width at (100svh − --edit-pinned-top − 9.25 rem) × 4/3 + 2 px (9.25 rem: one row of chips, one add row, the line and the gaps; 2 px: the box's border), keeping its 4:3 ratio: the cap follows the window's small viewport height, never the scroll nor a collapsing browser toolbar. The box is unchanged when the browser window (not the screen) is 1 024 × 768, 1 180 × 820 or 1 280 × 800, and smaller in shorter windows (capped below 672, 789 and 672 px of window height at those widths; a tablet's browser toolbars take their height off the screen's); a capped box sits left, with spare width on its right. The column's focusables carry only the bar's margin there (the strip's margin, larger than the pinned top, would scroll the page on a focus of a pinned control). The 9.25 rem assumes one row of view chips: a sheet whose chips wrap to a second row makes the column about 38 px taller than the cap allows, so where the cap binds the column's top goes under the strip at the end of the page. Below 644 px of window height the tool column (365 px) no longer fits beside a capped box: nothing is pinned or capped, and the drawing scrolls under the strip as before, with the strip's margin on its focusables.

The editor page's other focusables (criterion 25: the header's « Enregistrer », the tab row, « Défaire » and « Refaire », the notices' controls) carry a smaller margin, the bar's height plus 0.5 rem, at every width since the bar is sticky everywhere. It is one rule in styles/index.css, scoped to [data-editor-workspace] through :where() so its specificity stays under the drawing place's rule, which wins for its targets with the strip's height added. It excludes the strip's commands and a dialog's controls, and the bar itself lies outside the workspace.

A press on a held « Défaire » or « Refaire » (D1, criterion 33) says why in a bubble under that button, on every tab. It is portalled to the body with position: fixed (no layout shift), at z-20: over the sticky strip and the pinned column, under the top bar (z-30, and it never sits higher than the bar's bottom) and the modal dialogs. At most 18 rem wide, its right edge follows the button's, kept 8 px inside the window; while the strip is on screen it ends 4 px left of the strip's command box, so the commands its text names stay visible. It is aria-hidden: each button carries an always-mounted visually hidden role="status" region whose keyed child holds the text per press. It ends with the hold, a tab change, the focus leaving the button, a press elsewhere, a scroll, a dialog opening, or Escape, which it takes before any other Escape (typed in a text field it only closes the bubble).

A creation (U2 Task 7, A2, A4, A12) is drawn by the overlay too, never by the core, since the new shape is not in the document until « Créer »:

  • the point tool's preview: with a mouse (touch has no hover), a dashed accent circle at the size the strip chose for the next point, with a small cross at its centre, follows the pointer over the drawing;
  • the open tracing of a new zone or link: the accent dashed polyline and its vertex circles;
  • the ghost, the placed point or the closed tracing waiting for its properties: filled with the colour of the category the form holds (0.45 opacity), so a category change recolours it at once (A4), drawn with a white halo (a wider white stroke under it) and an accent dashed outline over the halo. It stays visible under the creation dialog's light veil;
  • the corrected position of a point (C26): the proposal in accent dashes and the click marked apart by a hollow cross;
  • a resumed trace (« Reprendre le tracé », board 04 C, rev 4): the closed ghost stays drawn as above, and the handle layer draws the polygon handles on it exactly as on a selected polygon (« + », vertices, the chosen vertex's « − » bubble, the R-9 zoom rule). A resumed shape above 40 vertices shows no handle, and no press inside the pending shape moves it. The handle names carry the form's name in the current locale, or « cette nouvelle zone » / « ce nouvel accès » while it is empty (« Sommets de ce nouvel accès »). During a vertex drag the ghost stays at its last place and the dragged outline is drawn as a selection preview (dashed ink, its vertices), without the grey old place; the loupe follows a finger as on a stored zone. A change of the shape only replaces the ghost's geometry: the document is untouched until « Créer ».

While a creation is in progress the canvas box carries data-creating. The stylesheet then dims every core marker ([data-anno-id] at 0.35 opacity, no hover brightening, the crosshair cursor) so the other annotations read as unselectable (A12); the core's drawing and markers are left untouched, only their presentation changes. The attribute goes with the creation.

The overlay only proposes geometry. Whether a position, a radius or a polygon is acceptable (frame, minimum visible size, interior) is the core's verdict on the candidate document; the page keeps no copy of those rules.

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