Validate POC A and POC B foundations

docs/POC_B_TECHNICAL_BASELINE.md

@@ -0,0 +1,430 @@
+# POC B — Bilan technique consolidé du sonar bathymétrique
+
+## Statut
+
+- Date de consolidation : 7 août 2026.
+- État : direction validée et POC figé comme référence de conception.
+- Nature : prototype jetable sous Godot 4.7.1, renderer GL Compatibility.
+- Dépendance : reprend le véhicule, le POV et les commandes validés dans le POC A.
+- Conclusion : la représentation bathymétrique 3D est retenue ; le système n'est
+  pas considéré comme finalisé ni prêt pour la production.
+
+Le joueur a jugé la dernière version « vraiment mieux » et sa direction
+« bien meilleure », tout en signalant qu'il reste des raffinements. Cette
+validation porte sur le langage visuel et la boucle d'utilisation, pas sur tous
+les réglages, la fidélité acoustique ou la qualité graphique définitive.
+
+## Résultat du POC
+
+Le sonar devient compréhensible lorsqu'il représente le fond marin comme un
+modèle numérique de terrain continu observé en perspective. Le joueur peut lire
+les creux et les hauteurs, identifier un passage et distinguer une anomalie sans
+interpréter un nuage de points abstrait.
+
+La boucle validée est la suivante :
+
+1. Le joueur déclenche manuellement une impulsion avec F.
+2. La carte se révèle pendant 2,5 secondes, du proche vers le lointain.
+3. La couleur code l'élévation et l'ombrage montre les pentes.
+4. Une anomalie matérielle est renforcée en orange.
+5. Le joueur peut consulter le résultat dans un petit écran ou l'agrandir.
+6. Un nouveau scan remplace progressivement le précédent.
+
+## Historique des essais et leçons
+
+### Essai 1 — distance, azimut et points
+
+Le premier système montrait une progression de retours ponctuels et des
+distances. Le joueur comprenait la notion de distance, mais ne pouvait ni
+reconnaître le relief ni transformer les points en itinéraire. L'image devenait
+encore plus déroutante lorsque son orientation ne suivait pas clairement le cap.
+
+Leçon : une donnée techniquement interprétable n'est pas nécessairement une
+information navigable. La rotation de la représentation avec le véhicule est
+indispensable, mais ne suffit pas à rendre des points lisibles.
+
+### Essai 2 — surfaces facettées
+
+Les impacts ont ensuite été reliés en plaques. Les fragments paraissaient
+flotter et le joueur ne reconnaissait qu'une vague forme en T.
+
+Leçon : relier des échos ne produit pas automatiquement un terrain. Il faut une
+surface cohérente, un référentiel stable et une lecture explicite de la hauteur.
+
+### Essai 3 — volumes voxelisés
+
+Les plaques ont été épaissies et fusionnées en voxels de trois mètres. Le relief
+avait davantage de masse, mais les blocs et leurs ruptures dominaient toujours
+la lecture. La scène restait illisible.
+
+Leçon : l'épaisseur ne corrige pas une mauvaise grammaire visuelle. Points,
+facettes et voxels sont abandonnés pour l'affichage principal.
+
+### Essai 4 — modèle bathymétrique continu
+
+La dernière version s'inspire des modèles numériques d'élévation : grille
+régulière, surface continue, caméra oblique, palette d'altitude et relief
+ombré. La scène cubique a également été remplacée par un fond sculpté. Après un
+premier test concluant, la portée a été augmentée et la caisse métallique rendue
+plus visible.
+
+Leçon : la lisibilité vient de la combinaison de trois indices redondants :
+silhouette continue, couleur d'altitude et ombrage. Aucun de ces indices ne doit
+porter seul toute l'information.
+
+## Décisions de conception validées
+
+### Déclenchement et temporalité
+
+- Le scan est une action manuelle sur F.
+- Le résultat ne doit jamais être immédiat.
+- Les retours proches apparaissent avant les retours lointains.
+- La durée de référence est de 2,5 secondes pour 95 mètres.
+- Un délai technique de 0,35 seconde suit un scan avant la prochaine impulsion.
+- Le scan automatique est réservé à une amélioration future.
+- Une éventuelle difficulté facile pourra fournir davantage d'assistance, mais
+  aucune aide automatique n'est requise dans la baseline.
+
+### Présentation
+
+- Le sonar montre une maquette 3D continue du fond devant le sous-marin.
+- Le point de vue est oblique et légèrement surélevé, comparable à une carte de
+  relief plutôt qu'à un écran radar.
+- Le sous-marin blanc reste en bas de l'image et son cap pointe vers le haut.
+- La caméra ne devient jamais une caméra libre sortant du véhicule.
+- Lorsque le sous-marin tourne, la vue sonar tourne avec lui.
+- Noir signifie inconnu ou hors de la couverture.
+- Bleu signifie bas/profond ; cyan et vert signifient relief intermédiaire ;
+  jaune et rouge signifient haut.
+- Orange signale un matériau anormal. Dans le POC, il s'agit d'une caisse.
+- Les ouvertures ne sont ni nommées, ni encadrées, ni indiquées par une flèche.
+
+### Interface
+
+- Un petit écran sonar reste présent dans le cockpit.
+- Un clic sur cet écran l'agrandit ; Tab fournit le même basculement.
+- La vue agrandie affiche exactement la même texture que la petite.
+- Ouvrir la grande vue ne suspend ni la simulation ni les commandes clavier.
+- Le véhicule peut donc poursuivre son mouvement pendant la consultation.
+- Le statut textuel indique le pourcentage, la fin du scan et la présence d'une
+  anomalie, sans expliquer automatiquement la géométrie du terrain.
+
+### Mémoire des relevés
+
+- Le POC ne construit pas une carte persistante du monde.
+- Un seul relevé précédent est conservé pendant l'arrivée du suivant.
+- Cet ancien relevé passe d'environ 52 % d'opacité à l'invisibilité pendant les
+  2,5 secondes du nouveau scan.
+- Il est supprimé lorsque le nouveau relevé est terminé.
+
+## Baseline numérique du capteur
+
+| Paramètre | Valeur actuelle |
+|---|---:|
+| Portée minimale | 5 m |
+| Portée maximale | 95 m |
+| Ouverture horizontale | 76° |
+| Grille bathymétrique | 49 colonnes × 31 lignes |
+| Nombre maximal d'échantillons de terrain | 1 519 |
+| Durée de révélation | 2,5 s |
+| Premier retour planifié | 4 % du scan, soit environ 0,10 s |
+| Délai après impulsion | 0,35 s |
+| Masque physique | couche 1 |
+| Taille de cellule du modèle d'échos | 0,65 m |
+| Hauteur de départ des sondes de terrain | 48 m au-dessus du capteur |
+| Profondeur des sondes de terrain | 92 m sous le capteur |
+
+L'origine logique du capteur se trouve à `(0 ; -0,75 ; -2,2)` mètres dans le
+repère local du sous-marin. La grille forme un trapèze qui s'élargit selon
+`tan(76° / 2) × distance`.
+
+Pour chaque ligne, le temps de révélation est interpolé de 4 % à 100 % de la
+durée totale. Le balayage visible est donc volontairement piloté par la distance
+avant et non par une simulation exacte du temps aller-retour acoustique.
+
+## Acquisition bathymétrique actuelle
+
+La passe principale ne projette pas réellement 1 519 rayons depuis le nez. Elle
+place une grille horizontale devant le véhicule et lance, pour chaque cellule,
+une sonde verticale de haut en bas. Le premier impact fournit :
+
+- la position mondiale ;
+- la normale de surface ;
+- la distance au capteur ;
+- la ligne et la colonne ;
+- l'intensité ;
+- la catégorie de matériau ;
+- le type d'échantillon ;
+- le temps de retour visuel ;
+- l'élévation normalisée.
+
+Cette technique est un substitut de POC destiné à produire une carte d'altitude
+continue et lisible. Elle peut révéler le dessus d'un relief que le capteur réel
+ne verrait pas directement. Elle ne doit donc pas être présentée comme une
+simulation fidèle d'un sonar multifaisceau.
+
+L'intensité combine :
+
+1. une atténuation linéaire avec la distance ;
+2. une réponse d'incidence allant de 0,18 à 1 ;
+3. une réflectivité propre au collider ;
+4. un bornage entre 0 et 1.
+
+La passe bathymétrique utilise une portée d'intensité interne égale à 1,4 fois
+la portée nominale afin de ne pas perdre les coins éloignés du trapèze.
+
+## Détection complémentaire des anomalies
+
+Une seconde passe utilise 31 × 21 rayons réellement projetés depuis le nez :
+
+| Paramètre | Valeur actuelle |
+|---|---:|
+| Ouverture horizontale | 76° |
+| Ouverture verticale | 64° |
+| Inclinaison centrale | -18° |
+| Portée | 95 m |
+
+Seuls les impacts classés `METAL` sont conservés. Cette passe permet de détecter
+une anomalie frontale sans réintroduire le nuage de points dans l'affichage.
+
+Le renderer moyenne actuellement toutes les positions métalliques et affiche un
+seul marqueur. Plusieurs objets éloignés seraient donc fusionnés en une position
+moyenne incorrecte. La production devra regrouper les retours en amas distincts.
+
+## Normalisation de l'élévation
+
+Pour chaque scan, l'altitude minimale devient 0 et l'altitude maximale devient
+1, avec une amplitude minimale forcée à six mètres. Ce choix garantit un bon
+contraste même sur un terrain peu accidenté.
+
+Conséquence : une même couleur ne correspond pas nécessairement à la même
+profondeur absolue entre deux scans. La palette actuelle communique la forme
+locale, pas une mesure bathymétrique universelle. Une production devra choisir
+entre contraste adaptatif, échelle absolue ou combinaison des deux avec une
+légende chiffrée.
+
+## Reconstruction et rendu
+
+### Maillage
+
+- Les échantillons sont indexés par `(colonne, ligne)`.
+- Deux triangles relient chaque groupe complet de quatre cellules adjacentes.
+- Les normales des faces sont accumulées puis normalisées par sommet pour lisser
+  l'éclairage.
+- Une absence d'échantillon interrompt le maillage ; les zones inconnues ne sont
+  pas comblées automatiquement.
+- Les deux faces de la surface sont rendues afin que le tangage du véhicule ne
+  la fasse pas disparaître.
+- Une jupe verticale de 4,5 mètres ferme le pourtour et donne à la carte l'aspect
+  d'une maquette solide.
+- Le maillage complet est actuellement reconstruit sur le CPU chaque fois que le
+  nombre de retours visibles change.
+
+Cette dernière stratégie est acceptable pour le POC mais coûteuse. Un système
+de production devra mettre à jour des bandes ou tuiles incrémentales, réutiliser
+les buffers ou déléguer une partie de la reconstruction au GPU.
+
+### Palette
+
+| Intervalle normalisé | Dégradé |
+|---|---|
+| 0 à 0,28 | `#173f91` vers `#168fc1` |
+| 0,28 à 0,52 | `#168fc1` vers `#36b979` |
+| 0,52 à 0,76 | `#36b979` vers `#d7d93d` |
+| 0,76 à 1 | `#d7d93d` vers `#ee5734` |
+| Métal | `#ff6b22` |
+| Jupe | `#152a32` |
+| Inconnu | fond `#020407` |
+
+L'intensité du retour ajoute au maximum 8 % de blanc à la couleur du terrain.
+
+### Viewport et caméra
+
+| Paramètre | Valeur actuelle |
+|---|---:|
+| `SubViewport` | 960 × 540 |
+| Mise à jour | continue |
+| Projection | orthographique |
+| Taille orthographique | 116 m |
+| Plan lointain | 240 m |
+| Position caméra relative | 30 m derrière, 65 m au-dessus |
+| Point visé relatif | 43 m devant, 8 m sous le véhicule |
+
+Le sonar possède son propre `World3D`, son environnement, deux lumières
+directionnelles et sa caméra. Ce découplage permet aux vues compacte et agrandie
+de partager une image stable indépendamment de la caméra principale.
+
+L'environnement utilise un tonemapper filmique, une énergie ambiante de 0,42,
+une lumière principale d'énergie 1,25 avec ombres et une lumière de remplissage
+d'énergie 0,38.
+
+### Repères visuels
+
+- Le sous-marin est une capsule blanche émissive de 5,8 mètres, prolongée par un
+  nez conique.
+- La caisse/anomalie est représentée par un cube orange non éclairé de
+  `8 × 4,5 × 8` mètres, avec une émission d'énergie 4.
+- Le cube est placé 1,4 mètre au-dessus de la moyenne des retours métalliques
+  afin de rester identifiable dans la petite vue.
+
+Ces dimensions sont des exagérations d'interface, pas les dimensions physiques
+exactes des objets détectés.
+
+## Baseline de l'interface
+
+| Élément | Dimensions actuelles |
+|---|---:|
+| Panneau compact | 320 × 276 px |
+| Texture compacte | 298 × 190 px |
+| Panneau agrandi | 1 060 × 652 px |
+| Texture agrandie | 1 038 × 556 px |
+
+La légende actuelle est : bleu profond, vert/jaune hauteur, orange
+caisse/anomalie, noir inconnu. L'interface rappelle la portée de 95 mètres et le
+fait que le cap se trouve vers le haut.
+
+Les textes, tailles, bordures et positions sont provisoires. Sont validés : la
+présence des deux formats, leur texture commune, le clic d'agrandissement et la
+continuité de la simulation.
+
+## Scène de calibration
+
+| Élément | Valeur actuelle |
+|---|---:|
+| Position initiale du sous-marin | `(0 ; -25 ; 22)` m |
+| Terrain physique | 150 × 170 m |
+| Centre longitudinal du terrain | z = -28 m |
+| Maillage du terrain | 61 × 69 sommets |
+| Collision | `ConcavePolygonShape3D`, double face |
+| Position horizontale de la caisse | `(0 ; -45)` m |
+| Taille physique de la caisse | `8 × 5 × 7` m |
+
+Le terrain est généré par une pente légère, deux ondulations sinusoïdales et des
+fonctions gaussiennes. Il contient deux reliefs proches, deux crêtes hautes, une
+crête arrière et une dépression centrale étroite. Cette dépression forme un
+chenal en U lisible comme passage possible. La caisse repose dans ce chenal.
+
+La scène est un instrument de calibration de lisibilité. Sa topologie et ses
+dimensions ne constituent pas une règle de level design.
+
+## Architecture et flux de données
+
+### Fichiers principaux
+
+| Fichier | Responsabilité actuelle |
+|---|---|
+| `src/sonar_system.gd` | Déclenchement, acquisition, calendrier des retours et historique court |
+| `src/sonar_model.gd` | Déduplication spatiale et calcul d'intensité |
+| `src/sonar_relief_renderer.gd` | Reconstruction du maillage et rendu bathymétrique |
+| `src/sonar_hud.gd` | Vues compacte/agrandie, statuts, légende et interactions |
+| `src/poc_b.gd` | Assemblage du POC et génération de la scène de calibration |
+| `tests/run_poc_b_integration.gd` | Validation automatisée de la boucle complète |
+
+### Signaux
+
+- `ping_started()` vide le relevé courant et prépare le fondu du précédent.
+- `ping_progress(current_cells, previous_cells, progress)` alimente le maillage
+  progressif et les statuts.
+- `ping_completed(current_cells, previous_cells)` fige le nouveau résultat et
+  supprime l'ancien.
+- `expanded_changed(is_expanded)` gère notamment la capture de la souris.
+
+Les tableaux sont actuellement copiés en profondeur entre le système, les
+signaux et le renderer. Cette simplicité protège le POC des mutations partagées,
+mais deviendra coûteuse avec une carte plus grande.
+
+## Ce qui est validé et ce qui ne l'est pas
+
+### Validé
+
+- Principe d'une surface bathymétrique 3D continue.
+- Caméra oblique, orthographique et alignée sur le cap.
+- Triple lecture par silhouette, couleur d'altitude et ombrage.
+- Impulsion manuelle et résultat non immédiat.
+- Révélation du proche vers le lointain en 2,5 secondes.
+- Portée de POC suffisamment utile à 95 mètres et couverture de 76°.
+- Petit écran cliquable et vue agrandie non bloquante.
+- Remplacement progressif d'un seul relevé précédent.
+- Différenciation orange d'une anomalie.
+- Absence d'aide automatique signalant les ouvertures.
+
+### Provisoire
+
+- Toutes les valeurs numériques de portée, résolution et durée.
+- Palette exacte et seuils de couleur.
+- Caméra, éclairage, taille de la jupe et modèle du sous-marin.
+- Taille exagérée du marqueur de caisse.
+- Terrain et objet de calibration.
+- Textes et composition de l'interface.
+- Maintien d'un seul relevé précédent.
+- Utilisation du renderer GL Compatibility.
+
+### À reprendre ou approfondir
+
+- Acquisition physiquement crédible depuis le capteur sous le nez.
+- Représentation des parois verticales, plafonds, grottes et surplombs.
+- Regroupement et représentation de plusieurs anomalies.
+- Échelle bathymétrique absolue ou légende de profondeur.
+- Coût énergétique, bruit, faux retours et interférences.
+- Résolution et portée variables selon les améliorations du véhicule.
+- Accessibilité de la palette et alternatives à la couleur.
+- Courbes de niveau éventuelles dans la grande vue seulement.
+- Performance de reconstruction et allocations mémoire.
+- Contrôles à la manette et navigation complète dans l'interface.
+
+## Limite structurelle : grottes et surplombs
+
+Une carte d'altitude associe une seule hauteur à chaque position horizontale.
+Elle ne peut donc pas représenter simultanément le toit et le sol d'une grotte,
+ni un objet situé sous un surplomb.
+
+La production devra probablement utiliser une solution hybride :
+
+1. une carte bathymétrique continue pour le fond extérieur ;
+2. des surfaces locales supplémentaires pour les parois et plafonds visibles ;
+3. une règle d'occlusion empêchant de révéler ce que l'impulsion ne peut pas
+   atteindre ;
+4. une transition visuelle cohérente entre carte extérieure et intérieur scanné.
+
+Ce problème doit être testé dans un niveau réel, pas résolu en ajoutant des
+voxels à la baseline validée.
+
+## Vérification technique
+
+- 13 tests unitaires headless passent : neuf pour la survie et quatre pour la
+  fondation sonar.
+- 14 assertions d'intégration POC B passent.
+- L'intégration vérifie la durée, la portée, l'ouverture, le caractère non
+  immédiat, la densité du relevé, les coordonnées de grille, l'élévation, la
+  détection métallique, la génération de faces, l'agrandissement, la conservation
+  d'un relevé précédent et son remplacement progressif.
+- Le rendu a été contrôlé en 960 × 540 puis réduit à 298 × 190.
+- La vérification visuelle a été effectuée en OpenGL Compatibility sur Apple M1.
+
+Les tests ne valident pas automatiquement la compréhension humaine du relief,
+la perception des couleurs, la fidélité acoustique, les performances sur une
+grande carte ni le comportement de plusieurs anomalies.
+
+## Contrat de reprise pour la production
+
+Le code du POC B peut servir de référence, d'outil de calibration ou de point de
+départ temporaire. Il ne doit pas devenir silencieusement le sonar de production.
+
+Une réécriture devra préserver :
+
+- la surface continue et son orientation stable ;
+- la progression temporelle proche-vers-lointain ;
+- l'action manuelle et la possibilité d'une amélioration automatique ;
+- les formats compact et agrandi ;
+- la redondance couleur, volume et anomalie ;
+- le principe de ne pas révéler automatiquement le chemin.
+
+Elle devra remplacer explicitement :
+
+- les sondes verticales par un modèle d'acquisition cohérent avec le gameplay ;
+- la reconstruction complète à chaque retour par une mise à jour incrémentale ;
+- la moyenne unique des anomalies par un regroupement spatial ;
+- la carte à hauteur unique par une représentation hybride lorsque les grottes
+  le nécessitent ;
+- les copies profondes et données sous forme de dictionnaires par des structures
+  adaptées aux performances mesurées.