# @oya/core API Reference

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](#installation-and-setup)
2. [Branded ID Types](#branded-id-types)
3. [3D Math Types](#3d-math-types)
4. [Coordinate Types](#coordinate-types)
5. [Enumerations](#enumerations)
6. [Composite Types (Schemas)](#composite-types-schemas)
7. [Constants](#constants)
8. [Coordinate Transforms](#coordinate-transforms)
9. [Validation](#validation)
10. [Math Utilities](#math-utilities)
11. [Kinematics and Dynamics](#kinematics-and-dynamics)
12. [Error System](#error-system)
13. [Attitude Control](#attitude-control)
14. [Velocity and Position Control](#velocity-and-position-control)
15. [Mission Execution](#mission-execution)
16. [GPS Navigation](#gps-navigation)
17. [Indoor Positioning](#indoor-positioning)
18. [Visual SLAM](#visual-slam)
19. [Path Planning](#path-planning)
20. [Obstacle Avoidance](#obstacle-avoidance)
21. [Swarm Coordination](#swarm-coordination)
22. [Swarm Collision Avoidance](#swarm-collision-avoidance)
23. [Formation Flying](#formation-flying)
24. [Task Allocation](#task-allocation)
25. [Consensus Algorithms](#consensus-algorithms)
26. [Inter-Drone Communication](#inter-drone-communication)
27. [Shot Planning (Cinematography)](#shot-planning-cinematography)
28. [Subject Tracking](#subject-tracking)
29. [Cinematography Trajectory](#cinematography-trajectory)
30. [Multi-Camera Coordination](#multi-camera-coordination)
31. [Gimbal Control](#gimbal-control)
32. [Video Streaming](#video-streaming)
33. [Camera Systems](#camera-systems)
34. [Depth Sensors](#depth-sensors)
35. [LiDAR Integration](#lidar-integration)
36. [IMU Orientation](#imu-orientation)
37. [Audio Systems](#audio-systems)
38. [Multi-Sensor Fusion](#multi-sensor-fusion)
39. [Pose Detection 2D](#pose-detection-2d)
40. [Body Reconstruction 3D](#body-reconstruction-3d)
41. [Multi-View Fusion](#multi-view-fusion)
42. [Temporal Tracking](#temporal-tracking)
43. [Form Analysis](#form-analysis)
44. [DJI SDK Integration](#dji-sdk-integration)
45. [PX4 Autopilot Integration](#px4-autopilot-integration)
46. [ArduPilot Integration](#ardupilot-integration)
47. [MAVLink Protocol](#mavlink-protocol)
48. [Generic Hardware Abstraction](#generic-hardware-abstraction)
49. [Model Inference (Edge AI)](#model-inference-edge-ai)
50. [Model Optimization](#model-optimization)
51. [Pretrained Models](#pretrained-models)
52. [Edge Deployment](#edge-deployment)
53. [Simulation (Gazebo)](#simulation-gazebo)
54. [Simulation (AirSim)](#simulation-airsim)
55. [API Versioning](#api-versioning)
56. [Rate Limits and Quotas](#rate-limits-and-quotas)
57. [Authentication](#authentication)
58. [WebSocket Protocol](#websocket-protocol)
59. [Error Codes](#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)     |

### 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  |

---

## 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

### MAVLink

```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 |

---

## 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
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.

### MAVLink Signing

```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

```
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._
