122 lines
7.1 KiB
Markdown
122 lines
7.1 KiB
Markdown
# 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).
|