Guide Configuration API
Types
| Name | Description |
|---|---|
| Config | Configuration parameters for the Raptor Guide™ SDK These settings apply to the entire SDK session and cannot be changed after initialization. |
| ConfigParseError | Error codes for configuration parsing Describes different errors that may occur when parsing a configuration file. |
Functions
| Name | Description |
|---|---|
| parseConfigFromJson | Parse a Config object from a JSON file Reads a JSON configuration file and parses it into a Config struct. |
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 Higher values = more accurate but slower processing. |
| detailStage2 | Level of detail of map for final pose refinement Should be >= detailStage1 for best results. |
| confidenceInterval | Confidence interval for covariance estimation (0.0-1.0) |
| coordinateSystem | Coordinate system specification Defines the complete coordinate system configuration including reference frame, geodetic options, and coordinate epoch for tectonic plate correction. |
Variable Details
imageWidth
std::uint32_t 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
std::uint32_t 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
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
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
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.
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)
parseConfigFromJson
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
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;
}