Files
faunosteo/docs/ANATOMY-SVG-CONVENTION.md
2026-05-23 22:22:33 +02:00

180 lines
6.3 KiB
Markdown
Raw Permalink 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.
# Anatomy SVG Convention
**Status**: Source of truth. All SVG assets and parser code must conform.
---
## Required data attributes
Every clickable zone element must carry all four attributes:
| Attribute | Type | Description |
|---|---|---|
| `data-anno-id` | `string` | Stable kebab-case identifier. Unique per bone. |
| `data-anno-name-fr` | `string` | French anatomical label (e.g. "Colonne cervicale"). |
| `data-anno-name-en` | `string` | English anatomical label (e.g. "Cervical spine"). |
| `data-anno-category` | `BoneCategory` | One of the seven valid categories below. |
## Optional data attributes
| Attribute | Type | Description |
|---|---|---|
| `data-anno-opens-detail` | `string` | Id of the detail popup SVG to open on click. Key must exist in `SpeciesManifest.details`. |
| `data-anno-special` | `string` | Free-form behavior hint consumed by the app. Known value: `vertebral-precision` → clicking the zone opens VertebraPicker. Opaque to the parser; new values can be added without code changes (just unused). |
| `data-anno-lateral` | `string` | Laterality hint: `bilateral` (zone has left/right instances, e.g. knee) or `unpaired` (no laterality). Default when absent: `unpaired`. Used by the report editor to prompt side selection on bilateral zones. |
---
## Valid categories
| Value | Meaning |
|---|---|
| `articulation` | Joint space |
| `charniere` | Junctional / transitional zone |
| `spine-zone` | Vertebral region bloc — click opens VertebraPicker |
| `os` | Single bone |
| `os-overlay` | Overlapping bone layer |
| `head` | Head region (main SVG entry point for detail popup) |
| `cadran-crane` | Cranial quadrant (inside detail popup) |
---
## Rendering patterns
### Pattern 1 — Hitbox + visible twin
Used for: `articulation`, `charniere`, `os-overlay`, `head`.
Two sibling SVG elements share the **same** `data-anno-id`:
```xml
<!-- hitbox: transparent fill, receives pointer events -->
<polygon
data-anno-id="cervical-spine"
data-anno-name-fr="Colonne cervicale"
data-anno-name-en="Cervical spine"
data-anno-category="spine-zone"
class="bone-hitbox"
fill="transparent"
style="pointer-events: all; cursor: pointer"
/>
<!-- visible twin: colored fill, no pointer events -->
<polygon
data-anno-id="cervical-spine"
class="bone-visible"
fill="#c8d8e8"
style="pointer-events: none"
/>
```
- Hitbox must have `class` containing `hitbox` (case-insensitive substring).
- Visible twin must have `class` containing `visible`.
- Order in DOM does not matter — parser groups by `data-anno-id`.
### Pattern 2 — Single element
Used for: `spine-zone`, standalone `head` zones inside detail SVGs.
One polygon carries everything:
```xml
<polygon
data-anno-id="thoracic-t1-t18"
data-anno-name-fr="Thoracique T1-T18"
data-anno-name-en="Thoracic T1-T18"
data-anno-category="spine-zone"
fill="#d4e8d4"
style="pointer-events: all; cursor: pointer"
/>
```
---
## Parser behavior (`src/anatomy/svgConvention.ts`)
1. `parseSvgBones(svgRoot)` — walks all elements with `data-anno-id`.
2. Groups by `data-anno-id` → one `Bone` per id.
3. For each group, validates required attributes.
4. Classifies elements into `hitboxEls` (class contains "hitbox") and `visibleEls` (class contains "visible"). Elements in neither class land in `visibleEls` by default.
5. Returns `Map<string, Bone>`.
6. Throws `SvgConventionError(message, boneId, missingAttribute)` on first violation.
### Validated rules
- `data-anno-name-fr` must be non-empty.
- `data-anno-name-en` must be non-empty.
- `data-anno-category` must be one of the seven valid values.
- If `data-anno-opens-detail` is present, the value must be a non-empty string (runtime check against species manifest happens in the canvas component).
---
## Click handling (delegated listener)
A single `click` listener on the root `<svg>` element:
```
event.target → walk up ancestors → find data-anno-id
→ if data-anno-opens-detail present → emit requestDetail({id})
→ else if data-anno-special === 'vertebral-precision' →
add zone to current observation (if absent) and open VertebraPicker
→ else → toggle bone in current observation
```
Never attach per-element click listeners — the SVG may have thousands of elements.
Note: `data-anno-category` is opaque to click handling — branching is
driven by `data-anno-opens-detail` and `data-anno-special` only.
---
## Zone visual states
Applied as `data-state` attribute on all elements sharing a `data-anno-id`:
| `data-state` | Condition | Visual |
|---|---|---|
| `current` | Bone is in the active observation | Solid accent fill |
| `linked` | Bone is in another (non-active) observation | Faded dashed border, accent color of owning obs |
| `multi` | Bone is in ≥2 observations | Striped CSS background pattern + indicator badge |
| *(absent)* | Default / unselected | SVG original fill |
Accent colors cycle through 6 HSL tones (defined in `src/styles/tokens.css`):
terracotta → sauge → bleu canard → ambre → prune → ocre.
---
## Detail popup mechanism
When a zone has `data-anno-opens-detail="head"`:
1. Canvas emits `requestDetail({ id: 'head' })`.
2. `DetailModal` resolves the path via `SpeciesManifest.details['head']`.
3. Loads and renders the detail SVG inline.
4. Clicks inside the modal add `ObservationZone` entries with `detailSourceId: 'head'`.
5. The "entry" zone itself (the polygon that triggered the popup) is **never** persisted.
---
## Vertebra picker trigger
When a bone has `data-anno-special="vertebral-precision"`, clicking it adds the
zone to the active observation (if absent) and opens `VertebraPicker`:
- Region tabs: Cervicales (C1–C7), Thoraciques (T1–T18), Lombaires (L1–L6), Sacrales (S1–S5), Caudales (Cd1–Cd18).
- Multi-select chip grid, ≥40 px touch targets.
- Per-region "Tout cocher / Tout décocher".
- Stored as `vertebrae: Vertebra[]` on `ObservationZone`, replacing the bloc semantically.
- PDF prints precise vertebrae: "T12, T15" instead of the zone label.
---
## Adding a new SVG
1. Place SVG at `public/species/<speciesId>/<filename>.svg`.
2. Ensure every clickable element has the four required attributes.
3. Use Pattern 1 or Pattern 2 consistently per category.
4. Add to `SpeciesManifest.details` if it is a detail popup SVG.
5. Run `pnpm test:run` — the convention parser tests will catch missing attributes.
6. See `docs/ADDING-A-SPECIES.md` for adding a full new species.