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.