Server Integration Guide

Introduction

The Raptor Guide Server provides a network-accessible interface to the Raptor Guide SDK for visual pose estimation. This guide covers how to integrate client applications with the Guide Server using either the high-level Python client API or directly via Protocol Buffers API over ZeroMQ.

For detailed SDK concepts, see:

• SDK integration details: integration_guide.md
• Coordinate and attitude conventions: conventions.md
• Protocol specification: guide.proto

Architecture Overview

                                            ┌─────────────────────────────┐
                                            │ Guide Server                │
┌────────────┐  GuideRequest/GuideResponse  │  ├─ Raptor Guide SDK        │
│ Client App │◄────────────────────────────►│  ├─ Maps (.r3db/.3tz)       │
└────────────┘    ZeroMQ REQ/REP + Protobuf │  ├─ Geo Resources           │
                                            │  └─ License                 │
                                            └─────────────────────────────┘

Server Configuration

The server supports JSON configuration. Configuration file locations are searched in order:

1. Explicit --config <path> argument (highest priority)
2. ~/.raptor_guide_server/config.json (user config)
3. /etc/raptor_guide_server/config.json (system config)

Example configuration:

{
  "address": "*",
  "port": 5555,
  "geo_resources": "/path/to/geo/resources",
  "license": "/path/to/RaptorGuide.license",
  "map_dirs": ["/path/to/maps"]
}

Notes:

• Relative paths are resolved relative to the config file's directory
• Guide options (coordinate system, detail levels, etc.) can also be set in the config file under the "guide" key; see integration_guide.md

Server-Specific Options

Option	CLI	Type	Description
address	-a, --address	string	Network bind address (* = all interfaces)
port	-p, --port	integer	TCP port (default: 5555)
geo_resources	--geo-resources	string	Path to geo resources directory
license	--license	string	Path to license file (see license_management_guide.md)
map_paths	--maps	array	Default map files for all guides
map_dirs	--map-dirs	array	Directories to scan for .r3db and .3tz maps

Map Configuration

Maps can be specified via server-side configuration, config.map_paths for explicit paths, or config.map_ids for selection by ID. The server discovers .r3db and .3tz files recursively from map_dirs; clients can query available maps via query_available_maps().

Precedence: map_ids → map_paths → server startup config (error if none available)

Transport Layer and Protocol

The Guide Server uses ZeroMQ with a REQ/REP pattern (ZMQ_REQ client, ZMQ_REP server). Messages are serialized using Protocol Buffers v3. Clients send a GuideRequest with one request field populated; the server responds with a GuideResponse. See guide.proto for complete message definitions.

Available Operations

The server exposes SDK functionality and additional service-specific operations through Protocol Buffer messages.

Operations Summary

SDK Component	Server Request	Server Response	Python Client Method
Guide(...) constructor	GuideInitRequest	GuideInitResponse	initialize_guide()
Guide::updatePose(...)	UpdatePoseRequest	UpdatePoseResponse	update_pose()
Guide::updatePosition(...)	UpdatePositionRequest	UpdatePositionResponse	update_position()
Guide::renderReferenceImage(...)	RenderReferenceImageRequest	RenderReferenceImageResponse	render_reference_image()
Guide::~Guide() destructor	GuideDestroyRequest	GuideDestroyResponse	destroy_guide()
raptor::guide::Config (get)	GetConfigRequest	GetConfigResponse	get_config()
N/A (server-specific)	GetStatusRequest	GetStatusResponse	get_status()
N/A (server-specific)	QueryAvailableMapsRequest	QueryAvailableMapsResponse	query_available_maps()

Core SDK Operations

GuideInit - Create guide instance with maps and image dimensions

• Optionally accepts a Config message to configure per-initialization
• Configuration is applied only for this initialization; server defaults remain unchanged

UpdatePose - Refine pose using image matching

UpdatePosition - Refine position only (no attitude estimation)

RenderReferenceImage - Generate synthetic view from map

DestroyGuide - Clean up guide instance and free resources

Server Management Operations

GetStatus - Get server status, version, and license status

QueryAvailableMaps - Discover maps available on the server

• Returns: List of directories with available .r3db and .3tz maps
• Each map entry includes: map_id, relative_path, and base_dir
• Map IDs can be used with initialize_guide(config) where config.map_ids=[...]

GetConfig - Retrieve server's default configuration

• Note: Returns server startup defaults only; not modified by individual guide initializations
• Note: geo_resource_path is configured server-side only (via CLI or JSON config)

For complete message definitions and field details, see:

• Protocol specification: guide.proto
• SDK integration details: integration_guide.md (quality metrics, confidence thresholds, best practices)
• Coordinate conventions: conventions.md (position/attitude formats, reference frames)

Client Integration

Prerequisites: The Raptor Guide Server should already be installed and running.

Option 1: Python Client API

The Python client provides a high-level, Pythonic interface to the Guide Server.

Installation

Recommendation: Use a virtual environment

# Create a virtual environment
python3 -m venv raptor_guide_env

# Activate it
source raptor_guide_env/bin/activate  # On Linux/macOS

Install client module

pip install raptor_guide_client-0.1.0-py3-none-any.whl

Dependencies: The client requires:

• Python 3.9 or later
• pyzmq (ZeroMQ Python bindings)
• protobuf (Protocol Buffers)

These are automatically installed when you install the client package.

Running the Example

A complete working example is provided in the documentation package under examples/python/guide_client/.

Prerequisites:

• Guide Server must be running and accessible
• Install the client module (see above)
• Install Pillow for image handling: pip install Pillow

Run with default settings:

python example_basic_usage.py

Option 2: Raw Protocol Buffers over ZeroMQ

Use Protocol Buffers directly over ZeroMQ REQ/REP sockets.

Protocol specification: guide.proto (included with the Guide Server)