alsdb.processing.waveform.simulate_waveform#

alsdb.processing.waveform.simulate_waveform(provider: TileDBProvider, center_x: float, center_y: float, year: int | None = None, footprint_radius: float = 12.5, z_step: float = 0.15, sigma: float = 0.64, beam_id: str | None = None, noise_std: float = 0.0, intensity_weighted: bool = False, gaussian_beam_weighting: bool = True, sigma_beam: float | None = None, slope_correction: bool = False, min_points: int = 25, cover_threshold: float = 2.0, rh_levels: tuple[int, ...] = (0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100), rng: Generator | None = None) → WaveformResult | None[source]#

Simulate a GEDI large-footprint waveform at a given UTM location.

Parameters:

  • provider (TileDBProvider) – Local or S3 ALS array.

  • center_x (float) – Footprint centre in UTM metres (same CRS as the array). Convert from GEDI lat/lon with e.g. pyproj.Transformer.

  • center_y (float) – Footprint centre in UTM metres (same CRS as the array). Convert from GEDI lat/lon with e.g. pyproj.Transformer.

  • year (int, optional) – Survey year filter. None merges all years.

  • footprint_radius (float) – Footprint radius in metres (default 12.5 → 25 m diameter).

  • z_step (float) – Vertical bin size in metres (GEDI native = 0.15 m).

  • sigma (float) – Gaussian pulse width σ in metres. Used only when beam_id is None. Use _SIGMA_FULL (0.64 m) for full-power beams or _SIGMA_COV (0.93 m) for coverage beams.

  • beam_id (str, optional) – GEDI beam identifier (e.g. "BEAM0000"). When provided, the bundled mean TX pulse shape for that beam is used as the convolution kernel instead of a symmetric Gaussian, giving a more physically accurate waveform (the real GEDI pulse has an asymmetric tail). Must be one of _BEAM_IDS; silently falls back to Gaussian if unrecognised.

  • noise_std (float) – Standard deviation of additive Gaussian noise (0 = noise-free).

  • intensity_weighted (bool) – Weight histogram by return intensity rather than point count.

  • gaussian_beam_weighting (bool) – If True (default), weight each ALS point by the GEDI Gaussian beam profile: exp(-r² / (2 σ_beam²)). Points near the footprint edge contribute less than those at the centre, matching the real instrument response and reducing systematic bias in heterogeneous canopy.

  • sigma_beam (float, optional) – Beam σ in metres for Gaussian weighting. Defaults to footprint_radius / 2 (so the 1/e² point is at the footprint edge).

  • slope_correction (bool) – If True, fit a plane to the ALS ground points (Classification == 2) inside the footprint and subtract it from all Z values before building the histogram. This collapses the slope-broadened ground return back to a sharp peak and measures vegetation height perpendicular to the terrain surface rather than vertically. Requires at least 3 ground points; silently skipped otherwise. Default False — only enable for terrain with slopes > ~15°.

  • min_points (int) – Minimum ALS points in footprint; returns None below this.

  • cover_threshold (float) – HAG threshold (m) for canopy cover calculation.

  • rh_levels (tuple of int) – RH percentile levels to compute. Default: RH0–RH100 (GEDI L2A). Result rh dict has integer keys, e.g. result.rh[50] → RH50.

  • rng (np.random.Generator, optional) – Random number generator used for additive noise when noise_std > 0. Pass np.random.default_rng(seed) for reproducible results. None (default) uses a fresh unseeded generator each call.

Return type:

WaveformResult or None

On this page