jbrodovsky · jbrodovsky · Jan 8, 2026 · Jan 8, 2026 · Jan 8, 2026 · Jan 8, 2026
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/README.md b/README.md
@@ -38,4 +38,10 @@ The toolbox is designed for research, teaching, and development purposes and aim
 
 The simulation program provides a simple command line interface for running various configurations of the INS. In can run in open-loop (dead reckoning) mode or closed-loop (full state loosely couple UKF or EKF) mode. It can simulate various scenarios such as intermittent GPS, GPS degradation, and more. The simulation is designed to be easy to use and provides a simple API for generating datsets for further navigation processing or research.
 
-Both `strapdown-sim` and `geonav-sim` include built-in logging capabilities using the Rust `log` crate with `env_logger`. You can control log output via command-line options (`--log-level` and `--log-file`) for monitoring simulation progress, debugging issues, and recording detailed execution information. See [LOGGING.md](LOGGING.md) for detailed usage instructions.
+`strapdown-sim` includes built-in logging capabilities using the Rust `log` crate with `env_logger`. You can control log output via command-line options (`--log-level` and `--log-file`) for monitoring simulation progress, debugging issues, and recording detailed execution information. See [LOGGING.md](LOGGING.md) for detailed usage instructions.
+
+**Geophysical Navigation**: To enable geophysical navigation capabilities (gravity/magnetic anomaly aiding), build with `--features geonav` and use the `--geo` flag:
+```bash
+cargo build --release --package strapdown-sim --features geonav
+strapdown-sim cl --input data.csv --output out/ --geo --gravity-resolution one-minute
+```
diff --git a/geonav/Cargo.toml b/geonav/Cargo.toml
@@ -24,6 +24,6 @@ env_logger = "0.11"
 name = "geonav"
 path = "src/lib.rs"
 
-[[bin]]
-name = "geonav-sim"
-path = "src/main.rs"
+# Note: The geonav-sim binary has been consolidated into strapdown-sim.
+# Use: cargo build --package strapdown-sim --features geonav
+# Run: strapdown-sim cl --geo --gravity-resolution ...
diff --git a/geonav/README.md b/geonav/README.md
@@ -1,168 +1,134 @@
-# Geonav-Sim Usage Guide
+# Strapdown Geonav - Geophysical Navigation Library
 
-This guide demonstrates how to use the `geonav-sim` program for geophysical navigation simulations.
+This crate provides geophysical navigation capabilities for strapdown inertial navigation systems, enabling gravity and magnetic anomaly aiding for improved navigation accuracy, particularly in GNSS-denied environments.
 
 ## Overview
 
-`geonav-sim` extends the basic strapdown navigation simulation by incorporating geophysical measurements (gravity and magnetic anomalies) to aid navigation, particularly in GNSS-denied environments.
+`strapdown-geonav` is a library crate that extends the basic strapdown navigation simulation by incorporating geophysical measurements (gravity and magnetic anomalies) to aid navigation.
 
-## Basic Usage
+**Note**: The standalone `geonav-sim` binary has been consolidated into `strapdown-sim`. Use `strapdown-sim` with the `--features geonav` flag to access geophysical navigation capabilities.
+
+## Usage
+
+### As a Simulation Tool
+
+Build and run with geophysical navigation support:
 
 ```bash
-# Basic gravity-aided navigation simulation
-geonav-sim -i data/input.csv -o results/output.csv --geo-type gravity
-
-# Magnetic-aided navigation simulation with higher resolution
-geonav-sim -i data/input.csv -o results/output.csv \
-    --geo-type magnetic \
-    --geo-resolution two-minutes \
-    --geo-noise-std 50.0
-
-# Custom map file specification
-geonav-sim -i data/input.csv -o results/output.csv \
-    --geo-type gravity \
-    --map-file data/custom_gravity_map.nc
+# Build strapdown-sim with geonav feature
+cargo build --release --package strapdown-sim --features geonav
+
+# Run geophysical navigation simulation
+strapdown-sim cl --input data.csv --output out/ \
+    --geo \
+    --gravity-resolution one-minute \
+    --filter ukf
+
+# Magnetic navigation
+strapdown-sim cl --input data.csv --output out/ \
+    --geo \
+    --magnetic-resolution two-minutes \
+    --magnetic-noise-std 150.0
 ```
 
-## Input File Requirements
+### As a Library
 
-### CSV Data File
-The input CSV must contain standard IMU/GNSS data with the following columns:
-- `time` - ISO UTC timestamp (YYYY-MM-DD HH:mm:ss.ssss+HH:MM)
-- `latitude`, `longitude`, `altitude` - Position measurements
-- `speed`, `bearing` - Velocity measurements  
-- `acc_x`, `acc_y`, `acc_z` - Accelerometer data (m/s²)
-- `gyro_x`, `gyro_y`, `gyro_z` - Gyroscope data (rad/s)
-- `grav_x`, `grav_y`, `grav_z` - Gravity measurements (m/s²) [for gravity-aided navigation]
-- `mag_x`, `mag_y`, `mag_z` - Magnetometer data (μT) [for magnetic-aided navigation]
+Add to your `Cargo.toml`:
 
-### Geophysical Map Files
-Maps should be in NetCDF format with specific naming conventions:
+```toml
+[dependencies]
+strapdown-geonav = { path = "../geonav" }
+```
 
-- **Gravity maps**: `{input_name}_gravity.nc`
-- **Magnetic maps**: `{input_name}_magnetic.nc`
+Use in your code:
+
+```rust
+use geonav::{GeoMap, GeophysicalMeasurementType, GravityResolution};
+use geonav::{build_event_stream, geo_closed_loop_ukf};
+
+// Load a gravity map
+let measurement_type = GeophysicalMeasurementType::Gravity(GravityResolution::OneMinute);
+let map = GeoMap::load_geomap("gravity_map.nc", measurement_type)?;
+
+// Build event stream with geophysical measurements
+let events = build_event_stream(
+    &records,
+    &gnss_config,
+    Some(Rc::new(map)),
+    Some(100.0),  // gravity noise std (mGal)
+    None,         // no magnetic map
+    None,
+    None,
+);
+
+// Run simulation
+let results = geo_closed_loop_ukf(&mut ukf, events)?;
+```
 
-For example, if your input CSV is `flight_data.csv`, the program will look for:
-- `flight_data_gravity.nc` (for gravity-aided navigation)
-- `flight_data_magnetic.nc` (for magnetic-aided navigation)
+## Command Line Options
 
-#### Map File Structure
-Maps should contain:
-- `lat` variable: latitude coordinates (degrees)
-- `lon` variable: longitude coordinates (degrees)  
-- `z` variable: anomaly data (mGal for gravity, nT for magnetic)
+When using `strapdown-sim --features geonav`:
 
-## Command Line Options
+### Enabling Geophysical Navigation
+- `--geo`: Enable geophysical navigation mode (required)
 
-### Geophysical Measurement Configuration
-- `--geo-type`: Choose between `gravity` or `magnetic` measurements
-- `--geo-resolution`: Map resolution (from `one-degree` to `one-second`)
-- `--geo-noise-std`: Measurement noise standard deviation
-- `--map-file`: Custom map file path (overrides auto-detection)
+### Gravity Configuration
+- `--gravity-resolution`: Map resolution (one-degree to one-minute)
+- `--gravity-bias`: Measurement bias in mGal
+- `--gravity-noise-std`: Noise standard deviation in mGal (default: 100)
+- `--gravity-map-file`: Custom map file path
 
-### GNSS Degradation Configuration
-The program inherits all GNSS degradation options from `strapdown-sim`:
+### Magnetic Configuration
+- `--magnetic-resolution`: Map resolution (one-degree to two-minutes)
+- `--magnetic-bias`: Measurement bias in nT
+- `--magnetic-noise-std`: Noise standard deviation in nT (default: 150)
+- `--magnetic-map-file`: Custom map file path
 
-#### Scheduler Options (controls GNSS availability)
-- `--sched passthrough`: Use all available GNSS measurements
-- `--sched fixed --interval-s 10`: GNSS fixes every 10 seconds
-- `--sched duty --on-s 30 --off-s 60`: 30s ON, 60s OFF cycles
+### Common Options
+- `--geo-frequency-s`: Geophysical measurement frequency in seconds
 
-#### Fault Models (corrupts GNSS measurements)
-- `--fault none`: No GNSS corruption
-- `--fault degraded`: AR(1) correlated errors
-- `--fault slowbias`: Slow-drifting bias
-- `--fault hijack`: Position spoofing attack
+## Geophysical Map Files
 
-## Example Scenarios
+Maps should be in NetCDF format:
 
-### 1. GNSS-Denied Navigation with Gravity Aiding
-```bash
-# Simulate complete GNSS denial with gravity measurements
-geonav-sim -i urban_canyon.csv -o gravity_aided.csv \
-    --geo-type gravity \
-    --geo-noise-std 50.0 \
-    --sched fixed --interval-s 999999  # Effectively no GNSS
-```
+- **Gravity maps**: `{input_name}_gravity.nc` or specified via `--gravity-map-file`
+- **Magnetic maps**: `{input_name}_magnetic.nc` or specified via `--magnetic-map-file`
 
-### 2. Intermittent GNSS with Magnetic Aiding
-```bash
-# GNSS available 20% of the time, magnetic aiding throughout
-geonav-sim -i flight_data.csv -o magnetic_aided.csv \
-    --geo-type magnetic \
-    --geo-resolution five-minutes \
-    --sched duty --on-s 10 --off-s 40
-```
+### Map File Structure
+Maps should contain:
+- `lat` variable: latitude coordinates (degrees)
+- `lon` variable: longitude coordinates (degrees)
+- `z` variable: anomaly data (mGal for gravity, nT for magnetic)
+
+## Example Scenarios
 
-### 3. GNSS Spoofing with Geophysical Validation
+### GNSS-Denied Navigation with Gravity Aiding
 ```bash
-# Simulate spoofing attack with gravity measurements for validation
-geonav-sim -i test_route.csv -o spoofing_test.csv \
-    --geo-type gravity \
-    --fault hijack --hijack-offset-n-m 100 --hijack-start-s 300
+strapdown-sim cl --input urban_canyon.csv --output out/ \
+    --geo --gravity-resolution one-minute \
+    --dropout-start-s 0 --dropout-duration-s 999999
 ```
 
-### 4. High-Precision Survey with Multiple Aiding
+### Intermittent GNSS with Magnetic Aiding
 ```bash
-# High-resolution gravity aiding with minimal GNSS degradation
-geonav-sim -i survey_data.csv -o high_precision.csv \
-    --geo-type gravity \
-    --geo-resolution one-minute \
-    --geo-noise-std 10.0 \
-    --fault degraded --sigma-pos-m 1.0
+strapdown-sim cl --input flight_data.csv --output out/ \
+    --geo --magnetic-resolution five-minutes \
+    --sched duty --on-s 10 --off-s 40
 ```
 
-## Output
+## API Documentation
 
-The program generates a CSV file with navigation results including:
-- Estimated position, velocity, and attitude
-- Covariance diagonal elements  
-- Input measurements and derived quantities
-- Geophysical anomaly values used for aiding
+See the Rust API documentation for detailed information on:
+- `GeoMap` - Geophysical map loading and interpolation
+- `GravityMeasurement` - Gravity anomaly measurement model
+- `MagneticAnomalyMeasurement` - Magnetic anomaly measurement model
+- `build_event_stream` - Event stream construction with geophysical measurements
+- `geo_closed_loop_ukf` / `geo_closed_loop_ekf` - Simulation functions
 
-## Performance Considerations
+## Performance Notes
 
-- **Map Resolution**: Higher resolution maps provide better accuracy but require more memory and computation
-- **Noise Levels**: Typical values:
+- **Map Resolution**: Higher resolution maps provide better accuracy but require more memory
+- **Typical Noise Levels**:
   - Gravity: 10-100 mGal standard deviation
   - Magnetic: 50-200 nT standard deviation
 - **Coverage**: Ensure geophysical maps cover the entire trajectory area
-
-## Troubleshooting
-
-### Common Issues
-1. **Map file not found**: Ensure proper naming convention or use `--map-file`
-2. **Out of bounds errors**: Trajectory extends beyond map coverage
-3. **Memory issues**: Very high-resolution maps may require significant RAM
-
-### Error Messages
-- `"Map file not found"`: Check file naming and paths
-- `"Latitude out of bounds"`: Trajectory extends beyond map area
-- `"Failed to read config"`: GNSS config file format issues
-
-## Integration with Analysis Tools
-
-Output CSV files are compatible with standard navigation analysis tools and can be processed with:
-- Python pandas/numpy for analysis
-- MATLAB navigation toolboxes
-- R for statistical analysis
-- Excel for basic visualization
-
-Example Python analysis:
-```python
-import pandas as pd
-import matplotlib.pyplot as plt
-
-# Load results
-results = pd.read_csv('output.csv')
-
-# Plot trajectory
-plt.figure(figsize=(10, 8))
-plt.scatter(results['longitude'], results['latitude'], 
-           c=results['timestamp'], cmap='viridis')
-plt.xlabel('Longitude (degrees)')
-plt.ylabel('Latitude (degrees)')
-plt.title('Geophysical Navigation Trajectory')
-plt.colorbar(label='Time')
-plt.show()
-```