Guide API - High-Precision Camera Pose Estimation

Python API

This documentation covers the C++ API. A Python API is also available with a 1:1 mapping of all functions and types, except for using snake_case instead of camelCase. See 'bindings_sdk.cpp' in python examples/.

Types

Name	Description
Result	Result Result status for pose estimation operations Indicates whether the updatePose method completed without errors.
GroundPositionError	GroundPositionError Error codes for ground position query operations Describes different errors that may occur when querying for ground position.
PoseOutput	PoseOutput Output data from pose estimation Contains the refined camera pose, uncertainty estimates, and quality metrics.
PositionOutput	Output data from position estimation Contains the refined position, uncertainty estimates, and quality metrics.
Guide	Main Raptor Guide™ SDK class for camera pose estimation This class provides high-precision camera pose refinement using Vantor 3D maps.

Type Aliases

Name	Description
ImageData	ImageData Grayscale image data pointer Pointer to 8-bit grayscale image data (single channel).
Fov	Fov Field of view angle in radians Used for both horizontal and vertical field of view parameters.
Position	Position Camera position estimate Format depends on the configured reference frame: • Geodetic: [Latitude(rad), Longitude(rad), Height(m)] • ECEF: [X(m), Y(m), Z(m)]
Attitude	Attitude Camera attitude estimate as unit quaternion Format: [x, y, z, w] (scalar component last)
PoseCovariance	PoseCovariance 6×6 covariance matrix for pose uncertainty Row-major layout representing the uncertainty of the initial pose estimate.
PositionCovariance	PositionCovariance 3×3 covariance matrix for position uncertainty Row-major layout representing the uncertainty of the position estimate.
Milliseconds	Milliseconds Processing time duration in milliseconds Used for defining maximum allowed processing time.
Timestamp	Timestamp High-resolution timestamp type.
Confidence	Confidence Confidence score (0.0-1.0) • Recommended quality metric Primary indicator of result quality and reliability.

Type Alias Details

ImageData

using ImageData = const std::uint8_t*

ImageData 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.

Fov

using Fov = double

Fov Field of view angle in radians

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

Position

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

Position Camera position estimate

Format depends on the configured reference frame:

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

Attitude

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

Attitude Camera attitude estimate as unit quaternion

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

PoseCovariance

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

PoseCovariance 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)

note

The search range is determined by the covariance values and the configured confidence interval. The relationship uses the chi-squared distribution.

See: Config::confidenceInterval for configuring the confidence interval

See: integration_guide.md for detailed examples of covariance usage

PositionCovariance

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

PositionCovariance 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

Milliseconds

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

Milliseconds Processing time duration in milliseconds

Used for defining maximum allowed processing time. The algorithm will return the best result found within this time. Not a hard limit - may exceed slightly. Not a minimum time - may return before this time. Increase pose uncertainty if you want the system to evaluate more hypotheses.

Timestamp

using Timestamp = std::chrono::nanoseconds

Timestamp 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.

Confidence

using Confidence = double

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

---

Result

enum class Result

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 parameter(s) contains invalid values - no pose was estimated

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

InsufficientMapCoverage : Insufficient 3D map coverage at the input pose location - pose is likely outside map bounds

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

---

GroundPositionError

enum class GroundPositionError

GroundPositionError Error codes for ground position query operations

Describes different errors that may occur when querying for ground position.

InvalidInput : Input position contains invalid values

InsufficientMapCoverage : Insufficient 3D map coverage at the input position - position is likely outside map bounds

Failed : Operation failed due to errors

---

PoseOutput

struct PoseOutput

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

Variables

Name	Description
result	Operation result status Indicates whether the operation completed without errors.
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)
confidence	Confidence score - recommended quality metric (see Confidence type for details)
timestamp	Optional timestamp (same as input)

Variable 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

position

Position position

Refined camera position (see Position type for format details)

attitude

Attitude attitude

Refined camera attitude (see Attitude type for format details)

poseCovariance

PoseCovariance poseCovariance

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

confidence

Confidence confidence

Confidence score (see Confidence type for details)

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.

warning

Two-step validation required:

1. Check result == Result::Ok (operation completed without errors)
2. Check confidence values for result quality

Variables

Name	Description
result	Operation result status Indicates whether the operation completed without errors.
position	Refined camera position (see Position type for format details)
positionCovariance	3x3 position covariance matrix (see PositionCovariance type for details)
confidence	Confidence score (see Confidence type for details)
timestamp	Optional timestamp (same as input)

Variable 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

position

Position position

Refined camera position (see Position type for format details)

positionCovariance

PositionCovariance positionCovariance

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

confidence

Confidence confidence

Confidence score (see Confidence type for details)

timestamp

std::optional<Timestamp> timestamp

Optional timestamp (same as input)

Preserved from input for correlation with image data.

---

Guide

Variables

Name	Description
_impl	Internal implementation (PIMPL pattern)

Variable Details

_impl

std::unique_ptr<internal::GuideImpl> _impl

Internal implementation (PIMPL pattern)

Functions

Name	Description
Guide	Initialize the Raptor Guide™ SDK with configuration Creates all required GPU resources and loads initial map data.
getVersion	Get the Raptor Guide™ SDK version and build information Return : Version number and version control metadata
generateFingerprint	Generate a license fingerprint for the current machine.
updatePose	Refine camera pose using image and 3D map matching This is the main SDK function.
updatePosition	Refine camera position using image and 3D map matching Same as updatePose but without updated attitude in the output.
renderReferenceImage	Render a reference image The reference image can be used to manually validate the input to the update pose function.
getGroundPosition	Get the ground intersection position for a given horizontal location Returns the 3D position on the map surface at the specified horizontal location.
~Guide	Destructor - automatically cleans up all resources All GPU resources and loaded maps are automatically freed.

Function Details

Guide

Function

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

getVersion

Function

static utils::Version getVersion()

Get the Raptor Guide™ SDK version and build information Returns: Version number and version control metadata

generateFingerprint

Function

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.

note

For detailed information, see the documentation.

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

updatePose

Function

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) Parameters:
• hFov - Horizontal field of view (see Fov type for details) Parameters:
• vFov - Vertical field of view (see Fov type for details) Parameters:
• position - Initial position estimate (see Position type for format details) Parameters:
• attitude - Initial attitude estimate (see Attitude type for format details) Parameters:
• poseCovariance - Optional covariance matrix (see PoseCovariance type for details). Covariance values should reflect input pose uncertainty for optimal results. Parameters:
• maxTime - Optional maximum processing time (see Milliseconds type for details). Parameters:
• 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 indicated by the Result enum. This method does not throw exceptions during normal operation.

note

This function is computationally intensive. For real-time applications, consider using maxTime parameter and monitoring the confidence score.

updatePosition

Function

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) Parameters:
• hFov - Horizontal field of view (see Fov type for details) Parameters:
• vFov - Vertical field of view (see Fov type for details) Parameters:
• position - Initial position estimate (see Position type for format details) Parameters:
• attitude - Initial attitude estimate (see Attitude type for format details) Parameters:
• poseCovariance - Optional covariance matrix (see PoseCovariance type for details). Covariance values should reflect input pose uncertainty for optimal results. Parameters:
• maxTime - Optional maximum processing time (see Milliseconds type for details). Parameters:
• 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 indicated by the Result enum. This method does not throw exceptions during normal operation.

note

This function is computationally intensive. For real-time applications, consider using maxTime parameter and monitoring the confidence score.

renderReferenceImage

Function

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 (see Fov type for details) Parameters:
• vFov - Vertical field of view (see Fov type for details) Parameters:
• position - Position (see Position type for format details) Parameters:
• 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.

getGroundPosition

Function

std::variant<Position, GroundPositionError> getGroundPosition( const Position& position) noexcept

Get the ground intersection position for a given horizontal location

Returns the 3D position on the map surface at the specified horizontal location. Parameters:

• position - The query position (see Position type for format details) Returns: std::variant containing either:
  • Position: The ground position at the query location
  • GroundPositionError: Error code if the query failed

note

This does not necessarily return the ground level position, rather it returns the position of the map surface. For example, if the map contains a building or trees at the given horizontal location, the position of the top of the building or tree is returned.

See: GroundPositionError for possible error conditions

~Guide

Function

~Guide()

Destructor - automatically cleans up all resources

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