Flight Lines

A FlightLine is the fundamental unit of data collection — a straight-and-level segment defined by two geographic endpoints, an altitude, and metadata.

FlightLine class

class FlightLine[source]

Bases: object

Represents a geospatial flight line with properties, validations, and operations.

A FlightLine is defined by two Waypoint objects (start and end). The Shapely LineString geometry and geodesic properties (length, azimuths) are derived from those waypoints.

Altitude is stored as MSL (above mean sea level), which is the standard aviation reference. Sensor calculations that depend on height above ground (AGL) must account for terrain elevation separately.

__init__(waypoint1, waypoint2, site_name=None, site_description=None, investigator=None)[source]
Parameters:
property geometry: LineString

Shapely LineString derived from the two waypoints.

property altitude_msl: Quantity

Flight altitude MSL (from waypoint1).

FlightLine is a single-altitude representation: both endpoints carry the same MSL altitude. This matches mission-design intent for survey lines flown at a chosen flight level, and the per-line residual against real sortie traces is small (≤2% on the validated NM17 B replay).

For staged climbs during the takeoff phase (e.g., a heavy ER-2 levelling off briefly to burn fuel before continuing to climb) use hyplan.aircraft.Aircraft.step_climb().

property lat1: float

Latitude of the start point in decimal degrees.

property lon1: float

Longitude of the start point in decimal degrees.

property lat2: float

Latitude of the end point in decimal degrees.

property lon2: float

Longitude of the end point in decimal degrees.

property length: Quantity

Geodesic length of the flight line (Vincenty formula) in meters.

property az12: Quantity

Forward azimuth from start to end point in degrees.

property az21: Quantity

Forward azimuth from end to start point in degrees.

property waypoint1: Waypoint

Start point Waypoint.

property waypoint2: Waypoint

End point Waypoint.

classmethod start_length_azimuth(lat1, lon1, length, az, altitude_msl=None, site_name=None, site_description=None, investigator=None, **kwargs)[source]

Create a flight line from a start point, length, and azimuth.

Parameters:

  • lat1 (float) – Start latitude in decimal degrees.

  • lon1 (float) – Start longitude in decimal degrees.

  • length (Quantity) – Line length as a Quantity with distance units.

  • az (float) – Forward azimuth in degrees from true north.

  • altitude_msl (Quantity | None) – Flight altitude MSL.

  • site_name (Optional[str]) – Optional site name.

  • site_description (Optional[str]) – Optional site description.

  • investigator (Optional[str]) – Optional investigator name.

Return type:

FlightLine

Returns:

A new FlightLine extending from (lat1, lon1) along the given azimuth.

classmethod from_endpoints(lat1, lon1, lat2, lon2, altitude_msl=None, site_name=None, site_description=None, investigator=None)[source]

Create a flight line from two endpoint coordinates.

Parameters:

  • lat1 (float) – Start latitude in decimal degrees.

  • lon1 (float) – Start longitude in decimal degrees.

  • lat2 (float) – End latitude in decimal degrees.

  • lon2 (float) – End longitude in decimal degrees.

  • altitude_msl (Quantity | None) – Flight altitude MSL.

  • site_name (Optional[str]) – Optional site name.

  • site_description (Optional[str]) – Optional site description.

  • investigator (Optional[str]) – Optional investigator name.

Return type:

FlightLine

Returns:

A new FlightLine from (lat1, lon1) to (lat2, lon2).

classmethod center_length_azimuth(lat, lon, length, az, altitude_msl=None, site_name=None, site_description=None, investigator=None, **kwargs)[source]

Create a flight line centered on a point, extending equally in both directions.

Parameters:

  • lat (float) – Center latitude in decimal degrees.

  • lon (float) – Center longitude in decimal degrees.

  • length (Quantity) – Total line length as a Quantity with distance units.

  • az (float) – Forward azimuth in degrees from true north.

  • altitude_msl (Quantity | None) – Flight altitude MSL.

  • site_name (Optional[str]) – Optional site name.

  • site_description (Optional[str]) – Optional site description.

  • investigator (Optional[str]) – Optional investigator name.

Return type:

FlightLine

Returns:

A new FlightLine centered on (lat, lon) along the given azimuth.

classmethod from_geojson(feature)[source]

Reconstruct a FlightLine from a GeoJSON Feature dict.

The feature must have a LineString geometry with at least two coordinates. Properties altitude_msl, site_name, site_description, and investigator are read if present.

Parameters:

feature (Dict) – GeoJSON Feature dict with LineString geometry.

Return type:

FlightLine

Returns:

A new FlightLine.

Raises:

HyPlanValueError – If the geometry is degenerate (start == end).

clip_to_polygon(clip_polygon, merge_gap=<Quantity(10, 'nautical_mile')>)[source]

Clip the flight line to a specified polygon.

When clipping produces multiple segments (e.g. a coastline inlet splits the line), adjacent fragments separated by less than merge_gap are merged into a single continuous line. This prevents short gaps from fragmenting what should be a single pass — at typical survey speeds a 10 nm gap is under 3 minutes of flight.

Parameters:

  • clip_polygon (Union[Polygon, MultiPolygon]) – The polygon to clip the flight line to.

  • merge_gap (Union[Quantity, float, None]) – Maximum gap between adjacent fragments to merge. Accepts a pint Quantity or a plain float (assumed meters). Set to None or 0 to disable merging.

Returns:

A list of resulting FlightLine(s), or None if no intersection exists.

Return type:

Optional[List[“FlightLine”]]

track(precision=100.0)[source]

Generate a LineString representing the flight line.

Parameters:

precision (Union[Quantity, float]) – Desired distance between interpolated points. Accepts a Quantity with length units or a plain float (assumed meters).

Returns:

A LineString object containing the interpolated track.

Return type:

LineString

reverse()[source]

Reverse the direction of the flight line.

Returns:

A new FlightLine object with reversed direction.

Return type:

FlightLine

offset_north_east(offset_north, offset_east)[source]

Offset the flight line in the north and east directions.

Parameters:

  • offset_north (Quantity) – Distance to offset in the north direction (positive or negative).

  • offset_east (Quantity) – Distance to offset in the east direction (positive or negative).

Returns:

A new FlightLine object with the offset applied.

Return type:

FlightLine

offset_across(offset_distance)[source]

Offset the flight line perpendicular to its direction by a specified distance.

Parameters:

offset_distance (Union[Quantity, float]) – Distance to offset the line (positive for right, negative for left). Plain floats are assumed meters.

Returns:

A new FlightLine object with the offset applied.

Return type:

FlightLine

offset_along(offset_start, offset_end)[source]

Offset the flight line along its direction by modifying the start and end points.

Parameters:

  • offset_start (Union[Quantity, float]) – Distance to offset the start point along the line (positive or negative). Plain floats are assumed meters.

  • offset_end (Union[Quantity, float]) – Distance to offset the end point along the line (positive or negative). Plain floats are assumed meters.

Returns:

A new FlightLine object with the offset applied.

Return type:

FlightLine

rotate_around_midpoint(angle)[source]

Rotate the flight line around its midpoint by a specified angle.

Parameters:

angle (float) – Rotation angle in degrees. Positive values indicate counterclockwise rotation.

Returns:

A new FlightLine object rotated around its midpoint.

Return type:

FlightLine

split_by_length(max_length, gap_length=None)[source]

Split the flight line into segments of a specified maximum length with an optional gap between segments.

Parameters:

  • max_length (Quantity) – Maximum length of each segment (meters).

  • gap_length (Optional[Quantity]) – Length of the gap between segments (meters). Default is None.

Returns:

List of FlightLine objects representing the segments.

Return type:

List[FlightLine]

to_dict()[source]

Convert the flight line to a dictionary representation.

Returns:

Dictionary with keys for geometry coordinates, endpoints,

length (meters), altitude (meters), and metadata fields.

Return type:

Dict

to_geojson()[source]

Convert the flight line to a GeoJSON Feature dictionary.

Returns:

GeoJSON Feature with LineString geometry and properties

including altitude, site name, description, and investigator.

Return type:

Dict

Utilities

to_gdf(flight_lines, crs='EPSG:4326')[source]

Convert a list of FlightLine objects to a GeoDataFrame.

Parameters:

  • flight_lines (List[FlightLine]) – Flight lines to convert.

  • crs (str) – Coordinate reference system (default: “EPSG:4326”).

Returns:

GeoDataFrame with flight line attributes and geometries.

Return type:

gpd.GeoDataFrame