Flight Box

Generate parallel, evenly-spaced flight lines covering a study area.

Box generators

box_around_center_line(instrument, altitude_msl, lat0, lon0, azimuth, box_length, box_width, box_name='Line', start_numbering=1, overlap=20, alternate_direction=True, starting_point='center', polygon=None)

Create a series of flight lines around a center line based on the given box dimensions and instrument properties.

Parameters:

• instrument (object) – An object with a swath_width(altitude_agl) method.

• altitude_msl (ureg.Quantity) – Flight altitude MSL. Must be a positive length Quantity. Note: this is passed directly to instrument.swath_width() which expects AGL. Over flat terrain near sea level the difference is negligible; for mountainous terrain, consider adjusting for mean terrain elevation.

• lat0 (float) – Latitude of the box center in decimal degrees (-90 to 90).

• lon0 (float) – Longitude of the box center in decimal degrees (-180 to 180).

• azimuth (float) – Orientation of the box in degrees. Will be wrapped to [-180, 180].

• box_length (ureg.Quantity) – Length of the box as a positive length Quantity.

• box_width (ureg.Quantity) – Width of the box as a positive length Quantity.

• box_name (str) – Name prefix for the flight lines.

• start_numbering (int) – Starting number for flight line naming. Must be a positive integer.

• overlap (float) – Percentage overlap between adjacent swaths. Must be between 0 and 100.

• alternate_direction (bool) – Whether to alternate flight line directions.

• starting_point (str) – Whether to start the first line from the “edge” or “center” of the box.

• polygon (Optional[Polygon]) – Optional polygon to clip flight lines. Must be valid.

Returns:

A list of generated flight lines.

Return type:

List[flight_line.FlightLine]

Raises:

ValueError – If inputs do not meet validation criteria.

Notes

• Flight lines are generated around the center of the box, with distances calculated from the centerline.

• Clipping is applied to each line if a polygon is provided.

box_around_polygon(instrument, altitude_msl, polygon, azimuth=None, box_name='Line', start_numbering=1, overlap=20, alternate_direction=True, clip_to_polygon=True)

Generate flight lines based on either: - The minimum rotated rectangle of a polygon (if azimuth=None) - A rotated rectangle at a specified azimuth (if azimuth is given)

Parameters:

• instrument (object) – Object with swath_width(altitude_agl) method.

• altitude_msl (ureg.Quantity) – Flight altitude MSL.

• polygon (Polygon) – Input polygon to generate flight lines within.

• azimuth (Optional[float]) – If provided, uses a user-defined azimuth instead of the minimum rotated rectangle.

• box_name (str) – Prefix for flight line names.

• start_numbering (int) – Starting number for flight line names.

• overlap (float) – Overlap percentage between adjacent swaths.

• alternate_direction (bool) – Whether to alternate flight line directions.

• clip_to_polygon (bool) – Whether to clip flight lines to the convex hull of the polygon.

• starting_point (str) – Whether to start the first line from the “edge” or “center”.

Returns:

A list of generated flight lines.

Return type:

List[flight_line.FlightLine]

Raises:

ValueError – If inputs are invalid.

Notes

• If azimuth is None, the function will automatically compute the minimum rotated rectangle.

• If azimuth is provided, a rotated rectangle at the given azimuth will be used.

box_around_polygon_terrain(instrument, altitude_msl, polygon, azimuth=None, box_name='Line', start_numbering=1, overlap=20, alternate_direction=True, clip_to_polygon=True, clip_polygon=None, safe_altitude=<Quantity(300, 'meter')>, min_line_length=<Quantity(200, 'meter')>, target_agl=None)

Generate terrain-aware flight lines covering a polygon.

Works for both LineScanner and SidelookingRadar sensors. Supports two altitude modes:

Mode 2 (default): A fixed altitude_msl is used for every flight line. Line spacing is computed by ray-terrain intersection at each candidate line position, ensuring the requested overlap is maintained even over variable terrain.

Mode 3: Pass target_agl instead of relying solely on altitude_msl. Each flight line is assigned an individual altitude derived from the mean terrain elevation along its nadir track plus target_agl, so GSD and overlap remain stable across mountainous terrain (Zhao et al. 2021). Raise HyPlanValueError if both altitude_msl and target_agl are provided.

Unlike box_around_polygon(), which uses a flat-earth swath_width() for line spacing, this function calls generate_swath_polygon() with a DEM at each candidate line to determine the actual terrain-projected swath width before stepping to the next line.

Unlike box_around_center_terrain(), this function accepts a polygon boundary (instead of explicit box dimensions), works with any sensor that implements swath_width() and swath_offset_angles(), and always uses a caller-supplied altitude rather than deriving one from a target pixel size.

Parameters:

• instrument (ScanningSensor) – Sensor with swath_width(altitude_agl) and swath_offset_angles() methods. Accepts both LineScanner and SidelookingRadar.

• altitude_msl (Quantity) – Flight altitude above mean sea level (Mode 2). Used as a reference altitude for box geometry in Mode 3.

• polygon (Polygon) – Study-area boundary polygon (WGS84 lon/lat).

• azimuth (Optional[float]) – Flight-line orientation in degrees from true north. If None, uses the minimum rotated rectangle of the polygon.

• box_name (str) – Prefix for flight-line site names.

• start_numbering (int) – First line number used in site names.

• overlap (float) – Swath overlap percentage between adjacent lines (0–100).

• alternate_direction (bool) – Reverse every other line direction.

• clip_to_polygon (bool) – Clip lines to the polygon boundary.

• clip_polygon (Optional[Polygon]) – If provided, clip lines to this polygon instead of polygon. Useful when the bounding box and the clip boundary differ (e.g. when delegating from box_around_center_terrain()).

• safe_altitude (Quantity) – Minimum required clearance above terrain. In Mode 2 this is checked globally; in Mode 3 it is checked per line against the maximum terrain elevation along that line’s nadir track.

• min_line_length (Quantity) – Drop clipped segments shorter than this value.

• target_agl (Optional[Quantity]) – Desired altitude above ground level for Mode 3. When provided each flight line receives an individual altitude_msl computed as mean nadir terrain + target_agl. Cannot be used together with a custom altitude_msl — raise HyPlanValueError if both are supplied.

Return type:

List[FlightLine]

Returns:

List of FlightLine objects with terrain-aware spacing. In Mode 3 each line carries a distinct altitude_msl derived from local terrain.

Raises:

HyPlanValueError – For invalid inputs, conflicting altitude arguments, or insufficient terrain clearance.

box_around_center_terrain(instrument, altitude_msl, lat0, lon0, azimuth, box_length, box_width, box_name='Line', start_numbering=1, overlap=20, alternate_direction=True, safe_altitude=<Quantity(300, 'meter')>, polygon=None, min_line_length=<Quantity(200, 'meter')>, target_agl=None)

Create terrain-aware flight lines around an explicit center point.

Constructs a rectangular survey box from the center coordinates and dimensions, then delegates to box_around_polygon_terrain() for terrain-aware line placement. Works with any sensor that implements swath_width() and swath_offset_angles() — including LineScanner, SidelookingRadar, and LVIS.

LineScanner users who need altitude derived from a target pixel size should call altitude_msl_for_pixel_size() first.

Parameters:

• instrument (ScanningSensor) – Sensor with swath_width(altitude_agl) and swath_offset_angles() methods.

• altitude_msl (Quantity) – Flight altitude above mean sea level (Mode 2). Used as a reference altitude for box geometry in Mode 3.

• lat0 (float) – Latitude of the box center in decimal degrees.

• lon0 (float) – Longitude of the box center in decimal degrees.

• azimuth (float) – Orientation of the box in degrees from true north.

• box_length (Quantity) – Along-track length of the box.

• box_width (Quantity) – Across-track width of the box.

• box_name (str) – Name prefix for flight lines.

• start_numbering (int) – Starting number for flight line naming.

• overlap (float) – Percentage overlap between adjacent swaths (0–100).

• alternate_direction (bool) – Whether to alternate flight line directions.

• safe_altitude (Quantity) – Minimum clearance above terrain (Mode 2: global; Mode 3: per-line against local max terrain).

• polygon (Optional[Polygon]) – Optional polygon to clip flight lines to.

• min_line_length (Quantity) – Minimum flight line length after clipping.

• target_agl (Optional[Quantity]) – Desired altitude above ground level for Mode 3. When provided each flight line receives an individual altitude_msl computed as mean nadir terrain + target_agl.

Return type:

List[FlightLine]

Returns:

A list of FlightLine objects with terrain-aware spacing.

Raises:

HyPlanValueError – If inputs fail validation or altitude clearance is insufficient.

Altitude helpers

altitude_msl_for_pixel_size(instrument, pixel_size, dem_file)

Compute the MSL altitude for a LineScanner to achieve a target pixel size.

Sets altitude so the nadir GSD equals pixel_size at the lowest terrain point in the DEM, guaranteeing the pixel size requirement is met everywhere in the survey area. Use this to compute altitude_msl before calling box_around_center_terrain() or box_around_polygon_terrain().

Parameters:

• instrument (LineScanner) – A LineScanner with altitude_agl_for_ground_sample_distance.

• pixel_size (Quantity) – Desired nadir ground sample distance.

• dem_file (str) – Path to a DEM file covering the survey area (see hyplan.terrain.generate_demfile()).

Return type:

Quantity

Returns:

Flight altitude MSL as a Quantity.