Pose Estimation API

Source: raptor/guide/errors.hpp, raptor/guide/PoseEstimator.hpp

Type Aliases

Name	Description
PoseCovariance	6x6 pose covariance matrix (row-major).
PositionCovariance	3x3 position covariance matrix (row-major).
Confidence	Confidence score (0.0-1.0).

Types

Name	Description
PoseEstimationError	Error codes for pose and position estimation operations.
DebugResult	Result status for debug capture operations.
PoseOutput	Successful output from pose estimation.
PositionOutput	Successful output from position estimation.
EstimationOptions	Per-call options for updatePose / updatePosition.
PoseEstimator	Main Raptor Guide class for camera pose estimation.

---

Error types for runtime operations

PoseEstimationError

enum class PoseEstimationError : std::uint8_t

Error codes for pose and position estimation operations.

PoseEstimationFailed : No pose could be estimated

InvalidInput : Input parameter(s) contains invalid values

ExpiredLicense : Operation could not be performed due to an expired license

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

PoorFeatureDensity : Insufficient feature density in the input image

Failed : Operation failed due to errors

---

DebugResult

enum class DebugResult : std::uint8_t

Result status for debug capture operations.

Ok : Operation completed without errors

AlreadyActive : Debug capture is already running

NotActive : Debug capture is not running

FileExists : Target archive already exists and overwrite is disabled

InvalidPath : Target path is empty or its parent directory does not exist

ExpiredLicense : Operation could not be performed due to an expired license

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

Failed : Operation failed due to errors

---

High-precision camera pose estimation

Type Alias Details

PoseCovariance

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

6x6 pose covariance matrix (row-major).

Represents the uncertainty of a pose over (x, y, z, yaw, pitch, roll) in the camera frame (DIN 9300: x forward, y right, z down). Yaw is rotation about z, pitch about y, roll about x. Users wishing to express uncertainty along another axis (e.g. local NED) must rotate it into the camera frame before passing it in.

Units:

• Position uncertainty: meters²
• Attitude uncertainty: radians²

The magnitude of the values controls the search range for pose hypotheses:

• WITH covariance: search range proportional to uncertainty values, scaled by the configured confidence interval (chi-squared distribution).
• WITHOUT covariance: assumes low uncertainty, single hypothesis only.

See: EstimationOptions::confidenceInterval

See: integration_guide.md for detailed examples of covariance usage.

PositionCovariance

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

3x3 position covariance matrix (row-major).

Represents the uncertainty of a position over (x, y, z) in the camera frame (DIN 9300: x forward, y right, z down).

Units: meters²

See: PoseCovariance for search-range semantics.

Confidence

using Confidence = double

Confidence score (0.0-1.0)

Primary indicator of result quality and reliability.

Quality assessment guidelines:

• 0.95: Excellent quality - high accuracy

• 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 before using pose data

PoseOutput

template <typename PoseType> struct PoseOutput

Successful output from pose estimation

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

Variables

Name	Description
pose	Refined camera pose.
covariance	Pose covariance matrix (see PoseCovariance).
confidence	Confidence score (see Confidence type for details).
mapCoverage	Fraction of the camera's view covered by valid 3D map data (0.0-1.0).
timestamp	Image timestamp (same as input).

Variable Details

pose

PoseType pose

Refined camera pose

covariance

std::optional<PoseCovariance> covariance

Pose covariance matrix (see PoseCovariance).

Set when the estimator was able to produce an uncertainty estimate; otherwise empty.

confidence

Confidence confidence

Confidence score (see Confidence type for details)

mapCoverage

double mapCoverage

Fraction of the camera's view covered by valid 3D map data (0.0-1.0)

Indicates how much of the camera's view intersects the loaded 3D map. Low values mean large portions of the frame fall outside the map, which reduces the quality of the matching and typically degrades result quality.

timestamp

std::chrono::nanoseconds timestamp

Image timestamp (same as input)

Preserved from the input timestamp identifying when the input image was captured.

---

PositionOutput

template <typename PositionType> struct PositionOutput

Successful output from position estimation

Contains the refined position, uncertainty estimates, and quality metrics.

Variables

Name	Description
position	Refined camera position.
covariance	Position covariance matrix (see PositionCovariance).
confidence	Confidence score (see Confidence type for details).
mapCoverage	Fraction of the camera's view covered by valid 3D map data (0.0-1.0).
timestamp	Image timestamp (same as input).

Variable Details

position

PositionType position

Refined camera position

covariance

std::optional<PositionCovariance> covariance

Position covariance matrix (see PositionCovariance).

Set when an uncertainty estimate is available; otherwise empty.

confidence

Confidence confidence

Confidence score (see Confidence type for details)

mapCoverage

double mapCoverage

Fraction of the camera's view covered by valid 3D map data (0.0-1.0)

Indicates how much of the camera's view intersects the loaded 3D map. Low values mean large portions of the frame fall outside the map, which reduces the quality of the matching and typically degrades result quality.

timestamp

std::chrono::nanoseconds timestamp

Image timestamp (same as input)

Preserved from the input timestamp identifying when the input image was captured.

---

EstimationOptions

struct EstimationOptions

Per-call options for updatePose / updatePosition.

Variables

Name	Description
maxTime	Optional maximum processing time.
confidenceInterval	Confidence interval driving the covariance search range (0.0, 1.0).
exhaustiveRangeSearch	Enable exhaustive range search (default: false).
featureDensityCheck	Enable feature density check before performing a ranged search.

Variable Details

maxTime

std::optional<std::chrono::milliseconds> maxTime

Optional maximum 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 or use the exhaustiveRangeSearch option to do a more thorough search within the range.

confidenceInterval

double confidenceInterval

Confidence interval driving the covariance search range (0.0, 1.0).

Controls how much of the input PoseCovariance ellipsoid is searched around the input pose. Per dimension, the search range is ±sqrt(chiSquared(confidenceInterval, 6 dof) * variance), where the chi-squared value is computed from this confidence level over the 6 degrees of freedom of the pose.

Larger values widen the search (slower, more robust to a poorly known prior); smaller values narrow it (faster, but may miss the true pose if the prior is off). Has no effect when no covariance is supplied.

Common values:

• 0.68: 1-sigma
• 0.90: Default
• 0.95: 2-sigma
• 0.99: High confidence

note

This controls how much of the prior uncertainty region is searched, not how confident you are in the covariance values themselves.

warning

Must be in range (0.0, 1.0) - validated at runtime.

See: PoseCovariance

See: integration_guide.md "Search Range" for the full derivation.

exhaustiveRangeSearch

bool exhaustiveRangeSearch

Enable exhaustive range search (default: false)

When enabled, performs a more thorough search which can improve accuracy in some scenarios but at a significant time cost.

warning

Enabling this option will significantly increase processing time. It is highly recommended to use the maxTime field when this option is enabled.

featureDensityCheck

bool featureDensityCheck

Enable feature density check before performing a ranged search

If true, updatePose and updatePosition will check if the image has sufficient visual features before attempting a ranged search. Images whose feature density is too low will return PoseEstimationError::PoorFeatureDensity.

---

PoseEstimator

class PoseEstimator

Main Raptor Guide 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: at most one call may be in flight per raptor::Context at a time, including calls on different instances. Serialize them.

note

See the documentation for complete working examples.

Variables

Name	Description
_impl	Internal implementation (PIMPL pattern).

Functions

Name	Description
PoseEstimator	Initialize Raptor Guide from an existing Raptor SDK context.
~PoseEstimator	Destructor - automatically cleans up all resources.
updatePose(Pose)	Refine camera pose using image and 3D map matching.
updatePose(Geodetic)	Convenience overload for Geodetic pose directly in return type.
updatePose(Ecef)	Convenience overload for ECEF pose directly in return type.
updatePosition(Pose)	Refine camera position using image and 3D map matching.
updatePosition(Geodetic)	Convenience overload for Geodetic pose directly in return type.
updatePosition(Ecef)	Convenience overload for ECEF pose directly in return type.
startDebug	Start capturing debug data to a CanV archive.
stopDebug	Stop the active debug capture and finalize the CanV archive.

Variable Details

_impl

std::unique_ptr<PoseEstimatorImpl> _impl

Internal implementation (PIMPL pattern)

Function Details

PoseEstimator

Function

explicit PoseEstimator(raptor::Context& context)

Initialize Raptor Guide from an existing Raptor SDK context

Parameters:

• context - Shared Raptor SDK context. Must outlive this PoseEstimator instance.

Throws: std::runtime_error - If initialization fails

~PoseEstimator

Function

~PoseEstimator()

Destructor - automatically cleans up all resources

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

updatePose

Function

std::variant<PoseOutput<Pose>, PoseEstimationError> updatePose( ImageView image, const LensModel& lens, const Pose& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

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:

• image - Image (see ImageView type for format details)
• lens - Lens model parameters (see LensModel type for details)
• pose - Initial pose estimate (see Pose type for format details).
• covariance - Optional prior pose covariance (see PoseCovariance). Covariance values should reflect input pose uncertainty for optimal results.
• timestamp - Timestamp identifying when the input image was captured. Must be > 0. The epoch is application-defined and must be consistent across calls. Preserved unchanged in the output timestamp field.
• options - Per-call tuning (see EstimationOptions for details).

Returns: std::variant containing either: - PoseOutput: refined pose, uncertainty, and quality metrics on success - PoseEstimationError: error code on failure

note

This method performs comprehensive parameter validation and exception handling internally. Invalid parameters or system errors are reported via PoseEstimationError. This method does not throw exceptions during normal operation.

note

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

Function

std::variant<PoseOutput<pose::Geodetic>, PoseEstimationError> updatePose( ImageView image, const LensModel& lens, const pose::Geodetic& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

Convenience overload for Geodetic pose directly in return type

Function

std::variant<PoseOutput<pose::Ecef>, PoseEstimationError> updatePose( ImageView image, const LensModel& lens, const pose::Ecef& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

Convenience overload for ECEF pose directly in return type

updatePosition

Function

std::variant<PositionOutput<Position>, PoseEstimationError> updatePosition( ImageView image, const LensModel& lens, const Pose& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

Refine camera position using image and 3D map matching

Same as updatePose but without updated attitude in the output.

Function

std::variant<PositionOutput<raptor::position::Geodetic>, PoseEstimationError> updatePosition( ImageView image, const LensModel& lens, const pose::Geodetic& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

Convenience overload for Geodetic pose directly in return type

Function

std::variant<PositionOutput<raptor::position::Ecef>, PoseEstimationError> updatePosition( ImageView image, const LensModel& lens, const pose::Ecef& pose, std::chrono::nanoseconds timestamp, const std::optional<PoseCovariance>& covariance = std::nullopt, const EstimationOptions& options = {}) noexcept

Convenience overload for ECEF pose directly in return type

startDebug

Function

DebugResult startDebug(const std::filesystem::path& path, bool overwrite = false) noexcept

Start capturing debug data to a CanV archive

When debug capture is active, every subsequent call to updatePose() or updatePosition() is recorded as a frame in a CanV archive.

Parameters:

• path - Output CanV archive path. Parent directory must exist.
• overwrite - If true, an existing file at path is replaced. If false, returns DebugResult::FileExists when the file already exists.

Returns: DebugResult::Ok on success; another DebugResult value describing why the start request failed otherwise.

See: stopDebug

See: DebugResult

stopDebug

Function

DebugResult stopDebug() noexcept

Stop the active debug capture and finalize the CanV archive

Closes the writer and flushes all pending frame metadata to disk. After this call, subsequent updatePose() calls no longer record frames until startDebug() is called again.

Returns: DebugResult::Ok on success; DebugResult::NotActive if no capture was active; DebugResult::Failed on a finalization error.

See: startDebug