Swath

Compute ground footprints and widths for line-scanning sensors along flight lines.

Swath generation

generate_swath_polygon(flight_line, sensor, along_precision=100.0, across_precision=10.0, dem_file=None, heading_mode='track', crab_angle_deg=None, heading_deg=None, terrain_aware=True)[source]

Generate a swath polygon for a given flight line and sensor.

Works with any sensor satisfying the ScanningSensor protocol — i.e. exposing swath_offset_angles() returning (port_edge_angle, starboard_edge_angle) in degrees from nadir (negative = port, positive = starboard). This includes nadir-looking line scanners, tilted line scanners, LVIS, and side-looking radar.

Parameters:

  • flight_line (FlightLine) – The flight line containing geometry and altitude (MSL).

  • sensor (ScanningSensor) – Any object satisfying ScanningSensor.

  • along_precision (float) – Along-track interpolation spacing (meters).

  • across_precision (float) – Ray-terrain intersection sampling (meters).

  • dem_file (str | None) – Path to the DEM file. If None and terrain_aware is True, one is generated automatically. Ignored when terrain_aware is False.

  • heading_mode (str) – "track" (default) orients the swath perpendicular to the ground track. "crabbed" orients it perpendicular to the aircraft heading, which differs from the track when the aircraft crabs into a crosswind.

  • crab_angle_deg (float | None) – Crab angle (degrees) to add to track azimuths. Only used when heading_mode="crabbed".

  • heading_deg (float | None) – Constant aircraft heading (degrees true). Only used when heading_mode="crabbed".

  • terrain_aware (bool) – When True (default), edge rays are intersected with the DEM via ray_terrain_intersection() — appropriate for real campaign planning. When False, swath edges are computed analytically from altitude × tan(edge_angle) (flat-earth, no DEM access) — appropriate for synthetic geometry demos and tests that should not depend on network DEM downloads.

Return type:

Polygon

Returns:

A Shapely Polygon representing the swath.

calculate_swath_widths(swath_polygon)[source]

Calculate the minimum, mean, and maximum width of a swath polygon.

Parameters:

swath_polygon (Polygon) – The swath polygon generated for a flight line.

Returns:

A dictionary containing the min, mean, and max widths in meters.

Return type:

dict

Coverage analysis

analyze_swath_gaps_overlaps(swath_polygons)[source]

Pairwise gap/overlap analysis between adjacent swath polygons.

For each consecutive pair (swath_polygons[i], swath_polygons[i+1]), reports the area of overlap and the area of any gap between them. Either value is zero when the polygons abut or overlap entirely. The caller is responsible for ordering the polygons (e.g. in the perpendicular-offset order produced by hyplan.flight_box.box_around_center_line()).

Each pair is projected to a local UTM zone before computing areas, so the resulting values are in square meters regardless of the input CRS (must be lon/lat in WGS84).

Parameters:

swath_polygons (list[Polygon]) – Polygons in adjacency order. Must be in WGS84 (EPSG:4326). Returns an empty DataFrame if fewer than two polygons are provided.

Returns:

  • pair_index: index i of the first polygon in the pair.

  • overlap_area_m2: area of intersection in m².

  • gap_area_m2: area between the two polygons in m² when they don’t overlap; 0.0 if they do.

  • overlap_fraction: overlap_area_m2 divided by the mean of the two polygon areas.

Return type:

DataFrame with columns

Export

export_polygon_to_kml(swath_polygon, kml_filename, name='Swath Polygon')[source]

Export a Shapely polygon to a KML file with an unfilled style using simplekml.

Parameters:

  • swath_polygon (Polygon) – A Shapely Polygon representing the swath.

  • kml_filename (str) – Output KML file path.

  • name (str) – Name for the KML placemark.

Return type:

None