AR-VMS-Seaman/docs/coords.md

# Coordenadas navales — convención del proyecto

> Regla de oro #11: **coordenadas navales consistentes en TODO el código.**

## Sistema `ShipCoord`

```python
from vmssailor.core import ShipCoord

position = ShipCoord(x_pp=10.5, y_cl=-0.9, z_bl=1.4)  # metros
```

### Ejes

- **`x_pp`**: distancia desde la **Perpendicular de Popa (Pp)**, positivo hacia **proa**.
- **`y_cl`**: distancia desde la **Línea de Crujía (CL)**, positivo a **estribor**, negativo a **babor**.
- **`z_bl`**: altura sobre la **Línea Base (BL)**, positivo hacia **arriba**.

### Unidad

**Metros (SI)** siempre. Sin excepciones internas. La conversión a pies/yardas se hace exclusivamente en renderers de UI cuando el usuario lo pida.

### Visualización mental

```
                     +y (estribor)
                          ↑
                          │
                          │
   Pp                     │                       Proa
   (popa)─────────────────┼─────────────────────► +x
                          │
                          │
                          │
                          ↓
                     −y (babor)
```

Y la altura:

```
              +z (arriba, mástil)
                   ↑
                   │
   ───────────────┼──────  línea de cubierta
                   │
   ═══════════════│══════  línea de flotación (aprox z_bl ≈ draft)
                   │
   ═══════════════│══════  Línea Base (BL = z_bl 0)
                   │
                   ↓ −z (no se usa en práctica)
```

## Buques típicos del segmento 30-40 m

- Eslora total: **20-60 m** → x_pp en [0, 60]
- Manga máxima: **5-15 m** → y_cl en [-7.5, +7.5]
- Calado: 0.5-5 m → z_bl en [0.5, 5] para el casco bajo flotación
- Punto más alto (mástil): hasta z_bl +20 m

Validators de `ShipCoord` permiten márgenes (x ∈ [-5, 200], y ∈ [-30, +30], z ∈ [-10, +50]) para cubrir buques en desarrollo y errores tipográficos del integrador.

## Por qué este sistema y no otro

- **Estándar de la industria naval/arquitectura naval**. La Pp es el origen natural usado en arquitectura, despacho, regulación.
- **Independiente de UI / pantalla.** Los pixels y rotaciones de cámara viven en renderers, no en core.
- **Compatible con NMEA 2000.** El backbone publica posición geodésica (PGN 129025/129029) y actitud (PGN 127257). Para transformar a ShipCoord local del buque, se aplica el lay-out del buque (mounting offset y rotación de la IMU/GPS respecto al origen del buque) registrado en config del proyecto.

## Reglas para escribir código

✅ **Sí:**
```python
location = ShipCoord(x_pp=5.5, y_cl=-0.9, z_bl=1.2)
distance = a.distance_to(b)  # metros, 3D euclídea
```

❌ **No:**
```python
# ¡No! No mezcles coordenadas de pantalla con coordenadas del buque.
location = (mouse_x, mouse_y)

# ¡No! Las transformaciones a pantalla viven en renderers, no en core.
class ShipCoord:
    def to_screen_xy(self, ...): ...  # ← esto NO va en core
```

## Conversión a pantalla (UI sprints)

En Sprint 1+ los renderers (QGraphicsView, Flutter Canvas) implementan **una sola** función `ship_to_screen(coord: ShipCoord, viewport) → QPointF` y todo lo demás trabaja en ShipCoord.

## Tests relevantes

- `tests/core/test_coords.py` — comportamiento de `ShipCoord`
- `tests/core/test_validation.py::test_equipment_out_of_hull_warning` — chequea que equipos no caigan fuera de la envolvente del buque