Message Definition API

raptor_sync_message_definition.proto

ActivateApiLogIndication

The ActivateApiLogIndication requests the server to activate API logging for the given stream.

Field	Type	Description
stream_id	uint64	The stream for which the API logging shall be activated.

ApiError

An ApiError is returned by the server in response to a malformed or unexpected UserMessage.

Field	Type
error_type	ApiError.ErrorType

Attitude

Attitude message. All input attitude values to Raptor Sync is expected to be degrees. All response values from Raptor Sync will be degrees.

For KLV oriented user applications yaw is equal to heading/azimuth angle, pitch is pitch/elevation angle and roll is roll angle.

Field	Type
yaw	double
pitch	double
roll	double

DeactivateApiLogIndication

The DeactivateApiLogInication requests the server to deactivate API logging for the given stream.

Field	Type	Description
stream_id	uint64	The stream for which the API logging shall be deactivated.

FieldOfView

Field of view message. All input field of view to Raptor Sync is expected to be degrees. All response values from Raptor Sync will be degrees.

Field	Type
horizontal	double
vertical	double

Frame

The Frame message encapsulate raster data as well as metadata for an image.

Field	Type	Description
metadata	ImageMetadata	Image metadata.
rgb_image	RgbImage
png_image	PngImage
grayscale_image	GrayscaleImage

GeoRegistration

Geo registration message. A grid of 3D points earth intersection points produced by ray/terrain intersections.

The grid size and layout is specified through Raptor Sync configuration outside the message API.

Each point in the grid represents a UV coordinate (normalized image space, see below) and the 3D coordinate where a ray from the camera through that UV coordinate intersect the terrain.

If Raptor Sync is unable to perform the ray intersection (e.g. because outside of database, image is looking into the sky) the 3D point for an earth intersection is NaN (not a number).

The UV coordinates used by Raptor Sync looks like:

 U axis ----->       V axis
                       |
0 0 ------- 1 0        |
 |           |         |
 |           |         |
 |  0.5 0.5  |         |
 |           |         |
 |           |         |
0 1 ------- 1 1       \ /

Field	Type	Label	Description
earth_intersection	GeoRegistration.EarthIntersection	repeated	An array of earth intersection.

GeoRegistration.EarthIntersection

EarthIntersection message.

Field	Type	Description
u	double	U coordinate in range [0.0 - 1.0].
v	double	V coordinate in range [0.0 - 1.0].
location	Point	The location where the ray intersects the terrain.

GrayscaleImage

Field	Type	Description
width	uint32	Pixel width of the image.
height	uint32	Pixel height of the image.
raw	bytes	Raster data is inlined in the message body.
path	string	Raster data is external and can be read from the the file system at path.

ImageMetadata

Image metadata message. The message contains information describing how the image was captured.

Field	Type	Description
position	Point	Sensor position.
attitude	Attitude	Sensor attitude.
fov	FieldOfView	Image field of view.
lens_parameters	LensParameters	Lens distortion parameters.

LensParameters

Lens distortion message. Parameters are describing radial distortion.

Can be set to zero.

Field	Type
k2	double
k3	double
k4	double

ListReferenceDatasetsRequest

Request the list of reference datasets used for the given stream. The server will response with a ListReferenceDatasetsResponse message.

Field	Type	Description
stream_id	uint64	The stream for which to list reference datasets.

ListReferenceDatasetsResponse

Message listing reference datasets used by particular stream, sent in response to a successful ListReferenceDatasetsRequest user message.

Field	Type	Label	Description
stream_id	uint64		The stream from which the list of reference datasets comes.
reference_datasets	string	repeated	Paths to reference datasets used by the stream.

OpenStreamRequest

Request the server to open a new registration stream. The server will respond with an OpenStreamResponse message.

Field	Type	Label	Description
reference_datasets	string	repeated	Paths to reference datasets to use for the stream. May be empty, in which case the server must have been started with default reference datasets.

OpenStreamResponse

Message sent in response to a successful OpenStreamRequest user message.

Field	Type	Description
stream_id	uint64	The stream id assigned to the new stream.

PngImage

PngImage message.

Field	Type	Description
raw	bytes	Image data inlined in message body.
path	string	Image data is external and can be read from the file system at path.

Point

A 3D point message. Shall be interpreted according to the coordinate system being used.

latitude and longitude are in degrees, and height is expressed as a negative number.

Field	Type
latitude	double
longitude	double
height	double

RaptorSyncMessage

The RaptorSyncMessage is an enumeration of messages that can be sent from Raptor Sync to the user application.

Field	Type
response	RegistrationResponse
error	RegistrationError
apiError	ApiError
openStreamResponse	OpenStreamResponse
versionResponse	VersionResponse
listReferenceDatasetsResponse	ListReferenceDatasetsResponse

RegistrationError

The RegistrationError is sent from Raptor Sync to the user in case of an error related to registration of a frame.

Field	Type	Description
stream_id	uint64	Identity for the stream. The message will reply with the identifier from the request.
frame_id	uint64	Identity for the frame. The message will reply with the identifier from the request.
error_type	RegistrationError.ErrorType
error_string	string	Some more information about the error in string form.

RegistrationRequest

The RegistrationRequest message initiates the start of an image registration.

Field	Type	Description
stream_id	uint64	Identity for the stream which the image belongs to. Images from different feeds/sources must not be mixed in the same stream. The user application is expected to manage the streams properly. Raptor Sync will create an internal context when it receives a request with an unknown stream identifier. Raptor Sync may remove the internal context for streams that are inactive.
frame_id	uint64	Identity for the frame. Assigned by the user application.
frame	Frame	Frame content.

RegistrationResponse

The RegistrationResponse message is the reply from Raptor Sync to the user application.

Field	Type	Description
stream_id	uint64	Identity for the stream. The response will reply with the identifier from the request.
frame_id	uint64	Identity for the frame. The response will reply with the identifier from the request.
figure_of_merit	double	Figure of merit, or FOM, is a value describing the similarity (correlation) between the input image and the best fitting image rendered from the database during the registration procedure. Successful registrations will return FOM-values in range [0.0 - 1.0]. A higher value indicates a better result. In case of error Raptor Sync will return -1.
metadata	ImageMetadata	Image metadata updated during the Raptor Sync procedure.
geo_registration	GeoRegistration	A grid of geo registration points from the registered image's footprint on ground. The size and layout of the geo registration grid is configured outside the message API.

RgbImage

RgbImage message.

Field	Type	Description
width	uint32	Pixel width of the image.
height	uint32	Pixel height of the image.
raw	bytes	Raster data is inlined in the message body.
path	string	Raster data is external and can be read from the the file system at path.

UserMessage

The UserMessage is an enumeration of messages that can be sent from the user application.

Field	Type
request	RegistrationRequest
activateApiLogIndication	ActivateApiLogIndication
deactivateApiLogIndication	DeactivateApiLogIndication
openStreamRequest	OpenStreamRequest
versionRequest	VersionRequest
listReferenceDatasetsRequest	ListReferenceDatasetsRequest

VersionRequest

Request version information from the server. The server will respond with a VersionResponse message.

VersionResponse

Message with server version information, sent in response to a VersionRequest user message.

Field	Type	Description
branch	string	Raptor Sync server branch.
revision	string	Raptor Sync server revision.

ApiError.ErrorType

Enumeration of possible types of error.

Name	Number	Description
INVALID_STREAM_ID	0	The stream id specified in a user message could not be matched to a live stream.
NO_REFERENCE_DATASETS	1	No reference datasets have been specified when attempting to start a new stream.

RegistrationError.ErrorType

Enumeration of possible types of error.

Name	Number	Description
MISSING_FRAME	0	The Frame object was missing from the RegistrationRequest
MISSING_METADATA	1	The ImageMetadata object was missing from the Frame object
MISSING_IMAGE	2	No RgbImage or PngImage was present in the Frame object
INVALID_INPUT_COORDINATE_SYSTEM	3	Raptor Sync could not decipher the input coordinate system, check the error_string for more information
INTERNAL_FAIL_CREATE_IMAGE	4	Raptor Sync could not internally create an image, check the error_string for more information
INTERNAL_FAIL_CREATE_PROJECTION	5	Raptor Sync could not internally create a projection from the input metadata, check the error_string for more information
INTERNAL_FAIL_REGISTRATION	6	Raptor Sync failed to register the provided frame. This can typically happen if the frame lies outside of the provided database, or if the frame points away from the database, e.g. to the sky
NO_REFERENCE_DATASETS	7	No reference datasets have been set for this stream.

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)