Design document: Marine TF frame hierarchy with vertical datum frames

[rolker]

Summary

Design and document a TF frame hierarchy for marine robotics that extends REP-105 with vertical datum frames specific to marine operations. This is a project-level spec to be implemented in mru_transform, with potential future formalization as a contribution to the marine robotics REP.

Motivation

Marine robots need multiple vertical reference surfaces that don't exist in standard REP-105:

• Chart datum (MLLW, LAT, etc.) — the static reference for nautical charts and S57 data
• Sea surface / tide — the dynamic water level, needed for navigation and depth interpretation
• Ellipsoidal height — what GPS measures directly

Currently these relationships are handled ad-hoc. A well-defined TF tree makes vertical datum conversions available to any node via standard tf2 lookups, and establishes conventions that other marine ROS projects can adopt.

Proposed Frame Hierarchy

earth (ECEF)
└─ map  (ENU, WGS84 ellipsoid, established at first GPS fix)
   ├─ chart_datum   (static offset via VDatum/PROJ, position-dependent, optional)
   ├─ map_tide      (dynamic, current water surface in ellipsoidal height)
   └─ odom          (identity or localization correction)
       └─ base_link
           ├─ base_link_north_up   (position only, no orientation)
           ├─ base_link_level      (heading only, no pitch/roll)
           ├─ waterline            (static, from URDF)
           └─ [sensor frames]

Design Decisions

1. map stays ellipsoidal — GPS positions work directly without VDatum. The system functions without datum conversion; chart_datum is additive/optional.

2. chart_datum is a child of map — the map→chart_datum transform encodes the static VDatum offset (ellipsoid to chart datum) for the current geographic position. Updated spatially as the robot moves. Requires VDatum grids (PROJ + .GTX files) or NOAA VDatum API.

3. map_tide is a child of map — water surface expressed in ellipsoidal height. Tide height above chart datum is recoverable via tf2 lookup from chart_datum to map_tide.

4. Multiple strategies for deriving map_tide:

   • RTK averaging (current sea_surface_estimator approach) — averages base_link Z over time to filter out wave motion and estimate sea surface
   • MRU heave — if the MRU provides heave data, subtract heave from current position for an instantaneous sea surface estimate (no buffer delay)
   • Tidal model — predicted tide from a model or external source
   • The map_tide frame is the same regardless of derivation method; consumers don't need to know the source.

5. waterline frame in URDF — resolves the existing TODO in sea_surface_estimator (the node currently averages base_link Z, but the robot isn't at the waterline).

6. NED convention variants — suffixed frames (map_ned, base_link_fsd) connected by static rotations, per the marine REP discussion. Not detailed here; to be addressed separately.

Analogies to Aviation

Aviation	Marine	Nature
pressure_altitude (REP-105)	map_tide	Dynamic surface measurement
MSL / geoid (EGM96)	chart_datum (MLLW/LAT)	Static reference, position-dependent
WGS84 ellipsoid	map	Geodetic reference

REP-105 already suggests pressure_altitude as an extra intermediate frame for aerial vehicles. The marine vertical datum frames follow the same pattern.

Scope

• Write the TF tree spec as a design document
• Document frame semantics, update strategies, and conventions
• Define the chart_datum node interface (links to mru_transform#7)
• Document map_tide derivation strategies (RTK averaging, MRU heave, tidal model)
• Document waterline frame convention

Out of scope (for now):

• NED/FSD convention details
• Formal REP contribution

Related

• mru_transform#7: VDatum service — implementation of the chart_datum node
• unh_marine_autonomy#86: Bathymetric data store — primary consumer of datum conversions
• ROS Discourse: Marine REP discussion — community discussion on marine coordinate conventions
• REP-105 — pressure_altitude frame precedent

---

Authored-By: Claude Code Agent
Model: Claude Opus 4.6

[CaptKrasno]

This looks great overall, Roland! This is a much-needed clarification for marine TF frames and something the ecosystem has been missing for a long time.

My main concern is with the chart_datum, map_tide, etc. frames being direct children of the map frame. Presumably we care about fairly high precision with these vertical references, and if map is a fixed ENU tangent plane established at an origin, then as the vehicle moves away from that origin the “up” axis of that frame will slowly diverge from the true local vertical. At larger distances this means the Z offsets of these datum frames no longer strictly represent the local height relationship.

One possible approach would be to introduce a local ellipsoid-normal ENU frame tied to the vehicle’s current geodetic position, and make the vertical datum frames children of that. That way the vertical axis always represents the correct local normal and the offsets remain meaningful as “height above/below datum” regardless of how far the vehicle moves.

Conceptually something like:

earth (ECEF)

└─ map
   Global ENU frame established at a fixed origin (REP-105 style)

   └─ odom
      Continuous local frame for navigation / localization

      └─ base_enu_ellipsoid
         Local tangent ENU frame whose +Z is the ellipsoid normal
         at the vehicle's current geodetic position.

         ├─ chart_datum
         │  Chart reference surface (MLLW/LAT/etc.)
         │  Offset from ellipsoidal height via VDatum / PROJ
         │
         ├─ map_tide
         │  Current water surface expressed in ellipsoidal height
         │  (RTK averaging, MRU heave correction, tidal model, etc.)
         │
         ├─ base_link_north_up
         │  Translation only
         │
         ├─ base_link_level
         │  Yaw only (roll/pitch removed)
         │
         └─ base_link
            Full 6-DOF vehicle frame

            ├─ waterline
            │  Static URDF offset from base_link
            │
            └─ [sensor frames]

This also has a nice side benefit for underwater vehicles. In my work with ROVs, we often have a pressure-derived depth sensor referenced to either the water surface or chart datum. I’ve found it surprisingly difficult to pull a meaningful “depth” value directly out of the TF tree because the vertical reference surfaces are not represented explicitly, especially far from the map origin.

In real operations, operators are often not very rigorous about resetting map origins, and using the odometry/base_link Z position in the map frame can accumulate significant error as the vehicle moves away from the tangent plane origin. Representing the vertical datum relationships explicitly in the TF tree would make it much easier to derive quantities like depth below sea surface or depth relative to chart datum in a consistent way.

This same hierarchy could therefore support both surface vehicles estimating sea level and underwater vehicles expressing depth relative to chart datum or sea surface.

This structure may also benefit control systems, since operating PID loops in a vehicle-centered local ENU frame helps keep the axes orthogonal and aligned with the local vertical, avoiding cross-coupling and bias that can appear when controllers rely on the map frame far from its tangent-plane origin.

Overall I really like the direction of this proposal! Tightening the vertical reference point like this could make the system more robust for both long-range surface operations and subsea platforms.

[rolker]

I like your idea @CaptKrasno. I think I can baby step my way to adding tides, then you up seeking frame can slot in easily I think.