Guide Server Protocol Buffer API

guide.proto

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.

CoordinateSystem

Coordinate system specification

Field	Type	Label	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.

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

GeodeticOptions

Options for geodetic coordinate representation

Field	Type	Label	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)

GetConfigRequest

Config management messages (read-only server default configuration)

GetConfigResponse

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

GetStatusRequest

A simple ping/status request

GetStatusResponse

Field	Type	Label	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)

GuideDestroyRequest

Request message for Guide cleanup/destruction

GuideDestroyResponse

Response message for Guide cleanup/destruction

Field	Type	Label	Description
success	bool		Success status

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	Label	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	Label	Description
success	bool		Success status
error_message	string		Error message if initialization failed

GuideRequest

ZeroMQ communication wrapper messages (separate request/response)

Field	Type	Label	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	Label	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

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

MapInfo

Per-directory map listing entry

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

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
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]
fom	double		DEPRECATED: Figure of Merit - quality score (0.0-1.0) This field is deprecated and will be removed in future versions. Use 'confidence' instead as the recommended quality metric.
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

Position3D

3D position vector

Field	Type	Label	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)

PositionOutput

Output data from position estimation Same as PoseOutput but without attitude 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
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]
fom	double		DEPRECATED: Figure of Merit - quality score (0.0-1.0) This field is deprecated and will be removed in future versions. Use 'confidence' instead as the recommended quality metric.
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

Quaternion

Unit quaternion for attitude representation

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

QueryAvailableMapsRequest

Request message for querying available maps

No parameters needed - returns all available maps

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

RenderReferenceImageRequest

Request message for rendering reference image

Field	Type	Label	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	Label	Description
success	bool		Success status
image_data	bytes		Rendered grayscale image data (if successful)
error_message	string		Error message if rendering failed

Timestamp

High-resolution timestamp (nanoseconds since epoch)

Field	Type	Label	Description
nanoseconds	int64

UpdatePoseRequest

Request message for pose update

Field	Type	Label	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	Label	Description
pose_output	PoseOutput		Pose estimation output

UpdatePositionRequest

Request message for position update

Field	Type	Label	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	Label	Description
position_output	PositionOutput		Position estimation output

HorizontalUnit

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

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

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

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

Result

Result status for pose estimation operations

Name	Number	Description
RESULT_UNSPECIFIED	0
OK	1	Operation completed without errors - check confidence for quality assessment
FAILED	2	Operation failed due to errors - output data should not be used

VerticalDatum

Vertical datum reference for height measurements

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

VerticalUnit

Unit of measurement for vertical coordinate (height/altitude)

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

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)