Skip to main content

Raptor Ace Integrator Guide

This guide enables system integrators to integrate custom drone platforms with Raptor Ace using the Raptor Drone Integration SDK (RDI SDK). It covers plugin development, deployment, testing, and coordinate validation procedures.

Prerequisites​

Operational Requirements​

Ensure intended concept of operations fits within Raptor Ace's operational envelope per product specification.

Hardware & Software​

  • Drone, SDK, camera, and lens meeting Raptor Ace product specification requirements
  • Ground computer meeting Raptor Ace product specification requirements
  • Raptor Ace application and Raptor Drone Integration SDK
  • Camera calibration:
    1. Plugin performs rectification–Provide rectified images according to pinhole camera model, or
    2. Raptor Ace performs rectification–Provide lens parameters:
      • Field of view expressed in pixel units
      • Principal point coordinates in pixel units
      • Distortion parameters (for applicable lens models)

Development & Validation Resources​

  • Skilled software developer experienced in plugin development
  • High-accuracy surveying equipment and qualified personnel for coordinate validation
  • Packaged 3D data covering intended test areas with specified quality requirements
  • Valid regulatory certificates and approvals for drone pilots and test areas

Required Skills for Plugin Development​

  • C/C++ Programming Proficiency–Core development language for plugin implementation
  • Video Streaming Protocols–Understanding of video streaming standards
  • Drone Platform Integration–Experience with drone manufacturer SDKs
  • Computer Vision Fundamentals–Knowledge of camera calibration, lens distortion models, and image processing
  • Debugging and Testing–Experience with debugging tools and methodologies

RDI System Overview​

The RDI system refers to the runtime component within Raptor Ace that loads the plugin, manages its lifecycle, and processes the frames submitted by the plugin.

Four key structures are used for the communication between Raptor Ace and the plugin:

  1. RDI Declaration–Provides Raptor Ace with plugin information and lifecycle functions
  2. RDI Context–Provides plugin with stream information and means to store data across plugin lifetime
  3. RDI Frame–Structure for submitting frame data to Raptor Ace
  4. RDI Functions–API functions for RDI Frame allocation and submission

RDI Plugin Core Responsibilities​

Provide an interface between the Raptor application and the drone platform:

  • Video Stream Acquisition–Capture live video feeds from drone camera and forward to Raptor processing pipeline
  • Lens Model Provision–Supply camera lens model information and calibration parameters to Raptor
  • Timestamp Synchronization–Provide precise image capture timestamps for each video frame
  • Error Handling & Recovery–Manage connection failures, data loss scenarios, and automatic reconnection procedures
  • Performance Optimization–Minimize latency and ensure stable data transmission
  • Configuration Management–Handle drone-specific parameters and camera calibration data

Lens Models and Distortion Correction​

Raptor Ace requires a rectified image according to the pinhole camera model for optimal navigation performance.

Rectification Options​

Option 1: Plugin-Side Rectification (Recommended)

  • Plugin performs undistortion and cropping to achieve pinhole projection
  • Set lens model to "Pinhole" in submitted RDI frame
  • Plugin developer has full control over rectification quality and cropping
  • Camera intrinsics for the rectified pinhole model must still be provided

Option 2: RDI System Rectification

  • RDI system applies undistortion using provided distortion parameters
  • Set lens model to appropriate distorted type (see SDK documentation for supported models)
  • Less control over final image quality and field of view

Required Intrinsic Camera Parameters​

ParameterDescription
Field of viewExpressed in pixel units (fx, fy)
Principal pointExpressed in pixel units (cx, cy)
Distortion parametersRequired for Option 2 only (model-specific, see SDK documentation)

Development Setup & Core Implementation​

What You Need to Build​

  • Output: Shared library (.so) named rdiplugin_<plugin-name>.so
  • API Headers: Provided in SDK (see SDK documentation)
  • Reference: Example plugin included in SDK

Core Implementation Requirements​

  1. Plugin Declaration Structure

    • API version, name, version, description
    • Pointers to three lifecycle functions (initialization, run, shutdown)

  2. Export Function (required)

    • Must export plugin declaration to RDI system
    • See SDK documentation for exact signature and macro

  3. Plugin Responsibilities

    • Connect to drone
    • Decode video frames to supported format
    • Extract metadata
    • Submit RDI Frames to RDI system via API functions

Plugin Lifecycle​

1. Initialization Phase​

Purpose: Establish drone connection, validate stream parameters, and prepare processing resources.

  • Parse URL from stream context
  • Establish connection to drone
  • Initialize video decoder
  • Allocate internal data structures
  • Store state in context user data (persists across lifecycle calls)

Return: Success or error result code

2. Run Phase (Called Repeatedly)​

Purpose: Process and submit frames.

  • Fetch and decode one frame from drone
  • Allocate RDI frame using provided API function
  • Populate frame data:
    • Image data in supported format
    • Lens model and parameters (camera intrinsics, distortion)
    • Timestamp (accurate capture time - critical for tracking!)
  • Submit or drop frame using provided API functions

Return: Success, stream completed, or error result codes

Critical Performance Considerations
  • Timestamps: Must accurately represent image capture time since it is used by the tracking algorithms. Sudden gaps or bursts in timestamps lead to degraded or failed tracking.
  • Processing Time: Raptor Ace runs all tracking algorithms in real time. Excessive processing in the run phase leads to degraded or failed tracking. Keep frame processing minimal and efficient.
  • Frame Drops: Occasional dropped frames are supported. Maintain a healthy stream rate to avoid disrupting tracking continuity.

3. Shutdown Phase​

Purpose: Clean up resources.

  • Close drone connection
  • Free all allocated resources
  • Clean up context user data

Return: Success result code

Build & Deployment​

Build​

  • Use CMake or equivalent build system
  • Build as shared library with proper symbol export

Deployment​

Installation Location: RaptorAce/rdiplugin/rdiplugin_<plugin-name>.so

Place any additional plugin dependencies in the same directory.

Plugin Validation Process​

Plugin Conformance Testing​

Use Raptor Ace's command line tool for plugin conformance validation.

Required flags:

  • --rdiplugintest (path to developed plugin's shared library file)
  • --rditeststream (RTSP address)–required for full stream health testing

For complete conformance testing with active streams, plugin must be in final location: RaptorAce/rdiplugin/ directory.

Example:

./RaptorAce --rdiplugintest=/RaptorAce/rdiplugin/rdiplugin_example.so --rditeststream=rtsp://192.168.1.100:8554/stream

Consult SDK documentation for complete conformance test descriptions.

Full Application Testing​

  • Test initialization, GNSS-denied navigation, and coordinate extraction using complete Raptor Ace application
  • Requires 3D data supplied by Vantor
  • Follow detailed procedures in Raptor Ace User Guide

Validation Requirements​

Perform thorough validation of extracted coordinate points.

Coordinate Systems​

Raptor Ace presents extracted points using a geodetic coordinate system.

The coordinates are expressed as longitude, latitude, and elevation values in the WGS 84 coordinate reference system, specifically the G1674 realization.

Elevation values are referenced to the EGM2008 geoid model. The coordinate epoch of mission is provided with three decimal places of precision.

note

Coordinates extracted in a tectonic deformation zone can have reduced precision. Compare with reference coordinates from surveying to verify accuracy.

Surveying​

Overview​

High-accuracy surveying provides ground truth measurements essential for validating coordinates captured by Raptor Ace. This validation process ensures that extracted 3D points meet specified accuracy requirements and helps identify systematic errors in the capture workflow.

Survey-Grade GNSS Equipment​

Modern GNSS receivers can achieve centimeter-level accuracy under optimal conditions. These systems use:

  • Base and rover configurations if using differential processing
  • Multiple constellation support (GPS, GLONASS, Galileo, BeiDou)
  • Carrier phase measurements for high precision positioning

Measurement Best Practices​

  • Perform multiple measurements of the same point with temporal separation for geometric independence (e.g., with few hours delay or with different satellite configurations)
  • Be aware that objects obstructing direct view between surveying equipment and satellites (e.g., buildings, trees) can affect reference coordinate quality
note

Consult a professional surveyor for reference measurements. Using high-quality equipment alone does not guarantee precise coordinates.

Validation Methodology​

Control Point Establishment​

Survey-grade equipment establishes known control points throughout the area of interest. These points serve as reference benchmarks with precisely determined coordinates.

Target Placement​

Clearly identifiable targets (survey markers, painted crosses, or retroreflective targets) are positioned at control points to ensure visibility in captured imagery.

Raptor Ace Coordinate Validation​

When validating coordinates extracted by Raptor Ace, select the same control point locations within the Raptor Ace interface and extract their coordinates.

Raptor Ace presents coordinates in WGS 84 G1674 with EGM2008 elevation reference. Survey measurements must be transformed to the same coordinate system and datum for direct comparison.

note

Consult a geodesist to ensure accurate coordinate transformations. Negligent or incorrect transformations can introduce errors of several meters, invalidating the validation process.

Coordinate Comparison​

Extracted coordinates from photogrammetric processing are compared against surveyed control point coordinates to calculate positional accuracy metrics such as Root Mean Square Error (RMSE). Coordinates must be in the same coordinate reference system and epoch for valid comparison.

Validation of Extracted Points​

Purpose​

Verify integration performance to ensure acquired coordinates meet operational accuracy requirements.

Validation Process​

  1. Establish Ground Truth–Obtain reference coordinates using survey-grade GNSS equipment operated by qualified personnel
  2. Extract Test Coordinates–Use Raptor Ace with integrated plugin to extract coordinates from the same control point locations
  3. Coordinate System Alignment–Transform both Raptor Ace and reference coordinates to common coordinate reference system (WGS 84 G1674, EGM2008) at equal epoch
  4. Accuracy Assessment–Compare coordinates and calculate positional accuracy metrics to verify specifications are met
  5. Operational Envelope Testing–Repeat validation across various operational conditions including different zoom levels, slant angles, and lighting conditions

Key Considerations​

  • Coordinate accuracy is limited by the weakest component in the imaging chain (camera quality, image resolution, environmental conditions)
  • Use clearly identifiable targets at control points for consistent measurement between survey and extraction methods

References​