Architecture

HyPlan is organized around six subsystems that compose into a flight-planning pipeline. Each subsystem is a self-contained package or module with a well-defined interface.

Data flow

FlightLine / Waypoint / Pattern
        │
        ▼
FlightBox / FlightPatterns   ──▶   Campaign / flight sequence
                                        │
                          Aircraft ──▶   │   ◀── WindField
                                        ▼
                              compute_flight_plan
                                        │
                                        ▼
                                  GeoDataFrame
                                   ╱         ╲
                             exports        plotting

Subsystems

Geometry and flight lines

The atomic unit of data collection is a FlightLine — a straight-and-level segment defined by two endpoints, an altitude, and metadata. Flight lines are generated individually or in bulk via box_around_center_line() (parallel coverage of a study area) and the pattern generators in hyplan.flight_patterns (racetracks, rosettes, spirals, polygons). Pattern generators now return Pattern, which preserves generator parameters and element ordering for reuse, editing, and persistence. Intermediate route points use Waypoint.

See: Flight Lines, Waypoints, Flight Box, Flight Patterns

Planning

compute_flight_plan() is the main orchestrator. It takes an ordered sequence of flight lines, waypoints, and patterns, connects them with 3-D Dubins paths (hyplan.dubins3d), classifies each segment (takeoff, climb, transit, flight line, descent, approach, pattern), and returns a GeoDataFrame with timing, distance, altitude, and geometry for every segment. The hyplan.flight_optimizer provides graph-based line ordering with endurance constraints and refueling stops.

See: Flight Plan, Flight Optimizer, Dubins 3D

Winds and atmosphere

The WindField abstract base defines a single method — wind_at(lat, lon, altitude, time) — that returns eastward and northward wind components. Concrete implementations range from StillAirField and ConstantWindField to gridded providers that fetch data from MERRA-2, NOAA GFS, and GMAO GEOS-FP via OPeNDAP or GRIB. The planner uses these to compute crab angles, groundspeeds, and wind-corrected segment times.

The hyplan.atmosphere module provides the International Standard Atmosphere (ISA) model for pressure-altitude conversions and airspeed calculations (CAS/TAS/Mach).

See: Winds, Atmosphere

Aircraft

Aircraft models an aircraft’s performance envelope: speed schedules (CAS/Mach vs altitude), climb and descent rates, bank angles, turn radii, and endurance. Fifteen pre-configured research aircraft are included (NASA ER-2, GV, P-3, etc.). The planner calls time_to_cruise, time_to_takeoff, and time_to_return to generate Dubins paths with realistic vertical profiles.

See: Aircraft

Terrain and swath

hyplan.terrain downloads and caches 30-meter Copernicus DEM tiles, merges them with rasterio, and provides bulk elevation lookup and a vectorized ray-terrain intersection algorithm for off-nadir sensors. hyplan.swath computes ground footprint polygons for any sensor type using the sensor’s half-angle and the flight line geometry.

See: Terrain, Swath

Exports and visualization

Flight plans are exported to pilot-facing formats (ForeFlight CSV, Honeywell FMS, Excel briefing sheets), archival formats (ICARTT, KML, GPX), and plain text. hyplan.plotting provides Folium maps, altitude profiles, and terrain cross-sections.

See: Exports, Plotting

Supporting modules

Module	Purpose
hyplan.sun	Solar position and data-collection windows
hyplan.glint	Specular reflection (glint) angle prediction
hyplan.clouds	Cloud climatology via Open-Meteo or Google Earth Engine
hyplan.satellites	Satellite overpass prediction and temporal coincidence
hyplan.airspace	Airspace conflict detection (OpenAIP, FAA TFR/NASR)
hyplan.airports	Airport database and runway queries
hyplan.campaign	Persistent folder structure, revision metadata, and mutation API for a study area
hyplan.pattern	Serializable reusable pattern object returned by pattern generators

Units

All public APIs accept and return pint.Quantity objects with explicit units. The shared unit registry is hyplan.units.ureg. Parameter names include suffixes like _msl, _agl, _cas, _tas to make the reference frame explicit.