Version: 1.0 (Latest)

Release Notes

May 29, 2026

Raptor SDK v1.0.0 Release (Latest)

Overview

This is a major API refactor and the first 1.0 release. The SDK has been renamed from Raptor Guide SDK to Raptor SDK, the public C++ namespace has been reorganised, and many APIs have been redesigned for type safety and better separation of concerns.

Highlights:

The Guide class has been renamed to PoseEstimator and moved into a new raptor::guide sub-namespace.
A new top-level raptor::Context holds the SDK-wide resources and is now required to construct a PoseEstimator.
Configuration has been split into SDK-wide settings (raptor::Config, consumed by Context) and per-call tuning knobs (raptor::guide::EstimationOptions).
Pose, position, image, and lens parameters are now expressed as structured types instead of raw arrays/pointers; CRS configuration lives on the pose / position types rather than globally on Config.
The pose covariance are now expressed in the camera frame (DIN 9300: x forward, y right, z down), independent of the pose CRS. Previously the frame followed the pose CRS (local NED for geodetic poses, ECEF for ECEF poses).
New top-level free functions for map intersection queries (raptor::queryMapIntersection), image rendering (raptor::renderMap), and feature density analysis (raptor::computeFeatureDensity).
The Raptor Server protocol and JSON config have been updated to match the new SDK data model and are wire-incompatible with the v0.6.0 server. See the service integration guide for details.

Migration difficulty: High. Most call sites that touch the SDK will need changes. A detailed migration checklist is included at the end of this document.

Breaking Changes — SDK

SDK Rename: Raptor Guide SDK → Raptor SDK

SDK-wide symbols have moved out of the guide-specific subtrees and now live at the top level of the raptor include root, namespace, and Python module. The guide-specific symbols remain grouped under raptor::guide / raptor/guide/ / raptor.guide:

	v0.6.0	v1.0.0
Public headers	all under `raptor/guide/` (e.g. `raptor/guide/Guide.hpp`, `raptor/guide/Config.hpp`)	SDK-wide headers under `raptor/` (e.g. `raptor/Context.hpp`, `raptor/Config.hpp`, `raptor/lens.hpp`); guide-specific headers under `raptor/guide/` (e.g. `raptor/guide/PoseEstimator.hpp`)
C++ namespaces	SDK-wide types under `raptor::` and `raptor::guide::` (e.g. `raptor::Guide`, `raptor::guide::Config`); `LicenseStatus` under `raptor::license`	SDK-wide types under `raptor::` (e.g. `raptor::Context`, `raptor::Config`, `raptor::LicenseStatus`); guide-specific types under `raptor::guide::` (e.g. `raptor::guide::PoseEstimator`); new sub-namespaces such as `raptor::lens`
CMake link target	`raptor::guide`	`raptor::raptor`
Python module	SDK entry point at `raptor.guide` (e.g. `from raptor.guide import Guide, Config`)	SDK-wide types at `raptor` (e.g. `from raptor import Config, Context`); guide-specific types at `raptor.guide` (e.g. `from raptor.guide import PoseEstimator`)

find_package(raptor ...) is unchanged. The per-symbol sections below list the exact header, namespace, and Python import path for each renamed or moved API.

`Guide` Class Renamed and Moved Namespace

The Guide class has been renamed to PoseEstimator and moved from namespace raptor to namespace raptor::guide. Its header has been renamed from raptor/guide/Guide.hpp to raptor/guide/PoseEstimator.hpp.

Old API (v0.6.0):

#include <raptor/guide/Guide.hpp>

raptor::Guide guide(config);

New API:

#include <raptor/guide/PoseEstimator.hpp>

raptor::guide::PoseEstimator estimator(context);

Migration:

Replace #include <raptor/guide/Guide.hpp> with #include <raptor/guide/PoseEstimator.hpp>
Replace raptor::Guide with raptor::guide::PoseEstimator

New Structured Types

The SDK introduces structured types to replace simple type aliases, providing better type safety and clearer API semantics.

Image Types

Old API:

using ImageData = const std::uint8_t*;

auto result = guide.updatePose(imageData, hFov, vFov, position, attitude);

New API:

raptor::ImageView image{raptor::ImageType::Gray8, width, height, data};
// Or owning container
raptor::Image image{raptor::ImageType::Gray8, width, height, data};

auto result = estimator.updatePose(image, lens, pose);

Migration:

Replace raw ImageData pointer with raptor::ImageView or raptor::Image
Image type and dimensions are part of the image object
Image format can be specified (Gray8, Rgb8, Rgba8), reducing the need for conversions before passing images to the SDK

Lens Model Types

Old API:

auto result = guide.updatePose(imageData, hFov, vFov, position, attitude);

New API (preferred — explicit pinhole parameters from camera calibration):

auto lens = raptor::LensModel{
    raptor::lens::Pinhole{.fx = focalX, .fy = focalY,
                          .cx = centerX, .cy = centerY}
};

auto result = estimator.updatePose(image, lens, pose);

New API (FOV-based construction, when calibrated focal length and principal point are not available):

auto lens = raptor::LensModel{
    raptor::lens::Pinhole::fromFov(hFov, vFov, width, height)
};

Migration:

Create a raptor::LensModel from raptor::lens::Pinhole parameters. Prefer constructing it directly from your camera's calibrated fx, fy, cx, cy values; use lens::Pinhole::fromFov(...) only when only the field of view is known (it assumes the principal point is at the image center).
Pass the lens model instead of separate hFov and vFov parameters.

Coordinate System Configuration Moved to Pose/Position Types

CRS configuration has been moved from the global config into the individual Pose and Position types. This provides better locality and type safety.

Old API (v0.6.0):

using Position = std::array<double, 3>;
using Attitude = std::array<double, 4>;

raptor::guide::Config config{
    .imageWidth = 1920,
    .imageHeight = 1080,
    .licensePath = "license.license",
    .mapPaths = {"map.r3db"},
    .coordinateSystem = {
        .referenceFrame = raptor::ReferenceFrame::Geodetic,
        .geodeticOptions = {
            .verticalDatum = raptor::VerticalDatum::EGM2008,
            .horizontalUnit = raptor::HorizontalUnit::Degrees,
            .verticalUnit = raptor::VerticalUnit::Meter
        }
    }
};

raptor::Position position = {39.5, -77.5, 1542};
raptor::Attitude attitude = {qx, qy, qz, qw};

auto result = guide.updatePose(imageData, hFov, vFov, position, attitude);

New API:

raptor::pose::Geodetic pose{
    .coords = {.lat = 39.5, .lon = -77.5, .alt = 1542},
    .attitude = {.x = qx, .y = qy, .z = qz, .w = qw},
    .crs = {
        .horizontalUnit = raptor::crs::HorizontalUnit::Degrees,
        .heightSystem = raptor::crs::HeightSystem::Egm2008
    }
};

// Or ECEF
raptor::pose::Ecef poseEcef{
    .coords = {.x = 1067420.0, .y = -4799270.0, .z = 4030580.0},
    .attitude = {.x = qx, .y = qy, .z = qz, .w = qw}
};

auto result = estimator.updatePose(image, lens, pose);

Migration:

Replace separate Position and Attitude arrays with unified Pose types
Use raptor::pose::Geodetic / raptor::pose::Ecef (and the equivalent raptor::position::* types for position-only inputs)
Move CRS configuration from Config.coordinateSystem to .crs on the pose
Remove Config.coordinateSystem and Config.geodeticOptions fields

Pose Covariance Frame Changed to Camera Frame (DIN 9300)

The prior and result pose covariance are now expressed in the camera frame following DIN 9300 (x forward, y right, z down), independent of the pose CRS. Yaw is rotation about z, pitch about y, roll about x. Previously the covariance frame followed the pose CRS — local NED (north, east, down, yaw, pitch, roll) for geodetic poses and ECEF (x, y, z, yaw about z, pitch about y, roll about x) for ECEF poses.

Other related changes that affect existing call sites:

The covariance is still optional and still passed positionally to updatePose() / updatePosition(), but its position has shifted: it was the 6th argument in v0.6.0 (after attitude); it is the 5th argument in v1.0.0 (after timestamp, before EstimationOptions).
The output covariance field has been renamed from poseCovariance to covariance on PoseOutput, and from positionCovariance to covariance on PositionOutput. It is now std::optional<PoseCovariance> / std::optional<PositionCovariance> and is left empty when the estimator was unable to produce an uncertainty estimate.
The covariance type aliases have moved from namespace raptor to namespace raptor::guide:

namespace raptor::guide {
    using PoseCovariance     = std::array<double, 36>; // 6x6 row-major, (x,y,z,yaw,pitch,roll)
    using PositionCovariance = std::array<double,  9>; // 3x3 row-major, (x,y,z)
}

Units are unchanged (meters² for position, radians² for attitude). The position search range continues to be driven by the magnitude of the prior covariance scaled by EstimationOptions::confidenceInterval (chi-squared over 6 degrees of freedom); the search is now performed in the eigen-basis of the supplied covariance (see General Improvements below).

Old API (v0.6.0):

// 6x6 prior in the local NED frame, ordered (north, east, down, yaw, pitch, roll)
// for the configured Geodetic reference frame.
std::optional<raptor::PoseCovariance> covariance = nedCovariance;

raptor::PoseOutput result = guide.updatePose(imageData, hFov, vFov,
                                             position, attitude,
                                             covariance, maxTime, timestamp);
// Result covariance returned in the same NED frame as the pose:
use(result.poseCovariance);

New API:

// Prior covariance in the DIN 9300 camera frame, regardless of pose CRS,
// ordered (x, y, z, yaw, pitch, roll).
const raptor::guide::PoseCovariance covariance{/* 6x6 row-major */};

auto result = estimator.updatePose(image, lens, pose, timestamp, covariance, options);

if (auto* output = std::get_if<raptor::guide::PoseOutput<raptor::pose::Geodetic>>(&result)) {
    if (output->covariance) {
        // Output covariance, also in the DIN 9300 camera frame.
        use(*output->covariance);
    }
}

Migration:

Rotate prior covariances from the previous frame (NED for geodetic poses, ECEF for ECEF poses) into the camera frame (DIN 9300: x forward, y right, z down) before passing them in. Apply the rotation cov_body = R_body_from_world · cov_world · R_body_from_world^T independently to the 3x3 position and 3x3 attitude blocks; build R_body_from_world from the pose's body-to-world orientation (and the local NED-to-ECEF rotation as well when the prior was in NED).
Move the covariance argument from position 6 (after attitude) to position 5 (after timestamp, before EstimationOptions).
Replace reads of result.poseCovariance / result.positionCovariance with result.covariance (now std::optional); guard against the empty state and treat the returned values as camera-frame quantities.
Update fully-qualified covariance type names from raptor::PoseCovariance / raptor::PositionCovariance to raptor::guide::PoseCovariance / raptor::guide::PositionCovariance.

Configuration Split: `raptor::Config` and `raptor::guide::EstimationOptions`

The monolithic raptor::guide::Config has been removed. Its fields are split:

SDK-wide settings (imageWidth, imageHeight, licensePath, mapPaths, detailStage1, detailStage2, coordinateEpoch, geoResourcePath, logger) live on raptor::Config and are consumed by raptor::Context.
Per-call tuning knobs (confidenceInterval, exhaustiveRangeSearch, featureDensityCheck, maxTime) live on raptor::guide::EstimationOptions and are passed to each updatePose() / updatePosition() call.

raptor::guide::PoseEstimator is constructed from a raptor::Context&. A new raptor::parseConfigFromJson() function (along with raptor::ConfigParseError and raptor::ConfigParseFailure) parses the SDK-wide fields from JSON. raptor::guide::parseConfigFromJson() has been removed.

Old API (v0.6.0):

raptor::guide::Config config{
    .imageWidth = 1920,
    .imageHeight = 1080,
    .licensePath = "/path/to/license.license",
    .mapPaths = {"/path/to/map.r3db"},
    .detailStage1 = 8,
    .detailStage2 = 9,
    .confidenceInterval = 0.9,
    .coordinateEpoch = 2025.0f,
    .exhaustiveRangeSearch = false,
};
raptor::Guide guide{config};
auto result = guide.updatePose(imageData, hFov, vFov, position, attitude);

New API:

raptor::Config config{
    .imageWidth = 1920,
    .imageHeight = 1080,
    .licensePath = "/path/to/license.license",
    .mapPaths = {"/path/to/map.r3db"},
    .detailStage1 = 8,
    .detailStage2 = 9,
    .coordinateEpoch = 2025.0f,
};
raptor::Context context{config};
raptor::guide::PoseEstimator estimator{context};

raptor::guide::EstimationOptions options{
    .confidenceInterval = 0.9,
    .exhaustiveRangeSearch = false,
};
auto result = estimator.updatePose(image, lens, pose, timestamp, options);

Migration:

Split existing raptor::guide::Config initialisers into a raptor::Config (SDK-wide fields, including coordinateEpoch) and a raptor::guide::EstimationOptions (per-call tuning knobs).
Pass the raptor::Config to the raptor::Context constructor and the context to the raptor::guide::PoseEstimator constructor.
Pass the raptor::guide::EstimationOptions to each updatePose() / updatePosition() call site.
When loading from JSON, call raptor::parseConfigFromJson() and handle the new raptor::ConfigParseError / raptor::ConfigParseFailure types.

SDK Initialization Moved to Context

SDK initialization — loading maps, setting up GPU resources, and verifying the license — now happens when raptor::Context is constructed. raptor::guide::PoseEstimator construction is lightweight and binds to an existing context.

Practical consequences:

The one-time cost of map loading and GPU initialization is paid at raptor::Context construction time, not on the first PoseEstimator.
SDK-wide fields on raptor::Config (mapPaths, imageWidth, imageHeight, detailStage1, detailStage2) cannot change for the lifetime of a Context. To switch maps or image dimensions at runtime, destroy and reconstruct the Context.
Constructing a PoseEstimator from a Context whose raptor::Config has empty mapPaths or zero imageWidth/imageHeight throws std::runtime_error.

Geo Resources Initialization Changed

The geoResourcePath field has been removed from raptor::guide::Config. Geo resources are initialised by raptor::Context from raptor::Config. The path is now optional; when empty, the SDK will check the RAPTOR_GEO_RESOURCE_PATH and RAPTOR_DATA_DIR environment variables (the latter has /resources/geo appended), and otherwise search the following paths in order:

data/resources/geo
/usr/local/share/raptor/data/resources/geo
/usr/share/raptor/data/resources/geo
/opt/raptor/share/raptor/data/resources/geo

Migration:

Move geoResourcePath from raptor::guide::Config to raptor::Config (or leave empty for auto-discovery).
Set RAPTOR_GEO_RESOURCE_PATH or RAPTOR_DATA_DIR to override the search.
Construct a raptor::Context before any PoseEstimator.

Map Query API Renamed and Moved to a Free Function

Renamed GroundPositionError to MapQueryError.
Renamed Guide::getGroundPosition(Position) to the free function raptor::queryMapIntersection(Context&, Position) declared in <raptor/query.hpp>. It returns std::variant<Position, MapQueryError>.

See Map Intersection Query under New Features for the additional Ray-based and per-pixel overloads, and for the typed-return overloads that take/return position::Geodetic / position::Ecef directly.

Migration:

Replace GroundPositionError with MapQueryError.
Replace guide.getGroundPosition(position) with raptor::queryMapIntersection(context, position).
Add #include <raptor/query.hpp>.

Version Accessor Renamed and Moved to Context

Renamed Guide::getVersion() to version().
Moved version() from raptor::Guide to raptor::Context.
The returned type is now raptor::Version (declared in <raptor/version.hpp>); previously it was raptor::utils::Version.
raptor::Version::major, minor, and patch are now std::uint32_t (previously int).

License API Moved to Context

Moved generateFingerprint() from raptor::Guide to raptor::Context::generateFingerprint().
LicenseStatus is now raptor::LicenseStatus (was raptor::license::LicenseStatus).
LicenseStatus::InvalidPath has been renamed to LicenseStatus::FileNotFound to better describe the condition (license file at the configured path cannot be opened).
Context::validateLicense(path) is a new public entry point for validating a license file from application code; previously the equivalent check was performed implicitly during Guide construction and was not callable on its own.

Image Timestamp Now Required on Update Calls

updatePose() and updatePosition() now take a mandatory std::chrono::nanoseconds argument identifying when the input image was captured. The parameter has moved ahead of the optional maxTime, and the output timestamp field on PoseOutput/PositionOutput is no longer wrapped in std::optional — it is always populated with the input value.

The timestamp must reflect the image acquisition time. The epoch is application-defined and must be consistent across calls within your application.

Old API (v0.6.0):

auto result = guide.updatePose(imageData, hFov, vFov, position, attitude);
// or with optional arguments:
auto result = guide.updatePose(imageData, hFov, vFov, position, attitude,
                               poseCovariance, maxTime, timestamp);

if (result.timestamp.has_value()) { use(*result.timestamp); }

New API:

const auto timestamp = std::chrono::duration_cast<std::chrono::nanoseconds>(
    std::chrono::system_clock::now().time_since_epoch());

auto result = estimator.updatePose(image, lens, pose, timestamp);
// or with a covariance:
auto result = estimator.updatePose(image, lens, pose, timestamp, covariance);
// or with per-call options (e.g. maxTime):
auto result = estimator.updatePose(image, lens, pose, timestamp, std::nullopt, options);

use(result.timestamp); // always set

Migration:

Pass a std::chrono::nanoseconds timestamp to every updatePose() / updatePosition() call.
Swap the positions of timestamp and maxTime in existing call sites (maxTime now lives on EstimationOptions).
Replace result.timestamp.value() / *result.timestamp with result.timestamp; remove has_value() checks.

Breaking Changes — Raptor Server

The Raptor Server protocol, JSON config, and Python client have been updated to match the new SDK data model. The changes are wire-incompatible with the v0.6.0 server: messages have been renamed and restructured (pose, position, CRS, lens, and image types are now variant messages mirroring the new C++ types), request/response layouts have changed, and the JSON config schema has been flattened.

Migration: regenerate client stubs from the new raptor.proto, update any custom server config.json files to the new flat schema, and read the service integration guide for the full list of messages and config keys.

New Features

Map Intersection Query

New top-level free function raptor::queryMapIntersection() in <raptor/query.hpp>:

// Intersection point at a horizontal location (looking straight down)
std::variant<Position, MapQueryError> queryMapIntersection(
    Context& context, const Position& position) noexcept;

// Intersection point from an origin looking in a direction
std::variant<Position, MapQueryError> queryMapIntersection(
    Context& context, const Ray& ray) noexcept;

// Per-pixel intersection: for each pixel coordinate, cast a ray from the
// camera through the pixel using the lens model and pose, and return the
// map-surface hit
std::vector<std::variant<Position, MapQueryError>> queryMapIntersection(
    Context& context, const LensModel& lens, const Pose& pose,
    std::span<PixelCoordinates> pixelCoordinates) noexcept;

Overloads taking position::Geodetic / position::Ecef / ray::Geodetic / ray::Ecef (and pose::Geodetic / pose::Ecef for the per-pixel form) return the corresponding concrete type directly. PixelCoordinates is a new {double x, double y} struct in <raptor/query.hpp> using fractional pixel coordinates with [0,0] at the upper-left corner of the upper-left pixel.

Map Image Rendering

New top-level free functions in <raptor/render.hpp>:

raptor::renderMap() renders the loaded 3D map from a given camera viewpoint, returning std::variant<Image, OperationError>. Useful for manually validating the input to pose estimation. (Moved from Guide::renderReferenceImage())
raptor::renderMapCoverage() renders an 8-bit grayscale coverage mask for the same viewpoint where 0x00 marks pixels with no 3D map data and 0xFF marks pixels with coverage. Useful for diagnosing low mapCoverage values returned by updatePose() / updatePosition().

Automatic Geo Resource Discovery

Geo resources are now discovered automatically from standard installation paths (and from RAPTOR_GEO_RESOURCE_PATH / RAPTOR_DATA_DIR), eliminating the need for explicit configuration in most cases.

Feature Density Pre-Check

New top-level free function raptor::computeFeatureDensity() in <raptor/analyze.hpp> returns the ratio of detected features to total pixels for an input image as std::variant<float, OperationError> (value in [0, 1]). Low values indicate visually ambiguous inputs (e.g. uniform surfaces) that are unlikely to produce a reliable pose. Useful for filtering frames prior to calling updatePose() / updatePosition().

raptor::ImageView image{raptor::ImageType::Gray8, width, height, imageData};
auto density = raptor::computeFeatureDensity(context, image);
if (auto* value = std::get_if<float>(&density); value && *value < 0.02f) {
    // Skip frame; insufficient visual features
    continue;
}

The same check is also available as an integrated pre-check inside updatePose() / updatePosition() via the new EstimationOptions::featureDensityCheck flag (default false). When enabled, low-density inputs are rejected early and PoseEstimationError::PoorFeatureDensity is returned.

Map Coverage in Result Output

PoseOutput and PositionOutput now expose a mapCoverage field (range [0, 1]) that reports the fraction of the rendered map image covered by valid 3D map data. Low values indicate that a large portion of the camera's view falls outside the loaded map, which typically correlates with lower Confidence and is useful for diagnosing poor quality results.

Debug Capture API

New PoseEstimator::startDebug() / PoseEstimator::stopDebug() methods record every subsequent updatePose() / updatePosition() call into a self-describing CanV archive containing the input image, input pose, rendered map image, refined output pose and per-frame extras. Intended for offline analysis and reproducing issues.

#include <raptor/guide/PoseEstimator.hpp>

raptor::guide::PoseEstimator estimator{context};

if (estimator.startDebug("/tmp/session.canv", /*overwrite=*/true) !=
    raptor::guide::DebugResult::Ok) {
    // Handle DebugResult::{AlreadyActive, FileExists, InvalidPath,
    //                      InvalidLicense, Failed}
}

estimator.updatePose(image, lens, pose, timestamp);

estimator.stopDebug();

Results are described by the new raptor::guide::DebugResult enum: Ok, AlreadyActive, NotActive, FileExists, InvalidPath, InvalidLicense, Failed.

Logging Framework

A new SDK-wide logger is wired through raptor::Context and used throughout the SDK. The logger is configured via raptor::Config::logger (name, level, and an optional custom callback). When no callback is supplied, formatted messages at the configured level and above are written to stdout; applications can route messages elsewhere by setting logger.callback to receive raptor::LogMessage values. See the integration guide for details.

GPU Selection via Environment Variable

Added RAPTOR_VULKAN_VISIBLE_DEVICES environment variable for GPU selection.

CANV Integration Tool

A new Python tool, python/tools/refine_canv_poses.py, is shipped with the SDK. It reads a CANV v6 recording, runs every frame through raptor.guide.PoseEstimator, prints per-frame results, and (optionally) writes a new CANV containing the refined poses, covariances, and confidence values. The tool is intended as an adaptable starting point for integration testing — Config and EstimationOptions are exposed via CLI flags and a JSON config file, and the CANV ↔ SDK adapters are isolated so they can be modified without touching the SDK plumbing. Requires the pycanv package (GitHub link will be available in the online documentation.) See python/tools/README.md for the full usage reference.

General Improvements

Confidence score has been tweaked to be more accurate when there is low map coverage.
Output pose covariance has been tweaked to improve numerical stability and reliability of the reported uncertainty.
Range search now operates in the eigen-basis of the input pose covariance instead of along fixed body axes. The search volume is sized from the eigenvalues of the prior, scaled by the configured confidenceInterval (chi-squared over 6 degrees of freedom).

Migration Checklist

Class Rename and Namespace Change

Replace #include <raptor/guide/Guide.hpp> with #include <raptor/guide/PoseEstimator.hpp>
Replace raptor::Guide with raptor::guide::PoseEstimator

Update Function Signatures

Replace updatePose(ImageData, hFov, vFov, Position, Attitude, ...) with updatePose(ImageView, LensModel, Pose, Timestamp, Covariance, EstimationOptions)
Replace updatePosition(ImageData, hFov, vFov, Position, Attitude, ...) with updatePosition(ImageView, LensModel, Position, Timestamp, Covariance, EstimationOptions)

Image Types

Replace raw ImageData pointer (const uint8_t*) with raptor::ImageView or raptor::Image

Lens Model

Create a raptor::LensModel object from raptor::lens::Pinhole, preferring the explicit {.fx, .fy, .cx, .cy} form when calibrated intrinsics are available; fall back to lens::Pinhole::fromFov(...) only when just the FOV is known
Replace separate hFov, vFov parameters with the single lens object

Pose and Position Types

Replace std::array<double, 3> position (raptor::Position) with raptor::position::Geodetic or raptor::position::Ecef
Combine separate raptor::Position and raptor::Attitude into a unified pose type (raptor::pose::Geodetic or raptor::pose::Ecef)

CRS Configuration

Remove Config.coordinateSystem and Config.geodeticOptions
Add .crs field to the Pose and Position initialisers

Covariance

Rotate prior covariances from the previous frame (NED for geodetic poses, ECEF for ECEF poses) into the camera frame (DIN 9300: x forward, y right, z down) over (x, y, z, yaw, pitch, roll)
Move the optional covariance argument from position 6 (after attitude) to position 5 (after timestamp, before EstimationOptions)
Update the covariance type from raptor::PoseCovariance / raptor::PositionCovariance to raptor::guide::PoseCovariance / raptor::guide::PositionCovariance
Replace reads of result.poseCovariance / result.positionCovariance with result.covariance (now std::optional, also in the DIN 9300 camera frame); guard against the empty state

Result Handling

Handle the std::variant<PoseOutput, PoseEstimationError> return from updatePose() (and std::variant<PositionOutput, PoseEstimationError> from updatePosition()); the previous raptor::Result enum (including Result::Ok, Result::UncertainOutput, Result::InsufficientMapCoverage, etc.) has been removed and the corresponding outcomes are now represented either by holding a PoseOutput/PositionOutput or one of the PoseEstimationError alternatives
Replace reads of result.position and result.attitude on PoseOutput with result.pose.coords and result.pose.attitude on the typed PoseOutput<pose::Geodetic> / PoseOutput<pose::Ecef> alternative
Remove has_value() checks on PoseOutput::timestamp / PositionOutput::timestamp

Configuration Split

Move imageWidth, imageHeight, licensePath, mapPaths, detailStage1, detailStage2, coordinateEpoch from raptor::guide::Config to raptor::Config
Move confidenceInterval, exhaustiveRangeSearch, featureDensityCheck, maxTime to raptor::guide::EstimationOptions and pass to each updatePose() / updatePosition() call
Pass the raptor::Config to raptor::Context and the context to raptor::guide::PoseEstimator
Replace JSON loading with raptor::parseConfigFromJson() and handle raptor::ConfigParseError / raptor::ConfigParseFailure

Geo Resources

Remove geoResourcePath from raptor::guide::Config; set it on raptor::Config if a custom path is needed
Optionally use RAPTOR_GEO_RESOURCE_PATH / RAPTOR_DATA_DIR env vars

Map Query API

Replace GroundPositionError with MapQueryError
Replace guide.getGroundPosition(position) with raptor::queryMapIntersection(context, position) (add #include <raptor/query.hpp>)

Renamed Methods

Replace Guide::getVersion() with Context::version(); update the returned type from raptor::utils::Version to raptor::Version and treat major/minor/patch as std::uint32_t
Replace Guide::generateFingerprint() with Context::generateFingerprint()
Replace raptor::license::LicenseStatus with raptor::LicenseStatus
Replace LicenseStatus::InvalidPath with LicenseStatus::FileNotFound

Timestamp

Pass a std::chrono::nanoseconds timestamp to every updatePose() / updatePosition() call
Swap the positions of timestamp and maxTime in existing call sites (maxTime is now on EstimationOptions)
Remove has_value() checks on PoseOutput::timestamp / PositionOutput::timestamp

Raptor Server

Re-generate client stubs from the v1.0.0 raptor.proto
Update any custom config.json files to the new flat schema
See the service integration guide for the full list of changes

Additional Notes

All usage examples have been updated to demonstrate the new API.
See the integration guide for detailed documentation.
Python bindings have been updated to match the new C++ API.
The raptor server protobuf interface and Python client mirror the new C++ data model for pose, position, image, lens, and CRS types.

May 29, 2026​

Raptor SDK v1.0.0 Release (Latest)​

Overview​

Breaking Changes — SDK​

SDK Rename: Raptor Guide SDK → Raptor SDK​

Guide Class Renamed and Moved Namespace​

New Structured Types​

Image Types​

Lens Model Types​

Coordinate System Configuration Moved to Pose/Position Types​

Pose Covariance Frame Changed to Camera Frame (DIN 9300)​

Configuration Split: raptor::Config and raptor::guide::EstimationOptions​

SDK Initialization Moved to Context​

Geo Resources Initialization Changed​

Map Query API Renamed and Moved to a Free Function​

Version Accessor Renamed and Moved to Context​

License API Moved to Context​

Image Timestamp Now Required on Update Calls​

Breaking Changes — Raptor Server​

New Features​

Map Intersection Query​

Map Image Rendering​

Automatic Geo Resource Discovery​

Feature Density Pre-Check​

Map Coverage in Result Output​

Debug Capture API​

Logging Framework​

GPU Selection via Environment Variable​

CANV Integration Tool​

General Improvements​

Migration Checklist​

Class Rename and Namespace Change​

Update Function Signatures​

Image Types​

Lens Model​

Pose and Position Types​

CRS Configuration​

Covariance​

Result Handling​

Configuration Split​

Geo Resources​

Map Query API​

Renamed Methods​

Timestamp​

Raptor Server​

Additional Notes​

May 29, 2026

Raptor SDK v1.0.0 Release (Latest)

Overview

Breaking Changes — SDK

SDK Rename: Raptor Guide SDK → Raptor SDK

`Guide` Class Renamed and Moved Namespace

New Structured Types

Image Types

Lens Model Types

Coordinate System Configuration Moved to Pose/Position Types

Pose Covariance Frame Changed to Camera Frame (DIN 9300)

Configuration Split: `raptor::Config` and `raptor::guide::EstimationOptions`

SDK Initialization Moved to Context

Geo Resources Initialization Changed

Map Query API Renamed and Moved to a Free Function

Version Accessor Renamed and Moved to Context

License API Moved to Context

Image Timestamp Now Required on Update Calls

Breaking Changes — Raptor Server

New Features

Map Intersection Query

Map Image Rendering

Automatic Geo Resource Discovery

Feature Density Pre-Check

Map Coverage in Result Output

Debug Capture API

Logging Framework

GPU Selection via Environment Variable

CANV Integration Tool

General Improvements

Migration Checklist

Class Rename and Namespace Change

Update Function Signatures

Image Types

Lens Model

Pose and Position Types

CRS Configuration

Covariance

Result Handling

Configuration Split

Geo Resources

Map Query API

Renamed Methods

Timestamp

Raptor Server

Additional Notes