Raptor Sync Server

The Raptor Sync server acts on request messages sent from the client application over the network protocol. Messages are defined and encoded using the Google Protocol Buffers (protobuf), and are sent over TCP/IP.

The client application sends a top-level message called UserMessage, usually with a submessage called RegistrationRequest. The Raptor Sync server replies with a top-level message called RaptorSyncMessage, with a RegistrationResponse or a RegistrationError as its submessage.

Note that in the wire protocol between the client application and the Raptor Sync server, each protobuf message must be prepended by its byte size. The byte size is a four-byte unsigned integer encoded in network byte order.

The Raptor Sync server can georegister multiple simultaneous video streams, with each stream being identified by a stream id. The different video streams can originate from the same or separate client applications. The stream id must be the same for all requests belonging to a particular video stream.

Once a TCP/IP connection is set-up between the client application and the Raptor Sync server, the client sends an OpenStreamRequest message, to which the server responds with an OpenStreamResponse message including the stream id to use for this video stream. The OpenStreamRequest message may also include the reference datasets to use for this stream, instead of any default datasets specified when starting the server.

To exchange messages, each RegistrationRequest from the client must be tagged with the stream id as well as a frame id. The frame id identifies a single frame within the video stream and is expected to be unique for each new request sent to the Raptor Sync server. In its response, the Raptor Sync server will include the same stream id and frame id as received in the request.

The Raptor Sync server can handle several concurrent RegistrationRequests for the same stream id. In general, having several concurrent requests in-flight increases the throughput performance of the video registration. Two things are important though:

The Raptor Sync server expects the requests to arrive in the temporal order of the video.
The Raptor Sync server may return the responses out of order to the client.

Command: run

Use the command raptor_sync_server run to start a server accepting TCP connections with video streams to georegister.

Options to the run command can be passed with a configuration file. It is possible to combine a configuration file and command line options. See Server configuration file.

Usage pattern for run

raptor_sync_server run [--config PATH_TO_CONFIG_FILE] [--in.references PATH_TO_DATASET_FILE...] [--address ADDRESS] [--port PORT] [--out.image-points IMAGE_POINT...] [--num-threads NUMBER_OF_THREADS] [--log.level error|warning|info|debug] [--log.destination PATH_TO_LOG_FILE]

Table 3: Options for command run

Option	Parameter	Description
`-c, --config` (optional)	`PATH_TO_CONFIG_FILE`	Specify a JSON configuration file with parameter values. If no configuration file has been specified, only command line options will be used.
`--in.references` (optional)	`PATH_TO_DATASET_FILE`	A Vivid Terrain 3D Surface Model (.r3db) or 3D Tiles (tileset.json, .zip, .3tz) dataset covering the area of the input video. Multiple files can be specified, separated by space. These datasets will be used if none are specified when opening a new video stream.
`--address` (optional)	`ADDRESS`	Specify the server's IP address or hostname. Defaults to `localhost`.
`--port` (optional)	`PORT`	Specify the port to listen to. Defaults to `0`, resulting in the system assigning the server an available port.
`--out.image-points` (optional)	`IMAGE_POINT`	Normalized image coordinates (u, v pair) of points whose georegistered world position will be included in the output. Specified as `u0 v0 u1 v1...`
`--num-threads` (optional)	`NUMBER_OF_THREADS`	Specify number of threads to use, see Number of execution threads.
`--log.level` (optional)	`error\|warning\|info\|debug`	Log severity level. Specify what types of messages to send to standard out. Messages with a severity level lower than the specified level will not be logged. Defaults to `warning`.
`--log.destination` (optional)	`PATH_TO_LOG_FILE`	Specify a file to log output to.

Server configuration file

Pass options to the run command via a JSON-formatted configuration file using the --config option. The option names follow the JSON object structure. For instance, the option --out.image-points will get its value from the image-points field of the out object in the configuration file.

If passing command line arguments while also specifying a configuration file, the command line arguments will override the values found in the configuration file. See the following example of a configuration file and its equivalent command line.

A local Raptor Sync server emitting georegistered frame center and corner positions:

raptor_sync_server run --in.references path/to/reference1.r3db path/to/reference2.r3db --out.image-points 0.5 0.5 0.0 0.0 0.0 1.0 1.0 0.0 1.0 1.0

{
  "in": {
    "references": ["path/to/reference1.r3db", "path/to/reference2.r3db"]
  },
  "out": {
    "image-points": [0.5, 0.5, 0.0, 0.0, 0.0, 1.0, 1.0, 0.0, 1.0, 1.0]
  }
}

Number of execution threads

With the --num-threads option it is possible to specify the maximal number of execution threads to use when running the application. The number of threads will never exceed the optimal number of threads supported by the host CPU, or the license's thread limit, regardless of the value of the parameter passed to --num-threads.

Command: run​

Usage pattern for run​

Table 3: Options for command run​

Server configuration file​

A local Raptor Sync server emitting georegistered frame center and corner positions:​

Number of execution threads​