Flight Patterns

Generate common flight patterns for use with compute_flight_plan().

All public generators return a Pattern, not a bare list. This lets HyPlan carry generator parameters, regenerate patterns after edits, persist them inside a Campaign, and round-trip them through GeoJSON/JSON-friendly structures used by interactive planning tools.

See also: Pattern

Pattern generators

racetrack(center, heading, altitude, leg_length, n_legs=1, offset=0, altitudes=None, stack_altitudes=None, name=None)[source]

Generate parallel out-and-back flight lines.

Handles racetracks, lawnmowers, bowling alleys, vertical walls, and stacked patterns through parameter variation. Consecutive legs alternate direction so end-to-start transitions are short turns.

Parameters:

  • center (tuple) – (lat, lon) center point of the pattern.

  • heading (float) – Bearing of the first leg in degrees from north.

  • altitude (Union[float, Quantity]) – Altitude MSL for all legs (overridden by altitudes if given).

  • leg_length (Union[float, Quantity]) – Length of each leg.

  • n_legs (int) – Number of parallel legs (default 1).

  • offset (Union[float, Quantity, list]) – Crosstrack spacing between legs. Scalar = uniform spacing. List = per-leg offsets from center (length must equal n_legs).

  • altitudes (Optional[list]) – Per-leg altitudes. Length must equal n_legs. Overrides altitude for each leg. Enables vertical walls.

  • stack_altitudes (Optional[list]) – Repeat the entire pattern at each altitude in this list. Produces n_legs * len(stack_altitudes) total legs.

  • name (Optional[str]) – Pattern display name (default “Racetrack”).

Return type:

Pattern

Returns:

A line-based Pattern (kind="racetrack").

rosette(center, heading, altitude, radius, n_lines=3, angles=None, name=None)[source]

Generate radial flight lines through a center point.

Creates a FlightLine centered on the point along the first angle, then rotates it for each subsequent line angle. Each line is a full diameter crossing through center.

Parameters:

  • center (tuple) – (lat, lon) center point.

  • heading (float) – Bearing of the first line in degrees from north.

  • altitude (Union[float, Quantity]) – Altitude MSL.

  • radius (Union[float, Quantity]) – Half-length of each line (center to tip).

  • n_lines (int) – Number of lines (default 3). Lines are spaced at 180/n_lines degree intervals.

  • angles (Optional[List[float]]) – Explicit angles for each line (degrees from north). Overrides n_lines and heading.

  • name (Optional[str]) – Pattern display name (default “Rosette”).

Return type:

Pattern

Returns:

A line-based Pattern (kind="rosette").

sawtooth(center, heading, altitude_min, altitude_max, leg_length, n_cycles=1, name=None)[source]

Generate an oscillating altitude profile along a straight track.

Parameters:

  • center (tuple) – (lat, lon) center point of the track.

  • heading (float) – Bearing of the track in degrees from north.

  • altitude_min (Union[float, Quantity]) – Bottom of each oscillation.

  • altitude_max (Union[float, Quantity]) – Top of each oscillation.

  • leg_length (Union[float, Quantity]) – Total track length.

  • n_cycles (int) – Number of up-down cycles.

  • name (Optional[str]) – Pattern display name (default “Sawtooth”).

Return type:

Pattern

Returns:

A waypoint-based Pattern (kind="sawtooth").

spiral(center, heading, altitude_start, altitude_end, radius, n_turns=3.0, direction='right', points_per_turn=36, name=None)[source]

Generate a helical spiral pattern for vertical profiling.

The aircraft flies a constant-radius circle while ascending or descending. Used for boundary layer profiling, aerosol vertical structure, and thermodynamic soundings.

Parameters:

  • center (tuple) – (lat, lon) ground target point.

  • heading (float) – Bearing from center to the entry point (degrees from north). The aircraft enters tangent to the circle at this point.

  • altitude_start (Union[float, Quantity]) – Altitude MSL at the start of the spiral.

  • altitude_end (Union[float, Quantity]) – Altitude MSL at the end of the spiral.

  • radius (Union[float, Quantity]) – Turn radius (distance from center to the flight path).

  • n_turns (float) – Number of complete revolutions (fractional OK). Default 3.

  • direction (str) – “right” (clockwise viewed from above) or “left” (counterclockwise). Default “right”.

  • points_per_turn (int) – Number of waypoints per revolution. Default 36 (one every 10 degrees).

  • name (Optional[str]) – Pattern display name (default “Spiral”).

Return type:

Pattern

Returns:

A waypoint-based Pattern (kind="spiral").

Raises:

HyPlanValueError – If n_turns <= 0, points_per_turn < 3, or direction is not “right” or “left”.

polygon(center, heading, altitude, radius, n_sides=4, aspect_ratio=1.0, closed=True, name=None)[source]

Generate a regular polygon perimeter (or stretched polygon).

Replaces separate rectangle() and circle() generators.

Parameters:

  • center (tuple) – (lat, lon) center point.

  • heading (float) – Bearing to the first vertex in degrees from north.

  • altitude (Union[float, Quantity]) – Altitude MSL.

  • radius (Union[float, Quantity]) – Circumscribed circle radius (center to vertex).

  • n_sides (int) – Number of sides (3=triangle, 4=square, 36=circle). Default 4.

  • aspect_ratio (float) – Stretch factor along the heading axis. 1.0 = regular polygon. 2.0 = twice as long as wide. Default 1.0.

  • closed (bool) – If True, last waypoint repeats the first to close the loop. Default True.

  • name (Optional[str]) – Pattern display name (default “Polygon”).

Return type:

Pattern

Returns:

A waypoint-based Pattern (kind="polygon").

glint_arc(center, observation_datetime, altitude, speed, bank_angle=None, bank_direction='right', collection_length=None, densify_m=200.0, name=None)[source]

Generate a banked specular-glint arc as a waypoint pattern.

Wraps GlintArc (Ayasse et al. 2022) so the arc can be carried inside a Pattern and round-tripped through Pattern.regenerate() and Campaign persistence. At the arc midpoint the bank angle tilts the sensor to view the target with a glint angle of zero (perfect specular reflection); the rest of the arc keeps glint within a narrow band around it.

Parameters:

  • center (tuple) – (target_lat, target_lon) of the surface point being observed.

  • observation_datetime – UTC datetime for solar position. Same takeoff_time value used elsewhere in the planner.

  • altitude (Union[float, Quantity]) – Aircraft altitude MSL.

  • speed (Union[float, Quantity]) – Aircraft true airspeed used for turn-radius computation (typically aircraft.cruise_speed_at(altitude)).

  • bank_angle (Optional[float]) – Bank angle in degrees. None (default) auto-selects the solar zenith angle (valid only when SZA <= 60°).

  • bank_direction (str) – "right" (default) or "left".

  • collection_length (Union[float, Quantity, None]) – Optional arc length to limit the collection (Quantity or float meters). None uses the full 180° arc.

  • densify_m (float) – Spacing of the densified arc waypoints, in meters.

  • name (Optional[str]) – Pattern display name (default "Glint Arc").

Return type:

Pattern

Returns:

A waypoint-based Pattern (kind="glint_arc") whose waypoints trace the densified arc with per-segment headings.

Raises:

HyPlanValueError – If solar zenith is too small (<5°) or too large (>60° without an explicit bank_angle), or if bank_direction is not “left”/”right”.

Multi-aircraft coordination

coordinated_line(center, heading, primary_leg_length, primary_aircraft, secondary_aircraft, primary_altitude, secondary_altitude, ground_speed_ratio=None, primary_name='P3', secondary_name='ER2')[source]

Generate a coordinated dual-aircraft line pattern (five-point line).

Two aircraft fly vertically stacked legs centered on a coordination point. The secondary (faster) aircraft’s leg is extended symmetrically so both aircraft pass over the center point simultaneously.

Based on the IMPACTS sampling strategy (Yorks et al. 2025, BAMS).

Parameters:

  • center (tuple) – (lat, lon) coordination point where both aircraft overlap.

  • heading (float) – Bearing of the line in degrees from north.

  • primary_leg_length (Union[float, Quantity]) – Leg length of the primary (slower) aircraft.

  • primary_aircraft (Aircraft) – Aircraft object for the primary (slower/sampling) platform.

  • secondary_aircraft (Aircraft) – Aircraft object for the secondary (faster/remote-sensing) platform.

  • primary_altitude (Union[float, Quantity]) – Altitude MSL for the primary aircraft.

  • secondary_altitude (Union[float, Quantity]) – Altitude MSL for the secondary aircraft.

  • ground_speed_ratio (Union[float, List[float], None]) – Ratio of secondary to primary ground speed. If None, computed from TAS at each altitude. Can be a list for multiple speed-ratio lines (e.g. [1.2, 1.45] for high/low P-3).

  • primary_name (str) – Name prefix for primary waypoints (default “P3”).

  • secondary_name (str) – Name prefix for secondary waypoints (default “ER2”).

Return type:

dict

Returns:

Dict with keys "primary" (list of 2 Waypoints [start, end] for the primary aircraft), "secondary" (list of 2 Waypoints [start, end] if a single ratio, or list of such pairs if multiple ratios), "center" (Waypoint at the coordination point), and "ground_speed_ratio" (the ratio(s) used).

Utilities

flight_lines_to_waypoint_path(flight_lines, altitude=None)[source]

Convert a list of FlightLine objects into a connected waypoint path.

Each flight line contributes its waypoint1 and waypoint2. No turn waypoints are inserted — compute_flight_plan() handles Dubins transitions between consecutive waypoints.

Parameters:

  • flight_lines (List[FlightLine]) – List of FlightLine objects (e.g. from box_around_polygon()).

  • altitude (Union[float, Quantity, None]) – If provided, overrides the altitude on all waypoints.

Return type:

List[Waypoint]

Returns:

List of Waypoint objects with segment_type=”pattern”.