Guide Configuration API

Source: raptor/Config.hpp

Types

Name	Description
Config	Configuration parameters for the Raptor SDK Context.
ConfigParseError	Error codes for configuration parsing.
ConfigParseFailure	Detailed configuration parsing failure.
LogLevel	Log severity levels.
LogMessage	A formatted log message delivered to a custom log callback.
LogCallback	Signature of a custom log callback.
Logger	Logger configuration.

Functions

Name	Description
parseConfigFromJson	Parse 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.

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

---

LogMessage

struct LogMessage

A formatted log message delivered to a custom log callback.

Variables

Name	Description
level	Severity level of the message.
timestamp	Timestamp in nanoseconds since epoch.
imageTimestamp	Timestamp of the image associated with the message, if any.
message	Formatted message string.
name	Logger name.

Variable Details

level

LogLevel level

Log level.

Messages below this level are not logged.

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

Name used for the logger.

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

---

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

Name	Description
name	Name used for the logger.
level	Log level.
callback	Optional 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.

---

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

Name	Description
geoResourcePath	Path to geo resources.
logger	Logger configuration.
imageWidth	Width of input images in pixels (REQUIRED).
imageHeight	Height of input images in pixels (REQUIRED).
licensePath	Path to license file (REQUIRED).
mapPaths	Paths to 3D map files (REQUIRED).
detailStage1	Level of detail of matching.
detailStage2	Level of detail of matching.
coordinateEpoch	Coordinate epoch for tectonic plate correction (optional, RECOMMENDED: omit).

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 or .3tz 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.

---

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

Name	Description
error	Category of the failure.
field	Path of the offending field in the JSON document.
detail	Human-readable contextual detail.
offset	0-based byte offset within the JSON content where the error was detected.
line	1-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"
  }
}

The accepted "logger.level" values are the names of (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;
    }