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 # Annotation rendering contract
**Status**: source of truth since Step 5. Replaces `ANATOMY-SVG-CONVENTION.md` **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 The drawing of a sheet is a plain SVG asset with no annotation element. The
application draws the markers itself from the canonical document application draws the markers itself from the canonical document
(`docs/development/ANATOMICAL_SHEET_MODEL.md`): `renderAnnotationLayer` in (`docs/development/ANATOMICAL_SHEET_MODEL.md`). One layer renderer turns the
`packages/anatomy/src/render/layer.ts` turns the annotations of one view into annotations of one view into a `<g data-layer="annotations" data-view-id="…">`
a pure element tree, materialised in the browser (`apps/app/src/anatomy/drawing.ts`) appended last to the view's `<svg>`, above the drawing. Since R3 the editor
or serialised by the pipeline (`draft/review/app-<view>.svg`). 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 ## Elements emitted per annotation
| Kind | Geometry | Elements | The element follows the geometry type, not the annotation kind, except for a
|---|---|---| trigger.
| `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`) |
Annotations without geometry draw nothing. Each element carries a `<title>` | Annotation | Elements |
"FR / EN" (native tooltip) and the attributes below. |---|---|
| `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) ## 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-id` | annotation id (stable, the report's `annotationId`) |
| `data-anno-kind` | `point`, `zone` or `detail_trigger` | | `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-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-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 Click handling walks up to the nearest `[data-anno-id]` and hands the
`(annotationId, viewId)` to the interaction service annotation id to the core's click rule (`zone.click`, R2). Behaviour never
(`apps/app/src/services/zoneInteraction.ts`). Behaviour never depends on a depends on a label, an element id or a class. The canvas sets and removes
label, an element id or a class. `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 ## Colours
`categories[].color` gives the colour of every annotation of a category; `annotations[].color` gives the colour of one annotation; otherwise the colour
`annotations[].color` overrides it (the head view keeps the shades the legacy of its category (`categories[].color`); otherwise `#888888` (no colour, or an
file used for the TMJ, the SBS and the hyoid). Both are document data, written unknown category). Colours are document data, written by the curation
by the curation changeset, never by the renderer. Without either, the renderer changeset, never by the renderer.
falls back to `#888888`.
## Views ## Views
A view renders on its `view_box` when set (the head view is the crop 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 `60 100 500 380` of the main drawing). Otherwise the canvas keeps the asset's
detail view with its own `svg_asset_id` renders that asset: independent own `viewBox`, and falls back to `0 0 100 100` when the asset has none; the PDF
drawings per view stay possible. 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 ## Styling and states
The application stylesheet keeps the legacy rules: `.svg-canvas [data-state='current']` The application stylesheet: `.svg-canvas [data-state='current']` fills the
fills the selected markers with the accent colour at 0.85, every `[data-anno-id]` selected markers with the accent colour at 0.85, every `[data-anno-id]` shows
shows a pointer cursor and brightens on hover. The PDF export reuses the same a pointer cursor and brightens on hover.
layer, then recolours the selected markers and hides the others before
rasterising (`apps/app/src/pdf/render/observationPage.ts`). ## 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 ## Checking the look
`pnpm import:equine` writes `draft/review/app-main.svg` and `app-head.svg`. `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>` (the curation pipeline's rendering, byte goldens until R5). Rasterise them with
elements first, ImageMagick's own SVG renderer drops shapes that carry one) to ImageMagick next to the legacy files (strip the `<title>` elements first,
compare markers and framing before and after a change. 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).