Guide Configuration API

Configuration parameters for Raptor Guide.

Functions

Name	Description
parseConfigFromJson	Parse a Config object from a JSON file.

Function Details

parseConfigFromJson

Function

std::variant<Config, ConfigParseError> 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 optional fields:

{
  "licensePath": "/path/to/license",                         // REQUIRED
  "mapPaths": ["/path/to/map1.r3db", "/path/to/map2.r3db"],  // REQUIRED
  "geoResourcePath": "/path/to/geo/resources",               // REQUIRED
  "detailStage1": 8,                                         // Optional, default: 8
  "detailStage2": 9,                                         // Optional, default: 9
  "confidenceInterval": 0.9,                                 // Optional, default: 0.9
  "coordinateSystem": {
    "referenceFrame": "ECEF" or "Geodetic",      // Optional, default: "Geodetic"
    "coordinateEpoch": 2025.0,                   // Optional (default: None)
                                                 // NOTE: For mission-specific accuracy,
                                                 // override in runtime to match mission epoch
    "geodeticOptions": {
      "verticalDatum": "Ellipsoid" or "EGM2008", // Optional, default: "Ellipsoid"
      "horizontalUnit": "Radian" or "Degree",    // Optional, default: "Radian"
      "verticalUnit": "Meter" or "Foot"          // Optional, default: "Meter"
    }
  }
}

Parameters:

• filePath - Path to the JSON configuration file

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

Example

auto result = raptor::guide::parseConfigFromJson("config.json");
if (std::holds_alternative<raptor::guide::Config>(result)) {
    auto config = std::get<raptor::guide::Config>(result);
    raptor::Guide guide(mapPaths, width, height, config);
} else {
    auto error = std::get<raptor::guide::ConfigParseError>(result);
    std::cerr << "Failed to load config: error code " << static_cast<int>(error) << std::endl;
}

Types

Name	Description
Config	Configuration parameters for the Raptor Guide SDK.
ConfigParseError	Parse a Config object from a JSON file. Error codes for configuration parsing.

Config

struct Config

Configuration parameters for the Raptor Guide SDK.

These settings apply to the entire SDK session and cannot be changed after initialization. Choose values based on your accuracy vs. performance requirements.

Variables

Name	Description
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).
geoResourcePath	Path to geo resource directory (REQUIRED).
detailStage1	Level of detail of map for initial pose search.
detailStage2	Level of detail of map for final pose refinement.
confidenceInterval	Confidence interval for covariance estimation (0.0-1.0).
coordinateSystem	Coordinate system specification.

Variable Details

imageWidth

unsigned int imageWidth

Width of input images in pixels (REQUIRED).

Must be consistent for all images processed with Raptor Guide. Must match the actual width of images passed to Guide methods.

imageHeight

unsigned int imageHeight

Height of input images in pixels (REQUIRED).

Must be consistent for all images processed with Raptor Guide. Must match the actual height of images passed to Guide methods.

licensePath

std::string licensePath

Path to license file (REQUIRED).

Must point to a readable Raptor Guide 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.

geoResourcePath

std::string geoResourcePath

Path to geo resource directory (REQUIRED).

Must point to the directory containing geodetic transformation data. Use absolute path for reliability. Geo resource folder included in SDK package.

Example: "/opt/raptor/resources/geo"

detailStage1

unsigned int detailStage1

Level of detail of map for initial pose search.

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 map for final pose refinement.

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

warning

Values >= 32 will cause overflow - validated at runtime

confidenceInterval

float confidenceInterval

Confidence interval for covariance estimation (0.0-1.0).

Statistical confidence level for uncertainty estimates.

• 0.68: 1-sigma (68% confidence)
• 0.90: Default, good balance
• 0.95: 2-sigma (95% confidence)
• 0.99: High confidence

warning

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

coordinateSystem

CoordinateSystem coordinateSystem

Coordinate system specification.

Defines the complete coordinate system configuration including reference frame, geodetic options, and coordinate epoch for tectonic plate correction.

See: CoordinateSystem for available options

ConfigParseError

enum class ConfigParseError

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

Value	Description
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).