docs(docs): ANNOTATION-RENDERING.md describes the code exactly (R3.0, no rendering change)

This commit is contained in:
bchanot committed 2026-10-14 23:37:14 +02:00
1 parent ddd3dc5332
commit 4e01710a34
1 file changed
+59 -37
+59 -37
View File
@@ -1,25 +1,35 @@
# 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).
(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`): `renderAnnotationLayer` in
`packages/anatomy/src/render/layer.ts` turns the annotations of one view into
a pure element tree, materialised in the browser (`apps/app/src/anatomy/drawing.ts`)
or serialised by the pipeline (`draft/review/app-<view>.svg`).
(`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`); the PDF engine and the curation pipeline still
use the TypeScript renderer (`packages/anatomy/src/render`) until R4 and R5,
with the same output.
## Elements emitted per annotation
| Kind | Geometry | Elements |
|---|---|---|
| `point` | circle | transparent hitbox (`r` of the geometry, `pointer-events: all`) + visible twin (`r − 12`, category or annotation colour, `fill-opacity` 0.65 on the main view / 0.5 on a detail view, black 1.5 stroke, `pointer-events: none`) |
| `zone` | polygon or path | one filled shape (`fill-opacity` 0.3, stroke 2) |
| `detail_trigger` | polygon or path | one dashed outline (`fill-opacity` 0.06, stroke 2, dash `8,4`, class `detail-zone`) |
The element follows the geometry type, not the annotation kind, except for a
trigger.
Annotations without geometry draw nothing. Each element carries a `<title>`
"FR / EN" (native tooltip) and the attributes below.
| 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.
## Attributes (the application's read contract)
@@ -27,44 +37,56 @@ Annotations without geometry draw nothing. Each element carries a `<title>`
|---|---|
| `data-anno-id` | annotation id (stable, the report's `annotationId`) |
| `data-anno-kind` | `point`, `zone` or `detail_trigger` |
| `data-anno-name-fr`, `data-anno-name-en` | annotation name; for a trigger, the opened view's name |
| `data-anno-lateral` | `unpaired`, `bilateral`, `left` or `right` |
| `data-anno-zone` | `finding_zone_id` when the annotation links a finding zone |
| `data-anno-region` | `vertebral_region_code` when the annotation opens the vertebra picker |
| `data-anno-opens-view` | `opens_view_id` of a trigger |
| `data-state` | `current` when the annotation belongs to the active observation |
| `data-anno-name-fr`, `data-anno-name-en` | the annotation's name; a trigger without a name carries the opened view's **French** name in both |
| `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
`(annotationId, viewId)` to the interaction service
(`apps/app/src/services/zoneInteraction.ts`). Behaviour never depends on a
label, an element id or a class.
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
`categories[].color` gives the colour of every annotation of a category;
`annotations[].color` overrides it (the head view keeps the shades the legacy
file used for the TMJ, the SBS and the hyoid). Both are document data, written
by the curation changeset, never by the renderer. Without either, the renderer
falls back to `#888888`.
`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), else on the asset's own `viewBox`. A
detail view with its own `svg_asset_id` renders that asset: independent
drawings per view stay possible.
`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).
## Styling and states
The application stylesheet keeps the legacy rules: `.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. The PDF export reuses the same
layer, then recolours the selected markers and hides the others before
rasterising (`apps/app/src/pdf/render/observationPage.ts`).
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`.
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 before and after a change.
`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).