ocean-imu: Marine IMU Filters That Learn Tilt While the Boat Is Already Moving

Why a Marine IMU Filter Is Not a Drone Filter

The README starts with a clear problem statement: a ship AHRS cannot reuse drone or aerospace filters unchanged. Drones initialize while sitting still, so the accelerometer reads pure gravity. A ship may be powered on while already heaving, rolling, and pitching in wind and waves. The accelerometer then mixes gravity with wave-induced translational accelerations. A filter that trusts that signal as a gravity direction will estimate the wrong attitude. ocean-imu addresses this by designing filters that learn tilt during motion, avoid treating wave-distorted acceleration as pure gravity, and adapt to different sea states. The intended users are engineers building ship MRUs, marine INS, or AHRS units, likely for autonomous vessels, navigation systems, or onboard monitoring. The library is not a finished product; it is a collection of algorithms and reference code, with a separate GUI client project for visualization.

The Filter Family: OU_II, OU_III, TFG, and PII

The repository offers three Kalman filters and one control-theory observer. OU_II is an 18-dimensional-state Kalman filter with direct integral drift correction, described as more responsive to sea-state changes. OU_III uses higher-order integral drift correction and has a 21-dimensional state; it is the variant used for the main 3D navigation study. TFG is a right-invariant two-frame Lie-group error-state EKF, also 21-dimensional. The key difference is that TFG keeps attitude, world-frame kinematic states, and body-frame biases on one Lie group, so an attitude correction rotates velocity, position, integral displacement, and wave acceleration coherently. In contrast, a standard EKF might correct attitude but leave the other states inconsistent. PII observer is a control-theory approach with no matrix operations, making it computationally light but less accurate than the Kalman filters. All filters are adaptive, meaning they adjust to changing sea states rather than relying on fixed tuning. This variety lets a developer choose between accuracy and computational cost, depending on the target hardware.

Wave Models and the Simulation-Driven Testing Framework

The library does not just filter; it simulates the marine environment to validate the filters. The testing framework uses Stokes and Airy waves, with Pierson-Moskowitz or JONSWAP spectra, and a directional spread model (cosine by default). This is a concrete mechanism: you can generate wave fields with known statistical properties, feed the resulting IMU signals through a filter, and compare the estimates against the ground truth. The README links several PDFs describing the math, including wave models, spectral models, and vessel RAO (Response Amplitude Operator). The results from the development branch are published as release artifacts under the vTest tag. This simulation-driven approach is a major strength for a research library, because it gives a reproducible way to evaluate filter performance across sea states. However, the README does not provide specific benchmark numbers or error metrics in the visible portion; those are in the linked PDFs and SVG artifacts, which you would need to inspect.

Getting It Running: Commands, Builds, and Arduino Sketches

The README states that the code is C++ and can run on an ESP32 or a regular computer. It mentions that individual modules can be built and exercised from the tests directory without a monolithic build system. The repository layout includes Arduino .ino sketches for the ESP32-S3, specifically for the atomS3R board. There are three sketches: one for Kalman OU_II, one for OU_III, and one for PII observer, all under sensors/full_marine_ins/. The README also mentions that all filters are tested to run on ESP32-S3, Windows, and Linux. For a developer, the first step would be to clone the repository and look at the tests directory to see how to build and run the unit tests. The GUI client is a separate project, ins-dashboard-gtk, for Windows and Linux. The README does not give explicit cmake or make commands in the visible portion, so you would need to inspect the repository's build files. The presence of releases like v2.1.8 suggests a versioned release process, but the exact installation steps are not detailed in the provided material.

The Hard Part: Compass Calibration and Weak Observability

One of the library's claimed capabilities is tilt-compensated compass and IMU calibration that can run directly on the microcontroller. This is practical for marine deployments where you cannot do a lab calibration. The README also mentions that the filters reconstruct 3D displacement of a vessel, with heave being strongly observable and surge/sway weakly observable. This is an honest admission of a limitation: surge and sway estimates will be less reliable than heave. The library also estimates apparent wave direction as seen from the vessel, which is useful for autopilot or seakeeping systems. The frequency tracking section lists several methods, including a Kalman-based adaptive notch filter (KalmANF), an Aranovskiy frequency tracker, a PLL tracker, and a zero-crossing tracker. This variety suggests that frequency estimation is a non-trivial problem in marine signals, and the right choice depends on the sea state and computational budget. The README does not specify which tracker is best; it only provides the PDFs.

Limitations and Wrong-Tool Cases

The most obvious limitation is that the library is research-oriented. The README links to a large number of PDFs describing the math, but the visible portion does not include a quick-start tutorial or a minimal example. An engineer looking for a drop-in IMU library might be overwhelmed. The project also has a vTest release tag, which suggests that the results are from a test branch, not a stable release. The README mentions a GUI client, but it is a separate project, and the integration is not described in the provided material. For production use, you would need to validate the filters on your own vessel, as sea conditions vary. The library is likely the wrong tool if you need a certified or industry-standard AHRS with formal guarantees, because the README does not mention any certification or compliance. It is also not ideal for users who want a single filter with one tuning knob; the adaptive filters still require configuration. Finally, the PII observer is explicitly less accurate than the Kalman filters, so it is only suitable for situations where computational resources are extremely tight.

Alternatives and the Difference in Approach

A common alternative to this library is to use a general-purpose open-source IMU filter like the Madgwick or Mahony AHRS algorithms, which are widely used in drones and robotics. The difference is fundamental: those algorithms assume a stationary initial condition and treat the accelerometer as a gravity reference. They do not model wave-induced translational accelerations or heave. For a ship, that leads to biased roll and pitch estimates in waves. Another alternative is to use a commercial marine INS, which often includes proprietary wave filtering and certification, but at a high cost and with closed algorithms. ocean-imu sits in between: it offers marine-specific modeling (OU wave model, wave direction, heave reconstruction) that general-purpose filters lack, while remaining open source and adaptable. The trade-off is that you must integrate and validate it yourself, whereas commercial systems come with support and guarantees. The README also mentions a separate autopilot methods PDF, which suggests the library is intended for integration into autopilot systems, but that is not a direct alternative.

Maintenance, Licensing, and Upgrade Cost

The repository is licensed under MIT, which is permissive and allows commercial use with attribution, but this is not legal advice. The last push was in August 2026, and there is a recent release v2.1.8, indicating active development. The presence of a vTest release and a main branch suggests a workflow where experiments are published separately from stable code. The upgrade cost is moderate: because the filters are algorithmically complex, upgrading from one variant to another (e.g., from OU_II to OU_III) requires re-tuning and re-validating, not just swapping a header. The README mentions that OU_II is more responsive to sea-state changes, while OU_III is used for the main study; this implies a design choice that affects behavior. The documentation is extensive but scattered across PDFs, so the cost of understanding the math is real. For a team adopting this, the maintenance burden includes reading those papers, adapting the code to their sensor hardware, and possibly contributing fixes back. The project seems to be maintained by a small group, so you cannot expect enterprise-grade support.

Editorial conclusion

Adopt ocean-imu if you are building a marine MRU, AHRS, or INS and need filters that initialize while the vessel is moving in waves, with adaptive sea-state handling and ESP32-class hardware support. Skip it if you need a plug-and-play product with a maintained GUI and a stable API; the project is research-grade, with many PDF papers and a vTest release that may change. Before integrating, verify the exact filter variant (OU_II vs OU_III vs TFG) against your vessel's motion profile, confirm the Arduino sketches match your ESP32-S3 board (atomS3R is the reference), and check the MIT license terms for your distribution model. The library's strength is the documented math and the simulation framework, not a polished user interface.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes