moulin-mapper/pipeline/SCHEMA.md

SCHEMA.md — Contrat de flux capteurs moulin-mapper

Principe

Une ligne JSONL = un échantillon Ping360 (un faisceau sonar émis à un angle donné) avec la télémétrie co-enregistrée à cet instant exact.

Le pipeline de traitement doit fonctionner identiquement sur :

• données simulées (simulator.py)
• données réelles BlueROV (juste changer la source)

Champs optionnels futurs (image_ref, confidence, etc.) peuvent s'ajouter sans casser le pipeline — tous les champs inconnus sont ignorés.

---

Format : JSONL (JSON Lines)

Un objet JSON par ligne, terminé par \n. Pas de tableau englobant.

Exemple

{"t": 12.345, "ping360_angle": 174.6, "ping360_distance": 3.21, "heading": 88.2, "altitude": 1.05, "depth": 1.82, "ax": 0.01, "ay": -0.02, "az": 9.79, "gx": 0.001, "gy": 0.0, "gz": 0.05}

---

Champs obligatoires

Champ	Type	Unité	Description
t	float	s	Timestamp depuis le démarrage du flux (epoch relatif)
ping360_angle	float	deg	Angle du faisceau sonar relatif au cap ROV (0 = avant ROV)
ping360_distance	float	m	Distance mesurée jusqu'au premier écho (0.0 = dropout/pas d'écho)
heading	float	deg	Cap magnétique ROV, convention Nord=0, Est=90 (CW)
altitude	float	m	Hauteur au-dessus du fond (Ping1D vers le bas), 0.0 = dropout
depth	float	m	Profondeur sous la surface (pression bar → m d'eau), positif vers le bas
ax	float	m/s²	Accélération IMU axe X (avant ROV dans repère corps)
ay	float	m/s²	Accélération IMU axe Y (gauche ROV dans repère corps)
az	float	m/s²	Accélération IMU axe Z (haut ROV dans repère corps), ~+9.81 au repos
gx	float	rad/s	Gyromètre axe X (roulis)
gy	float	rad/s	Gyromètre axe Y (tangage)
gz	float	rad/s	Gyromètre axe Z (lacet, positif = rotation CW vue du dessus)

---

Repères et conventions

Repère monde : ENU local

• X = Est, Y = Nord, Z = vers le haut
• Origine = position initiale du ROV au démarrage
• Le heading 0° correspond à +Y (Nord)

Ping360

• 400 pas/tour (comme le vrai Ping360 BlueRobotics) → résolution angulaire 0.9°/pas
• ping360_angle est relatif au cap ROV (0° = avant du ROV)
• Pour obtenir l'angle monde : angle_monde = (heading + ping360_angle) % 360
• Plage : [0, 360) degrés
• ping360_distance = 0.0 signifie absence d'écho (dropout) — à ignorer dans le pipeline

Heading

• Convention magnétique compas : 0°=Nord, 90°=Est, 180°=Sud, 270°=Ouest (CW)
• Bruit typique simulé : ~0.5° RMS
• Dérive lente optionnelle pour simuler un mauvais magnéto

Altitude (Ping1D)

• Sonar vertical pointant vers le bas
• Mesure la distance ROV → fond en mètres
• altitude = 0.0 signifie dropout (confidence trop basse)
• Hauteur ROV au-dessus du fond = altitude
• Profondeur fond = depth + altitude

IMU

• Repère corps ROV (Body frame) — PAS ENU
• az ≈ +9.81 m/s² au repos (gravité remontant dans le repère corps)
• Biais gyro simulé : ~0.005 rad/s — cause dérive dead-reckoning ~18°/min

---

Fréquences typiques

Source	Fréquence
Ping360	400 msgs/sweep, ~1 sweep/4 s (configurable)
IMU	1 msg par ligne JSONL (co-enregistré avec le ping sonar)
heading	idem
altitude	idem
depth	idem

---

Fichier vérité terrain (simulation uniquement)

run_L_truth.csv — colonnes : t, x, y, heading_deg, z

• x, y en mètres ENU depuis l'origine
• heading_deg : cap vrai (sans bruit)
• z : profondeur (positif vers le bas)
• Ce fichier n'existe PAS sur données réelles — sert uniquement à valider l'algo

---

Champs optionnels (présents dans la simulation, rétrocompatibles)

Champ	Type	Unité	Description
vf	float	m/s	Vitesse corps forward (avant ROV) — modèle thruster ou DVL
vl	float	m/s	Vitesse corps latérale — modèle thruster ou DVL
image_ref	string	—	Nom du fichier image caméra co-enregistrée
confidence	float	[0,1]	Confiance écho Ping360
temperature	float	°C	Capteur eau
battery_v	float	V	Tension batterie

vf et vl sont produits par le simulateur depuis le modèle de thruster. Sur un vrai BlueROV, ils peuvent venir d'un DVL ou du contrôleur de poussée. Le pipeline DR utilise vf/vl s'ils sont présents, sinon intègre ax/ay.