Guide Server Protocol Buffer API

raptor.proto

Error and status enums

Result

Result status for pose estimation operations.

Name	Number	Description
RESULT_UNSPECIFIED	0
OK	1	Operation completed without errors - check confidence for quality assessment
POSE_ESTIMATION_FAILED	2	No pose could be estimated
INVALID_INPUT	3	Input parameter(s) contains invalid values
INVALID_LICENSE	4	Operation could not be performed due to an invalid or insufficient license
INSUFFICIENT_MAP_COVERAGE	5	Insufficient 3D map coverage at the input pose location
POOR_FEATURE_DENSITY	6	Insufficient feature density in the input image
FAILED	7	Operation failed due to errors - output data should not be used

LicenseStatus

License verification status reported by server.

Name	Number	Description
LICENSE_STATUS_UNSPECIFIED	0
LICENSE_STATUS_NOT_SET	1	License path not configured on the server
LICENSE_STATUS_OK	2	License is valid
LICENSE_STATUS_FILE_NOT_FOUND	3	License file could not be opened at the configured path
LICENSE_STATUS_INVALID	4	License is malformed or not authorized for this application
LICENSE_STATUS_EXPIRED	5	License has expired
LICENSE_STATUS_EXPIRES_INVALID	6	License Expires timestamp is invalid
LICENSE_STATUS_ISSUED_INVALID	7	License Issued timestamp is invalid or in the future
LICENSE_STATUS_APPLICATION_ID_MISMATCH	8	License ApplicationId does not match this application
LICENSE_STATUS_PROFILE_INVALID	9	License fingerprint profile is invalid
LICENSE_STATUS_FINGERPRINT_MISMATCH	10	Machine fingerprint does not match the license
LICENSE_STATUS_FINGERPRINT_MISSING	11	License requires a fingerprint but none could be generated
LICENSE_STATUS_CONTEXT_INVALID	12	Fingerprint context is invalid
LICENSE_STATUS_FEATURES_MISSING	13	License is missing the required Features bitmap

Coordinate reference system

Crs

Field	Type
ecef	Crs.Ecef
geodetic	Crs.Geodetic

Crs.Ecef

Field	Type
reference_frame	Crs.ReferenceFrame

Crs.Geodetic

Field	Type
reference_frame	Crs.ReferenceFrame
horizontal_unit	Crs.HorizontalUnit
vertical_unit	Crs.VerticalUnit
height_system	Crs.HeightSystem

Crs.CoordinateSystem

Coordinate system type

Name	Number	Description
ECEF	0	Earth-Centered Earth-Fixed Cartesian coordinates (default)
GEODETIC	1	Geodetic coordinates (lat/lon/alt) with local NED orientation

Crs.HeightSystem

Height system reference for height measurements

Name	Number	Description
ELLIPSOID	0	WGS84 Ellipsoid (default)
EGM2008	1	EGM2008 Geoid

Crs.HorizontalUnit

Unit of measurement for horizontal geodetic coordinates (latitude/longitude)

Name	Number	Description
DEGREES	0	Degrees (default)
RADIANS	1	Radians

Crs.ReferenceFrame

Reference frame

Name	Number	Description
ITRF2008	0	ITRF2008 reference frame (default)
WGS84G1674	1	WGS84 (G1674) reference frame

Crs.VerticalUnit

Unit of measurement for vertical coordinate (height/altitude)

Name	Number	Description
METER	0	Meters (default)
FOOT	1	Feet

Quaternion

Quaternion

Unit quaternion for attitude representation

Field	Type	Description
x	double	x component
y	double	y component
z	double	z component
w	double	w component (scalar)

Pose and Position types

Pose

Pose: variant type for either ECEF or Geodetic pose.

Field	Type
ecef	Pose.Ecef
geodetic	Pose.Geodetic

Pose.Ecef

ECEF Pose: Earth-Centered Earth-Fixed coordinates with attitude

Field	Type	Description
x	double	meters
y	double	meters
z	double	meters
attitude	Quaternion
crs	Crs.Ecef

Pose.Geodetic

Geodetic Pose: lat/lon/alt coordinates with attitude

Field	Type	Description
lat	double	units defined by crs.horizontal_unit
lon	double	units defined by crs.horizontal_unit
alt	double	units defined by crs.vertical_unit
attitude	Quaternion
crs	Crs.Geodetic

Position

Position: variant type for either ECEF or Geodetic position.

Field	Type
ecef	Position.Ecef
geodetic	Position.Geodetic

Position.Ecef

ECEF Position: Earth-Centered Earth-Fixed coordinates

Field	Type	Description
x	double	meters
y	double	meters
z	double	meters
crs	Crs.Ecef

Position.Geodetic

Geodetic Position: lat/lon/alt coordinates

Field	Type	Description
lat	double	units defined by crs.horizontal_unit
lon	double	units defined by crs.horizontal_unit
alt	double	units defined by crs.vertical_unit
crs	Crs.Geodetic

Lens model

LensModel

Camera intrinsic parameters (lens model)

Field	Type
pinhole	LensModel.Pinhole

LensModel.Pinhole

Pinhole lens parameters

Field	Type
fx	double
fy	double
cx	double
cy	double

Image

Image

Field	Type
type	Image.Type
width	uint32
height	uint32
data	bytes

Image.Type

Name	Number	Description
GRAY8	0	8-bit grayscale (default)
RGB8	1	24-bit RGB
RGBA8	2	32-bit RGBA

Configuration

Config

Configuration that can be tuned via the Raptor Server RPC API.

Field	Type	Label	Description
image_width	uint32		Width of input images in pixels (REQUIRED) Must be consistent for all images processed with this PoseEstimator instance. Must match the actual width of images passed to updatePose() and updatePosition().
image_height	uint32		Height of input images in pixels (REQUIRED) Must be consistent for all images processed with this PoseEstimator instance. Must match the actual height of images passed to updatePose() and updatePosition().
map_paths	string	repeated	Optional server-side map selection for future PoseEstimators. When configured via the Config RPC, these override server defaults from JSON configuration and discovered maps from directories. If empty, the server falls back to CLI and JSON configuration.
detail_stage_1	uint32	optional	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
detail_stage_2	uint32	optional	Level of detail of map for final pose refinement Should be >= detail_stage_1 for best results. Recommended values: 8-9 Values >= 32 will cause overflow - validated at runtime
coordinate_epoch	float	optional	Coordinate epoch for tectonic plate correction (optional, RECOMMENDED: omit) Year as decimal number (e.g., 2025.0 for January 1st, 2025). 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. If not provided, no tectonic correction is applied. 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. LIMITATION: 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.
map_ids	string	repeated	Optional map IDs (resolved server-side to absolute paths). Map IDs are obtained from QueryAvailableMapsResponse. When provided, these override map_paths and the server's default map set.

Timestamp

High-resolution timestamp (nanoseconds since epoch)

Field	Type
nanoseconds	int64

PoseEstimator types

PoseCovariance

6x6 pose covariance in row-major order over (x, y, z, yaw, pitch, roll). Expressed in the camera frame (DIN 9300: x forward, y right, z down).

Field	Type	Label	Description
values	double	repeated	36 elements in row-major order

PositionCovariance

3x3 position covariance in row-major order over (x, y, z). Expressed in the camera frame (DIN 9300: x forward, y right, z down).

Field	Type	Label	Description
values	double	repeated	9 elements in row-major order

PoseOutput

Output data from pose estimation.

Field	Type	Label	Description
result	Result		Operation result status Indicates whether the operation completed without errors. This does NOT indicate quality - check confidence field for that. Only use other fields if result == Result::OK
pose	Pose		Refined camera pose (position + attitude).
covariance	PoseCovariance	optional	6x6 pose covariance over (x, y, z, yaw, pitch, roll) in the camera body frame (DIN 9300). Set when an uncertainty estimate is available; otherwise unset.
confidence	double		Confidence score (0.0-1.0) Primary indicator of result quality and reliability. Quality assessment guidelines: • > 0.95: Excellent quality - high confidence result • 0.85-0.95: Good quality - reliable for most applications • 0.7-0.85: Moderate quality - use with caution • < 0.7: Poor quality - recommended to reject the result Always check this value even when result == Result::OK
map_coverage	double		Fraction of the camera's view covered by valid 3D map data (0.0-1.0). Low values mean large portions of the frame fall outside the map, which reduces matching quality and typically degrades the result.
timestamp	Timestamp		Image timestamp (preserved from the request, identifies when the input image was captured). Always populated; echoed back unchanged from the request timestamp.

PositionOutput

Output data from position estimation.

Field	Type	Label	Description
result	Result		Operation result status
position	Position		Refined camera position.
covariance	PositionCovariance	optional	3x3 position covariance over (x, y, z) in the camera frame (DIN 9300). Set when an uncertainty estimate is available; otherwise unset.
confidence	double		Confidence score (0.0-1.0)
map_coverage	double		Fraction of the camera's view covered by valid 3D map data (0.0-1.0).
timestamp	Timestamp		Image timestamp (preserved from the request, identifies when the input image was captured). Always populated; echoed back unchanged from the request timestamp.

EstimationOptions

Per-call tuning knobs for updatePose / updatePosition.

Field	Type	Label	Description
max_time_ms	double	optional	Optional maximum processing time in milliseconds. The algorithm returns the best result found within this budget.
confidence_interval	double	optional	Confidence interval driving the covariance search range (0.0, 1.0). Controls how much of the input PoseCovariance ellipsoid is searched around the input pose. Per dimension, the search range is ±sqrt(chiSquared(confidence_interval, 6 dof) * variance). Common values: • 0.68: 1-sigma • 0.90: default • 0.95: 2-sigma • 0.99: high confidence Must be in range (0.0, 1.0) - validated at runtime.
exhaustive_range_search	bool	optional	Enable exhaustive range search (default: false). Significantly increases processing time; pair with max_time_ms.
feature_density_check	bool	optional	Enable a feature density check before range search (default: false). Images with too few features return POOR_FEATURE_DENSITY.

RPC requests and responses

PoseEstimatorInitRequest

Request message for PoseEstimator initialization. Global configuration such as image size, reference frame and coordinate epoch is configured via the server's default config or optionally attached here.

Field	Type	Label	Description
config	Config	optional	Optional configuration to apply before initializing this PoseEstimator. Semantics are equivalent to calling the Config RPC with this Config and then calling PoseEstimatorInitRequest without config.

PoseEstimatorInitResponse

Response message for PoseEstimator initialization.

Field	Type	Label
success	bool
error_message	string	optional

UpdatePoseRequest

Request message for pose update.

Field	Type	Label	Description
image	Image
lens	LensModel		Camera intrinsic parameters (lens model)
pose	Pose		Camera pose (position + attitude).
timestamp	Timestamp		Image timestamp identifying when the input image was captured. Required. The epoch is client-defined and must be consistent across calls. Echoed back unchanged in PoseOutput.timestamp.
covariance	PoseCovariance	optional	Optional input pose covariance. Drives the range search around the input pose. Values should reflect input pose uncertainty for optimal results.
options	EstimationOptions	optional	Optional per-call tuning knobs.

UpdatePoseResponse

Response message for pose update.

Field	Type
pose_output	PoseOutput

UpdatePositionRequest

Request message for position update.

Field	Type	Label
image	Image
lens	LensModel
pose	Pose
timestamp	Timestamp
covariance	PoseCovariance	optional
options	EstimationOptions	optional

UpdatePositionResponse

Response message for position update.

Field	Type
position_output	PositionOutput

PoseEstimatorDestroyRequest

Request message for PoseEstimator destruction.

PoseEstimatorDestroyResponse

Response message for PoseEstimator destruction.

Field	Type	Label
success	bool
error_message	string	optional

GetStatusRequest

Request message for getting server status (version, license, fingerprint).

GetStatusResponse

Response message for getting server status.

Field	Type	Label
success	bool
server_version	string
raptor_sdk_version	string
license_status	LicenseStatus
fingerprint	string	optional
pose_estimator_initialized	bool
error_message	string	optional

MapInfo

Map info entry within a map directory

Field	Type	Description
map_id	string	Stable identifier (relative path used by clients)
relative_path	string	Relative path within the directory

MapDirectoryEntry

Map directory entry (base directory + maps within)

Field	Type	Label	Description
base_dir	string		Base directory absolute path
maps	MapInfo	repeated	Maps discovered in this directory

QueryAvailableMapsRequest

Request message for querying available maps

QueryAvailableMapsResponse

Response message for querying available maps

Field	Type	Label
success	bool
directories	MapDirectoryEntry	repeated
error_message	string	optional

GetConfigRequest

Config management messages (read-only server default configuration)

GetConfigResponse

Field	Type	Label	Description
success	bool
config	Config	optional	Server default configuration only (not modified by RPCs)
error_message	string	optional

ZeroMQ communication wrapper messages (separate request/response)

RaptorRequest

Field	Type	Description
request_id	string	For request/response correlation
init_request	PoseEstimatorInitRequest
update_pose_request	UpdatePoseRequest
update_position_request	UpdatePositionRequest
destroy_request	PoseEstimatorDestroyRequest
query_maps_request	QueryAvailableMapsRequest
get_config_request	GetConfigRequest
get_status_request	GetStatusRequest

RaptorResponse

Field	Type	Description
request_id	string	Correlates to RaptorRequest.request_id
init_response	PoseEstimatorInitResponse
update_pose_response	UpdatePoseResponse
update_position_response	UpdatePositionResponse
destroy_response	PoseEstimatorDestroyResponse
query_maps_response	QueryAvailableMapsResponse
get_config_response	GetConfigResponse
get_status_response	GetStatusResponse

Scalar Value Types

.proto Type	Notes	C++	Java	Python	Go	C#	PHP	Ruby
double		double	double	float	float64	double	float	Float
float		float	float	float	float32	float	float	Float
int32	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
int64	Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.	int64	long	int/long	int64	long	integer/string	Bignum
uint32	Uses variable-length encoding.	uint32	int	int/long	uint32	uint	integer	Bignum or Fixnum (as required)
uint64	Uses variable-length encoding.	uint64	long	int/long	uint64	ulong	integer/string	Bignum or Fixnum (as required)
sint32	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sint64	Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.	int64	long	int/long	int64	long	integer/string	Bignum
fixed32	Always four bytes. More efficient than uint32 if values are often greater than 2^28.	uint32	int	int	uint32	uint	integer	Bignum or Fixnum (as required)
fixed64	Always eight bytes. More efficient than uint64 if values are often greater than 2^56.	uint64	long	int/long	uint64	ulong	integer/string	Bignum
sfixed32	Always four bytes.	int32	int	int	int32	int	integer	Bignum or Fixnum (as required)
sfixed64	Always eight bytes.	int64	long	int/long	int64	long	integer/string	Bignum
bool		bool	boolean	boolean	bool	bool	boolean	TrueClass/FalseClass
string	A string must always contain UTF-8 encoded or 7-bit ASCII text.	string	String	str/unicode	string	string	string	String (UTF-8)
bytes	May contain any arbitrary sequence of bytes.	string	ByteString	str	[]byte	ByteString	string	String (ASCII-8BIT)