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#
Installation and Setup
Branded ID Types
3D Math Types
Coordinate Types
Enumerations
Composite Types (Schemas)
Constants
Coordinate Transforms
Validation
Math Utilities
Kinematics and Dynamics
Error System
Attitude Control
Velocity and Position Control
Mission Execution
GPS Navigation
Indoor Positioning
Visual SLAM
Path Planning
Obstacle Avoidance
Swarm Coordination
Swarm Collision Avoidance
Formation Flying
Task Allocation
Consensus Algorithms
Inter-Drone Communication
Shot Planning (Cinematography)
Subject Tracking
Cinematography Trajectory
Multi-Camera Coordination
Gimbal Control
Video Streaming
Camera Systems
Depth Sensors
LiDAR Integration
IMU Orientation
Audio Systems
Multi-Sensor Fusion
Pose Detection 2D
Body Reconstruction 3D
Multi-View Fusion
Temporal Tracking
Form Analysis
DJI SDK Integration
PX4 Autopilot Integration
ArduPilot Integration
MAVLink Protocol
Generic Hardware Abstraction
Model Inference (Edge AI)
Model Optimization
Pretrained Models
Edge Deployment
Simulation (Gazebo)
Simulation (AirSim)
API Versioning
Rate Limits and Quotas
Authentication
WebSocket Protocol
Error Codes
Installation and Setup#
bash Copy
pnpm add @oya/core
Import from the barrel export:
typescript Copy
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 Copy
type DroneId = string & { readonly __brand: 'DroneId' };
UUID v4 string identifying a specific drone.
SwarmId#
typescript Copy
type SwarmId = string & { readonly __brand: 'SwarmId' };
UUID v4 string identifying a swarm group.
MissionId#
typescript Copy
type MissionId = string & { readonly __brand: 'MissionId' };
UUID v4 string identifying a mission.
WaypointId#
typescript Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
interface PayloadInfo {
id: string;
name: string;
type: string; // "Camera", "Sensor", "Delivery", "Sprayer"
weightGrams: number; // >= 0
isActive: boolean;
}
Schema: PayloadInfoSchema
WeatherConditions#
typescript Copy
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 Copy
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 Copy
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 Copy
interface WaypointActionEntry {
action: WaypointAction;
params?: Record<string, unknown>;
}
Schema: WaypointActionEntrySchema
Mission#
A complete mission containing waypoints, constraints, and metadata.
typescript Copy
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 Copy
interface MissionConstraints {
maxAltitude: number; // meters
minAltitude: number; // meters
maxSpeed: number; // m/s
minBatteryPercent: number; // 0-100
maxWindSpeed: number; // m/s
allowedAirspace: AirspaceClass[];
}
Schema: MissionConstraintsSchema
typescript Copy
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 Copy
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 Copy
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 Copy
airDensityAtAltitude(altitudeM: number): number;
atmosphericPressureAtAltitude(altitudeM: number): number;
temperatureAtAltitude(altitudeM: number): number;
Drone Classification#
typescript Copy
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 Copy
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)
Navigation Defaults#
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
Angle Utilities#
typescript Copy
degreesToRadians(degrees: number): number;
radiansToDegrees(radians: number): number;
normalizeAngle(radians: number): number; // normalizes to [-PI, PI]
GPS to NED Conversion#
typescript Copy
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 Copy
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 Copy
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 Copy
quaternionToEuler(q: Quaternion): Orientation;
eulerToQuaternion(euler: Orientation): Quaternion;
Distance and Bearing#
typescript Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
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 Copy
class TimestampSynchronizer {
addOffset(remoteTs: number, localTs: number): void;
toLocal(remoteTs: number): number;
toRemote(localTs: number): number;
}
Unit Conversions#
typescript Copy
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 Copy
crc8(data: Uint8Array): number;
crc16(data: Uint8Array): number;
crc32(data: Uint8Array): number;
Rate Limiter and Dead-Band#
typescript Copy
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 Copy
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 Copy
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 Copy
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 Copy
quadrotorDynamics(mass: number): MultirotorDynamics;
hexarotorDynamics(mass: number): MultirotorDynamics;
octorotorDynamics(mass: number): MultirotorDynamics;
coaxialRotorDynamics(mass: number): MultirotorDynamics;
Motor Mixing Matrices#
typescript Copy
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 Copy
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 Copy
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 Copy
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 Copy
enum ErrorSeverity {
Info = 'Info',
Warning = 'Warning',
Error = 'Error',
Critical = 'Critical',
Fatal = 'Fatal',
}
OyaError (Base Class)#
typescript Copy
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 Copy
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 Copy
class CascadedAttitudeController {
constructor(config: AttitudeControlConfig);
update(
targetAngle: AngleCommand,
currentOrientation: Orientation,
gyroRates: Vec3,
dt: number
): TorqueCommand;
}
QuaternionAttitudeController#
Singularity-free quaternion-based control.
typescript Copy
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 Copy
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 Copy
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 Copy
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 Copy
class MissionUploader {
upload(mission: Mission, droneId: DroneId): Promise<MissionUploadStatus>;
}
MissionValidator#
typescript Copy
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 Copy
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 Copy
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 Copy
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
Reynolds Flocking#
typescript Copy
class ReynoldsFlocking {
constructor(config: FlockingConfig);
computeSteeringForces(boids: Boid[]): Vec3[];
}
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)
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#
MAVLink#
typescript Copy
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
MAVLink Protocol#
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 Copy
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 Copy
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.
MAVLink Signing#
typescript Copy
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 Copy
import { StreamAuthenticator } from '@oya/core';
const auth = new StreamAuthenticator();
auth.setToken(jwtToken);
const isAuthorized = auth.validateConnection(clientInfo);
Message Encryption#
typescript Copy
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 Copy
ws://gcs-host:port/api/v1/drone/{droneId}/ws
All messages use JSON encoding:
typescript Copy
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 Copy
// 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 Copy
// 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.