Ransom-s-wake/docs/POC_B_TECHNICAL_BASELINE.md

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.