Concepts

Altitude: MSL vs AGL

HyPlan distinguishes between two altitude references:

  • MSL (Mean Sea Level) — The altitude above the geoid, as used in aviation. Flight lines and waypoints store altitude_msl because this is what pilots fly and what air traffic control assigns.

  • AGL (Above Ground Level) — The altitude above the local terrain surface. Sensor geometry methods (GSD, swath width, FOV) use altitude_agl because the sensor’s ground footprint depends on height above the target, not above sea level.

Variable and parameter names throughout HyPlan include _msl or _agl to make the reference explicit. Over flat terrain near sea level the two are nearly identical, but over mountainous terrain or high-elevation sites the distinction matters.

Sensor hierarchy

All sensors derive from the Sensor base class:

  • LineScanner — Whiskbroom/pushbroom imagers (AVIRIS-3, HyTES, PRISM, MASTER, G-LiHT, GCAS, eMAS, PICARD). Defined by FOV, across-track pixels, and frame rate.

  • SidelookingRadar — Side-looking SAR instruments (UAVSAR L-band, P-band, Ka-band). Defined by frequency, bandwidth, near/far range angles, and look direction.

  • LVIS — Full-waveform scanning lidar. The scanner geometry defines a fixed maximum swath (\(\text{swath} = 0.2 \times \text{altitude}\)), but the effective swath depends on laser repetition rate, lens divergence (footprint size), and aircraft speed.

  • FrameCamera — Frame cameras defined by sensor dimensions, focal length, resolution, and frame rate.

All sensor types provide half_angle and swath_width(altitude_agl) so they work with generate_swath_polygon(), generate_flight_lines(), and other planning tools.

Flight planning workflow

A typical mission planning workflow:

  1. Define flight lines — Use FlightLine to create individual lines by start/end coordinates, start/length/azimuth, or from GeoJSON.

  2. Generate coverage patterns — Use box_around_center_line() or box_around_polygon() to create parallel flight lines covering a target area, spaced by the sensor’s swath width.

  3. Compute the mission plan — Use compute_flight_plan() with an aircraft and departure/destination airports to generate a complete flight plan with climb, transit, data collection, descent, and landing segments.

  4. Analyze constraints — Check solar glint angles (hyplan.glint), cloud climatology (hyplan.clouds), and terrain interactions (hyplan.terrain).

Aircraft speed profiles

Aircraft performance is modeled with piecewise-linear speed profiles — a list of (altitude, speed) breakpoints. The aircraft’s speed at any altitude is interpolated from these breakpoints using numpy.interp(). This captures the variation between low-altitude maneuvering speeds and high-altitude cruise speeds.

Units

HyPlan uses Pint for physical quantities. All public APIs accept and return pint.Quantity objects with explicit units. The shared unit registry is available as hyplan.units.ureg.