Geospatial Representation API

Source: raptor/crs.hpp, raptor/quaternion.hpp, raptor/geo.hpp

Types

Name	Description
Crs	Coordinate Reference System wrapper holding either ECEF or Geodetic CRS.
Quaternion	Unit quaternion representing a 3D rotation.
Pose	Pose wrapper holding either ECEF or Geodetic.
Position	Position wrapper holding either ECEF or Geodetic.
Ray	Ray wrapper holding either ECEF or Geodetic.

---

Coordinate Reference System (CRS) types

CoordinateSystem

enum class CoordinateSystem : std::uint8_t

Coordinate system type - runtime enum

Ecef : Earth-Centered Earth-Fixed Cartesian coordinate system

Geodetic : Geodetic coordinate system (latitude, longitude, height)

---

ReferenceFrame

enum class ReferenceFrame : std::uint8_t

Reference frame (datum) - runtime enum

Wgs84g1674 : WGS84 (G1674) reference frame

Itrf2008 : ITRF2008 reference frame

---

HorizontalUnit

enum class HorizontalUnit : std::uint8_t

Angular unit for horizontal coordinates (lat/lon) - runtime enum

Radians : Radians

Degrees : Degrees

---

VerticalUnit

enum class VerticalUnit : std::uint8_t

Linear unit for vertical coordinate (altitude) - runtime enum

Meter : Meters

Foot : International foot (exactly 0.3048 meters)

---

HeightSystem

enum class HeightSystem : std::uint8_t

Height system (reference surface for altitude) - runtime enum

Ellipsoid : WGS84 Ellipsoid height (HAE - Height Above Ellipsoid)

Egm2008 : EGM2008 Geoid height (HAMSL - Height Above Mean Sea Level approximation)

---

Ecef

struct Ecef

ECEF (Earth-Centered Earth-Fixed) Coordinate Reference System

Earth-Centered Earth-Fixed Cartesian coordinate reference system.

• Position: [X, Y, Z] in meters from Earth's center according to the specified reference frame.
• Attitude (in Pose): Orientation relative to ECEF axes.

Variables

Name	Description
referenceFrame	Reference frame (default: ITRF2008).

Variable Details

referenceFrame

ReferenceFrame referenceFrame

Reference frame (default: ITRF2008)

---

Geodetic

struct Geodetic

Geodetic Coordinate Reference System

Geodetic coordinate reference system.

• Coordinates: [Latitude, Longitude, Height above reference surface] where height is positive upward (NEU (North-East-Up) convention).
• Attitude (in Pose): Orientation relative to the local NED (North-East-Down) frame.

Variables

Name	Description
referenceFrame	Reference frame (default: ITRF2008).
horizontalUnit	Angular unit for lat/lon (default: Degrees).
verticalUnit	Linear unit for altitude (default: Meter).
heightSystem	Reference surface for height (default: Ellipsoid/HAE).

Variable Details

referenceFrame

ReferenceFrame referenceFrame

Reference frame (default: ITRF2008)

horizontalUnit

HorizontalUnit horizontalUnit

Angular unit for lat/lon (default: Degrees)

verticalUnit

VerticalUnit verticalUnit

Linear unit for altitude (default: Meter)

heightSystem

HeightSystem heightSystem

Reference surface for height (default: Ellipsoid/HAE)

---

Crs

class Crs

Coordinate Reference System wrapper holding either ECEF or Geodetic CRS.

Functions

Name	Description
Crs()	Default constructor - creates a default ECEF CRS.
Crs(Ecef)	Construct from an ECEF CRS.
Crs(Geodetic)	Construct from a Geodetic CRS.

Function Details

Crs

Function

Crs()

Default constructor - creates a default ECEF CRS

Function

Crs(const crs::Ecef& crs) noexcept

Construct from an ECEF CRS

Function

Crs(const crs::Geodetic& crs) noexcept

Construct from a Geodetic CRS

---

Unit quaternion type for 3D rotations

Quaternion

struct Quaternion

Unit quaternion representing a 3D rotation

Quaternion using [x, y, z, w] convention where w is the scalar component. The quaternion must be normalized (unit quaternion with x² + y² + z² + w² = 1).

When used in a Pose, the inner frame used for the attitude is determined by the outer frame (CRS) coordinate system used in the pose:

• ECEF coordinate system -> ECEF inner frame
• Geodetic coordinate system -> NED inner frame

The direction of the rotation is from reference-to-camera.

Mathematically, for a vector \f$v_{ref} \f$ in the reference frame, the corresponding vector in the camera frame is: \f$v_{cam} = R \cdot v_{ref} \f$

For NED inner frame, the DIN 9300 camera frame convention is used:

• X-axis: Forward (optical axis, into the scene)
• Y-axis: Right
• Z-axis: Down

Functions

Name	Description
fromMatrix	Create quaternion from a 3x3 rotation matrix (row-major).
toMatrix	Convert quaternion to a 3x3 rotation matrix (row-major).
fromEuler	Create quaternion from intrinsic Z-Y-X Euler angles (yaw, pitch, roll).
toEuler	Convert quaternion to intrinsic Z-Y-X Euler angles (yaw, pitch, roll).
normSquared	Get the squared norm of the quaternion.
norm	Get the norm of the quaternion.
normalize	Normalize the quaternion to unit length.
isNormalized	Check if quaternion is approximately unit length.

Function Details

fromMatrix

Function

[[nodiscard]] static Quaternion fromMatrix(const std::array<double, 9>& matrix)

Create quaternion from a 3x3 rotation matrix (row-major)

Uses the algorithm from "Accurate computation of quaternions from rotation matrices" by Sarabandi & Thomas for numerical stability.

Parameters:

• matrix - Row-major 3x3 rotation matrix [R00, R01, R02, R10, R11, R12, R20, R21, R22]

Returns: Quaternion representing the same rotation

toMatrix

Function

[[nodiscard]] std::array<double, 9> toMatrix() const

Convert quaternion to a 3x3 rotation matrix (row-major)

Returns: Row-major 3x3 rotation matrix [R00, R01, R02, R10, R11, R12, R20, R21, R22]

fromEuler

Function

[[nodiscard]] static Quaternion fromEuler(double yaw, double pitch, double roll)

Create quaternion from intrinsic Z-Y-X Euler angles (yaw, pitch, roll)

Convention: the combined rotation is R = Rz(yaw) * Ry(pitch) * Rx(roll), applied to a column vector. Inputs are in radians.

Parameters:

• yaw - Rotation about the Z axis (radians)
• pitch - Rotation about the Y axis (radians)
• roll - Rotation about the X axis (radians)

Returns: Normalized quaternion representing the same rotation

toEuler

Function

[[nodiscard]] std::array<double, 3> toEuler() const

Convert quaternion to intrinsic Z-Y-X Euler angles (yaw, pitch, roll)

Inverse of fromEuler. Returned angles are in radians with ranges:

• yaw ∈ (-π, π]
• pitch ∈ [-π/2, π/2]
• roll ∈ (-π, π]

Near gimbal lock (|pitch| ≈ π/2) yaw and roll become coupled and the split between them is not unique; callers should handle that case explicitly.

Returns: Array {yaw, pitch, roll} in radians

normSquared

Function

[[nodiscard]] double normSquared() const noexcept

Get the squared norm of the quaternion

Returns: x² + y² + z² + w²

norm

Function

[[nodiscard]] double norm() const noexcept

Get the norm of the quaternion

Returns: sqrt(x² + y² + z² + w²)

normalize

Function

[[nodiscard]] Quaternion normalize() const noexcept

Normalize the quaternion to unit length

Returns: Normalized quaternion. If the quaternion is numerically zero (norm < 1e-15), the identity quaternion is returned instead.

isNormalized

Function

[[nodiscard]] bool isNormalized() const noexcept

Check if quaternion is approximately unit length

Returns: True if quaternion is normalized within tolerance (1e-6)

---

Geographic types for position, attitude, and pose representation

Ecef

struct Ecef

ECEF coordinates (Earth-Centered, Earth-Fixed) in meters

The CRS context is provided by the containing Position or Pose type.

---

Geodetic

struct Geodetic

Geodetic coordinates (latitude, longitude, altitude)

Units, height system, and axes convention are defined by the containing Position or Pose type's CRS.

---

Ecef

struct Ecef

Direction vector in ECEF axes

Components along the Earth-Centered, Earth-Fixed axes.

---

Ned

struct Ned

Direction vector in a local NED (North-East-Down) frame

Components in the local NED frame at the associated origin.

---

Ecef

struct Ecef

ECEF Position

The CRS is stored as a member variable and describes how the data should be interpreted.

position::Ecef pos{
    .coords = {4000000, 300000, 5000000},
    .crs = {.referenceFrame = ReferenceFrame::Wgs84g1674}
};

Variables

Name	Description
coords	[X, Y, Z] coordinates in meters.
crs	Coordinate reference system (CRS).

Variable Details

coords

coordinates::Ecef coords

[X, Y, Z] coordinates in meters

crs

crs::Ecef crs

Coordinate reference system (CRS)

---

Geodetic

struct Geodetic

Geodetic Position

The CRS is stored as a member variable and describes how the data should be interpreted.

position::Geodetic pos{
    .coords = {51.5, -0.1, 100.0},
    .crs = {.horizontalUnit = HorizontalUnit::Degrees}
};

Variables

Name	Description
coords	[lat, lon, alt] with NEU axis convention (units per CRS).
crs	Coordinate reference system (CRS).

Variable Details

coords

coordinates::Geodetic coords

[lat, lon, alt] with NEU axis convention (units per CRS)

crs

crs::Geodetic crs

Coordinate reference system (CRS)

---

Ecef

struct Ecef

ECEF Pose

The CRS is stored as a member variable and describes how the data should be interpreted.

pose::Ecef pose{
    .coords = {4000000, 300000, 5000000},
    .attitude = {0, 0, 0, 1},
    .crs = {.referenceFrame = ReferenceFrame::Wgs84g1674}
};

See: crs::Ecef for CRS details

Variables

Name	Description
coords	[X, Y, Z] coordinates in meters.
attitude	Orientation [x, y, z, w] relative to ECEF axes.
crs	Coordinate reference system (CRS).

Variable Details

coords

coordinates::Ecef coords

[X, Y, Z] coordinates in meters

attitude

Quaternion attitude

Orientation [x, y, z, w] relative to ECEF axes

crs

crs::Ecef crs

Coordinate reference system (CRS)

---

Geodetic

struct Geodetic

Geodetic Pose

The CRS is stored as a member variable and describes how the data should be interpreted.

pose::Geodetic pose{
    .coords = {51.5, -0.1, 100.0},
    .attitude = {0, 0, 0, 1},
    .crs = {.horizontalUnit = HorizontalUnit::Degrees}
};

Variables

Name	Description
coords	[lat, lon, alt] with the altitude being positive upwards and the height above the reference surface (units per CRS).
attitude	Orientation [x, y, z, w] relative to local NED frame.
crs	Coordinate reference system (CRS).

Variable Details

coords

coordinates::Geodetic coords

[lat, lon, alt] with the altitude being positive upwards and the height above the reference surface (units per CRS)

attitude

Quaternion attitude

Orientation [x, y, z, w] relative to local NED frame

crs

crs::Geodetic crs

Coordinate reference system (CRS)

---

Ecef

struct Ecef

ECEF Ray (origin + direction)

A line starting at an ECEF origin and travelling along the direction vector, expressed in the same Earth-Centered, Earth-Fixed frame as the origin.

The direction need not be normalized; only its orientation is significant. It must be finite and have non-zero magnitude.

ray::Ecef ray{
    .origin = {.coords = {4000000, 300000, 5000000}},
    .direction = {.x = 1.0, .y = 0.0, .z = 0.0},
};

Variables

Name	Description
origin	Ray origin in ECEF.
direction	Direction in ECEF axes.

Variable Details

origin

position::Ecef origin

Ray origin in ECEF

direction

direction::Ecef direction

Direction in ECEF axes

---

Geodetic

struct Geodetic

Geodetic Ray (origin + direction in local NED)

A line starting at a geodetic origin and travelling along the direction vector, expressed in the local NED frame at that origin.

The direction need not be normalized; only its orientation is significant. It must be finite and have non-zero magnitude.

ray::Geodetic ray{
    .origin = {.coords = {51.5, -0.1, 100.0}},
    .direction = {.north = 0.0, .east = 0.0, .down = 1.0},
};

Variables

Name	Description
origin	Ray origin in geodetic coordinates.
direction	Direction in local NED frame at origin.

Variable Details

origin

position::Geodetic origin

Ray origin in geodetic coordinates

direction

direction::Ned direction

Direction in local NED frame at origin

---

Pose

class Pose

Functions

Name	Description
Pose()	Default constructor - creates identity ECEF pose.
Pose(Ecef)	Construct from an ECEF pose.
Pose(Geodetic)	Construct from a Geodetic pose.

Function Details

Pose

Function

Pose()

Default constructor - creates identity ECEF pose

Creates a pose at origin (0,0,0) with identity attitude.

Function

Pose(const pose::Ecef& pose)

Construct from an ECEF pose. Validates that coordinates are finite and the attitude quaternion is normalized. Throws: std::invalid_argument - If coordinates are not finite or attitude is not normalized.

Function

Pose(const pose::Geodetic& pose)

Construct from a Geodetic pose. Validates coordinate ranges (per CRS units) and that the attitude quaternion is normalized. Throws: std::invalid_argument - If coordinates are out of range / not finite, or the attitude quaternion is not normalized.

---

Position

class Position

Functions

Name	Description
Position()	Default constructor - creates identity ECEF position.
Position(Ecef)	Construct from an ECEF position.
Position(Geodetic)	Construct from a Geodetic position.

Function Details

Position

Function

Position()

Default constructor - creates identity ECEF position

Creates a position at origin (0,0,0).

Function

Position(const position::Ecef& pos)

Construct from an ECEF position. Validates that coordinates are finite. Throws: std::invalid_argument - If coordinates are not finite.

Function

Position(const position::Geodetic& pos)

Construct from a Geodetic position. Validates coordinate ranges (per CRS units). Throws: std::invalid_argument - If coordinates are out of range or not finite.

---

Ray

class Ray

Functions

Name	Description
Ray()	Default constructor - creates a zero ECEF ray.
Ray(Ecef)	Construct from an ECEF ray.
Ray(Geodetic)	Construct from a Geodetic ray.

Function Details

Ray

Function

Ray()

Default constructor - creates a zero ECEF ray

Default-constructed Ray holds a zero-magnitude direction and is not valid for use; pass through one of the validating constructors before querying.

Function

Ray(const ray::Ecef& ray)

Construct from an ECEF ray. Validates that the origin is finite and the direction has finite components and non-zero magnitude. Throws: std::invalid_argument - If the origin or direction is invalid.

Function

Ray(const ray::Geodetic& ray)

Construct from a Geodetic ray. Validates origin coordinate ranges (per CRS units) and that the NED direction has finite components and non-zero magnitude. Throws: std::invalid_argument - If the origin or direction is invalid.