Skip to main content

Raptor Sync Client

The Raptor Sync client is a tool for georegistration of MPEG transport stream (MPEG-TS) full motion video that is accompanied by MISB 0601 KLV LDS (KLV) metadata. The MPEG-TS can either be located on file or streamed in real-time over UDP.

The Raptor Sync client reads the video imagery and KLV metadata sub-streams and uses them to georegister the imagery towards the reference data. The result from the Raptor Sync client is a new MPEG-TS, which is a copy of the input MPEG-TS with the addition of one or two new sub-streams related to the georegistration.

Input

  • h.262 or h.264 video
  • MISB 0601 KLV LDS stream (camera metadata)
  • Other streams (e.g. audio)

Output

  • h.262 or h.264 video (unmodified)
  • MISB 0601 KLV LDS stream (georegistered metadata, klv-registered)
  • Other streams (unmodified, misc-original)
  • MISB 0601 KLV LDS stream (unmodified, klv-original)
  • VSM stream (proprietary camera metadata, vsm-registered)

Command: register​

Use the raptor_sync_client register command to georegister a video stream to one or more Vivid Terrain 3D Surface Model reference datasets.

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

Usage pattern for register​

raptor_sync_client register [--config PATH_TO_CONFIG_FILE] --in.source INPUT_SOURCE [--in.klv_stream_id KLV_STREAM_ID] [--out.types ts-file|ts-udp] [--out.dir OUTPUT_DIRECTORY] [--out.basename BASENAME] [--out.ts.url OUTPUT_TS_URL] [--out.ts.streams klv-original|klv-registered|vsm-registered|misc-original...] [--server.url VIDEO_SERVER] [--server.references PATH_TO_DATASET_FILE...] [--server.inline-image] [--server.downsample-image] [--log.level error|warning|info|debug] [--out.overwrite]
OptionParameterDescription
-c, --config (optional)PATH_TO_CONFIG_FILESpecify a JSON configuration file with parameter values. If no configuration file has been specified, only command line options will be used.
--in.source (mandatory)INPUT_SOURCESpecify the .ts file or UDP stream (udp://<IP>:<PORT>) to georegister.
--in.klv_stream_id (optional)KLV_STREAM_IDSpecify id of klv stream to use. Default value (-1) results in the klv stream found first being used.
--out.types (optional)ts-file ts-udpSpecify the desired output stream type. Only one output type at a time is supported. Defaults to ts-file.
--out.basename (optional)BASENAMEBasename of output files. Defaults to input video name if INPUT_SOURCE is a .ts file. Name suffixes for generated files are appended to the basename. E.g., --out.basename myBasename generates the TS file myBasename_registered.ts.
--out.dir (optional)OUTPUT_DIRECTORYPath to output directory (location of generated files). Defaults to the current directory.
--out.overwrite (optional)n/aOverwrite the target files if they already exist. By default, existing files will not be overwritten.
--out.ts.url (conditionally mandatory)OUTPUT_TS_URLOutput UDP stream (udp://<IP>:<PORT>). Required if ts-udp is set as output type.
--out.ts.streams (optional)klv-registered|klv-original|vsm-registered|misc-originalSpecify TS streams to include in the output. Defaults to klv-registered klv-original.
--server.url (optional)VIDEO_SERVERAddress of running Raptor Sync server to connect to (tcp://<IP>:<PORT>) or the file system path to a Raptor Sync server binary. Defaults to a Raptor Sync server binary located next to the client binary.
--server.references (conditionally mandatory)PATH_TO_DATASET_FILEA 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. Required if starting a Raptor Sync server.
--server.inline-image (optional)n/aSend frame image data from client to server over TCP. If false, images will be passed as temporary files. Defaults to false.
--server.downsample-image (optional)n/aDownsample frame image before sending to the server. Defaults to false.
--log.level (optional)error|warning|info|debugLog 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.

Options for command register

Client configuration file​

Pass options to the register command via a JSON-formatted configuration file using the --config option. The option names follow the JSON object structure. For instance, the option --out.dir will get its value from the dir 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 two examples of configuration files and their equivalent command lines.

Connecting to a running Raptor Sync Server, with TS UDP input and output:​
raptor_sync_client register --in.source udp://127.0.0.1:8888 --out.types ts-udp --out.ts.url udp://127.0.0.1:8889 --server.url tcp://127.0.0.1:34567
{
  "in": {
    "source": "udp://127.0.0.1:8888"
  },
  "out": {
    "types": ["ts-udp"],
    "ts": {
      "url": "udp://127.0.0.1:8889"
    }
  },
  "server": {
    "url": "tcp://127.0.0.1:34567"
  }
}
Starting a Raptor Sync Server and georegistering a TS file:​
raptor_sync_client register --in.source path/to/video.ts --out.types ts-file --out.dir path/to/output/directory/ --out.basename sequence01 --server.url path/to/raptor_sync_server --server.references path/to/reference1.r3db path/to/reference2.r3db --out.overwrite
{
  "in": {
    "source": "path/to/video.ts"
  },
  "out": {
    "types": ["ts-file"],
    "dir": "path/to/output/directory/",
    "basename": "sequence01",
    "overwrite": true
  },
  "server": {
    "url": "path/to/raptor_sync_server",
    "references": ["path/to/reference1.r3db", "path/to/reference2.r3db"]
  }
}