Guide API - High-Precision Camera Pose Estimation

The API provides accurate camera pose refinement using 3D maps. It solves the Perspective-n-Point problem for calibrated airborne camera sensors.

Coordinate Systems & Conventions

• Data Format: All matrices and images use row-major order
• Terrestrial Reference Frame: ITRF2008 (~= WGS 84 G1674, == WGS 84 G1762)
• Rotation Convention:
  • Geodetic: Relative to local NED (North-East-Down) frame
  • ECEF: Relative to Earth-Centered Earth-Fixed X,Y,Z axes
• North Reference: True north (not magnetic north)
• Quaternion Format: [x, y, z, w] (scalar component last)

Quick Start

See examples in raptor_guide_usage_example/ directory for complete integration examples.

• basic_usage.cpp: Simple pose estimation
• advanced_usage.cpp: Error handling and covariance usage
• integration_guide.md: Complete integration documentation

Error Handling

The SDK uses exceptions for errors during initialization. Always wrap initialization calls in try-catch blocks. Runtime errors during pose estimation are indicated by the Result enum. The updatePose() method performs comprehensive parameter validation and exception handling internally, converting any errors to Result::Failed.

warning

Multiple instances may compete for GPU resources and memory, potentially causing resource conflicts and performance degradation. Consider the trade-offs between parallelism benefits and resource contention costs.

Recommended

Use a single Guide instance with sequential calls to updatePose() for optimal performance and resource utilization.

Types

Name	Description
Guide	Main Raptor Guide SDK class for camera pose estimation.
PoseOutput	Output data from pose estimation.
PositionOutput	Output data from position estimation.
Result	Result status for pose estimation operations.

Type Aliases

Name	Description
Attitude	Camera attitude estimate as unit quaternion.
Confidence	Confidence score (0.0-1.0) - Recommended quality metric. Primary indicator of result quality and reliability. Quality assessment guidelines: - > 0.95: Excellent quality - high confidence result - 0.85-0.95: Good quality - reliable for most applications - 0.7-0.85: Moderate quality - use with caution - < 0.7: Poor quality - recommended to reject the result !!! note Always check this value even when result == Result::Ok
FigureOfMerit	Figure of Merit (FOM) quality score (0.0-1.0). !!! warning "Deprecated" Figure of Merit is deprecated and will be removed in future versions. Use Confidence instead as the recommended quality metric. :material-eye-outline: See : Confidence for the recommended quality metric
Fov	Field of view angle in radians.
ImageData	Grayscale image data pointer.
Milliseconds	Processing time duration in milliseconds.
PoseCovariance	6×6 covariance matrix for pose uncertainty.
Position	Camera position estimate.
PositionCovariance	3×3 covariance matrix for position uncertainty.
Timestamp	High-resolution timestamp type.

Type Alias Details

Attitude

using Attitude = std::array<double, 4>

Camera attitude estimate as unit quaternion.

Format: [x, y, z, w] (scalar component last) Represents rotation from reference frame to camera frame.

Confidence

using Confidence = double

Confidence score (0.0-1.0) - Recommended quality metric.

Primary indicator of result quality and reliability.

Quality assessment guidelines:

• > 0.95: Excellent quality - high confidence result
• 0.85-0.95: Good quality - reliable for most applications
• 0.7-0.85: Moderate quality - use with caution
• < 0.7: Poor quality - recommended to reject the result

note

Always check this value even when result == Result::Ok

FigureOfMerit

using FigureOfMerit = double

Figure of Merit (FOM) quality score (0.0-1.0).

Deprecated

Figure of Merit is deprecated and will be removed in future versions. Use Confidence instead as the recommended quality metric.

See: Confidence for the recommended quality metric

Fov

using Fov = double

Field of view angle in radians.

Used for both horizontal and vertical field of view parameters. Must match your camera's actual FOV for accurate results.

ImageData

using ImageData = const std::uint8_t*

Grayscale image data pointer.

Pointer to 8-bit grayscale image data (single channel). Size must be exactly imageWidth × imageHeight bytes as specified in constructor. Data layout: row-major, top-to-bottom, left-to-right.

Milliseconds

using Milliseconds = std::chrono::duration<double, std::milli>

Processing time duration in milliseconds.

Used for defining maximum allowed processing time for updatePose() Typical values: 1000-10000ms. The algorithm will return the best result found within this time. Not a hard limit - may exceed slightly.

PoseCovariance

using PoseCovariance = std::array<double, 36>

6×6 covariance matrix for pose uncertainty.

Row-major layout representing the uncertainty of the initial pose estimate. The magnitude of covariance values defines the search range for pose hypotheses:

• WITH covariance: Search range proportional to uncertainty values
• WITHOUT covariance: Assumes low uncertainty, processes single hypothesis only

Units:

• Position uncertainty: meters (squared) - always in meters regardless of geodeticOptions.verticalUnit or geodeticOptions.horizontalUnit
• Attitude uncertainty: radians (squared)

Position

using Position = std::array<double, 3>

Camera position estimate.

Format depends on the configured reference frame:

• Geodetic: [Latitude(rad), Longitude(rad), Height(m)]
• ECEF: [X(m), Y(m), Z(m)]

PositionCovariance

using PositionCovariance = std::array<double, 9>

3×3 covariance matrix for position uncertainty.

Row-major layout representing the uncertainty of the position estimate. Units: meters (squared) - always in meters regardless of geodeticOptions.verticalUnit or geodeticOptions.horizontalUnit

Timestamp

using Timestamp = std::chrono::nanoseconds

High-resolution timestamp type.

Optional. Not currently used in SDK. Used for precise timing of image acquisition and pose estimates. Epoch is arbitrary but must be consistent within your application.

Type Details

Guide

class Guide

Main Raptor Guide SDK class for camera pose estimation.

This class provides high-precision camera pose refinement using Vantor 3D maps.

USAGE: Initialize once, then process images sequentially with updatePose() or updatePosition()

warning

This class is NOT thread-safe. Use separate instances for concurrent processing. However, multiple instances may compete for GPU resources and memory, potentially leading to resource conflicts and degraded performance. Consider the trade-offs between parallelism and resource contention.

note

See raptor_guide_usage_example/ directory for complete working examples.

Variables

Name	Description
_impl	Internal implementation (PIMPL pattern)

Functions

Name	Description
Guide	Initialize the Raptor Guide SDK with configuration.
~Guide	Destructor - automatically cleans up all resources.
getVersion	Get the Raptor Guide SDK version and build information.
generateFingerprint	Generate a license fingerprint for the current machine.
updatePose	Refine camera pose using image and 3D map matching.
updatePosition	Refine camera position using image and 3D map matching.
renderReferenceImage	Render a reference image.

Variable Details

_impl

std::unique_ptr<internal::GuideImpl> _impl

Internal implementation (PIMPL pattern)

Function Details

Guide

explicit Guide(const guide::Config& config)

Initialize the Raptor Guide SDK with configuration.

Creates all required GPU resources and loads initial map data. This is an expensive operation - reuse the instance for multiple images.

Image dimensions (imageWidth and imageHeight) must be specified in the config. They must be consistent for all images processed with this Guide instance.

Parameters:

• config — SDK configuration parameters (see Config struct for details)

Throws: std::runtime_error If initialization fails

See: raptor_guide_usage_example/ directory for complete initialization examples

generateFingerprint

static std::optional<std::string> generateFingerprint()

Generate a license fingerprint for the current machine.

This function creates a fingerprint that can be used when requesting a license for the machine where the SDK is running. For detailed information, see the License Management Guide.

Returns: The fingerprint on success; std::nullopt on failure

getVersion

static utils::Version getVersion()

Get the Raptor Guide SDK version and build information.

Returns: Version number and version control metadata

renderReferenceImage

std::optional<std::vector<std::uint8_t>> renderReferenceImage(
    Fov hFov, Fov vFov,
    const Position& position,
    const Attitude& attitude) noexcept

Render a reference image.

The reference image can be used to manually validate the input to the update pose function.

Parameters:

• hFov — Horizontal field of view angle in radians
• vFov — Vertical field of view angle in radians
• position — Position (see Position type for format details)
• attitude — Attitude (see Attitude type for format details)

Returns: An image buffer containing a grayscale reference image rendered from the 3D map matching the input pose. The return value std::nullopt indicates an error occurred.

updatePose

PoseOutput updatePose(
    ImageData imageData,
    Fov hFov, Fov vFov,
    const Position& position,
    const Attitude& attitude,
    const std::optional<PoseCovariance>& poseCovariance = std::nullopt,
    const std::optional<Milliseconds>& maxTime = std::nullopt,
    const std::optional<Timestamp>& timestamp = std::nullopt)

Refine camera pose using image and 3D map matching.

This is the main SDK function. It takes an approximate camera pose and refines it by matching the input image against rendered views from the 3D map.

Parameters:

• imageData — Image data (see ImageData type for format details)
• hFov — Horizontal field of view angle in radians
• vFov — Vertical field of view angle in radians
• position — Initial position estimate (see Position type for format details)
• attitude — Initial attitude estimate (see Attitude type for format details)
• poseCovariance — Optional covariance matrix (see PoseCovariance type for details). Covariance values should reflect input pose uncertainty for optimal results.
• maxTime — Optional maximum processing time (see Milliseconds type for details).
• timestamp — Optional timestamp for correlation with image data (see Timestamp type for details). Preserved in output for your reference.

Returns: PoseOutput containing refined pose, uncertainty, and quality metrics

note

This method performs comprehensive parameter validation and exception handling internally. Invalid parameters or system errors are converted to Result::Failed in the returned PoseOutput. This method does not throw exceptions during normal operation - all errors are communicated through the Result enum.

note

This function is computationally intensive. For real-time applications, consider using maxTime parameter and monitoring the figure of merit.

See: raptor_guide_usage_example/ directory for complete usage examples with error handling

updatePosition

PositionOutput updatePosition(
    ImageData imageData,
    Fov hFov, Fov vFov,
    const Position& position,
    const Attitude& attitude,
    const std::optional<PoseCovariance>& poseCovariance = std::nullopt,
    const std::optional<Milliseconds>& maxTime = std::nullopt,
    const std::optional<Timestamp>& timestamp = std::nullopt)

Refine camera position using image and 3D map matching.

Same as updatePose but without updated attitude in the output.

Parameters:

• imageData — Image data (see ImageData type for format details)
• hFov — Horizontal field of view angle in radians
• vFov — Vertical field of view angle in radians
• position — Initial position estimate (see Position type for format details)
• attitude — Initial attitude estimate (see Attitude type for format details)
• poseCovariance — Optional covariance matrix (see PoseCovariance type for details). Covariance values should reflect input pose uncertainty for optimal results.
• maxTime — Optional maximum processing time (see Milliseconds type for details).
• timestamp — Optional timestamp for correlation with image data (see Timestamp type for details). Preserved in output for your reference.

Returns: PositionOutput containing refined position, uncertainty, and quality metrics

note

This method performs comprehensive parameter validation and exception handling internally. Invalid parameters or system errors are converted to Result::Failed in the returned PositionOutput. This method does not throw exceptions during normal operation - all errors are communicated through the Result enum.

See: raptor_guide_usage_example/ directory for complete usage examples with error handling

~Guide

~Guide()

Destructor - automatically cleans up all resources.

All GPU resources and loaded maps are automatically freed. No manual cleanup required.

PoseOutput

struct PoseOutput

Output data from pose estimation.

Contains the refined camera pose, uncertainty estimates, and quality metrics.

warning

Two-step validation required:

1. Check result == Result::Ok (operation completed without errors)
2. Check confidence values for result quality (> 0.75 recommended minimum for both)

Variables

Name	Description
result	Operation result status.
position	Refined camera position (see Position type for format details).
attitude	Refined camera attitude (see Attitude type for format details).
poseCovariance	6x6 pose covariance matrix (see PoseCovariance type for details).
fom	Figure of Merit - quality score (see FigureOfMerit type for details).
confidence	Confidence score - recommended quality metric (see Confidence type for details).
timestamp	Optional timestamp (same as input).

Variable Details

attitude

Attitude attitude

Refined camera attitude (see Attitude type for format details).

confidence

Confidence confidence

Confidence score - recommended quality metric (see Confidence type for details).

fom

FigureOfMerit fom

Figure of Merit - quality score (see FigureOfMerit type for details).

Deprecated

Use confidence instead. FoM will be removed in future versions.

poseCovariance

PoseCovariance poseCovariance

6x6 pose covariance matrix (see PoseCovariance type for details).

position

Position position

Refined camera position (see Position type for format details).

result

Result result

Operation result status.

Indicates whether the operation completed without errors. This does NOT indicate quality - check confidence field for that. Only use other fields if result == Result::Ok

timestamp

std::optional<Timestamp> timestamp

Optional timestamp (same as input).

Preserved from input for correlation with image data.

PositionOutput

struct PositionOutput

Output data from position estimation.

Contains the refined position, uncertainty estimates, and quality metrics. Note: Same implementation as updatePose, but without attitude estimation.

warning

Two-step validation required:

1. Check result == Result::Ok (operation completed without errors)
2. Check confidence values for result quality (> 0.75 recommended minimum for both)

Variables

Name	Description
result	Operation result status.
position	Refined camera position (see Position type for format details).
positionCovariance	3x3 position covariance matrix (see PositionCovariance type for details).
fom	Figure of Merit - quality score (see FigureOfMerit type for details).
confidence	Confidence score (see Confidence type for details).
timestamp	Optional timestamp (same as input).

Variable Details

confidence

Confidence confidence

Confidence score (see Confidence type for details).

fom

FigureOfMerit fom

Figure of Merit - quality score (see FigureOfMerit type for details).

Deprecated

Use confidence instead. FoM will be removed in future versions.

position

Position position

Refined camera position (see Position type for format details).

positionCovariance

PositionCovariance positionCovariance

3x3 position covariance matrix (see PositionCovariance type for details).

result

Result result

Operation result status.

Indicates whether the operation completed without errors. This does NOT indicate quality - check confidence field for that. Only use other fields if result == Result::Ok

timestamp

std::optional<Timestamp> timestamp

Optional timestamp (same as input).

Preserved from input for correlation with image data.

Result

enum class Result

Result status for pose estimation operations.

Indicates whether the updatePose method completed without errors. This does NOT indicate the quality of the result - use the Confidence score in PoseOutput to assess result quality and reliability.

note

Always check both result == Ok AND confidence value before using pose data

Ok : Operation completed without errors - check confidence for quality assessment

UncertainOutput : Operation completed without errors, but with high uncertainty - pose may not be useful

PoseEstimationFailed : Operation completed without errors but no pose could be estimated - do not use pose-output

InvalidInput : Input pose was invalid (outside map, or facing the sky for example) - no pose was estimated

InvalidLicense : Operation could not be performed due to an invalid or insufficient license

Failed : Operation failed due to errors - no pose was estimated