diff --git a/gtsam/navigation/GPSFactor.cpp b/gtsam/navigation/GPSFactor.cpp index f01a16d90..cb42eea77 100644 --- a/gtsam/navigation/GPSFactor.cpp +++ b/gtsam/navigation/GPSFactor.cpp @@ -37,9 +37,9 @@ bool GPSFactor::equals(const NonlinearFactor& expected, double tol) const { } //*************************************************************************** -Vector GPSFactor::evaluateError(const Pose3& p, +Vector GPSFactor::evaluateError(const Pose3& nTb, OptionalMatrixType H) const { - return p.translation(H) -nT_; + return nTb.translation(H) -nT_; } //*************************************************************************** @@ -82,9 +82,9 @@ bool GPSFactorArm::equals(const NonlinearFactor& expected, double tol) const { } //*************************************************************************** -Vector GPSFactorArm::evaluateError(const Pose3& p, +Vector GPSFactorArm::evaluateError(const Pose3& nTb, OptionalMatrixType H) const { - const Matrix3 nRb = p.rotation().matrix(); + const Matrix3 nRb = nTb.rotation().matrix(); if (H) { H->resize(3, 6); @@ -92,7 +92,7 @@ Vector GPSFactorArm::evaluateError(const Pose3& p, H->block<3, 3>(0, 3) = nRb; } - return p.translation() + nRb * bL_ - nT_; + return nTb.translation() + nRb * bL_ - nT_; } //*************************************************************************** @@ -110,9 +110,9 @@ bool GPSFactorArmCalib::equals(const NonlinearFactor& expected, double tol) cons } //*************************************************************************** -Vector GPSFactorArmCalib::evaluateError(const Pose3& p, const Point3& bL, +Vector GPSFactorArmCalib::evaluateError(const Pose3& nTb, const Point3& bL, OptionalMatrixType H1, OptionalMatrixType H2) const { - const Matrix3 nRb = p.rotation().matrix(); + const Matrix3 nRb = nTb.rotation().matrix(); if (H1) { H1->resize(3, 6); @@ -124,7 +124,7 @@ Vector GPSFactorArmCalib::evaluateError(const Pose3& p, const Point3& bL, *H2 = nRb; } - return p.translation() + nRb * bL - nT_; + return nTb.translation() + nRb * bL - nT_; } //*************************************************************************** @@ -142,9 +142,9 @@ bool GPSFactor2::equals(const NonlinearFactor& expected, double tol) const { } //*************************************************************************** -Vector GPSFactor2::evaluateError(const NavState& p, +Vector GPSFactor2::evaluateError(const NavState& nTb, OptionalMatrixType H) const { - return p.position(H) -nT_; + return nTb.position(H) -nT_; } //*************************************************************************** @@ -164,9 +164,9 @@ bool GPSFactor2Arm::equals(const NonlinearFactor& expected, double tol) const { } //*************************************************************************** -Vector GPSFactor2Arm::evaluateError(const NavState& p, +Vector GPSFactor2Arm::evaluateError(const NavState& nTb, OptionalMatrixType H) const { - const Matrix3 nRb = p.attitude().matrix(); + const Matrix3 nRb = nTb.attitude().matrix(); if (H) { H->resize(3, 9); @@ -175,7 +175,7 @@ Vector GPSFactor2Arm::evaluateError(const NavState& p, H->block<3, 3>(0, 6).setZero(); } - return p.position() + nRb * bL_ - nT_; + return nTb.position() + nRb * bL_ - nT_; } //*************************************************************************** @@ -193,9 +193,9 @@ bool GPSFactor2ArmCalib::equals(const NonlinearFactor& expected, double tol) con } //*************************************************************************** -Vector GPSFactor2ArmCalib::evaluateError(const NavState& p, const Point3& bL, +Vector GPSFactor2ArmCalib::evaluateError(const NavState& nTb, const Point3& bL, OptionalMatrixType H1, OptionalMatrixType H2) const { - const Matrix3 nRb = p.attitude().matrix(); + const Matrix3 nRb = nTb.attitude().matrix(); if (H1) { H1->resize(3, 9); @@ -208,7 +208,7 @@ Vector GPSFactor2ArmCalib::evaluateError(const NavState& p, const Point3& bL, *H2 = nRb; } - return p.position() + nRb * bL - nT_; + return nTb.position() + nRb * bL - nT_; } }/// namespace gtsam diff --git a/gtsam/navigation/GPSFactor.h b/gtsam/navigation/GPSFactor.h index 4ef7c9794..3fc618b92 100644 --- a/gtsam/navigation/GPSFactor.h +++ b/gtsam/navigation/GPSFactor.h @@ -83,7 +83,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const Pose3& p, OptionalMatrixType H) const override; + Vector evaluateError(const Pose3& nTb, OptionalMatrixType H) const override; /// return the measurement, in the navigation frame inline const Point3 & measurementIn() const { @@ -171,7 +171,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const Pose3& p, OptionalMatrixType H) const override; + Vector evaluateError(const Pose3& nTb, OptionalMatrixType H) const override; /// return the measurement, in the navigation frame inline const Point3 & measurementIn() const { @@ -242,7 +242,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const Pose3& p, const Point3& bL, OptionalMatrixType H1, + Vector evaluateError(const Pose3& nTb, const Point3& bL, OptionalMatrixType H1, OptionalMatrixType H2) const override; /// return the measurement, in the navigation frame @@ -304,7 +304,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const NavState& p, OptionalMatrixType H) const override; + Vector evaluateError(const NavState& nTb, OptionalMatrixType H) const override; /// return the measurement, in the navigation frame inline const Point3 & measurementIn() const { @@ -384,7 +384,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const NavState& p, OptionalMatrixType H) const override; + Vector evaluateError(const NavState& nTb, OptionalMatrixType H) const override; /// return the measurement, in the navigation frame inline const Point3 & measurementIn() const { @@ -453,7 +453,7 @@ public: bool equals(const NonlinearFactor& expected, double tol = 1e-9) const override; /// vector of errors - Vector evaluateError(const NavState& p, const Point3& bL, + Vector evaluateError(const NavState& nTb, const Point3& bL, OptionalMatrixType H1, OptionalMatrixType H2) const override; diff --git a/gtsam/navigation/doc/GPSFactor.ipynb b/gtsam/navigation/doc/GPSFactor.ipynb new file mode 100644 index 000000000..658f2ad81 --- /dev/null +++ b/gtsam/navigation/doc/GPSFactor.ipynb @@ -0,0 +1,244 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# GPSFactor Family\n", + "\n", + "\"Open\n", + "\n", + "## Overview\n", + "\n", + "The `GPSFactor` family provides factors for incorporating Global Positioning System (GPS) measurements into a GTSAM factor graph. GPS typically provides measurements of position in Latitude/Longitude/Height. These GPS factors, however, assume the GPS measurement has been converted into a local Cartesian **navigation frame** (e.g., [ENU, NED, or ECEF](https://dirsig.cis.rit.edu/docs/new/coordinates.html)).\n", + "\n", + "Different variants exist to handle:\n", + "- State type: `Pose3` or `NavState`.\n", + "- Lever arm: Whether the GPS antenna is offset from the body frame origin.\n", + "- Calibration: Whether the lever arm itself is being estimated." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": { + "tags": [ + "remove-cell" + ] + }, + "outputs": [], + "source": [ + "%pip install --quiet gtsam-develop" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Factor Variants\n", + "\n", + "**For `Pose3` states:**\n", + "\n", + "- **`GPSFactor`**: \n", + " - Connects to: `Pose3` key.\n", + " - Assumes: Zero lever arm (GPS measurement corresponds directly to the `Pose3` origin).\n", + " - Measurement: 3D position (`Point3`) in the navigation frame.\n", + " - Error: $p_{pose} - p_{measured}$\n", + "\n", + "- **`GPSFactorArm`**: \n", + " - Connects to: `Pose3` key.\n", + " - Assumes: Known, fixed lever arm (`bL` vector in the body frame).\n", + " - Measurement: 3D position (`Point3`) in the navigation frame.\n", + " - Error: $(p_{pose} + R_{nb} \\cdot bL) - p_{measured}$\n", + "\n", + "- **`GPSFactorArmCalib`**: \n", + " - Connects to: `Pose3` key, `Point3` key (for the lever arm).\n", + " - Assumes: Lever arm (`bL`) is unknown and estimated.\n", + " - Measurement: 3D position (`Point3`) in the navigation frame.\n", + " - Error: $(p_{pose} + R_{nb} \\cdot bL_{estimated}) - p_{measured}$\n", + "\n", + "**For `NavState` states:**\n", + "\n", + "- **`GPSFactor2`**: Like `GPSFactor` but connects to a `NavState` key.\n", + "- **`GPSFactor2Arm`**: Like `GPSFactorArm` but connects to a `NavState` key.\n", + "- **`GPSFactor2ArmCalib`**: Like `GPSFactorArmCalib` but connects to a `NavState` key and a `Point3` lever arm key.\n", + "\n", + "(The '2' suffix historically denoted factors using `NavState`)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Mathematical Formulation (GPSFactorArm Example)\n", + "\n", + "Let:\n", + "- $T_{nb} = (R_{nb}, p_{nb})$ be the `Pose3` state (body frame $b$ in navigation frame $n$).\n", + "- $L_b$ be the known lever arm vector from the body origin to the GPS antenna, expressed in the body frame.\n", + "- $p_{gps}$ be the measured GPS position in the navigation frame.\n", + "\n", + "The predicted position of the GPS antenna in the navigation frame is:\n", + "$$ p_{ant, pred} = p_{nb} + R_{nb} \\cdot L_b $$ \n", + "\n", + "The factor's 3D error vector is the difference between the predicted antenna position and the measured GPS position:\n", + "$$ e = p_{ant, pred} - p_{gps} $$ \n", + "\n", + "The noise model reflects the uncertainty of the $p_{gps}$ measurement in the navigation frame." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Key Functionality / API (Common Patterns)\n", + "\n", + "- **Constructor**: Takes the relevant key(s), the measured `Point3` position `gpsIn` (in nav frame), the noise model, and potentially the `leverArm` (`Point3` in body frame).\n", + "- **`evaluateError(...)`**: Calculates the 3D error vector based on the connected state variable(s) and the measurement.\n", + "- **`measurementIn()`**: Returns the stored `Point3` measurement.\n", + "- **`leverArm()`** (For Arm variants): Returns the stored `Point3` lever arm." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Usage Example (GPSFactor and GPSFactorArm)\n", + "\n", + "Assume we have a GPS reading converted to a local ENU frame." + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Created GPSFactor (zero lever arm):\n", + "GPSFactor on x0\n", + " GPS measurement: 10.5\n", + "20.2\n", + " 5.1\n", + " noise model: diagonal sigmas [0.5; 0.5; 1];\n", + "\n", + "GPSFactor Error: [-0.5 -0.2 -0.1]\n", + "\n", + "Created GPSFactorArm:\n", + "GPSFactorArm on x0\n", + " GPS measurement: 10.5 20.2 5.1\n", + " Lever arm: -0.1 0 0.05\n", + " noise model: diagonal sigmas [0.5; 0.5; 1];\n", + "\n", + "GPSFactorArm Error: [-0.6 -0.2 -0.05]\n", + " ( Pose: [10. 20. 5.] )\n", + " ( Lever Arm: [-0.1 0. 0.05] )\n", + " ( Predicted Antenna Pos: [ 9.9 20. 5.05] )\n", + " ( Measured GPS Pos: [10.5 20.2 5.1] )\n", + "\n", + "Created GPSFactorArmCalib:\n", + "GPSFactorArmCalib on x0\n", + " GPS measurement: 10.5 20.2 5.1\n", + " noise model: diagonal sigmas [0.5; 0.5; 1];\n" + ] + } + ], + "source": [ + "import gtsam\n", + "import numpy as np\n", + "from gtsam.symbol_shorthand import X, L # Pose key, Lever arm key\n", + "\n", + "# --- Setup ---\n", + "pose_key = X(0)\n", + "\n", + "# GPS Measurement in local ENU frame (meters)\n", + "gps_measurement_enu = gtsam.Point3(10.5, 20.2, 5.1)\n", + "\n", + "# Noise model for GPS measurement (e.g., 0.5m horizontal, 1.0m vertical sigma)\n", + "gps_sigmas = np.array([0.5, 0.5, 1.0])\n", + "gps_noise_model = gtsam.noiseModel.Diagonal.Sigmas(gps_sigmas)\n", + "\n", + "# --- Scenario 1: GPSFactor (Zero Lever Arm) ---\n", + "gps_factor_zero_arm = gtsam.GPSFactor(pose_key, gps_measurement_enu, gps_noise_model)\n", + "print(\"Created GPSFactor (zero lever arm):\")\n", + "gps_factor_zero_arm.print()\n", + "\n", + "# Evaluate error: Error is difference between pose translation and measurement\n", + "test_pose1 = gtsam.Pose3(gtsam.Rot3(), gtsam.Point3(10.0, 20.0, 5.0))\n", + "error1 = gps_factor_zero_arm.evaluateError(test_pose1)\n", + "print(\"\\nGPSFactor Error:\", error1) # Expected: [0.5, 0.2, 0.1]\n", + "\n", + "# --- Scenario 2: GPSFactorArm (Known Lever Arm) ---\n", + "# Assume antenna is 10cm behind and 5cm above the body origin\n", + "lever_arm_body = gtsam.Point3(-0.1, 0.0, 0.05) \n", + "\n", + "gps_factor_with_arm = gtsam.GPSFactorArm(pose_key, gps_measurement_enu, \n", + " lever_arm_body, gps_noise_model)\n", + "print(\"\\nCreated GPSFactorArm:\")\n", + "gps_factor_with_arm.print()\n", + "\n", + "# Evaluate error: Error is difference between (pose + R*lever_arm) and measurement\n", + "# Use the same test pose as before\n", + "predicted_antenna_pos = test_pose1.transformFrom(lever_arm_body)\n", + "error2 = gps_factor_with_arm.evaluateError(test_pose1)\n", + "print(\"\\nGPSFactorArm Error:\", error2) \n", + "print(\" ( Pose: \", test_pose1.translation() , \")\")\n", + "print(\" ( Lever Arm: \", lever_arm_body, \")\")\n", + "print(\" ( Predicted Antenna Pos: \", predicted_antenna_pos, \")\")\n", + "print(\" ( Measured GPS Pos: \", gps_measurement_enu, \")\")\n", + "# Expected: predicted_antenna_pos - gps_measurement_enu \n", + "# = [9.9, 20.0, 5.05] - [10.5, 20.2, 5.1] = [-0.6, -0.2, -0.05]\n", + "\n", + "# --- Scenario 3: GPSFactorArmCalib (Example Setup - Not Evaluated) ---\n", + "lever_arm_key = L(0) # Key for the unknown lever arm\n", + "gps_factor_calib = gtsam.GPSFactorArmCalib(pose_key, lever_arm_key, \n", + " gps_measurement_enu, gps_noise_model)\n", + "print(\"\\nCreated GPSFactorArmCalib:\")\n", + "gps_factor_calib.print()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Coordinate Frames\n", + "\n", + "It's crucial to ensure consistency in coordinate frames:\n", + "- **GPS Measurement (`gpsIn`)**: Must be provided in the chosen local Cartesian **navigation frame** (e.g., ENU, NED).\n", + "- **Lever Arm (`leverArm`)**: Must be provided in the **body frame**.\n", + "- **Pose/NavState Variables**: Represent the pose of the body frame in the navigation frame ($T_{nb}$)." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Source\n", + "- [GPSFactor.h](https://github.com/borglab/gtsam/blob/develop/gtsam/navigation/GPSFactor.h)\n", + "- [GPSFactor.cpp](https://github.com/borglab/gtsam/blob/develop/gtsam/navigation/GPSFactor.cpp)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "py312", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.6" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/gtsam/navigation/navigation.i b/gtsam/navigation/navigation.i index f3d32251f..935428b4e 100644 --- a/gtsam/navigation/navigation.i +++ b/gtsam/navigation/navigation.i @@ -388,6 +388,41 @@ virtual class GPSFactor : gtsam::NonlinearFactor{ void serialize() const; }; +virtual class GPSFactorArm : gtsam::NonlinearFactor{ + GPSFactorArm(size_t key, const gtsam::Point3& gpsIn, + const gtsam::Point3& leverArm, + const gtsam::noiseModel::Base* model); + + // Testable + void print(string s = "", const gtsam::KeyFormatter& keyFormatter = + gtsam::DefaultKeyFormatter) const; + bool equals(const gtsam::NonlinearFactor& expected, double tol); + + // Standard Interface + gtsam::Point3 measurementIn() const; + gtsam::Vector evaluateError(const gtsam::Pose3& nTb); + + // enable serialization functionality + void serialize() const; +}; + +virtual class GPSFactorArmCalib : gtsam::NonlinearFactor{ + GPSFactorArmCalib(size_t key1, size_t key2, const gtsam::Point3& gpsIn, + const gtsam::noiseModel::Base* model); + + // Testable + void print(string s = "", const gtsam::KeyFormatter& keyFormatter = + gtsam::DefaultKeyFormatter) const; + bool equals(const gtsam::NonlinearFactor& expected, double tol); + + // Standard Interface + gtsam::Point3 measurementIn() const; + gtsam::Vector evaluateError(const gtsam::Pose3& nTb, const gtsam::Point3& leverArm); + + // enable serialization functionality + void serialize() const; +}; + virtual class GPSFactor2 : gtsam::NonlinearFactor { GPSFactor2(size_t key, const gtsam::Point3& gpsIn, const gtsam::noiseModel::Base* model); @@ -405,6 +440,41 @@ virtual class GPSFactor2 : gtsam::NonlinearFactor { void serialize() const; }; +virtual class GPSFactor2Arm : gtsam::NonlinearFactor{ + GPSFactor2Arm(size_t key, const gtsam::Point3& gpsIn, + const gtsam::Point3& leverArm, + const gtsam::noiseModel::Base* model); + + // Testable + void print(string s = "", const gtsam::KeyFormatter& keyFormatter = + gtsam::DefaultKeyFormatter) const; + bool equals(const gtsam::NonlinearFactor& expected, double tol); + + // Standard Interface + gtsam::Point3 measurementIn() const; + gtsam::Vector evaluateError(const gtsam::NavState& nTb); + + // enable serialization functionality + void serialize() const; +}; + +virtual class GPSFactor2ArmCalib : gtsam::NonlinearFactor{ + GPSFactor2ArmCalib(size_t key1, size_t key2, const gtsam::Point3& gpsIn, + const gtsam::noiseModel::Base* model); + + // Testable + void print(string s = "", const gtsam::KeyFormatter& keyFormatter = + gtsam::DefaultKeyFormatter) const; + bool equals(const gtsam::NonlinearFactor& expected, double tol); + + // Standard Interface + gtsam::Point3 measurementIn() const; + gtsam::Vector evaluateError(const gtsam::NavState& nTb, const gtsam::Point3& leverArm); + + // enable serialization functionality + void serialize() const; +}; + #include virtual class BarometricFactor : gtsam::NonlinearFactor { BarometricFactor();