The scanner geometry defines a maximum swath as a fixed fraction of altitude (±5.7 deg half-scan angle). Whether that full swath achieves contiguous ground coverage depends on the laser repetition rate, lens divergence (footprint size), and aircraft speed.

Formulas derived from NASA GSFC LVIS coverage planning spreadsheet (LVIScoveragecalcs-GVBioSCape.xlsx).

class LVISLens[source]¶

Bases: object

LVIS lens option defined by its beam divergence.

name: str¶

divergence_mrad: float¶

footprint_diameter(altitude_agl)[source]¶

Footprint diameter on the ground for a given altitude AGL.

Parameters:: altitude_agl (Quantity) – Flight altitude above ground level.
Return type:: Quantity
Returns:: Footprint diameter in meters.

__init__(name, divergence_mrad)¶

Parameters:

name (str)
divergence_mrad (float)

Return type:

None

class LVIS[source]¶

Bases: Sensor

LVIS full-waveform airborne scanning lidar.

Provides the standard Sensor interface (half_angle, swath_width) so that LVIS works with generate_swath_polygon, generate_flight_lines, and other HyPlan tools. The swath_width returned is the geometric maximum; use effective_swath_width to account for contiguous-coverage constraints.

All altitude parameters expect AGL (above ground level).

Parameters:

rep_rate (Quantity) – Laser pulse repetition rate (Hz). Default 4000 Hz.
lens (object) – Lens option — LVISLens instance, key from LVIS_LENSES (“narrow”, “medium”, “wide”), or None for wide (default).

__init__(rep_rate=<Quantity(4000, 'hertz')>, lens=None)[source]¶

Parameters:

rep_rate (Quantity)
lens (object)

property half_angle: float¶: Half-scan angle in degrees (≈5.71 deg).

swath_width(altitude_agl)[source]¶

Maximum swath width set by the scanner geometry.

This is the geometric limit: 2 * altitude_agl * tan(half_angle). Equivalent to 0.2 * altitude_agl.

Used by generate_swath_polygon and generate_flight_lines for swath polygon generation and line spacing.

Parameters:: altitude_agl (Quantity) – Flight altitude above ground level.
Return type:: Quantity
Returns:: Maximum swath width in meters.

effective_fov(altitude_agl, speed)[source]¶

Effective field of view in degrees, accounting for contiguous coverage.

When the laser footprint can fill the full scanner swath, this equals the geometric max FOV (≈11.42°). When coverage is limited, the effective FOV narrows: 2 * atan(effective_swath / (2 * altitude)).

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
speed (Quantity) – Aircraft ground speed.

Return type:

float

Returns:

Effective FOV in degrees.

footprint_diameter(altitude_agl)[source]¶

Laser footprint diameter on the ground for the configured lens.

footprint = tan(divergence_mrad / 1000) * altitude_agl

Parameters:: altitude_agl (Quantity) – Flight altitude above ground level.
Return type:: Quantity
Returns:: Footprint diameter in meters.

coverage_rate(altitude_agl, speed)[source]¶

Area coverage rate at maximum swath.

coverage_rate = speed * max_swath

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
speed (Quantity) – Aircraft ground speed.

Return type:

Quantity

Returns:

Coverage rate in m^2/s.

footprint_for_max_swath(altitude_agl, speed)[source]¶

Minimum footprint diameter needed to fill the max swath contiguously.

footprint = sqrt(speed * max_swath / rep_rate)

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
speed (Quantity) – Aircraft ground speed.

Return type:

Quantity

Returns:

Required footprint diameter in meters.

effective_swath_width(altitude_agl, speed)[source]¶

Achievable swath width accounting for contiguous coverage.

The effective swath is the minimum of: - the scanner’s max swath (geometric limit), and - footprint^2 * rep_rate / speed (contiguous-coverage limit)

When the footprint is too small relative to the flight speed, shots cannot tile the full max swath without gaps, and the effective swath narrows.

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
speed (Quantity) – Aircraft ground speed.

Return type:

Quantity

Returns:

Effective swath width in meters.

is_contiguous(altitude_agl, speed)[source]¶

Check whether the current configuration fills the max swath.

Returns True if the footprint is large enough to tile the full scanner swath at the given speed.

Return type:

bool

Parameters:

altitude_agl (Quantity)
speed (Quantity)

summary(altitude_agl, speed)[source]¶

Compute all LVIS coverage parameters for a given flight configuration.

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
speed (Quantity) – Aircraft ground speed.

Return type:

dict

Returns:

Dictionary with all computed parameters.

print_summary(altitude_agl, speed)[source]¶

Print a formatted summary of LVIS coverage parameters.

Return type:

None

Parameters:

altitude_agl (Quantity)
speed (Quantity)

compare_lenses(altitude_agl, speed)[source]¶

Print a comparison table across all standard lenses.

Return type:

None

Parameters:

altitude_agl (Quantity)
speed (Quantity)

Radar¶

class SidelookingRadar[source]¶

Bases: Sensor

Represents a side-looking Synthetic Aperture Radar (SAR).

Models the slant-range geometry where the swath is offset from nadir, defined by near-range and far-range incidence angles. Supports stripmap SAR instruments like UAVSAR.

The swath lies entirely on one side of the flight track (typically left).

__init__(name, frequency, bandwidth, near_range_angle, far_range_angle, azimuth_resolution, polarization, look_direction='left', peak_power=None, antenna_length=None)[source]¶

Parameters:

name (str)
frequency (Quantity)
bandwidth (Quantity)
near_range_angle (float)
far_range_angle (float)
azimuth_resolution (Quantity)
polarization (str)
look_direction (str)
peak_power (Quantity | None)
antenna_length (Quantity | None)

property wavelength: Quantity¶: Radar wavelength derived from frequency.

property range_resolution: Quantity¶

c / (2 * B).

Type:: Slant-range resolution from bandwidth

property half_angle: float¶

Effective half-angle for swath calculations.

For a side-looking radar this is the angular extent from the swath center to either edge, i.e. half the angular swath width.

property swath_center_angle: float¶: Incidence angle at swath center (degrees from nadir).

swath_width(altitude_agl)[source]¶

Ground swath width for a given altitude AGL.

Computed from the difference in ground range at near and far incidence angles.

Parameters:: altitude_agl (Quantity) – Flight altitude above ground level.
Return type:: Quantity
Returns:: Swath width in meters.

near_range_ground_distance(altitude_agl)[source]¶

Ground distance from nadir to near edge of swath.

Return type:: Quantity
Parameters:: altitude_agl (Quantity)

far_range_ground_distance(altitude_agl)[source]¶

Ground distance from nadir to far edge of swath.

Return type:: Quantity
Parameters:: altitude_agl (Quantity)

ground_range_resolution(altitude_agl, incidence_angle=None)[source]¶

Ground-range resolution at a given incidence angle.

ground_range_res = slant_range_res / sin(incidence_angle)

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
incidence_angle (float) – Incidence angle in degrees. Defaults to swath center.

Return type:

Quantity

Returns:

Ground-range resolution in meters.

ground_sample_distance(altitude_agl)[source]¶

Ground sample distance at near range, center, and far range.

Parameters:: altitude_agl (Quantity) – Flight altitude above ground level.
Return type:: dict
Returns:: Dict with ‘near_range’, ‘center’, ‘far_range’ ground-range resolutions and ‘azimuth’ resolution.

slant_range(altitude_agl, incidence_angle=None)[source]¶

Slant range distance to target at given incidence angle.

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
incidence_angle (float) – Incidence angle in degrees. Defaults to swath center.

Return type:

Quantity

Returns:

Slant range in meters.

swath_offset_angles()[source]¶

Return the (port_angle, starboard_angle) for swath polygon generation.

For a left-looking radar, the swath is on the left (port) side. For a right-looking radar, the swath is on the right (starboard) side.

Return type:: tuple
Returns:: Tuple of (near_side_angle, far_side_angle) where the sign convention matches swath.py: port = left of track, starboard = right of track.

interferometric_line_spacing(altitude_agl, overlap_fraction=0.0)[source]¶

Compute the required spacing between parallel flight lines for interferometric or mosaicking coverage.

Parameters:

altitude_agl (Quantity) – Flight altitude above ground level.
overlap_fraction (float) – Fraction of swath overlap (0.0 = edge-to-edge, 0.5 = 50% overlap). For InSAR mosaics, typically 0.1-0.2.

Return type:

Quantity

Returns:

Line spacing in meters (center-to-center).

class UAVSAR_Lband[source]¶

Bases: SidelookingRadar

NASA/JPL UAVSAR L-band fully polarimetric SAR.

Platform: Gulfstream III (C-20A) Typical altitude: ~12,500 m (41,000 ft)

__init__()[source]¶

class UAVSAR_Pband[source]¶

Bases: SidelookingRadar

NASA/JPL UAVSAR P-band SAR (AirMOSS configuration).

Platform: Gulfstream III (C-20A) Typical altitude: ~12,500 m (41,000 ft)

__init__()[source]¶

class UAVSAR_Kaband[source]¶

Bases: SidelookingRadar

NASA/JPL GLISTIN-A Ka-band single-pass cross-track interferometric SAR.

Platform: Gulfstream III (C-20A) Typical altitude: ~12,500 m (41,000 ft)

__init__()[source]¶

Frame camera¶

class FrameCamera[source]¶

Bases: Sensor

A frame (area-array) camera sensor.

Unlike line scanners, frame cameras capture a full 2D image per frame. The footprint is determined by both horizontal and vertical fields of view.

Parameters:

name (str) – Sensor name.
sensor_width (Quantity) – Physical sensor width in mm.
sensor_height (Quantity) – Physical sensor height in mm.
focal_length (Quantity) – Lens focal length in mm.
resolution_x (int) – Number of pixels across-track (horizontal).
resolution_y (int) – Number of pixels along-track (vertical).
frame_rate (Quantity) – Frame acquisition rate in Hz.
f_speed (float) – Lens f-number (focal length / aperture diameter).

__init__(name, sensor_width, sensor_height, focal_length, resolution_x, resolution_y, frame_rate, f_speed)[source]¶

Parameters:

name (str)
sensor_width (Quantity)
sensor_height (Quantity)
focal_length (Quantity)
resolution_x (int)
resolution_y (int)
frame_rate (Quantity)
f_speed (float)

property fov_x: float¶: Calculate horizontal Field of View (FoV) in degrees.

property fov_y: float¶: Calculate vertical Field of View (FoV) in degrees.

ground_sample_distance(altitude_agl)[source]¶

Calculate the ground sample distance (GSD) at nadir for a given altitude AGL.

Parameters:: altitude_agl (Quantity) – Altitude above ground level in meters.
Returns:: Ground sample distances in meters for both x (across-track) and y (along-track).
Return type:: Dict[str, Quantity]

altitude_agl_for_ground_sample_distance(gsd_x, gsd_y)[source]¶

Calculate the required altitude AGL for a given ground sample distance (GSD) at nadir.

Parameters:

gsd_x (Quantity) – Desired ground sample distance in meters along the x-axis (across-track).
gsd_y (Quantity) – Desired ground sample distance in meters along the y-axis (along-track).

Returns:

The required altitude AGL in meters.

Return type:

Quantity

footprint_at(altitude_agl)[source]¶

Calculate the footprint dimensions (m) for a given altitude AGL.

Return type:: Dict[str, Quantity]
Parameters:: altitude_agl (Quantity)

critical_ground_speed(altitude_agl)[source]¶

Calculate the maximum ground speed (m/s) to maintain proper along-track sampling.

Parameters:: altitude_agl (Quantity) – Altitude above ground level in meters.
Returns:: Maximum allowable ground speed in meters per second.
Return type:: Quantity

static footprint_corners(lat, lon, altitude_msl, fov_x, fov_y, dem_file)[source]¶

Calculate the lat/lon/elevation of the four corners of a FrameCamera’s ground footprint.

Parameters:

lat (float) – Latitude of the FrameCamera in degrees.
lon (float) – Longitude of the FrameCamera in degrees.
altitude_msl (float) – Altitude MSL of the FrameCamera in meters.
fov_x (float) – Horizontal Field of View (FoV) of the camera in degrees.
fov_y (float) – Vertical Field of View (FoV) of the camera in degrees.
dem_file (str) – Path to the DEM file for terrain elevation data.

Return type:

List[Tuple[Quantity, Quantity, Quantity]]

Returns:

List of four (lat, lon, elevation) tuples for each corner.

Factory function¶

create_sensor(sensor_type)[source]¶

Factory function to create and return an instance of a sensor.

Parameters:: sensor_type (str) – The name of the sensor class to instantiate. Must be one of the keys in SENSOR_REGISTRY.
Returns:: An instance of the requested sensor type.
Return type:: Sensor
Raises:: ValueError – If the specified sensor_type is not found in SENSOR_REGISTRY.