Refuse local references to ids a drawing does not define, scope canvas ids per view, upload every drawing in one stored form checked by the verdict and the preview, keep strict numeric rgb() colours, and commit real Inkscape 1.4.3 exports with their generator.
110 lines
6.3 KiB
Markdown
110 lines
6.3 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; a drawing whose reference names an id it does
|
||
not define is refused by the reader (`dangling_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.
|
||
|
||
## 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).
|