Skip to main content
Version: 1.1 (Latest)

Guide Configuration API

Source: raptor/Config.hpp

Types​

NameDescription
LogLevelLog severity levels.
LogMessageA formatted log message delivered to a custom log callback.
LogCallbackSignature of a custom log callback.
LoggerLogger configuration.
MemoryBudgetMemory headroom reserved outside the SDK's map-data caches.
ConfigConfiguration parameters for the Raptor SDK.
ConfigParseErrorError codes for configuration parsing.
ConfigParseFailureDetailed configuration parsing failure.

Functions​

NameDescription
parseConfigFromJsonParse a Config object from a JSON file.

SDK-wide configuration types​

LogLevel​

enum class LogLevel : std::uint8_t

Log severity levels.

Levels are ordered from least to most severe. Setting a minimum log level will enable that level and all higher levels.

The uppercase names (TRACE, DEBUG, INFO, WARNING, ERROR, CRITICAL, OFF) are deprecated aliases of the names above. They are not available on Windows or when RAPTOR_LOGGING_LEVEL_LEAN is defined, and may be removed in a future release.

Trace = 0 : Detailed trace information.

Debug = 1 : Debug information.

Info = 2 : Informational messages (default level).

Warning = 3 : Warning messages.

Error = 4 : Error messages.

Critical = 5 : Critical error messages.

Off = 6 : Disable all logging.

TRACE = Trace : Deprecated, use Trace instead. Detailed trace information.

DEBUG = Debug : Deprecated, use Debug instead. Debug information.

INFO = Info : Deprecated, use Info instead. Informational messages (default level).

WARNING = Warning : Deprecated, use Warning instead. Warning messages.

ERROR = Error : Deprecated, use Error instead. Error messages.

CRITICAL = Critical : Deprecated, use Critical instead. Critical error messages.

OFF = Off : Deprecated, use Off instead. Disable all logging.

LogMessage​

struct LogMessage

A formatted log message delivered to a custom log callback.

Variables​

NameDescription
levelSeverity level of the message.
timestampTimestamp in nanoseconds since epoch.
imageTimestampTimestamp of the image associated with the message, if any.
messageFormatted message string.
nameLogger name.

Variable Details​

level​

LogLevel level

Severity level of the message

timestamp​

std::chrono::nanoseconds timestamp

Timestamp in nanoseconds since epoch

imageTimestamp​

std::optional<std::chrono::nanoseconds> imageTimestamp

Timestamp of the image associated with the message, if any

message​

std::string message

Formatted message string

name​

std::string name

Logger name

LogCallback​

using LogCallback = std::function<void(const LogMessage&)>;

Signature of a custom log callback.

The callback may be invoked from any thread and must be thread-safe. Any state captured by the callback must also be safe to access concurrently for the lifetime of the Context that owns it.

Logger​

struct Logger

Logger configuration.

Variables​

NameDescription
nameName used for the logger.
levelLog level.
callbackOptional custom log callback.

Variable Details​

name​

std::string name

Name used for the logger.

Surfaced as the name field on every LogMessage delivered to a custom log callback.

level​

LogLevel level

Log level.

Messages below this level are not logged.

callback​

LogCallback callback

Optional custom log callback.

The callback may be invoked from any thread and must be thread-safe. If left null, formatted messages are written to stdout.

MemoryBudget​

struct MemoryBudget

Memory headroom reserved outside the SDK's map-data caches.

These values are reserve targets, not maximum cache sizes. The SDK derives cache capacity from the reported memory budget, these reserves, and memory used by other consumers. They do not bound the SDK's total memory use.

Variables​

NameDescription
gpuReserveBytesTarget GPU (device-local) memory kept available outside the map cache, in bytes.
hostReserveBytesTarget host memory kept available outside the map cache, in bytes.

Variable Details​

gpuReserveBytes​

std::size_t gpuReserveBytes

Target GPU (device-local) memory kept available outside the map cache, in bytes.

The SDK monitors total device-local memory usage and evicts cached map tiles when the reported free budget falls below this target. This is therefore not a maximum map-cache size; the cache capacity varies with other GPU memory use.

The effective reserve is capped at half the reported device-local budget, so an oversized value cannot prohibit all device-local usage. It is checked once per frame, so transient usage may enter the reserve.

Default: 256 MiB (268435456 bytes).

hostReserveBytes​

std::size_t hostReserveBytes

Target host memory kept available outside the map cache, in bytes.

The SDK dynamically sizes the host-side map cache to leave this amount available under the machine's memory limit, or the process's cgroup limit where one applies. Memory used by the process outside the map cache is accounted for separately. This is therefore not a maximum map-cache size.

The budget is revised once per frame, so decoding and other transient allocations may enter the reserve. If the platform reports no host memory availability, this setting has no effect.

Default: 1 GiB (1073741824 bytes).

Config​

struct Config

Configuration parameters for the Raptor SDK Context.

Passed to the Context constructor to control SDK-wide initialization. All fields have sensible defaults; populate only what you need to override.

Variables​

NameDescription
geoResourcePathPath to geo resources.
loggerLogger configuration.
imageWidthWidth of input images in pixels (REQUIRED).
imageHeightHeight of input images in pixels (REQUIRED).
licensePathPath to license file (REQUIRED).
mapPathsPaths to 3D map files (REQUIRED).
detailStage1Level of detail of matching.
detailStage2Level of detail of matching.
coordinateEpochCoordinate epoch for tectonic plate correction (optional, RECOMMENDED: omit).
memoryBudgetMemory budget configuration.

Variable Details​

geoResourcePath​

std::string geoResourcePath

Path to geo resources.

Resolved in the following order of precedence:

  1. Explicit value - If geoResourcePath is non-empty, it is used directly
  2. RAPTOR_GEO_RESOURCE_PATH - Environment variable pointing to geo resources directory
  3. RAPTOR_DATA_DIR - Environment variable pointing to data directory. Geo resources are expected at $RAPTOR_DATA_DIR/resources/geo
  4. System default paths - Searched in order until an existing path is found:

Linux/Unix Default Paths:

  • data/resources/geo (relative to runtime location)
  • /usr/local/share/raptor/data/resources/geo
  • /usr/share/raptor/data/resources/geo
  • /opt/raptor/share/raptor/data/resources/geo

logger​

Logger logger

Logger configuration.

imageWidth​

int imageWidth

Width of input images in pixels (REQUIRED)

Must be consistent for all images processed by a PoseEstimator created from this Context. Must match the actual width of images passed to PoseEstimator methods (e.g. updatePose, updatePosition).

imageHeight​

int imageHeight

Height of input images in pixels (REQUIRED)

Must be consistent for all images processed by a PoseEstimator created from this Context. Must match the actual height of images passed to PoseEstimator methods (e.g. updatePose, updatePosition).

licensePath​

std::string licensePath

Path to license file (REQUIRED)

Must point to a readable Raptor license file.

mapPaths​

std::vector<std::string> mapPaths

Paths to 3D map files (REQUIRED)

Vector of paths to 3D map files (.r3db, .3tz, or .3dtiles.zip format). At least one map is required. Maps should cover your area of interest. The drawing order of the maps follow the list order, so if the same area is covered by multiple maps, the first in the list will be drawn.

detailStage1​

unsigned int detailStage1

Level of detail of matching.

Higher values = more accurate but slower processing. Recommended values: 7-8

warning

Values >= 32 will cause overflow - validated at runtime

detailStage2​

unsigned int detailStage2

Level of detail of matching.

Should be >= detailStage1 for best results. Recommended values: 8-9

warning

Values >= 32 will cause overflow - validated at runtime

coordinateEpoch​

std::optional<float> coordinateEpoch

Coordinate epoch for tectonic plate correction (optional, RECOMMENDED: omit)

Enables correction for tectonic plate movement between epoch of reference map and epoch of mission, improving accuracy for high-precision applications. Uses GSRM2.1 model for tectonic plate movement.

Year as decimal number (e.g., 2025.0 for January 1st, 2025).

tip

If provided, the epoch should match the mission epoch (i.e., today's date for real-time, recording date for post-processing)

note

Tectonic plate shift is typically only a few centimeters per year in most locations, so this can be omitted for many applications unless high precision is required.

caution

Models average, long-term plate movement only (GSRM2.1). Does NOT model deformation in zones along tectonic plate borders, compensate for sudden shifts (earthquakes, landslides), or account for local subsidence/uplift from other geological processes.

If not provided, no tectonic correction is applied.

memoryBudget​

MemoryBudget memoryBudget

Memory budget configuration.

ConfigParseError​

enum class ConfigParseError : std::uint8_t

Error codes for configuration parsing

Describes different errors that may occur when parsing a configuration file.

FileNotFound : Failed to open the configuration file

InvalidJson : JSON parsing failed (malformed JSON)

NotAnObject : Root element is not a JSON object

MissingRequiredField : Required field is missing

InvalidType : Field has invalid type (e.g., expected string but got number)

InvalidValue : Field has invalid value (e.g., enum value not recognized)

ConfigParseFailure​

struct ConfigParseFailure

Detailed configuration parsing failure.

Returned in place of a Config when parseConfigFromJson() fails. Carries the error category along with location information so callers can render actionable diagnostics.

Variables​

NameDescription
errorCategory of the failure.
fieldPath of the offending field in the JSON document.
detailHuman-readable contextual detail.
offset0-based byte offset within the JSON content where the error was detected.
line1-based line number derived from the byte offset.

Variable Details​

error​

ConfigParseError error

Category of the failure.

field​

std::string field

Path of the offending field in the JSON document.

Examples: "licensePath", "mapPaths", "mapPaths[2]". Empty for file-level (FileNotFound) and document-level (InvalidJson, NotAnObject) errors that cannot be attributed to a specific field.

detail​

std::string detail

Human-readable contextual detail.

For InvalidType: the expected type (e.g. "string", "unsigned integer"). For InvalidJson: the parser error description. Empty if no further context is available.

offset​

std::optional<std::size_t> offset

0-based byte offset within the JSON content where the error was detected.

Populated for InvalidJson; empty otherwise.

line​

std::optional<std::size_t> line

1-based line number derived from the byte offset.

Populated for InvalidJson; empty otherwise.

parseConfigFromJson​

Function
std::variant<Config, ConfigParseFailure> parseConfigFromJson( const std::string& filePath)

Parse a Config object from a JSON file

Reads a JSON configuration file and parses it into a Config struct. The JSON file should contain the following fields:

{
  "licensePath": "/path/to/license",                         // REQUIRED
  "mapPaths": ["/path/to/map1.r3db", "/path/to/map2.r3db"],  // REQUIRED
  "imageWidth": 1920,                                        // Optional, default: 0
  "imageHeight": 1080,                                       // Optional, default: 0
  "detailStage1": 8,                                         // Optional, default: 8
  "detailStage2": 9,                                         // Optional, default: 9
  "coordinateEpoch": 2025.0,                                 // Optional, default: None
  "geoResourcePath": "/path/to/geo",                         // Optional, default: ""
  "logger": {                                                // Optional
    "name": "Raptor",                                        // Optional, default: "Raptor"
    "level": "Info"                                          // Optional, default: "Info"
  },
  "memoryBudget": {                                          // Optional
    "gpuReserveBytes": 268435456,                            // Optional, default: 256 MiB
    "hostReserveBytes": 1073741824                           // Optional, default: 1 GiB
  }
}

The accepted "logger.level" values are the names of LogLevel (case-insensitive): "Trace", "Debug", "Info", "Warning", "Error", "Critical", "Off". A custom log callback cannot be expressed in JSON and must be set programmatically after parsing.

Parameters:

  • filePath - Path to the JSON configuration file

Returns: std::variant containing either a parsed Config object or a ConfigParseFailure

Example
    auto result = raptor::parseConfigFromJson("config.json");
    if (std::holds_alternative<raptor::Config>(result)) {
        const auto& config = std::get<raptor::Config>(result);
        raptor::Context context{config};
    } else {
        const auto& failure = std::get<raptor::ConfigParseFailure>(result);
        std::cerr << "Failed to load config: error code "
                  << static_cast<int>(failure.error)
                  << " at field '" << failure.field << "': " << failure.detail << std::endl;
    }