Files
faunosteo/docs/ANNOTATION-RENDERING.md
T

71 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 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`).
## 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`) |
Annotations without geometry draw nothing. Each element carries a `<title>`
"FR / EN" (native tooltip) and the attributes below.
## 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-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 |
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.
## 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`.
## 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.
## 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`).
## 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.