// Sensor definitions for CAP Protocol
// Version: 1.0.0
//
// This module defines sensor specifications including mount types, orientation,
// field of view, and gimbal capabilities. Sensors can be fixed (static FOV) or
// articulated (PTZ, gimbal) with varying degrees of freedom.
syntax = "proto3";
package cap.sensor.v1;
import "common.proto";
// ============================================================================
// Sensor Mount Types
// ============================================================================
// Type of sensor mount determining articulation capabilities
enum SensorMountType {
SENSOR_MOUNT_TYPE_UNSPECIFIED = 0;
// Fixed mount with static field of view relative to platform
// Examples: body-mounted camera, fixed radar array
SENSOR_MOUNT_TYPE_FIXED = 1;
// Pan-Tilt-Zoom capable mount (typically 2-3 DOF)
// Examples: security cameras, observation posts
SENSOR_MOUNT_TYPE_PTZ = 2;
// Full gimbal mount (typically 2-3 DOF with stabilization)
// Examples: UAV camera gimbals, aircraft targeting pods
SENSOR_MOUNT_TYPE_GIMBAL = 3;
// Turret mount (typically 1-2 DOF, heavier duty)
// Examples: vehicle-mounted sensors, naval systems
SENSOR_MOUNT_TYPE_TURRET = 4;
}
// ============================================================================
// Sensor Modality
// ============================================================================
// Sensor modality / imaging type
enum SensorModality {
SENSOR_MODALITY_UNSPECIFIED = 0;
// Electro-Optical (visible light)
SENSOR_MODALITY_EO = 1;
// Infrared / Thermal (general)
SENSOR_MODALITY_IR = 2;
// Mid-Wave Infrared (3-5 micron)
SENSOR_MODALITY_MWIR = 3;
// Long-Wave Infrared (8-14 micron)
SENSOR_MODALITY_LWIR = 4;
// Radar (active RF)
SENSOR_MODALITY_RADAR = 5;
// LiDAR (laser scanning)
SENSOR_MODALITY_LIDAR = 6;
// Synthetic Aperture Radar
SENSOR_MODALITY_SAR = 7;
// Multi-spectral / Hyperspectral
SENSOR_MODALITY_MULTISPECTRAL = 8;
// Acoustic / Sonar
SENSOR_MODALITY_ACOUSTIC = 9;
}
// ============================================================================
// Orientation and Field of View
// ============================================================================
// Sensor orientation relative to platform body frame
//
// Uses standard aerospace convention:
// - Bearing: 0 = forward (nose), 90 = right, 180 = aft, 270 = left
// - Elevation: 0 = level, positive = up, negative = down
// - Roll: 0 = upright, positive = clockwise when looking forward
message SensorOrientation {
// Bearing offset from platform heading (degrees, 0-360)
// 0 = forward, 90 = starboard/right, 180 = aft, 270 = port/left
float bearing_offset_deg = 1;
// Elevation offset from platform level (degrees, -90 to +90)
// 0 = level with platform, positive = above horizon, negative = below
float elevation_offset_deg = 2;
// Roll offset (degrees, -180 to +180)
// 0 = sensor upright, positive = clockwise rotation
float roll_offset_deg = 3;
}
// Sensor field of view specification
message FieldOfView {
// Horizontal field of view (degrees)
// Typical values: 60-90 for wide angle, 10-30 for telephoto
float horizontal_deg = 1;
// Vertical field of view (degrees)
// Usually determined by aspect ratio: vertical = horizontal * (height/width)
float vertical_deg = 2;
// Diagonal field of view (degrees, optional)
// Can be computed from H/V FOV and aspect ratio
float diagonal_deg = 3;
// Maximum detection range (meters, optional)
// Depends on target size and environmental conditions
float max_range_m = 4;
}
// ============================================================================
// Gimbal / PTZ Capabilities
// ============================================================================
// Articulation limits for PTZ, gimbal, or turret mounts
message GimbalLimits {
// Pan range (degrees from center)
// Continuous rotation: -180 to +180 or 0 to 360
float pan_min_deg = 1;
float pan_max_deg = 2;
// Tilt range (degrees from level)
// Negative = down, positive = up
float tilt_min_deg = 3;
float tilt_max_deg = 4;
// Roll range (degrees, for 3-axis gimbals)
float roll_min_deg = 5;
float roll_max_deg = 6;
// Zoom range (multiplier, 1.0 = no zoom)
float zoom_min = 7;
float zoom_max = 8;
// Slew rates (degrees per second)
float pan_rate_max = 9;
float tilt_rate_max = 10;
}
// Current gimbal/PTZ state
message GimbalState {
// Current pan position (degrees from center/forward)
float pan_deg = 1;
// Current tilt position (degrees from level)
float tilt_deg = 2;
// Current roll position (degrees, for 3-axis gimbals)
float roll_deg = 3;
// Current zoom level (multiplier)
float zoom = 4;
// Whether gimbal is actively tracking a target
bool tracking = 5;
// Target being tracked (if tracking == true)
string tracked_target_id = 6;
}
// ============================================================================
// Complete Sensor Specification
// ============================================================================
// Complete sensor specification combining mount, orientation, FOV, and state
message SensorSpec {
// Unique sensor identifier within the platform
// Format: lowercase alphanumeric with hyphens, e.g., "eo-main", "ir-turret"
string sensor_id = 1;
// Human-readable sensor name
// e.g., "Main Electro-Optical Camera", "Forward-Looking IR"
string name = 2;
// Mount type determining articulation capabilities
SensorMountType mount_type = 3;
// Base orientation relative to platform body frame
// For fixed mounts: the permanent orientation
// For articulated mounts: the "home" or default position
SensorOrientation base_orientation = 4;
// Field of view at 1x zoom
FieldOfView field_of_view = 5;
// Sensor modality (EO, IR, radar, etc.)
SensorModality modality = 6;
// Resolution (pixels)
uint32 resolution_width = 7;
uint32 resolution_height = 8;
// Frame rate (frames per second)
float frame_rate_fps = 9;
// Articulation limits (only for PTZ/gimbal/turret mounts)
// Should be null/empty for FIXED mount type
GimbalLimits gimbal_limits = 10;
// Current gimbal state (only for PTZ/gimbal/turret mounts)
// Should be null/empty for FIXED mount type
GimbalState current_state = 11;
// Timestamp of last state update
common.v1.Timestamp updated_at = 12;
}
// ============================================================================
// Sensor Events
// ============================================================================
// Sensor status for health monitoring
enum SensorStatus {
SENSOR_STATUS_UNSPECIFIED = 0;
SENSOR_STATUS_OPERATIONAL = 1; // Normal operation
SENSOR_STATUS_DEGRADED = 2; // Reduced capability
SENSOR_STATUS_CALIBRATING = 3; // Calibration in progress
SENSOR_STATUS_STOWED = 4; // Gimbal stowed/protected
SENSOR_STATUS_OFFLINE = 5; // Not available
}
// Sensor state update message (flows upward with capability advertisements)
message SensorStateUpdate {
// Platform this sensor belongs to
string platform_id = 1;
// Sensor specification with current state
SensorSpec sensor = 2;
// Current operational status
SensorStatus status = 3;
// Timestamp of this update
common.v1.Timestamp timestamp = 4;
}