Eve library

@oya/core API Reference

Guide

Revision 1

On this page

Version: 0.1.0

This document provides a comprehensive reference for the @oya/core package, the foundation library of the Oya drone platform. It covers every public type, interface, class, function, constant, and enum exported by the library.


Table of Contents#

  1. Installation and Setup
  2. Branded ID Types
  3. 3D Math Types
  4. Coordinate Types
  5. Enumerations
  6. Composite Types (Schemas)
  7. Constants
  8. Coordinate Transforms
  9. Validation
  10. Math Utilities
  11. Kinematics and Dynamics
  12. Error System
  13. Attitude Control
  14. Velocity and Position Control
  15. Mission Execution
  16. GPS Navigation
  17. Indoor Positioning
  18. Visual SLAM
  19. Path Planning
  20. Obstacle Avoidance
  21. Swarm Coordination
  22. Swarm Collision Avoidance
  23. Formation Flying
  24. Task Allocation
  25. Consensus Algorithms
  26. Inter-Drone Communication
  27. Shot Planning (Cinematography)
  28. Subject Tracking
  29. Cinematography Trajectory
  30. Multi-Camera Coordination
  31. Gimbal Control
  32. Video Streaming
  33. Camera Systems
  34. Depth Sensors
  35. LiDAR Integration
  36. IMU Orientation
  37. Audio Systems
  38. Multi-Sensor Fusion
  39. Pose Detection 2D
  40. Body Reconstruction 3D
  41. Multi-View Fusion
  42. Temporal Tracking
  43. Form Analysis
  44. DJI SDK Integration
  45. PX4 Autopilot Integration
  46. ArduPilot Integration
  47. MAVLink Protocol
  48. Generic Hardware Abstraction
  49. Model Inference (Edge AI)
  50. Model Optimization
  51. Pretrained Models
  52. Edge Deployment
  53. Simulation (Gazebo)
  54. Simulation (AirSim)
  55. API Versioning
  56. Rate Limits and Quotas
  57. Authentication
  58. WebSocket Protocol
  59. Error Codes

Installation and Setup#

bash
pnpm add @oya/core

Import from the barrel export:

typescript
import {
  Position3D,
  DroneState,
  FlightMode,
  haversineDistance,
  TelemetrySchema,
} from '@oya/core';

The package uses Zod for runtime schema validation. All composite types export both a Schema object (for validation) and a TypeScript type (for static typing).


Branded ID Types#

Branded types prevent accidental mixing of identifiers. A DroneId cannot be used where a MissionId is expected, even though both are strings at runtime.

DroneId#

typescript
type DroneId = string & { readonly __brand: 'DroneId' };

UUID v4 string identifying a specific drone.

SwarmId#

typescript
type SwarmId = string & { readonly __brand: 'SwarmId' };

UUID v4 string identifying a swarm group.

MissionId#

typescript
type MissionId = string & { readonly __brand: 'MissionId' };

UUID v4 string identifying a mission.

WaypointId#

typescript
type WaypointId = string & { readonly __brand: 'WaypointId' };

UUID v4 string identifying a waypoint.

Validation Schemas#

Each ID type has a corresponding Zod schema that validates UUID v4 format:

typescript
import { DroneIdSchema, MissionIdSchema } from '@oya/core';

const result = DroneIdSchema.safeParse('550e8400-e29b-41d4-a716-446655440000');
if (result.success) {
  const droneId: DroneId = result.data;
}
Schema Validates
DroneIdSchema UUID v4 DroneId
SwarmIdSchema UUID v4 SwarmId
MissionIdSchema UUID v4 MissionId
WaypointIdSchema UUID v4 WaypointId

3D Math Types#

Position3D#

Geodetic coordinates in the WGS84 datum.

typescript
interface Position3D {
  latitude: number; // -90 to 90 decimal degrees
  longitude: number; // -180 to 180 decimal degrees
  altitude: number; // meters above mean sea level
}

Schema: Position3DSchema

Velocity3D#

3D velocity vector in the local NED frame.

typescript
interface Velocity3D {
  vx: number; // m/s along X axis
  vy: number; // m/s along Y axis
  vz: number; // m/s along Z axis
}

Schema: Velocity3DSchema

Acceleration3D#

3D acceleration vector.

typescript
interface Acceleration3D {
  ax: number; // m/s^2 along X axis
  ay: number; // m/s^2 along Y axis
  az: number; // m/s^2 along Z axis
}

Schema: Acceleration3DSchema

Orientation#

Euler angles using the Tait-Bryan convention (ZYX intrinsic).

typescript
interface Orientation {
  roll: number; // radians, -PI to PI
  pitch: number; // radians, -PI/2 to PI/2
  yaw: number; // radians, -PI to PI
}

Schema: OrientationSchema

Quaternion#

Unit quaternion for rotation representation.

typescript
interface Quaternion {
  w: number; // scalar component, -1 to 1
  x: number; // vector X, -1 to 1
  y: number; // vector Y, -1 to 1
  z: number; // vector Z, -1 to 1
}

The schema enforces unit-quaternion normalization (norm approximately 1 within 0.01 tolerance).

Schema: QuaternionSchema

EulerAngles#

Alias for Orientation. Use when emphasizing angle representation.

Schema: EulerAnglesSchema


Coordinate Types#

GPSCoordinates#

WGS84 geodetic coordinates. Identical structure to Position3D but semantically distinct.

typescript
interface GPSCoordinates {
  latitude: number; // -90 to 90
  longitude: number; // -180 to 180
  altitude: number; // meters MSL
}

Schema: GPSCoordinatesSchema

LocalCoordinates#

North-East-Down (NED) local tangent plane coordinates relative to an origin.

typescript
interface LocalCoordinates {
  north: number; // meters, positive = north
  east: number; // meters, positive = east
  down: number; // meters, positive = below origin
}

Schema: LocalCoordinatesSchema

BodyCoordinates#

Body-frame coordinates relative to the drone's center of mass.

typescript
interface BodyCoordinates {
  forward: number; // meters, positive = forward
  right: number; // meters, positive = starboard
  down: number; // meters, positive = below
}

Schema: BodyCoordinatesSchema


Enumerations#

FlightMode#

Flight control modes available on the autopilot.

Value Description
Manual Full manual control, no stabilization
Stabilized Attitude stabilized, throttle manual
Altitude Altitude hold, horizontal manual
Position Full position hold
Mission Autonomous mission execution
ReturnToHome Autonomous return to launch/home point
Land Autonomous landing
Loiter Hold position and altitude (circle)
Guided External guided control (companion computer)
Acro Acrobatic mode, no angle limits

DroneState#

Operational lifecycle states.

Value Description
Idle Powered on but inactive
Preflight Running preflight checks
Armed Motors armed, ready for takeoff
TakingOff In the process of taking off
Flying Active flight between waypoints
Hovering Holding position in the air
Landing In the process of landing
Landed On the ground after landing
Emergency Emergency state, executing procedure
Disarmed Motors disarmed

ConnectionStatus#

Communication link states.

Value Description
Disconnected No connection established
Connecting Connection attempt in progress
Connected Connection established and active
Reconnecting Lost, attempting to reconnect
Lost Lost, cannot reconnect
Error Connection error

AirspaceClass#

ICAO airspace classification.

Value Description
A IFR only, ATC clearance required
B IFR/VFR, ATC clearance required
C IFR/VFR, ATC service
D IFR/VFR, ATC service
E IFR/VFR, ATC service for IFR
G Uncontrolled airspace
Restricted Hazardous activities
Prohibited Flight not permitted
Danger Potential hazard
TemporaryFlightRestriction TFR

GimbalMode#

Value Description
Free Moves freely based on operator input
Follow Follows the drone's heading
Lock Locks onto a target/direction
FPV First-person view, follows attitude

GeofenceBehavior#

Action taken when a geofence is breached.

Value Description
Warn Issue warning alert
ReturnToHome Autonomously return home
Land Land immediately
Stop Stop movement and hover

GeofenceType#

Value Description
Circle Defined by center and radius
Polygon Defined by vertices (minimum 3)

EmergencyType#

Value Description
ReturnToHome Return to launch/home point
Land Land immediately at current pos
Hover Hover in place
MotorKill Kill motors immediately (last res)

FlightPlanStatus#

Value Description
Draft Created but not reviewed
Approved Reviewed and approved
Active Currently being executed
Completed Execution completed
Cancelled Cancelled before completion
Failed Failed during execution

WaypointAction#

Actions that can be executed at a waypoint.

Value Description
TakePhoto Capture a photograph
StartVideo Start video recording
StopVideo Stop video recording
SetGimbal Set gimbal angle
ChangeSpeed Change flight speed
ChangeAltitude Change altitude
Hover Hover for a duration
OrbitPOI Orbit point of interest

WeatherResistance#

Value Description
None No weather protection
Light Light rain/drizzle capable
Moderate Moderate rain and wind capable
Heavy Heavy weather capable (IP rated)
AllWeather All-weather capable

Composite Types (Schemas)#

Every composite type is defined as a Zod schema with a corresponding TypeScript type alias. Use the schema for runtime validation and the type for compile-time checking.

BatteryState#

typescript
interface BatteryState {
  voltage: number; // volts, >= 0
  current: number; // amps (negative = charging)
  percentage: number; // 0-100
  temperatureCelsius: number; // -40 to 85
  cellCount: number; // integer, 1-14
  timeRemainingSeconds: number; // >= 0
  isCharging: boolean;
  cycleCount: number; // integer, >= 0
}

Schema: BatteryStateSchema

Telemetry#

Complete telemetry snapshot from a drone at a single point in time.

typescript
interface Telemetry {
  droneId: DroneId;
  timestamp: string; // ISO 8601 datetime
  position: Position3D;
  velocity: Velocity3D;
  acceleration: Acceleration3D;
  orientation: Orientation;
  batteryState: BatteryState;
  gpsCoordinates: GPSCoordinates;
  signalStrength: number; // dBm, -120 to 0
  satellites: number; // integer, 0-50
  flightMode: FlightMode;
  droneState: DroneState;
  connectionStatus: ConnectionStatus;
}

Schema: TelemetrySchema

Example:

typescript
import { TelemetrySchema, type Telemetry } from '@oya/core';

const rawData = await receiveTelemetry();
const result = TelemetrySchema.safeParse(rawData);
if (result.success) {
  const telemetry: Telemetry = result.data;
  console.log(`Drone ${telemetry.droneId} at ${telemetry.position.altitude}m`);
}

DroneCapabilities#

Hardware and software capability descriptor.

typescript
interface DroneCapabilities {
  maxSpeed: number; // m/s
  maxAltitude: number; // meters MSL
  maxFlightTime: number; // minutes
  hasCamera: boolean;
  hasGimbal: boolean;
  hasRTK: boolean;
  hasThermal: boolean;
  hasLidar: boolean;
  maxPayloadGrams: number;
  obstacleAvoidance: boolean;
  weatherResistance: WeatherResistance;
}

Schema: DroneCapabilitiesSchema

CameraSettings#

typescript
interface CameraSettings {
  resolution: string; // e.g., "3840x2160"
  fps: number; // 1-240
  codec: string; // e.g., "H.264", "H.265", "ProRes"
  fov: number; // degrees, 0-360
  whiteBalance: number; // Kelvin (0 = auto)
  iso: number; // 0-102400 (0 = auto)
  shutterSpeed: number; // fraction denominator (0 = auto)
  format: string; // e.g., "JPEG", "RAW", "MP4"
}

Schema: CameraSettingsSchema

GimbalState#

typescript
interface GimbalState {
  pan: number; // degrees, -180 to 180
  tilt: number; // degrees, -90 to 90
  roll: number; // degrees, -45 to 45
  mode: GimbalMode;
}

Schema: GimbalStateSchema

PayloadInfo#

typescript
interface PayloadInfo {
  id: string;
  name: string;
  type: string; // "Camera", "Sensor", "Delivery", "Sprayer"
  weightGrams: number; // >= 0
  isActive: boolean;
}

Schema: PayloadInfoSchema

WeatherConditions#

typescript
interface WeatherConditions {
  windSpeedMs: number; // m/s, >= 0
  windDirection: number; // degrees 0-360, 0 = North
  temperatureCelsius: number; // -60 to 60
  humidity: number; // 0-100 percentage
  pressure: number; // hPa, 870-1084
  visibility: number; // meters, >= 0
  precipitation: string; // "None", "Rain", "Snow", "Hail"
}

Schema: WeatherConditionsSchema

GeofenceZone#

typescript
interface GeofenceZone {
  id: string;
  name: string;
  type: GeofenceType;
  center?: GPSCoordinates; // for Circle type
  radius?: number; // meters, for Circle type
  vertices?: GPSCoordinates[]; // min 3, for Polygon type
  minAltitude: number; // meters
  maxAltitude: number; // meters
  behavior: GeofenceBehavior;
}

Schema: GeofenceZoneSchema

Waypoint#

typescript
interface Waypoint {
  id: WaypointId;
  position: GPSCoordinates;
  speed: number; // m/s, >= 0
  heading: number; // degrees 0-360
  holdTimeSeconds: number; // seconds, >= 0
  actions: WaypointActionEntry[];
  radius: number; // acceptance radius in meters
}

Schema: WaypointSchema

WaypointActionEntry#

typescript
interface WaypointActionEntry {
  action: WaypointAction;
  params?: Record<string, unknown>;
}

Schema: WaypointActionEntrySchema

Mission#

A complete mission containing waypoints, constraints, and metadata.

typescript
interface Mission {
  id: MissionId;
  name: string; // min 1 character
  waypoints: Waypoint[]; // min 1 waypoint
  constraints: MissionConstraints;
  metadata: MissionMetadata;
  estimatedDuration: number; // seconds
  totalDistance: number; // meters
}

Schema: MissionSchema

MissionConstraints#

typescript
interface MissionConstraints {
  maxAltitude: number; // meters
  minAltitude: number; // meters
  maxSpeed: number; // m/s
  minBatteryPercent: number; // 0-100
  maxWindSpeed: number; // m/s
  allowedAirspace: AirspaceClass[];
}

Schema: MissionConstraintsSchema

MissionMetadata#

typescript
interface MissionMetadata {
  createdBy: string;
  createdAt: string; // ISO 8601
  updatedAt: string; // ISO 8601
  description: string;
  tags: string[];
}

Schema: MissionMetadataSchema

FlightPlan#

Links a mission to a specific drone, including weather and airspace checks.

typescript
interface FlightPlan {
  id: string;
  missionId: MissionId;
  droneId: DroneId;
  plannedAt: string; // ISO 8601
  estimatedStartTime: string; // ISO 8601
  estimatedEndTime: string; // ISO 8601
  weatherCheck: {
    passed: boolean;
    conditions?: WeatherConditions;
    warnings: string[];
  };
  airspaceCheck: {
    passed: boolean;
    airspaceClass?: AirspaceClass;
    authorization?: string;
    warnings: string[];
  };
  status: FlightPlanStatus;
}

Schema: FlightPlanSchema

EmergencyProcedure#

typescript
interface EmergencyProcedure {
  type: EmergencyType;
  priority: number; // 1 (highest) to 10
  conditions: string[]; // trigger conditions
  altitudeLimit: number; // meters, 0 = no limit
}

Schema: EmergencyProcedureSchema


Constants#

WGS84 Ellipsoid#

Constant Value Description
WGS84_A 6378137.0 Semi-major axis (m)
WGS84_B 6356752.314245 Semi-minor axis (m)
WGS84_E First eccentricity
WGS84_E2 First eccentricity squared
WGS84_F Flattening
WGS84_INVERSE_F 298.257223563 Inverse flattening

Physical Constants#

Constant Value Unit
STANDARD_GRAVITY 9.80665 m/s^2
EARTH_MEAN_RADIUS 6371000 m
EARTH_EQUATORIAL_RADIUS 6378137 m
EARTH_POLAR_RADIUS 6356752 m
SPEED_OF_SOUND_SEA_LEVEL 343.2 m/s

Atmospheric Model#

Constant Description
AIR_DENSITY_SEA_LEVEL kg/m^3 at sea level
STANDARD_PRESSURE_SEA_LEVEL Pa at sea level
STANDARD_TEMPERATURE_SEA_LEVEL K at sea level
TEMPERATURE_LAPSE_RATE K/m
TROPOPAUSE_ALTITUDE m
DRY_AIR_GAS_CONSTANT J/(kg*K)
DRY_AIR_SPECIFIC_HEAT_RATIO dimensionless
DRY_AIR_MOLAR_MASS kg/mol
UNIVERSAL_GAS_CONSTANT J/(mol*K)

Functions:

typescript
airDensityAtAltitude(altitudeM: number): number;
atmosphericPressureAtAltitude(altitudeM: number): number;
temperatureAtAltitude(altitudeM: number): number;

Drone Classification#

typescript
enum DroneClass {
  /* consumer, professional, industrial, military */
}

MAX_WIND_SPEED_BY_CLASS maps each drone class to its maximum operable wind speed.

Regulatory Constants#

Constant Value Description
FAA_MAX_ALTITUDE_AGL_FT 400 FAA max AGL (feet)
FAA_MAX_ALTITUDE_AGL_M ~122 FAA max AGL (meters)

Battery Thresholds#

Constant Description
BATTERY_CRITICAL_PERCENT Emergency landing threshold
BATTERY_LOW_PERCENT Return-to-home threshold
BATTERY_WARNING_PERCENT Warning alert threshold
BATTERY_MAX_TEMP_CELSIUS Max safe temperature
BATTERY_MIN_TEMP_CELSIUS Min safe temperature
BATTERY_MIN_CELL_VOLTAGE Minimum safe cell voltage
BATTERY_NOMINAL_CELL_VOLTAGE Nominal cell voltage
BATTERY_FULL_CELL_VOLTAGE Fully charged cell voltage

Battery chemistry profiles: BATTERY_LIPO, BATTERY_LION, BATTERY_LIHV

PID Defaults#

typescript
interface PIDGains {
  kp: number;
  ki: number;
  kd: number;
}
interface DronePIDProfile {
  roll: PIDGains;
  pitch: PIDGains;
  yaw: PIDGains;
  altitude: PIDGains;
}

PID_DEFAULTS provides sensible starting values.

Telemetry Intervals#

Constant Description
TELEMETRY_INTERVAL_HIGH_FREQ_MS High-rate telemetry (ms)
TELEMETRY_INTERVAL_MED_FREQ_MS Medium-rate telemetry (ms)
TELEMETRY_INTERVAL_LOW_FREQ_MS Low-rate telemetry (ms)
TELEMETRY_INTERVAL_GPS_MS GPS update interval (ms)
TELEMETRY_HEARTBEAT_INTERVAL_MS Heartbeat interval (ms)
TELEMETRY_HEARTBEAT_TIMEOUT_MS Heartbeat timeout (ms)
Constant Description
DEFAULT_WAYPOINT_RADIUS Acceptance radius for waypoints
DEFAULT_LOITER_RADIUS Default loiter circle radius
DEFAULT_CRUISE_SPEED Default cruise speed m/s
DEFAULT_LANDING_SPEED Default landing speed m/s
DEFAULT_TAKEOFF_SPEED Default takeoff speed m/s
DEFAULT_RTH_ALTITUDE Default RTH altitude m
MIN_SAFE_AGL Minimum safe above-ground m

Communication#

Constant Description
GCS_SYSTEM_ID Ground Control Station ID
GCS_COMPONENT_ID GCS Component ID
DEFAULT_DRONE_SYSTEM_ID Default drone system ID
MAX_SWARM_SIZE Maximum drones per swarm

Coordinate Transforms#

Angle Utilities#

typescript
degreesToRadians(degrees: number): number;
radiansToDegrees(radians: number): number;
normalizeAngle(radians: number): number; // normalizes to [-PI, PI]

GPS to NED Conversion#

typescript
gpsToLocal(
  point: GPSCoordinates,
  origin: GPSCoordinates
): LocalCoordinates;

localToGps(
  local: LocalCoordinates,
  origin: GPSCoordinates
): GPSCoordinates;

Converts between WGS84 geodetic coordinates and North-East-Down local tangent plane coordinates. The origin parameter defines the tangent point.

Example:

typescript
import { gpsToLocal, localToGps } from '@oya/core';

const homePos = { latitude: 37.7749, longitude: -122.4194, altitude: 0 };
const dronePos = { latitude: 37.776, longitude: -122.418, altitude: 50 };

const ned = gpsToLocal(dronePos, homePos);
console.log(`North: ${ned.north}m, East: ${ned.east}m, Down: ${ned.down}m`);

const backToGps = localToGps(ned, homePos);

NED to Body Frame#

typescript
localToBody(
  local: LocalCoordinates,
  orientation: Orientation
): BodyCoordinates;

bodyToLocal(
  body: BodyCoordinates,
  orientation: Orientation
): LocalCoordinates;

Rotates vectors between the NED frame and the drone's body frame.

Quaternion / Euler Conversion#

typescript
quaternionToEuler(q: Quaternion): Orientation;
eulerToQuaternion(euler: Orientation): Quaternion;

Distance and Bearing#

typescript
haversineDistance(a: GPSCoordinates, b: GPSCoordinates): number;
// Returns distance in meters using the Haversine formula

distance3D(a: Position3D, b: Position3D): number;
// Euclidean 3D distance

bearing(from: GPSCoordinates, to: GPSCoordinates): number;
// Returns bearing in radians from north

destinationPoint(
  from: GPSCoordinates,
  bearing: number,
  distance: number
): GPSCoordinates;
// Computes a destination point given a start, bearing, and distance

Example:

typescript
import { haversineDistance, bearing } from '@oya/core';

const a = { latitude: 37.7749, longitude: -122.4194, altitude: 0 };
const b = { latitude: 37.7849, longitude: -122.4094, altitude: 0 };

const dist = haversineDistance(a, b);
const brg = bearing(a, b);
console.log(`Distance: ${dist.toFixed(1)}m, Bearing: ${brg.toFixed(4)} rad`);

Validation#

typescript
validateGPSCoordinates(coords: GPSCoordinates): ValidationResult;
validateBatteryState(battery: BatteryState): ValidationResult;
validateFlightPlan(plan: FlightPlan): ValidationResult;
validateGeofence(zone: GeofenceZone): ValidationResult;
isWithinGeofence(position: GPSCoordinates, zone: GeofenceZone): boolean;
validateMission(mission: Mission): ValidationResult;

Each validation function returns a result indicating success or a list of validation errors. isWithinGeofence is a pure boolean check.


Math Utilities#

Vincenty Distance#

typescript
vincentyDistance(a: GPSCoordinates, b: GPSCoordinates): number;

High-precision geodesic distance using the Vincenty inverse formula. More accurate than Haversine for long distances.

Rotation Matrices#

typescript
type RotationMatrix = number[][]; // 3x3

eulerToRotationMatrix(euler: Orientation): RotationMatrix;
rotationMatrixToEuler(R: RotationMatrix): Orientation;
multiplyRotationMatrices(A: RotationMatrix, B: RotationMatrix): RotationMatrix;
transposeRotationMatrix(R: RotationMatrix): RotationMatrix;
const IDENTITY_MATRIX: RotationMatrix;

Interpolation#

typescript
slerp(a: Quaternion, b: Quaternion, t: number): Quaternion;
// Spherical linear interpolation between quaternions

lerp(a: number, b: number, t: number): number;
inverseLerp(a: number, b: number, value: number): number;
remap(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
clamp(value: number, min: number, max: number): number;

Spline Interpolation#

typescript
cubicSpline(points: number[], t: number): number;
bsplineEval(knots: number[], controlPoints: number[], degree: number, t: number): number;
bsplineEvalND(knots: number[], controlPoints: number[][], degree: number, t: number): number[];
bezierQuadratic(p0: number, p1: number, p2: number, t: number): number;
bezierCubic(p0: number, p1: number, p2: number, p3: number, t: number): number;
bezierCubicND(p0: number[], p1: number[], p2: number[], p3: number[], t: number): number[];

Signal Filters#

typescript
class MovingAverageFilter {
  update(value: number): number;
}
class ExponentialMovingAverageFilter {
  update(value: number): number;
}
class LowPassFilter {
  update(value: number, dt: number): number;
}
class HighPassFilter {
  update(value: number, dt: number): number;
}
class BandPassFilter {
  update(value: number, dt: number): number;
}

Kalman Filters#

typescript
class KalmanFilter {
  predict(dt: number): void;
  update(measurement: number): void;
  getState(): number;
}

class ExtendedKalmanFilter {
  predict(dt: number): void;
  update(measurement: number[]): void;
  getState(): number[];
}

IMU Fusion Filters#

typescript
class ComplementaryFilter {
  update(accel: Vec3, gyro: Vec3, dt: number): Orientation;
}

class MadgwickFilter {
  update(accel: Vec3, gyro: Vec3, mag: Vec3, dt: number): Quaternion;
}

PID Controllers#

typescript
interface PIDConfig {
  kp: number;
  ki: number;
  kd: number;
  minOutput?: number;
  maxOutput?: number;
  integralLimit?: number;
}

class PIDController {
  constructor(config: PIDConfig);
  update(error: number, dt: number): number;
  reset(): void;
}

class CascadedPIDController {
  constructor(outer: PIDConfig, inner: PIDConfig);
  update(outerError: number, innerMeasurement: number, dt: number): number;
}

Geometry Utilities#

typescript
isInsideCircle(point: Vec3, center: Vec3, radius: number): boolean;

interface BoundingBox3D {
  min: Vec3; max: Vec3;
}

createBoundingBox(points: Vec3[]): BoundingBox3D;
isInsideBoundingBox(point: Vec3, box: BoundingBox3D): boolean;
boundingBoxesIntersect(a: BoundingBox3D, b: BoundingBox3D): boolean;
sphereCollision(c1: Vec3, r1: number, c2: Vec3, r2: number): boolean;
pointInSphere(point: Vec3, center: Vec3, radius: number): boolean;

Timestamp Synchronization#

typescript
class TimestampSynchronizer {
  addOffset(remoteTs: number, localTs: number): void;
  toLocal(remoteTs: number): number;
  toRemote(localTs: number): number;
}

Unit Conversions#

typescript
class UnitConversion {
  static metersToFeet(m: number): number;
  static feetToMeters(ft: number): number;
  static knotsToMs(knots: number): number;
  static msToKnots(ms: number): number;
  // ... many more conversions
}

Checksums#

typescript
crc8(data: Uint8Array): number;
crc16(data: Uint8Array): number;
crc32(data: Uint8Array): number;

Rate Limiter and Dead-Band#

typescript
class RateLimiter {
  limit(value: number, dt: number): number;
}
class DeadBandFilter {
  apply(value: number): number;
}

Kinematics and Dynamics#

Vec3 / Quat / Mat3 Helpers#

Low-level math primitives for physics simulation.

typescript
type Vec3 = { x: number; y: number; z: number };
type Quat = { w: number; x: number; y: number; z: number };
type Mat3 = number[][]; // 3x3 matrix

vec3(x: number, y: number, z: number): Vec3;
vec3Zero(): Vec3;
vec3Add(a: Vec3, b: Vec3): Vec3;
vec3Sub(a: Vec3, b: Vec3): Vec3;
vec3Scale(v: Vec3, s: number): Vec3;
vec3Dot(a: Vec3, b: Vec3): number;
vec3Cross(a: Vec3, b: Vec3): Vec3;
vec3Mag(v: Vec3): number;
vec3Normalize(v: Vec3): Vec3;
vec3Negate(v: Vec3): Vec3;

quatIdentity(): Quat;
quatNormalize(q: Quat): Quat;
quatMultiply(a: Quat, b: Quat): Quat;
quatRotateVec3(q: Quat, v: Vec3): Vec3;
quatConjugate(q: Quat): Quat;

RigidBody6DOF#

Full 6-degree-of-freedom rigid body simulation.

typescript
interface RigidBodyState {
  position: Vec3;
  velocity: Vec3;
  orientation: Quat;
  angularVelocity: Vec3;
}

class RigidBody6DOF {
  constructor(mass: number, inertia: Mat3);
  step(force: Vec3, torque: Vec3, dt: number): RigidBodyState;
  getState(): RigidBodyState;
}

MultirotorDynamics#

Multirotor physics model supporting quad, hex, and octorotor configurations.

typescript
interface MotorConfig {
  position: Vec3; // relative to CoG
  direction: number; // +1 CW, -1 CCW
  thrustCoeff: number;
  torqueCoeff: number;
}

interface MultirotorParams {
  mass: number;
  inertia: Mat3;
  motors: MotorConfig[];
  dragCoeff: number;
}

class MultirotorDynamics {
  constructor(params: MultirotorParams);
  step(motorSpeeds: number[], dt: number, wind?: Vec3): RigidBodyState;
}

Factory Functions:

typescript
quadrotorDynamics(mass: number): MultirotorDynamics;
hexarotorDynamics(mass: number): MultirotorDynamics;
octorotorDynamics(mass: number): MultirotorDynamics;
coaxialRotorDynamics(mass: number): MultirotorDynamics;

Motor Mixing Matrices#

typescript
type MixingMatrix = number[][];

xConfigMixingMatrix(): MixingMatrix;     // X-configuration quad
plusConfigMixingMatrix(): MixingMatrix;   // Plus-configuration quad
hConfigMixingMatrix(): MixingMatrix;     // H-configuration quad
customMixingMatrix(motors: MotorConfig[]): MixingMatrix;

Propeller and Aerodynamic Models#

typescript
propellerThrust(rpm: number, diameter: number, pitch: number): number;
propellerTorque(rpm: number, diameter: number, pitch: number): number;
bladeElementThrust(rpm: number, radius: number, chord: number, aoa: number): number;
groundEffectFactor(altitude: number, propRadius: number): number;
ceilingEffectFactor(distToCeiling: number, propRadius: number): number;
propellerWashVelocity(thrust: number, propArea: number, airDensity: number): number;
aerodynamicDrag(velocity: Vec3, dragCoeff: number, area: number, airDensity: number): Vec3;

Wind and Turbulence#

typescript
interface WindDisturbanceResult {
  force: Vec3;
  torque: Vec3;
}
windDisturbance(windVelocity: Vec3, droneVelocity: Vec3, params: object): WindDisturbanceResult;

class DrydenTurbulence {
  step(dt: number): Vec3;
}

function gustResponse(state: DroneStateForGust, gustVelocity: Vec3): GustResponseResult;

Power and Flight Time#

typescript
powerConsumption(throttle: number, voltage: number, current: number): number;
flightTimePrediction(batteryCapacityWh: number, avgPowerW: number): number;
hoverFlightTime(batteryCapacityWh: number, mass: number): number;
thrustToWeightRatio(maxThrust: number, weight: number): number;
hoverThrottle(mass: number, maxThrust: number): number;

Error System#

ErrorSeverity#

typescript
enum ErrorSeverity {
  Info = 'Info',
  Warning = 'Warning',
  Error = 'Error',
  Critical = 'Critical',
  Fatal = 'Fatal',
}

OyaError (Base Class)#

typescript
class OyaError extends Error {
  readonly code: OyaErrorCode;
  readonly severity: ErrorSeverity;
  readonly timestamp: Date;
  readonly droneId?: DroneId;
  serialize(): SerializedOyaError;
}

Specialized Error Classes#

Class Use Case
ConnectionError Network/link failures
AuthenticationError Auth failures
CommandError Command rejected by autopilot
TimeoutError Operation timeout
BatteryError Battery issues (low, overtemp, cell fault)
GPSError GPS failures (no fix, poor accuracy)
IMUError IMU failures (bias, drift)
MotorError Motor failures (stall, overheat)
ESCError ESC failures
CompassError Magnetometer interference/calibration
BarometerError Barometer failures
CameraError Camera system failures
GimbalError Gimbal mechanical/electrical failures
GeofenceViolation Geofence boundary breach
AltitudeLimitError Altitude limit exceeded
SpeedLimitError Speed limit exceeded
CollisionWarning Imminent collision detected
WeatherError Unsafe weather conditions
MissionError Mission planning/execution failures
SwarmError Swarm coordination failures
CommunicationError Inter-drone communication failures
PayloadError Payload issues
RegulatoryError Regulatory compliance issues
EmergencyError Emergency situations

Error Utilities#

typescript
getRecoverySuggestions(error: OyaError): string[];
aggregateSwarmErrors(errors: OyaError[]): SwarmErrorSummary;
formatErrorForLogging(error: OyaError): string;
createErrorTelemetryPayload(error: OyaError): object;

Attitude Control#

CascadedAttitudeController#

Industry-standard cascaded PID architecture: outer angle loop feeds inner rate loop.

typescript
class CascadedAttitudeController {
  constructor(config: AttitudeControlConfig);
  update(
    targetAngle: AngleCommand,
    currentOrientation: Orientation,
    gyroRates: Vec3,
    dt: number
  ): TorqueCommand;
}

QuaternionAttitudeController#

Singularity-free quaternion-based control.

typescript
class QuaternionAttitudeController {
  constructor(gains: { kp: number; kd: number });
  update(
    targetQuat: Quaternion,
    currentQuat: Quaternion,
    gyro: Vec3,
    dt: number
  ): TorqueCommand;
}

SO3GeometricController#

Geometric control on the SO(3) manifold, providing global stability guarantees.

typescript
class SO3GeometricController {
  update(
    Rd: RotationMatrix,
    R: RotationMatrix,
    omega: Vec3,
    omegaD: Vec3,
    dt: number
  ): TorqueCommand;
}

Attitude Estimation#

Class Description
AttitudeEKF Extended Kalman Filter for attitude
AttitudeComplementaryFilter Complementary filter (accel + gyro)
AttitudeMadgwickAHRS Madgwick AHRS with magnetometer
MahonyAHRS Mahony complementary filter
GyroBiasEstimator Online gyro bias estimation
MagnetometerHeadingFusion Mag heading into attitude estimate

Motor Management#

Class Description
MotorSaturationHandler Handles motor saturation/clipping
ControlAllocator Optimal control allocation
MotorFailureDetector Detects motor failures in-flight
MotorFailureCompensator Redistributes after motor failure
PIDAutoTuner Automatic PID gain tuning
GainScheduler Gain scheduling across flight envelope

Velocity and Position Control#

Velocity Controllers#

typescript
class HorizontalVelocityController {
  update(
    targetVel: Vec3,
    currentVel: Vec3,
    dt: number
  ): { roll: number; pitch: number };
}

class VerticalVelocityController {
  update(targetVz: number, currentVz: number, dt: number): number; // thrust
}

class BodyFrameVelocityController {
  /* body-frame control */
}
class EarthFrameVelocityController {
  /* earth-frame control */
}

Velocity Profiles#

Class Description
NormalVelocityProfile Standard flight profile
SportVelocityProfile Aggressive/fast response
CinematicVelocityProfile Smooth, gentle movements
TripodVelocityProfile Very slow, precise movements

Position Controllers#

typescript
class HorizontalPositionController {
  update(targetPos: Vec3, currentPos: Vec3, dt: number): Vec3; // velocity command
}

class VerticalPositionController {
  update(targetAlt: number, currentAlt: number, dt: number): number; // vz command
}

Position Providers#

Class Description
GPSPositionProvider GPS-based position
RTKPositionProvider RTK cm-level precision
VIOPositionProvider Visual-Inertial Odometry position
UWBPositionProvider Ultra-Wideband indoor position
PositionSensorFusion Fuses multiple position sources

Specialized Controllers#

Class Description
LoiterController Hold position (circle)
CircleController Fly in a circle
OrbitController Orbit a point of interest
CableCamController Follow a virtual cable path
AltitudeController Altitude hold with terrain following
GeofencePositionClamp Enforce geofence boundaries

Mission Execution#

MissionUploader#

typescript
class MissionUploader {
  upload(mission: Mission, droneId: DroneId): Promise<MissionUploadStatus>;
}

MissionValidator#

typescript
class MissionValidator {
  validate(mission: Mission): MissionValidationResult;
}

Waypoint Navigation#

Class Description
WaypointSequencer Manages waypoint ordering
WaypointNavigationStateMachine State machine for waypoint nav
WaypointAcceptanceChecker Determines when a waypoint is reached
CurvedWaypointTransition Smooth curved transitions
StraightLineNavigation Straight-line segment navigation
StopAndTurnMode Stop, rotate, then proceed
FlythroughMode Fly through waypoints without stopping
HeadingController Controls heading between waypoints

Mission Generators#

Class Description
SurveyMissionGenerator Grid/lawnmower survey patterns
InspectionMissionGenerator Structural inspection paths
SearchAndRescuePatternGenerator SAR search patterns
MissionTemplateLibrary Reusable mission templates

Return-to-Home#

Class Description
ReturnToHomeController Basic RTH
SmartRTHController Obstacle-aware RTH
RTHAltitudeSelector Optimal RTH altitude selection
RallyPointSystem Alternative landing sites

GPS Navigation#

NMEA and UBX Parsers#

typescript
class NMEAParser {
  parse(sentence: string): NMEAParsedData;
}

class UBXParser {
  parse(buffer: Uint8Array): UBXParsedMessage;
}

RTK and NTRIP#

Class Description
RTKBaseStation RTK base station management
RTKRoverProcessor RTK rover processing
RTCM3Parser RTCM3 correction parsing
NTRIPClient NTRIP caster connection
PPKLogger Post-Processing Kinematic logging

GPS Security#

Class Description
GPSSpoofingDetector Detects GPS spoofing attacks
GPSJammingDetector Detects GPS jamming
GPSHealthMonitor Monitors overall GPS health

GPS-IMU Fusion#

typescript
class LooseCoupledGPSIMU {
  update(
    gps: GPSMeasurement,
    imu: IMUMeasurement,
    dt: number
  ): FusedNavigationState;
}

class TightCoupledGPSIMU {
  update(
    pseudoranges: PseudorangeMeasurement[],
    imu: IMUMeasurement,
    dt: number
  ): FusedNavigationState;
}

Indoor Positioning#

UWB#

Class Description
UWBTWRProtocol Two-Way Ranging
UWBTDoAAlgorithm Time Difference of Arrival
UWBAnchorCalibration Anchor calibration
DWM1001Integration Decawave DWM1001 support
PozyxIntegration Pozyx UWB support
LinkTrackIntegration LinkTrack UWB support
MarvelmindIntegration Marvelmind UWB support
UWBMultipathMitigation Multipath error correction
UWBNLOSDetector Non-line-of-sight detection
UWBIMUFusion UWB + IMU sensor fusion

VIO (Visual-Inertial Odometry)#

Class Description
VIOPipeline Generic VIO pipeline
VINSMonoIntegration VINS-Mono support
VINSFusionIntegration VINS-Fusion support
ROVIOIntegration ROVIO support
OKVISIntegration OKVIS support
RealSenseT265Integration Intel T265 support

Motion Capture#

Class Description
OptiTrackIntegration OptiTrack NatNet
ViconIntegration Vicon DataStream
QualisysIntegration Qualisys Track Manager
VRPNClient VRPN generic tracker client
NatNetClient NatNet SDK client
MocapFrameTransformer Coordinate frame transformations
MocapLatencyCompensator Latency compensation
IndoorOutdoorTransition Seamless indoor/outdoor switching

Visual SLAM#

SLAM System Integrations#

Class Description
ORBSLAMMonoIntegration ORB-SLAM3 monocular
ORBSLAMStereoIntegration ORB-SLAM3 stereo
ORBSLAMRGBDIntegration ORB-SLAM3 RGB-D
ORBSLAMVisualInertialIntegration ORB-SLAM3 VI
RTABMapIntegration RTAB-Map
LSDSLAMIntegration LSD-SLAM
DSOIntegration Direct Sparse Odometry
LDSOIntegration Stereo DSO
IsaacROSVSLAMIntegration NVIDIA Isaac ROS VSLAM

SLAM Components#

Class Description
SLAMMapInitializer Map initialization strategies
KeyframeSelector Keyframe selection heuristics
LoopClosureDetector DBoW2-based loop closure detection
PoseGraphOptimizer g2o-compatible pose graph optimization
BundleAdjuster Local and global bundle adjustment
MapPointCuller Removes unreliable map points
SLAMRelocalizer Re-localization from known maps
SLAMMapSerializer Save/load SLAM maps
SLAMMapMerger Merge maps from multiple sessions

Dense Reconstruction#

Class Description
DenseReconstructor Dense 3D reconstruction
OccupancyGridGenerator 2D/3D occupancy grids
MeshGenerator Triangle mesh from point cloud
SemanticSLAMIntegration Semantic labels in SLAM map
DynamicObjectFilter Filter dynamic objects from map

Path Planning#

Graph-Based Planners#

Class Description
AStarPlanner A* on a 3D grid
WeightedAStarPlanner Weighted A* (faster, suboptimal)
DijkstraPlanner Dijkstra shortest path
DStarLitePlanner D* Lite (incremental replanning)

Sampling-Based Planners#

Class Description
RRTPlanner Rapidly-exploring Random Tree
RRTStarPlanner Asymptotically optimal RRT
RRTConnectPlanner Bidirectional RRT
InformedRRTStarPlanner Informed RRT* (ellipsoidal sampling)
PRMPlanner Probabilistic Roadmap

Potential Fields#

Class Description
PotentialFieldPlanner Artificial potential field
ArtificialPotentialFieldNavigator APF real-time navigation

Velocity Obstacles#

Class Description
VelocityObstacleCalculator VO computation
ReciprocalVelocityObstacles RVO for multi-agent

Trajectory Optimization#

Class Description
CHOMPOptimizer Covariant Hamiltonian optimization
STOMPOptimizer Stochastic trajectory optimization
TrajOptOptimizer Sequential convex optimization
MinimumSnapTrajectory Minimum snap (4th derivative)
MinimumJerkTrajectory Minimum jerk (3rd derivative)
PolynomialTrajectoryOptimizer Polynomial piece-wise optimization
TimeOptimalPlanner Time-optimal path
EnergyOptimalPlanner Energy-optimal path
MPCPathPlanner Model Predictive Control planner

Obstacle Avoidance#

Sensors#

Class Description
DepthCameraDetector Depth camera obstacle detection
StereoVisionDetector Stereo pair depth estimation
MonocularDepthEstimator Monocular depth learning
ToFSensorIntegration Time-of-Flight sensors
UltrasonicSensorIntegration Ultrasonic ranging
LiDARObstacleDetector LiDAR point cloud obstacles
RadarObstacleDetector Radar returns processing
ObstacleSensorFusion Multi-sensor obstacle fusion
SensingCoverage360 360-degree coverage management

Avoidance Maneuvers#

Class Description
AvoidanceManeuverGenerator Generates avoidance commands
VerticalAvoidance Ascend to avoid
LateralAvoidance Lateral dodge
BrakeToHoverAvoidance Emergency stop
FlyAroundAvoidance Fly around obstacle
AscendDescendAvoidance Vertical escape

Specialized Detectors#

Class Description
WireDetector Power line / wire detection
SmallObstacleDetector Small obstacle detection
TransparentSurfaceDetector Glass / transparent surfaces
WaterSurfaceDetector Water surface detection
HumanDetector Human detection and tracking
AnimalDetector Animal detection
VehicleDetector Vehicle detection
AircraftDetector ADS-B and visual aircraft detect

Swarm Coordination#

Core Management#

typescript
class SwarmManager {
  addDrone(drone: SwarmDrone): void;
  removeDrone(id: SwarmDroneId): void;
  getState(): SwarmState;
  broadcast(message: object): void;
}

Coordination Strategies#

Class Description
LeaderFollowerCoordinator Leader-follower architecture
VirtualLeaderCoordinator Virtual leader (no physical leader)
DecentralizedCoordinator Fully decentralized
ConsensusCoordinator Consensus-based coordination
BehaviorBasedCoordinator Behavior-based (Reynolds-like)

Task Assignment#

Class Description
AuctionTaskAssigner Auction-based task assignment
ContractNetProtocol Contract Net Protocol (CNP)
SwarmPrioritySystem Priority management

Swarm Collision Avoidance#

ORCA Family#

Class Description
ORCAComputer 2D ORCA half-planes
ORCA3DComputer 3D ORCA half-spaces
VelocityObstacleComputer Velocity obstacles
ReciprocalVelocityObstacleComputer Reciprocal VO
HRVOComputer Hybrid Reciprocal VO
NHORCAComputer Non-holonomic ORCA
CollisionConeComputer Collision cone computation

Safety#

Class Description
SafeVelocitySelector Select safe velocity from ORCA
DeadlockDetector Detect deadlocks
LivelockPreventer Prevent oscillating avoidance
PriorityCollisionResolver Priority-based resolution
RightOfWaySystem Right-of-way rules
SafetyMarginConfig Configurable safety margins
DynamicSafetyRadius Speed-dependent safety radius
CollisionProbabilityEstimator Monte Carlo collision probability
NearMissLogger Log near-miss events

Formation Flying#

Reynolds Flocking#

typescript
class ReynoldsFlocking {
  constructor(config: FlockingConfig);
  computeSteeringForces(boids: Boid[]): Vec3[];
}

Formation Shapes#

Class Description
LineFormation Linear formation
VFormation V-shaped (geese) formation
CircleFormation Circular formation
GridFormation Grid/matrix formation
TriangleFormation Triangular formation
PolygonFormation Custom polygon formation
Formation3D 3D formations (stacked, sphere, helix)

Formation Operations#

Class Description
FormationScaler Scale formation size
FormationRotator Rotate formation orientation
FormationTranslator Translate formation center
FormationTransitioner Animate between formations
FormationMorpher Smooth morphing with keyframes
PositionAssignmentOptimizer Optimal drone-to-position mapping
HungarianAlgorithm O(n^3) optimal assignment
FormationRepairer Repair formation gaps
FormationSplitter Split formation into sub-groups
FormationMerger Merge sub-groups into one

Task Allocation#

Class Description
CentralizedTaskAllocator Central authority allocation
DistributedTaskAllocator Peer-to-peer allocation
MarketBasedAllocator Market/auction mechanisms
CBBAAllocator Consensus-Based Bundle Algorithm
HungarianTaskAllocator Hungarian algorithm for tasks
GreedyTaskAllocator Greedy nearest-first
GeneticAlgorithmAllocator GA-based optimization
ParticleSwarmAllocator PSO-based optimization
DRLTaskAllocator Deep RL-based allocation

Consensus Algorithms#

Class Description
AverageConsensusProtocol Average consensus
MaxMinConsensusProtocol Max/min consensus
WeightedConsensusProtocol Weighted averaging
FiniteTimeConsensus Finite-time convergence
EventTriggeredConsensus Event-triggered updates
QuantizedConsensus Quantized state consensus
DelayTolerantConsensus Delay-tolerant consensus
PacketLossConsensus Robust to packet loss
RaftConsensusAlgorithm Raft leader election + log replication
LeaderElectionProtocol Leader election
ByzantineFaultTolerance PBFT
GossipProtocol Epidemic gossip dissemination
FederatedLearningArch Federated learning architecture

Inter-Drone Communication#

typescript
class MAVLinkV2Protocol {
  encode(frame: MAVLinkV2Frame): Uint8Array;
  decode(buffer: Uint8Array): MAVLinkV2Frame;
}

class MAVLinkSerializer {
  /* field-level serialization */
}
class MAVLinkRouter {
  /* route messages between vehicles */
}

Transport#

Class Description
UDPBroadcast UDP broadcast transport
UDPMulticast UDP multicast transport
TCPReliable TCP reliable transport

Mesh Networking#

Class Description
MeshNetworkTopology Mesh topology management
AdHocNetworkFormation Ad-hoc network formation
MultiHopRouter Multi-hop routing
AODVRouter AODV reactive routing
OLSRRouter OLSR proactive routing
NetworkPartitionHandler Handle network partitions
NetworkHealingProcedure Automatic network healing

Quality of Service#

Class Description
BandwidthManager Bandwidth allocation
QoSPrioritizer Message priority queuing
MessageCompressor Message compression
MessageAuthenticator HMAC authentication
MessageEncryptor AES encryption

Shot Planning (Cinematography)#

Composition Rules#

Class Description
RuleOfThirdsGrid Rule of thirds scoring
GoldenRatioComposition Golden ratio (phi) scoring
GoldenSpiralFraming Golden spiral placement
CenterWeightedComposition Center-weighted scoring
DynamicSymmetry Dynamic symmetry analysis
LeadingLinesDetector Leading line detection
FrameBalanceAnalyzer Visual balance analysis

Shot Types#

Class Description
ShotSizeClassifier ECU/CU/MCU/MS/MLS/LS/VLS/ELS
ShotAngleClassifier High/low/eye-level/bird/worm
ShotTypeDetector Detects current shot type
EstablishingShotPlanner Plans establishing shots
MasterShotPlanner Plans master shots
CoverageShotPlanner Plans coverage shots
GroupShotPlanner Plans group shots

Film Grammar#

Class Description
Rule180Enforcer 180-degree rule enforcement
Rule30Enforcer 30-degree rule enforcement
EyeLineMatching Eye line matching between shots

Subject Tracking#

Detectors#

Class Description
YOLO11Detector YOLO v11 object detection
YOLOPoseDetector YOLO pose estimation
SSDMobileNetDetector SSD MobileNet detection
FasterRCNNDetector Faster R-CNN detection
FaceDetector Face detection
FaceRecognizer Face recognition / identification
BodyTracker Full body tracking
SkeletonTracker Skeleton/pose tracking

Multi-Object Trackers#

Class Description
MultiObjectTracker Generic multi-object tracker
DeepSORTTracker DeepSORT (appearance + motion)
ByteTracker ByteTrack (high/low confidence)
OCSORTTracker OC-SORT
SORTTracker Simple SORT (Kalman + Hungarian)

Tracking Modes#

Class Description
ActiveTrackMode Active subject following
SpotlightMode Keep subject centered
POIOrbitTracking Orbit while tracking POI
GestureControl Hand gesture drone control
VehicleTrackingMode Vehicle tracking mode

Cinematography Trajectory#

Spline Trajectories#

Class Description
BSplineTrajectory B-spline camera path
BezierTrajectory Bezier curve camera path
CatmullRomTrajectory Catmull-Rom spline (passes thru pts)
NURBSTrajectory NURBS camera path

Cinematic Shot Trajectories#

Class Description
DollyZoomTrajectory Hitchcock dolly zoom
RevealShotTrajectory Reveal shot (pull back)
CraneShotTrajectory Crane shot (vertical arc)
OrbitShotTrajectory Orbital shot
FlybyShotTrajectory Flyby shot
CableCamTrajectory Cable cam (virtual wire)
HelixTrajectory Helical path
DronieShotTrajectory Dronie (selfie pullback)
RocketShotTrajectory Rocket (straight up)
BoomerangShotTrajectory Boomerang (elliptical loop)
AsteroidShotTrajectory Asteroid (orbit + ascend)

Multi-Camera Coordination#

Class Description
MultiDroneShotSequencer Sequence shots across drones
SynchronizedRecordingTrigger Synchronized record start/stop
TimecodeSynchronizer SMPTE timecode sync
GenlockSync Genlock frame sync
CameraMAPF Multi-Agent Path Finding (MAPF)
CoverageOptimizer Maximize scene coverage
BulletTimeCoordinator Bullet-time effect (Matrix)
CameraHandoff Seamless camera handoff
DirectorMode AI director for shot selection
ABCameraAssigner A/B camera role assignment

Gimbal Control#

Class Description
ThreeAxisGimbalController 3-axis PID gimbal control
GimbalFollowMode Follow drone heading
GimbalFPVMode First-person view
GimbalFreeMode Free manual control
GimbalSubjectTrackMode Track subject
GimbalPOILockMode Lock on point of interest
HorizonLeveling Auto horizon leveling
DutchAngleController Dutch angle control
CoordinatedDroneGimbal Coordinated drone + gimbal movement
GimbalVibrationFilter Vibration filtering

Video Streaming#

Encoding#

Class Description
H264EncodingPipeline H.264/AVC encoding
H265EncodingPipeline H.265/HEVC encoding
AV1EncodingPipeline AV1 encoding
AdaptiveBitrateEncoder ABR encoding

Streaming Protocols#

Class Description
RTMPStreamOutput RTMP streaming
RTSPServer RTSP server
WebRTCStreamer WebRTC peer-to-peer
SRTTransport Secure Reliable Transport
HLSGenerator HTTP Live Streaming
DASHGenerator MPEG-DASH
LowLatencyStreamMode Ultra-low latency mode

Camera Systems#

Camera Control#

Class Description
CameraDiscovery Auto-discover connected cameras
ExposureController Auto/manual exposure
ISOGainController ISO sensitivity control
FocusController Auto/manual focus
ZoomController Optical/digital zoom
PhotoCaptureController Photo capture
VideoRecordingController Video recording
StorageManager Storage device management

Thermal and Multispectral#

Class Description
ThermalCameraIntegration Thermal camera support
RadiometricTemperatureReader Radiometric temperature
ThermalVisibleFusion Thermal + visible fusion
MultispectralCameraIntegration Multispectral support
NDVICalculationPipeline NDVI vegetation index

Depth Sensors#

Class Description
RealSenseD435Integration Intel RealSense D435
RealSenseL515Integration Intel RealSense L515
StereoDepthCalculator Stereo depth computation
StereoCalibration Stereo camera calibration
DisparityMapGenerator Disparity map generation
DepthObstacleDetector Depth-based obstacle detection
GroundPlaneDetector Ground plane estimation
CeilingDetector Ceiling detection
WallDetector Wall detection

LiDAR Integration#

Hardware#

Class Description
OusterLiDARIntegration Ouster OS series
VelodyneLiDARIntegration Velodyne VLP/Alpha
LivoxLiDARIntegration Livox Mid/Avia

LiDAR SLAM#

Class Description
LOAMIntegration LiDAR Odometry and Mapping
LeGOLOAMIntegration Lightweight Ground-Optimized LOAM
LIOSAMIntegration LiDAR-Inertial Odometry SLAM
FASTLIOIntegration FAST-LIO direct LiDAR-inertial

Point Cloud Processing#

Class Description
PointCloudAcquisition Acquire point clouds
PointCloudFilter Statistical/radius outlier removal
VoxelGridDownsampler Voxel grid downsampling
ICPRegistration Iterative Closest Point registration
PointCloudAccumulator Accumulate scans into a map
PointCloudCompressor Draco/octree compression

IMU Orientation#

Sensor Acquisition#

Class Description
AccelerometerAcquisition Accelerometer data acquisition
GyroscopeAcquisition Gyroscope data acquisition
MagnetometerAcquisition Magnetometer data acquisition

Sensor Fusion#

Class Description
NineAxisIMUFusion 9-axis (accel + gyro + mag) fusion
SixAxisIMUFusion 6-axis (accel + gyro) fusion
StrapdownINS Strapdown inertial navigation

Calibration#

Class Description
IMUCalibrationProcedure Multi-position calibration
AccelerometerBiasEstimator Accel bias estimation
GyroscopeBiasEstimator Gyro bias estimation
MagnetometerCalibration Hard/soft iron calibration
TemperatureCompensator Temperature drift compensation
AllanVarianceAnalyzer Allan variance noise analysis
ConingScullingCompensator Coning/sculling error correction

Audio Systems#

Class Description
MicrophoneArrayIntegration Mic array setup
BeamformingProcessor Beamforming (delay-and-sum, MVDR)
DOAEstimator Direction of arrival
PropellerNoiseCancel Propeller noise cancellation
WindNoiseFilter Wind noise reduction
VoiceActivityDetector Voice activity detection (VAD)
SpeechEnhancer Speech enhancement
SoundClassifier Sound event classification
GunshotDetector Gunshot detection for security
VoiceCommandRecognizer Voice command recognition
AudioBasedLocalizer Audio-based source localization

Multi-Sensor Fusion#

Class Description
SensorTimeSynchronizer Sensor timestamp synchronization
TemporalAligner Align measurements across sensors
SpatialCalibrator Sensor extrinsic calibration
MultiSensorEKF Extended Kalman Filter fusion
MultiSensorUKF Unscented Kalman Filter fusion
FactorGraphFusion Factor graph optimization
GTSAMIntegration GTSAM library integration
CeresSolverIntegration Google Ceres solver integration
G2OIntegration g2o graph optimization
OutlierRejector Mahalanobis distance outlier test
SensorDegradationDetector Detect sensor quality degradation
SensorFailoverLogic Automatic sensor failover

Pose Detection 2D#

Detector Integrations#

Class Description
MediaPipePoseDetector Google MediaPipe Pose
MediaPipeLandmarker MediaPipe Pose Landmarker
YOLO11PoseDetector YOLO v11 pose
RTMPoseDetector RTMPose (MMPose)
OpenPoseDetector OpenPose (CMU)
HRNetDetector High-Resolution Net
ViTPoseDetector Vision Transformer Pose

Aerial Adaptations#

Class Description
AerialPoseAdapter Adapt ground-trained models to aerial
AltitudePoseScaler Scale keypoints by altitude
ViewpointPoseProcessor Handle aerial viewpoint angles

Body Reconstruction 3D#

Body Models#

Class Description
SMPLBodyModel SMPL parametric body model
SMPLXBodyModel SMPL-X (body + hands + face)
SKELBodyModel SKEL skeletal body model

Reconstruction Pipelines#

Class Description
HMR2Integration Human Mesh Recovery 2.0
FourDHumansIntegration 4D Humans integration
HSMRIntegration HSMR body recovery
ROMPIntegration ROMP multi-person mesh recovery
PyMAFIntegration PyMAF mesh-aligned feedback

Multi-View Fusion#

Class Description
TriangulationFusion Multi-view triangulation
EpipolarConstraints Epipolar geometry constraints
MultiViewCalibrator Multi-camera calibration
KeypointLifter3D 2D to 3D keypoint lifting
JointLevelFusion Joint-level multi-view fusion
PersonLevelFusion Person-level multi-view fusion
CrossViewReID Cross-view person re-identification
VolumetricReconstructor Volumetric 3D reconstruction

DJI SDK Integration#

Key Classes#

Class Description
DJIAppKeyManager App key activation
DJIAircraftConnectionManager Aircraft connection management
DJIFlightControllerAccess Flight controller access
DJIGimbalController Gimbal control
DJICameraController Camera control
DJIVideoFeedManager Video feed management
DJITelemetryStream Telemetry data stream
DJIWaypointMissionEngine Waypoint mission execution
DJIVirtualStickController Virtual stick control
DJIIntelligentFlightModes ActiveTrack, Spotlight, QuickShot
DJIBatteryManager Battery management
DJIRTKService RTK positioning service
DJISDKManager Top-level SDK lifecycle manager

PX4 Autopilot Integration#

Class Description
PX4SITLConnection SITL simulation connection
PX4MAVLinkTransport MAVLink transport layer
PX4OffboardController Offboard flight control
PX4PositionSetpointManager Position setpoint management
PX4VelocitySetpointManager Velocity setpoint management
PX4AttitudeSetpointManager Attitude setpoint management
PX4ParameterAccess Parameter read/write
PX4MissionProtocol Mission upload/download
PX4TelemetryStream Telemetry streaming
PX4ArmingController Arming/disarming
PX4FlightModeManager Flight mode switching
PX4FailsafeConfig Failsafe configuration
PX4GeofenceManager Geofence management
PX4ROS2Bridge PX4-ROS2 bridge (micro-XRCE-DDS)
PX4VTOLTransitionManager VTOL transition management

ArduPilot Integration#

Class Description
APConnectionManager Connection management
APArmingController Arming/disarming
APFlightModeManager Flight mode management
APGuidedModeController Guided mode control
APAutoMissionController Auto mission execution
APParameterManager Parameter management
APTelemetryStream Telemetry streaming
APGeofenceController Geofence management
APTerrainFollowingController Terrain following
APLuaScriptingInterface Lua scripting support
APCompanionComputerInterface Companion computer interface

Class Description
MAVLinkV2Codec Encode/decode MAVLink v2 frames
MAVLinkMessageDictionary Message definition registry
MAVLinkSystemRegistry System/component ID management
MAVLinkHeartbeatManager Heartbeat send/receive
MAVLinkCommandProtocol Command long/int protocol
MAVLinkAckManager Acknowledgment handling
MAVLinkRetransmissionController Automatic retransmission
MAVLinkMessageSigning Message signing (SHA-256)
MAVLinkParameterProtocol Parameter protocol
MAVLinkMissionProtocol Mission item protocol
MAVLinkFTPClient MAVLink FTP file transfer
MAVLinkTransport Serial/UDP/TCP transport

Generic Hardware Abstraction#

Class Description
GenericDroneInterface Platform-agnostic drone interface
MotorController Motor speed control
ESCProtocolHandler DShot/OneShot/PWM ESC protocols
PWMOutputManager PWM channel management
SerialPortManager Serial port communication
SPIBusManager SPI bus device management
I2CBusManager I2C bus device management
CANBusManager CAN bus (DroneCAN/UAVCAN)
GPIOManager GPIO pin management
ADCManager ADC channel reading
BarometerDriver Barometer sensor driver
AirspeedSensor Airspeed sensor driver
RangefinderDriver Rangefinder sensor driver
OpticalFlowSensor Optical flow sensor driver
PowerMonitor Power rail monitoring
LEDController Status LED control
BuzzerController Audio buzzer control
RCInputProcessor RC receiver input processing
TelemetryRadioManager Telemetry radio management

Model Inference (Edge AI)#

Runtimes#

Class Description
TensorRTRuntime NVIDIA TensorRT inference
OnnxRuntimeSession ONNX Runtime inference
TFLiteRuntime TensorFlow Lite inference
OpenVINORuntime Intel OpenVINO inference

Pipeline Components#

Class Description
ModelLoader Load models (ONNX, TRT, TFLite)
InputPreprocessor Image/tensor preprocessing
OutputPostprocessor Detection/classification postprocess
BatchInferenceEngine Batch inference scheduling
AsyncInferencePipeline Async inference with callbacks
NonMaxSuppression NMS for detection results
AnchorGenerator Anchor box generation
InferenceCache Result caching
MultiModelScheduler Multi-model scheduling
ModelVersionManager Model version management

Model Optimization#

Class Description
INT8Quantizer INT8 quantization
FP16Converter FP16 precision conversion
ModelPruner Model weight pruning
KnowledgeDistiller Knowledge distillation
NeuralArchitectureSearch Neural architecture search (NAS)
LayerFusionOptimizer Layer fusion (Conv+BN+ReLU)
GraphOptimizer Computation graph optimization
TensorRTEngineBuilder TensorRT engine building
OptimizationPipeline End-to-end optimization pipeline

Pretrained Models#

Class Description
ModelRegistry Central model registry
ModelDownloadManager Download models with verification
YOLOModelFamily YOLO model variants
EfficientNetMobileNetFamily EfficientNet/MobileNet variants
PoseEstimationModels Pose estimation model catalog
SegmentationModels Segmentation model catalog
DepthEstimationModels Depth estimation model catalog
ModelEnsemble Multi-model ensemble
ModelSwitcher Dynamic model switching
ModelFallbackChain Fallback chain on failure
ModelCatalogAPI Searchable model catalog

Edge Deployment#

Class Description
JetsonNanoDeployment NVIDIA Jetson Nano deployment
JetsonOrinDeployment NVIDIA Jetson Orin deployment
CoralTPUDeployment Google Coral Edge TPU
Hailo8Deployment Hailo-8 AI accelerator
QualcommSNPEDeployment Qualcomm SNPE deployment
DockerContainerPackager Docker container packaging
OTAModelUpdater Over-the-air model updates
HardwareCapabilityDetector Detect hardware capabilities
ThermalThrottleController Thermal throttling management
EdgeCloudHybridInference Edge-cloud split inference
FleetModelManager Fleet-wide model management
CanaryDeploymentManager Canary deployment rollout

Simulation (Gazebo)#

Key Functions#

typescript
createDefaultWorldConfig(): GazeboWorldConfig;
generateWorldSDF(config: GazeboWorldConfig): string;
generateModelSDF(model: SDFModelDescriptor): string;
simulateIMU(dt: number, noise?: SensorNoiseConfig): SimulatedSensorReading;
simulateGPS(position: Position3D, noise?: SensorNoiseConfig): SimulatedSensorReading;
simulateLiDAR(scene: object, config: object): SimulatedSensorReading;
generateTerrainHeightmap(config: TerrainConfig): number[][];

Classes#

Class Description
MultiRobotSimulation Multi-robot simulation manager
SimulationRecorder Record/playback simulation
GazeboPerformanceMonitor Performance monitoring

Simulation (AirSim)#

Key Functions#

typescript
createAirSimVehicle(config: AirSimVehicleConfig): object;
generateVehicleSettings(vehicles: AirSimVehicleConfig[]): string;
captureImage(type: AirSimImageType): AirSimCapturedImage;
simulateSensorBundle(position: Position3D): AirSimSensorBundle;
computeRLReward(observation: RLObservation, action: RLAction): RLStepResult;

Classes#

Class Description
AirSimConnection AirSim API connection
AirSimMultiVehicleManager Multi-vehicle management
AirSimRecorder Recording management

API Versioning#

The @oya/core package follows semantic versioning (SemVer):

  • Major (X.0.0): Breaking changes to public API
  • Minor (0.X.0): New features, backward compatible
  • Patch (0.0.X): Bug fixes, backward compatible

Current version: 0.1.0 (pre-release).

All public exports are considered part of the stable API once version 1.0.0 is released. Types prefixed with an underscore or marked @internal in JSDoc are not part of the public API.

Deprecation Policy#

Deprecated APIs are marked with @deprecated in JSDoc and will emit a console warning when used. Deprecated APIs are removed no earlier than the next major version.


Rate Limits and Quotas#

Telemetry Rates#

Data Type Default Rate Max Rate
IMU 200 Hz 1000 Hz
GPS 5 Hz 20 Hz
Magnetometer 100 Hz 200 Hz
Barometer 50 Hz 100 Hz
Telemetry 10 Hz 50 Hz
Video Frame 30 fps 240 fps
LiDAR Scan 10 Hz 20 Hz
Depth Frame 30 fps 90 fps

Command Rates#

Command Type Max Rate Description
Position Setpoint 50 Hz Position commands
Velocity Setpoint 50 Hz Velocity commands
Attitude Setpoint 250 Hz Attitude commands
Gimbal Command 50 Hz Gimbal orientation
Camera Command 5 Hz Camera settings changes

Swarm Limits#

Parameter Limit
Max Swarm Size MAX_SWARM_SIZE (see constants)
Heartbeat Rate 1 Hz per drone
Broadcast Rate 10 Hz
Mesh Network Hops 5 max

Authentication#

Authentication is required for all remote drone connections and GCS communication.

typescript
import { MAVLinkMessageSigning } from '@oya/core';

const signer = new MAVLinkMessageSigning();
signer.setSecretKey(secretKeyBytes);

const signedFrame = signer.sign(frame);
const isValid = signer.verify(receivedFrame);

Stream Authentication#

typescript
import { StreamAuthenticator } from '@oya/core';

const auth = new StreamAuthenticator();
auth.setToken(jwtToken);
const isAuthorized = auth.validateConnection(clientInfo);

Message Encryption#

typescript
import { MessageEncryptor } from '@oya/core';

const encryptor = new MessageEncryptor();
encryptor.setKey(aesKey);
const encrypted = encryptor.encrypt(payload);
const decrypted = encryptor.decrypt(encrypted);

WebSocket Protocol#

The Oya platform uses WebSocket for real-time GCS-to-drone communication.

Connection#

text
ws://gcs-host:port/api/v1/drone/{droneId}/ws

Message Format#

All messages use JSON encoding:

typescript
interface WebSocketMessage {
  type: 'telemetry' | 'command' | 'event' | 'ack' | 'error';
  id: string; // message UUID
  timestamp: string; // ISO 8601
  droneId: DroneId;
  payload: unknown;
}

Message Types#

Type Direction Description
telemetry Drone -> GCS Periodic telemetry data
command GCS -> Drone Flight command
event Drone -> GCS State change / alert
ack Drone -> GCS Command acknowledgment
error Drone -> GCS Error notification

Telemetry Stream#

typescript
// Subscribe to telemetry
ws.send(
  JSON.stringify({
    type: 'command',
    id: uuid(),
    timestamp: new Date().toISOString(),
    droneId: myDroneId,
    payload: {
      command: 'subscribe_telemetry',
      interval: 100, // ms
    },
  })
);

// Receive telemetry
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'telemetry') {
    const telemetry = TelemetrySchema.parse(msg.payload);
    updateUI(telemetry);
  }
};

Command Protocol#

typescript
// Send position command
ws.send(
  JSON.stringify({
    type: 'command',
    id: uuid(),
    timestamp: new Date().toISOString(),
    droneId: myDroneId,
    payload: {
      command: 'goto_position',
      position: { latitude: 37.7749, longitude: -122.4194, altitude: 50 },
      speed: 5.0,
    },
  })
);

Error Codes#

Error codes follow the pattern {CATEGORY}_{SPECIFIC}:

Connection Errors (1xxx)#

Code Constant Description
1001 CONN_TIMEOUT Connection timed out
1002 CONN_REFUSED Connection refused
1003 CONN_LOST Connection lost unexpectedly
1004 CONN_AUTH_FAILED Authentication failed

Sensor Errors (2xxx)#

Code Constant Description
2001 GPS_NO_FIX No GPS fix available
2002 GPS_POOR_ACCURACY GPS accuracy below threshold
2003 IMU_BIAS_EXCEEDED IMU bias too large
2004 MAG_INTERFERENCE Magnetic interference
2005 BARO_FAILED Barometer failure

Battery Errors (3xxx)#

Code Constant Description
3001 BATT_LOW Battery low
3002 BATT_CRITICAL Battery critical
3003 BATT_OVERTEMP Battery over temperature
3004 BATT_CELL_IMBALANCE Cell voltage imbalance

Motor Errors (4xxx)#

Code Constant Description
4001 MOTOR_STALL Motor stalled
4002 MOTOR_OVERTEMP Motor over temperature
4003 ESC_FAILURE ESC failure

Mission Errors (5xxx)#

Code Constant Description
5001 MISSION_INVALID Mission validation failed
5002 MISSION_UPLOAD_FAILED Mission upload failed
5003 MISSION_ABORT Mission aborted
5004 WAYPOINT_UNREACHABLE Waypoint cannot be reached

Geofence Errors (6xxx)#

Code Constant Description
6001 GEOFENCE_BREACH Geofence boundary breached
6002 ALTITUDE_EXCEEDED Altitude limit exceeded
6003 SPEED_EXCEEDED Speed limit exceeded

Collision Errors (7xxx)#

Code Constant Description
7001 COLLISION_IMMINENT Collision imminent
7002 COLLISION_AVOIDANCE Avoidance maneuver triggered

Swarm Errors (8xxx)#

Code Constant Description
8001 SWARM_DRONE_LOST Drone lost from swarm
8002 SWARM_COMM_FAILURE Swarm communication failure
8003 SWARM_FORMATION_BREAK Formation broken

Weather Errors (9xxx)#

Code Constant Description
9001 WIND_EXCEEDED Wind speed exceeded limit
9002 VISIBILITY_LOW Visibility below minimum
9003 PRECIPITATION Unsafe precipitation

This API reference is auto-maintained. For the latest generated API docs, run npx typedoc from the libs/oya/core directory.