diff --git a/docs/ANNOTATION-RENDERING.md b/docs/ANNOTATION-RENDERING.md index 0a7f8f90..2b0fde1c 100644 --- a/docs/ANNOTATION-RENDERING.md +++ b/docs/ANNOTATION-RENDERING.md @@ -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-.svg`). +(`docs/development/ANATOMICAL_SHEET_MODEL.md`). One layer renderer turns the +annotations of one view into a `` +appended last to the view's ``, 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 `` -"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 `` +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).