Guide Server Protocol Buffer API

guide.proto

Result

Result status for pose estimation operations

Name	Number	Description
RESULT_UNSPECIFIED	0
OK	1	Operation completed without errors - check confidence for quality assessment
INSUFFICIENT_MAP_COVERAGE	2	Insufficient 3D map coverage at the input pose location
FAILED	3	Operation failed due to errors - output data should not be used

ReferenceFrame

Spatial reference frame for input/output coordinates

Name	Number	Description
REFERENCE_FRAME_UNSPECIFIED	0
ECEF	1	Earth-Centered Earth-Fixed coordinates
GEODETIC	2	Geodetic coordinates with local NED orientation

HorizontalUnit

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

Name	Number	Description
HORIZONTAL_UNIT_UNSPECIFIED	0
RADIAN	1	Radians (default)
DEGREE	2	Degrees

VerticalUnit

Unit of measurement for vertical coordinate (height/altitude)

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

VerticalDatum

Vertical datum reference for height measurements

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

LicenseStatus

License verification status reported by server

Name	Number	Description
LICENSE_STATUS_UNSPECIFIED	0
LICENSE_STATUS_OK	1
LICENSE_STATUS_INVALID	2
LICENSE_STATUS_EXPIRED	3
LICENSE_STATUS_PROFILE_INVALID	4
LICENSE_STATUS_FINGERPRINT_MISMATCH	5
LICENSE_STATUS_FINGERPRINT_MISSING	6
LICENSE_STATUS_DISABLED	7	License enforcement disabled at build time
LICENSE_STATUS_NOT_SET	8	License path not configured

GeodeticOptions

Options for geodetic coordinate representation

Field	Type	Description
vertical_datum	VerticalDatum	Vertical datum reference (default: ELLIPSOID)
horizontal_unit	HorizontalUnit	Unit for latitude and longitude (default: RADIAN)
vertical_unit	VerticalUnit	Unit for height/altitude (default: METER)

CoordinateSystem

Coordinate system specification

Field	Type	Description
reference_frame	ReferenceFrame	Spatial reference frame for coordinates (default: GEODETIC)
geodetic_options	GeodeticOptions	Geodetic coordinate options (optional) Only applies when reference_frame is GEODETIC. If not provided, default GeodeticOptions will be used.
coordinate_epoch	float	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. Configure this via the server options CoordinateSystem when high-precision tectonic correction is required. 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.

Config

Configuration that can be tuned via the Guide 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 Guide 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 Guide instance. Must match the actual height of images passed to updatePose() and updatePosition().
coordinate_system	CoordinateSystem		Coordinate system specification Defines the complete coordinate system configuration including reference frame, geodetic options, and coordinate epoch for tectonic plate correction.
detail_stage_1	uint32		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		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
confidence_interval	float		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
map_paths	string	repeated	Optional server-side map selection for future guides. 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.
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

Position3D

3D position vector

Field	Type	Description
x	double	For Geodetic: Latitude(rad), For ECEF: X(m)
y	double	For Geodetic: Longitude(rad), For ECEF: Y(m)
z	double	For Geodetic: Height above Ellipsoid(m), For ECEF: Z(m)

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)

CovarianceMatrix3x3

3x3 covariance matrix in row-major order

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

CovarianceMatrix6x6

6x6 covariance matrix in row-major order

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

PoseOutput

Output data from pose estimation

Field	Type	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
position	Position3D	Refined camera position Format depends on the configured reference frame: • Geodetic: [Latitude(rad), Longitude(rad), Height above Ellipsoid(m)] • ECEF: [X(m), Y(m), Z(m)]
attitude	Quaternion	Refined camera attitude as unit quaternion Format: [x, y, z, w] where w is the scalar component. Represents rotation from reference frame to camera frame: • Geodetic: Rotation from local NED to camera • ECEF: Rotation from ECEF axes to camera
pose_covariance	CovarianceMatrix6x6	6x6 pose covariance matrix in row-major order Represents uncertainty in position (first 3 diagonal elements) and attitude (last 3 diagonal elements). Both position and attitude uncertainties are represented as variances (squared values) and refer to the axes of the configured reference frame. Units: • Position uncertainty: meters (squared) • Attitude uncertainty: radians (squared) Access element (i,j) as: poseCovariance[i*6 + j]
timestamp	Timestamp	Optional timestamp (same as input) Preserved from input for correlation with image data.
confidence	double	Confidence score (0.0-1.0) • Recommended quality metric 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

PositionOutput

Output data from position estimation Same as PoseOutput but without attitude estimation.

Field	Type	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
position	Position3D	Refined camera position Format depends on the configured reference frame: • Geodetic: [Latitude(rad), Longitude(rad), Height above Ellipsoid(m)] • ECEF: [X(m), Y(m), Z(m)]
position_covariance	CovarianceMatrix3x3	3x3 position covariance matrix in row-major order Represents uncertainty in position. Units: meters (squared) Access element (i,j) as: positionCovariance[i*3 + j]
timestamp	Timestamp	Optional timestamp (same as input) Preserved from input for correlation with image data.
confidence	double	Confidence score (0.0-1.0) • Recommended quality metric 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

GuideInitRequest

Request message for Guide 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	Description
config	Config	Optional configuration to apply before initializing this guide. Semantics are equivalent to calling the Config RPC with this Config and then calling GuideInitRequest without config.

GuideInitResponse

Response message for Guide initialization

Field	Type	Description
success	bool	Success status
error_message	string	Error message if initialization failed

UpdatePoseRequest

Request message for pose update

Field	Type	Description
image_data	bytes	Grayscale image data (8-bit, single channel)
h_fov	double	Horizontal field of view in radians
v_fov	double	Vertical field of view in radians
position	Position3D	Refined camera position Format depends on the configured reference frame: • Geodetic: [Latitude(rad), Longitude(rad), Height above Ellipsoid(m)] • ECEF: [X(m), Y(m), Z(m)]
attitude	Quaternion	Refined camera attitude as unit quaternion Format: [x, y, z, w] where w is the scalar component. Represents rotation from reference frame to camera frame: • Geodetic: Rotation from local NED to camera • ECEF: Rotation from ECEF axes to camera
pose_covariance	CovarianceMatrix6x6	6x6 pose covariance matrix in row-major order Represents uncertainty in position (first 3 diagonal elements) and attitude (last 3 diagonal elements). Both position and attitude uncertainties are represented as variances (squared values) and refer to the axes of the configured reference frame. Units: • Position uncertainty: meters (squared) • Attitude uncertainty: radians (squared) Access element (i,j) as: poseCovariance[i*6 + j]
max_time_ms	double	Optional maximum processing time in milliseconds
timestamp	Timestamp	Optional timestamp (same as input) Preserved from input for correlation with image data.

UpdatePoseResponse

Response message for pose update

Field	Type	Description
pose_output	PoseOutput	Pose estimation output

UpdatePositionRequest

Request message for position update

Field	Type	Description
image_data	bytes	Grayscale image data (8-bit, single channel)
h_fov	double	Horizontal field of view in radians
v_fov	double	Vertical field of view in radians
position	Position3D	Camera position Format depends on the configured reference frame: • Geodetic: [Latitude(rad), Longitude(rad), Height above Ellipsoid(m)] • ECEF: [X(m), Y(m), Z(m)]
position_covariance	CovarianceMatrix3x3	3x3 position covariance matrix in row-major order Represents uncertainty in position. Units: meters (squared) Access element (i,j) as: positionCovariance[i*3 + j]
max_time_ms	double	Optional maximum processing time in milliseconds
timestamp	Timestamp	Optional timestamp (same as input) Preserved from input for correlation with image data.

UpdatePositionResponse

Response message for position update

Field	Type	Description
position_output	PositionOutput	Position estimation output

RenderReferenceImageRequest

Request message for rendering reference image

Field	Type	Description
h_fov	double	Horizontal field of view in radians
v_fov	double	Vertical field of view in radians
position	Position3D	Position for rendering
attitude	Quaternion	Attitude as unit quaternion

RenderReferenceImageResponse

Response message for rendering reference image

Field	Type	Description
success	bool	Success status
image_data	bytes	Rendered grayscale image data (if successful)
error_message	string	Error message if rendering failed

GuideDestroyRequest

Request message for Guide cleanup/destruction

GuideDestroyResponse

Response message for Guide cleanup/destruction

Field	Type	Description
success	bool	Success status

GetStatusRequest

A simple ping/status request

GetStatusResponse

Field	Type	Description
success	bool
server_version	string
message	string	optional human-readable info
guide_initialized	bool	whether a guide instance exists
license_status	LicenseStatus	server-side license status
fingerprint_b64	string	device fingerprint (base64), if available
guide_sdk_version	string	Raptor Guide SDK version (MAJOR.MINOR.PATCH)

QueryAvailableMapsRequest

Request message for querying available maps

No parameters needed - returns all available maps

MapInfo

Per-directory map listing entry

Field	Type	Description
map_id	string	Unique identifier for the map
relative_path	string	Relative path to the map with respect to its base directory

MapDirectoryEntry

Field	Type	Label	Description
directory	string		Directory path (absolute or canonical top-level directory configured on server)
maps	MapInfo	repeated	Maps under this directory

QueryAvailableMapsResponse

Response message for querying available maps

Field	Type	Label	Description
success	bool		Success status
directories	MapDirectoryEntry	repeated	Maps grouped per directory
error_message	string		Error message if query failed

GetConfigRequest

Config management messages (read-only server default configuration)

GetConfigResponse

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

GuideRequest

ZeroMQ communication wrapper messages (separate request/response)

Field	Type	Description
request_id	string	For request/response correlation
init_request	GuideInitRequest
update_pose_request	UpdatePoseRequest
update_position_request	UpdatePositionRequest
render_request	RenderReferenceImageRequest
destroy_request	GuideDestroyRequest
query_maps_request	QueryAvailableMapsRequest
get_config_request	GetConfigRequest
get_status_request	GetStatusRequest

GuideResponse

Field	Type	Description
request_id	string	Correlates to GuideRequest.request_id
init_response	GuideInitResponse
update_pose_response	UpdatePoseResponse
update_position_response	UpdatePositionResponse
render_response	RenderReferenceImageResponse
destroy_response	GuideDestroyResponse
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)