Files
faunosteo/docs/faunosteo-audit/04-detail-svg-generation.md
T
bastien e471d41c6b docs(docs): add anatomical audit of existing SVG, catalog and report systems
Read-only technical audit before the SaaS redesign: 13 reports,
a logical anatomical-sheet JSON built from real horse data, verbatim
copies of the 52 relevant source files, and a self-contained ZIP.
2026-10-06 23:51:35 +02:00

12 KiB

04. SVG de détail (zoom) : comment la tête du cheval a été construite

Périmètre : mécanisme réel qui relie Horse.svg à Horse_head.svg, de la production du fichier jusqu'au PDF, et ce qui manque pour généraliser "sélectionner une zone → générer un SVG zoomable".

Sources lues

  • public/species/equine/Horse.svg, public/species/equine/Horse_head.svg (diff complet)
  • src/domain/species/equine/index.ts, src/domain/species/types.ts
  • src/app/routes/SvgEditorRoute.tsx (bloc "opens detail")
  • src/app/routes/EditorRoute.tsx, src/components/canvas/DetailModal.tsx, src/components/canvas/AnatomyCanvas.tsx
  • src/anatomy/svgConvention.ts
  • src/domain/schema/observation.ts
  • src/pdf/export.ts, src/pdf/render/observationPage.ts, src/pdf/render/svgToPng.ts
  • public/pathology-editor.html
  • scripts/scaffold-species.mjs
  • docs/ANATOMY-SVG-CONVENTION.md
  • historique git des deux SVG

1. Constat central

FACTUEL. Aucun code du dépôt ne génère un SVG de détail. Un grep viewBox sur src/, scripts/ et public/pathology-editor.html ne renvoie que trois usages : la valeur par défaut posée au chargement quand l'attribut manque (SvgEditorRoute.tsx:543-549, pathology-editor.html:1139-1143) et la lecture du ratio pour dimensionner le PNG de rasterisation (svgToPng.ts:29-41). Aucune fonction ne lit un polygone pour en dériver un cadrage, ne découpe un SVG, ne recalcule des coordonnées, ni n'écrit un fichier.

FACTUEL. Ce que fait l'éditeur SVG : poser data-anno-opens-detail="<id>" sur un polygone existant et retirer ses attributs de nommage/catégorie (SvgEditorRoute.tsx:1131-1141). Voir 03-svg-editor.md, section 6.3.

FACTUEL. Le lien entre cet id et un fichier est déclaré à la main dans le manifeste d'espèce :

// src/domain/species/equine/index.ts:8-11
mainSvg: '/species/equine/Horse.svg',
details: {
  head: '/species/equine/Horse_head.svg',
},

Le type SpeciesManifest.details est un Record<string, string> dont les clés doivent correspondre aux valeurs de data-anno-opens-detail (src/domain/species/types.ts:22-28). Le script scripts/scaffold-species.mjs:138-155 demande ces clés et chemins à l'opérateur ; il ne crée pas le fichier SVG.

2. Anatomie du fichier Horse_head.svg

FACTUEL (diff Horse.svg ↔ Horse_head.svg, 10 lignes de diff sur 704 lignes chacun) :

Élément Horse.svg Horse_head.svg
viewBox racine 0 0 2073.4 1629.4 60 100 500 380
Lignes 3 à 703 (dessin complet du cheval : gradients, filtres, <g> et <path>) identiques identiques
Ligne 704, groupe <g id="osteo-overlays"> 12 points + 5 polygones colonne + 1 polygone déclencheur 9 points

Conséquences factuelles :

  • Le fichier de détail contient l'intégralité du dessin du corps. Seul le viewBox recadre l'affichage sur la tête. Le poids du fichier est dupliqué.
  • Les coordonnées des points de la tête sont exprimées dans le repère du SVG principal. Exemple : point-mpbykomv (Pariétal) à cx="348" cy="161", compris dans la fenêtre x ∈ [60, 560], y ∈ [100, 480]. Aucune translation, aucune mise à l'échelle.
  • Les rayons des points de la tête (r=27 / r=15) sont plus petits que ceux du corps (r=34 / r=22), ce qui est cohérent avec un dessin à une échelle d'affichage plus grande. Ce choix est manuel.

FACTUEL. Le polygone déclencheur zone-mpby55kd dans Horse.svg a 15 sommets, boîte englobante x ∈ [164, 454], y ∈ [150, 468]. Cette boîte est incluse dans la fenêtre 60 100 500 380 du détail mais n'en est pas égale, et aucun code ne compare les deux.

DEDUIT. Le fichier a été produit à la main : copie de Horse.svg, édition du viewBox, puis ajout des 9 points probablement via l'éditeur SVG (les points portent les mêmes attributs, le même groupe osteo-overlays, les mêmes <title> "FR / EN" que ceux que produit addCircleAt + applyEdit). L'historique git ne contient pas de script ni de commit intermédiaire : Horse_head.svg entre au commit de scaffold 8ca36b5 puis est modifié par les renommages d'attributs et l'adoption du catalogue v2.0.

3. Réponses aux dix questions du brief

  1. Comment la zone sélectionnée est choisie : il n'y a pas de sélection logicielle. L'auteur du SVG dessine un polygone en mode polygon, le sélectionne et coche "Cette zone ouvre une vue détaillée" en saisissant un id (SvgEditorRoute.tsx:136-152).
  2. Comment le contour est récupéré : il ne l'est pas. Les points du polygone ne sont lus par aucun code en dehors du drag et des poignées de l'éditeur.
  3. Comment le nouveau SVG de détail est créé : manuellement, hors de l'application (section 2).
  4. Transformations : aucune.
  5. Recalcul des coordonnées : aucun, même repère.
  6. Calcul du viewBox : manuel. Valeur 60 100 500 380, non reliée au polygone.
  7. Comment le parent sait qu'un détail existe : deux déclarations indépendantes. (a) L'attribut data-anno-opens-detail="head" sur l'élément du SVG parent, lu par parseSvgBones dans Bone.opensDetail (svgConvention.ts:53-54). (b) La clé head dans species.details. Le clic n'ouvre le détail que si les deux existent : if (bone.opensDetail && species?.details[bone.opensDetail]) (EditorRoute.tsx:295). Un attribut sans clé de manifeste est silencieusement ignoré et le clic tombe dans le flux "zone normale" (DEDUIT du if suivant, EditorRoute.tsx:300-319 : le déclencheur n'a pas de special ni de lateral, il serait donc ajouté comme zone via toggleZone).
  8. Chargement dans l'application :
    • au montage de l'éditeur de bilan, tous les fichiers de species.details sont préchargés et parsés dans detailBones, chaque fetch étant indépendant (EditorRoute.tsx:138-152) ;
    • au clic sur le déclencheur, handleDetailOpen pose l'état detail = { id, src, title } (EditorRoute.tsx:202-208), titre = libellé du bone ou id ;
    • un effet reparse le détail ouvert et le fusionne dans detailBones sans écraser les ids déjà connus (EditorRoute.tsx:162-173, mergeBones EditorRoute.tsx:36-42) ;
    • DetailModal rend un AnatomyCanvas avec src=detailSrc dans un Dialog xl, et remonte chaque clic sous la forme (boneId, detailId) (DetailModal.tsx:27-33) ;
    • onZoneClick(boneId, detailSourceId) résout le bone par bones.get(boneId) ?? detailBones.get(boneId) (EditorRoute.tsx:292) et crée une ObservationZone portant detailSourceId (EditorRoute.tsx:234-237, EditorRoute.tsx:279-282, EditorRoute.tsx:537-543).
  9. Données permettant de retrouver le détail : ObservationZone.detailSourceId (observation.ts:24-25), valeur = clé de details (head). Le chemin du fichier n'est jamais persisté ; il est re-résolu via le manifeste de l'espèce du rapport à chaque rendu et à chaque export.
  10. Limites : section 5.

4. Propagation jusqu'au PDF

FACTUEL observationPage.ts:361-395 (buildObservationImages) :

  • une image "VUE GÉNÉRALE" (pdf.view.general) est rendue si au moins une zone n'a pas de detailSourceId ;
  • une image par detailSourceId distinct présent dans l'observation, libellée pdf.view.detail_prefix + id en majuscules (observationPage.ts:380), soit "VUE DÉTAIL — HEAD" ;
  • un detailSourceId absent du manifeste est ignoré sans erreur (observationPage.ts:377-378).

FACTUEL observationPage.ts:214-255 (colorizedSvgString) : recharge le fichier SVG, ne conserve en couleur que les zones dont detailSourceId est égal à celui de la vue, masque les autres (display="none"), applique un halo flou seulement sur la vue générale, retire tous les attributs data-anno-* avant sérialisation.

FACTUEL export.ts:38-69 (buildZoneLabels) : les libellés imprimés proviennent du re-parse de mainSvg et de chaque details au moment de l'export, par id. Un détail introuvable produit un avertissement console et le PDF imprime l'id brut (observationPage.ts:406-407).

5. Limites actuelles

Limite Preuve
Un seul niveau de détail en pratique DEDUIT. Si un SVG de détail portait data-anno-opens-detail, le parser le lirait et onZoneClick l'honorerait depuis le modal (le bone vient de detailBones, EditorRoute.tsx:292-298) : setDetail remplacerait le détail courant dans le même modal. Mais buildObservationImages ne rend qu'une image par detailSourceId sans hiérarchie, et le detailSourceId d'une zone cliquée dans ce second détail serait la clé du second détail, sans trace du chemin. Rien ne l'interdit, rien ne le gère.
Le déclencheur n'est jamais persisté FACTUEL EditorRoute.tsx:295-298 : handleDetailOpen puis return avant tout ajout de zone. docs/ANATOMY-SVG-CONVENTION.md:155 le documente. Il n'a pas de nom, donc aucun match catalogue (06-svg-findings-link.md).
Espace d'ids partagé entre principal et détails FACTUEL EditorRoute.tsx:175-181 et mergeBones : premier arrivé conservé, collision silencieuse. Les ids sont des horodatages base 36 générés sans registre (03-svg-editor.md E).
Le tooltip masque les déclencheurs FACTUEL AnatomyCanvas.tsx:93 : !el.hasAttribute('data-anno-opens-detail'). Le polygone de la tête n'affiche aucun libellé au survol (il n'en a pas).
Fichier dupliqué FACTUEL section 2 : 703 lignes identiques.
Aucune métadonnée de cadrage persistée FACTUEL : ni le polygone ni le manifeste ne stockent la fenêtre 60 100 500 380 ; seule la racine du fichier de détail la porte.
Liste d'espèces codée en dur dans l'éditeur de pathologies FACTUEL pathology-editor.html:786-796 : SPECIES_CONFIG répète Horse.svg, Horse_head.svg et pathologies.json indépendamment du manifeste TypeScript. Un nouveau détail doit être ajouté à deux endroits.
Chemins absolus /species/... FACTUEL manifeste + loadSvg(publicPath) (svgLoader.ts:1-2). Les fichiers doivent être servis à la racine web.
Le détail ne sait pas d'où il vient FACTUEL : Horse_head.svg ne contient aucune référence à Horse.svg ni à zone-mpby55kd.
Préchargement sans mise en cache FACTUEL : EditorRoute précharge au montage, DetailModal recharge à chaque ouverture (AnatomyCanvas effet [src]), buildZoneLabels et colorizedSvgString rechargent à l'export. Quatre fetch du même fichier au minimum.

6. Généralisation « sélectionner une zone → générer automatiquement un SVG zoomable »

Ce qui existe déjà et pourrait servir de matière (FACTUEL) :

  • un polygone de zone avec ses points dans le repère du SVG (finalizePolygon, SvgEditorRoute.tsx:1357-1360) ;
  • la conversion écran → repère SVG (getSVGPoint, SvgEditorRoute.tsx:927-932) ;
  • un viewBox racine toujours présent après chargement (SvgEditorRoute.tsx:543-549) ;
  • l'identité structurelle parent/détail : même dessin, même repère, seul le viewBox diffère, ce qui rend le "zoom par viewBox" trivial à produire par copie ;
  • le contrat de liaison déjà en place côté application : attribut data-anno-opens-detail + entrée details + detailSourceId sur la zone d'observation, qui fonctionne pour n'importe quel nombre de détails tant que chaque id est unique ;
  • la sérialisation et le téléchargement d'un SVG (exportSVG).

Ce qui manque (FACTUEL, absent du code) :

  • calcul d'une boîte englobante à partir des points d'un polygone, avec marge ;
  • écriture d'un second fichier avec ce viewBox, ou d'un viewBox par détail stocké dans un format de données ;
  • enregistrement du mapping id → fichier ailleurs que dans un fichier TypeScript édité à la main ;
  • un espace d'ids distinct ou préfixé par détail ;
  • une gestion de la profondeur (détail de détail) dans les zones d'observation et dans le PDF ;
  • un mécanisme d'écriture (l'éditeur ne peut que télécharger).

Aucune solution n'est proposée ici ; voir 11-future-merge.md pour la liste des points de couplage.

Points non déterminés

  • Outil exact utilisé pour produire Horse_head.svg (éditeur SVG du projet, éditeur de texte, Inkscape). HYPOTHESE : éditeur SVG du projet pour les points, édition manuelle pour le viewBox.
  • Comportement réel d'un détail imbriqué : DEDUIT de la lecture, jamais testé (aucun test ni fixture n'en contient).