flight-planner/dist/navigation.d.ts

Plan and route VFR flights

import type { RouteLeg, RouteTrip, NavLogOptions, WaypointType, RouteSegment } from './navigation.types.js';
/**
 * Checks if a given track is eastbound (0-179 degrees).
 *
 * @param {number} track - The track in degrees.
 * @returns {boolean} True if the track is eastbound, false otherwise.
 */
export declare const isEastbound: (track: number) => boolean;
/**
 * Checks if a given track is westbound (180-359 degrees).
 *
 * @param {number} track - The track in degrees.
 * @returns {boolean} True if the track is westbound, false otherwise.
 */
export declare const isWestbound: (track: number) => boolean;
/**
 * Calculates the appropriate VFR cruising altitude based on the track and desired minimum altitude.
 *
 * Eastbound flights (0-179 degrees) use odd thousands + 500 feet (e.g., 3500, 5500).
 * Westbound flights (180-359 degrees) use even thousands + 500 feet (e.g., 4500, 6500).
 * The function returns the lowest VFR cruising altitude that is at or above the given minimum altitude.
 *
 * @param {number} track - The true track in degrees.
 * @param {number} altitude - The minimum desired altitude in feet.
 * @returns {number} The calculated VFR cruising altitude in feet.
 */
export declare function calculateVFRCruisingAltitude(track: number, altitude: number): number;
/**
 * Converts an altitude in feet to the corresponding flight level.
 * Flight levels are expressed in hundreds of feet, so the function divides the altitude by 100.
 *
 * @param {number} altitude - The altitude in feet.
 * @returns {number} The flight level (FL) corresponding to the given altitude.
 */
export declare const flightLevel: (altitude: number) => number;
/**
 * Finds the closest route leg to a given location.
 *
 * @param routeTrip - The route trip to search within.
 * @param location - The location to find the closest leg to, as a [longitude, latitude] tuple.
 * @returns The closest route leg, or undefined if no route legs are found or the input is invalid.
 */
export declare function closestRouteLeg(routeTrip: RouteTrip, location: [number, number]): RouteLeg | undefined;
/**
 * Finds the closest waypoint in a route trip to a given location.
 *
 * @param routeTrip - The route trip to search within.
 * @param location - The location to find the closest waypoint to, as a [longitude, latitude] tuple.
 * @returns The closest waypoint, or undefined if no waypoints are found or the input is invalid.
 */
export declare function closestWaypoint(routeTrip: RouteTrip, location: [number, number]): WaypointType | undefined;
/**
 * Maps a route trip to an array of unique waypoints.
 *
 * This function extracts all waypoints from a route trip by taking the start and end
 * waypoints of each leg and removing duplicates.
 *
 * @param routeTrip - The route trip containing legs with start and end waypoints
 * @returns An array of unique waypoints representing all points in the route trip
 */
export declare function routeTripWaypoints(routeTrip: RouteTrip): WaypointType[];
/**
 * Converts an array of waypoints to an array of route segments.
 *
 * This is a convenience function for preparing waypoints to be used with `calculateNavLog`.
 * Each waypoint is converted to a segment with an optional altitude.
 *
 * @param waypoints - Array of waypoints to convert to segments
 * @param altitude - Optional altitude in feet to apply to all segments
 * @returns Array of route segments ready for navigation log calculation
 *
 * @example
 * ```typescript
 * const waypoints = [departureAerodrome, enrouteWaypoint, arrivalAerodrome];
 * const segments = waypointsToSegments(waypoints, 5500);
 * const navLog = calculateNavLog({ segments, aircraft });
 * ```
 */
export declare function waypointsToSegments(waypoints: WaypointType[], altitude?: number): RouteSegment[];
/**
 * Gets the departure waypoint from a route trip.
 *
 * @param routeTrip - The route trip from which to extract the departure waypoint
 * @returns The departure waypoint, which is the first waypoint in the route
 */
export declare const routeTripDepartureWaypoint: (routeTrip: RouteTrip) => WaypointType;
/**
 * Gets the arrival waypoint from a route trip.
 *
 * @param routeTrip - The route trip from which to extract the arrival waypoint
 * @returns The arrival waypoint, which is the last waypoint in the route
 */
export declare const routeTripArrivalWaypoint: (routeTrip: RouteTrip) => WaypointType;
/**
 * Calculates a detailed navigation log (nav log) based on the provided options.
 *
 * A navigation log contains comprehensive flight performance calculations for each leg of the route,
 * including wind corrections, heading calculations, groundspeed, fuel consumption, and timing.
 * This is the detailed computational output that pilots use for in-flight navigation, as opposed
 * to a flight plan which is the route description submitted to ATC.
 *
 * The function performs the following calculations:
 * - Route leg analysis: distance, true/magnetic tracks, and headings
 * - Wind correction angles and ground speeds based on forecast winds
 * - Fuel planning: trip fuel, reserves, taxi, takeoff, landing, and alternate fuel
 * - Timing: leg durations, departure/arrival times
 * - Performance metrics: true airspeed, headwind/crosswind components
 *
 * @param options - Navigation log options containing segments, aircraft, and fuel parameters.
 * @returns A RouteTrip object containing the complete navigation log with all calculated performance data.
 * @throws {InsufficientWaypointsError} If fewer than 2 waypoints are provided in segments.
 *
 * @example
 * ```typescript
 * const navLog = calculateNavLog({
 *   segments: [
 *     { waypoint: departureAerodrome },
 *     { waypoint: enrouteWaypoint, altitude: 5500 },
 *     { waypoint: arrivalAerodrome }
 *   ],
 *   aircraft: { cruiseSpeed: 120, fuelConsumption: 8.5 },
 *   altitude: 5500,
 *   reserveFuelDuration: 45
 * });
 * ```
 */
export declare function calculateNavLog(options: NavLogOptions): RouteTrip;