Skip to content

spaceborne_lidar

Read ICESat-2 and GEDI spaceborne LiDAR footprints from HDF5 granules.

This is the Python counterpart of the app's ICESat-2 / GEDI reader (packages/plugins/src/plugins/spaceborne-lidar.ts) and follows the same rules, so a layer built here looks like one added through Add Data in the app:

  • ICESat-2 ATL06 (land ice height) and ATL08 (land and vegetation height), one footprint per along-track segment in each ground track gt1l..gt3r.
  • GEDI L2A (elevation and relative heights), L2B (canopy cover and vertical profile) and L4A (aboveground biomass density), one footprint per shot in each beam BEAM0000..BEAM1011.

Each footprint becomes a GeoJSON point with the chosen fields plus beam, beam_type (strong/weak or power/coverage), time (UTC) and distance_km (along-track distance from the first footprint of its beam).

Reading needs h5py and NumPy: pip install "geolibre[spaceborne]".

FieldSpec dataclass 

FieldSpec(path: str, name: str | None = None, column: int | None = None, scale: float | None = None)

A dataset to read for every footprint, relative to the beam group.

Attributes:

Name Type Description
path str

Dataset path, e.g. "land_segments/terrain/h_te_best_fit".
name str | None

Property name; defaults to the path's last segment.
column int | None

Column of a 2-D dataset (GEDI rh is [shots, 101]).
scale float | None

Multiplier applied to the stored value (GEDI L2B rh100 is cm).

key property 

key: str

The property name this field produces.

ProductSpec dataclass 

ProductSpec(id: str, label: str, mission: str, beam_pattern: Pattern[str], lat: str, lon: str, time: str, defaults: tuple[FieldSpec, ...], primary_field: str, quality_paths: tuple[str, ...] = (), quality_keep: Any = None, footprint: str = 'segment', extra: dict[str, Any] = dict())

How to read one product: datasets, defaults and the quality rule.

SpaceborneLidarResult dataclass 

SpaceborneLidarResult(product: str, geojson: dict[str, Any], total: int, matched: int, kept: int, stride: int, per_beam: dict[str, int])

Footprints read from a granule, with counts for reporting.

Attributes:

Name Type Description
product str

The product id.
geojson dict[str, Any]

A FeatureCollection of points.
total int

Footprints in the chosen beams.
matched int

Footprints that passed the quality and extent filters.
kept int

Footprints in geojson after thinning to max_points.
stride int

The thinning step (1 when nothing was dropped).
per_beam dict[str, int]

{beam: kept}.

spec property 

spec: ProductSpec

The product's reading rules.

detect_product 

detect_product(short_name: str | None, file_name: str | None = None) -> str | None

Identify a product from a short_name attribute or a file name.

Parameters:

Name Type Description Default
short_name str | None

The granule's short_name attribute, if any.

 required
file_name str | None

The file name, used when the attribute is missing.

 None

Returns:

Type Description
str | None

The product id ("ATL06", "ATL08", "GEDI_L2A",
str | None

"GEDI_L2B" or "GEDI_L4A"), or None when neither names one.

read_spaceborne_lidar 

read_spaceborne_lidar(source: str | PathLike[str], *, product: str | None = None, beams: Sequence[str] | None = None, fields: Iterable[Any] | None = None, quality_filter: bool = True, bbox: Sequence[float] | None = None, max_points: int | None = DEFAULT_MAX_POINTS, missions: Sequence[str] | None = None) -> SpaceborneLidarResult

Read an ICESat-2 or GEDI granule's footprints as GeoJSON points.

Parameters:

Name Type Description Default
source str | PathLike[str]

Path to the HDF5 granule.

 required
product str | None

Product id; detected from the granule when omitted.

 None
beams Sequence[str] | None

Beam or ground-track groups to read (all by default).

 None
fields Iterable[Any] | None

Fields to attach: default-field names ("rh98"), dataset paths relative to the beam group, or FieldSpec objects. The product's default fields when omitted.

 None
quality_filter bool

Drop footprints the product's quality flag rejects.

 True
bbox Sequence[float] | None

[west, south, east, north] to keep only footprints inside.

 None
max_points int | None

Cap on footprints; each beam is thinned evenly to stay under it. None or 0 keeps every footprint.

 DEFAULT_MAX_POINTS
missions Sequence[str] | None

Accepted missions ("ICESat-2", "GEDI"), checked before any footprint is read; any when None.

 None

Returns:

Type Description
SpaceborneLidarResult

The footprints and counts.

Raises:

Type Description
ImportError

Without h5py / NumPy.
ValueError

For an unsupported product or a granule with no footprints.

spaceborne_lidar_layer 

spaceborne_lidar_layer(source: str | PathLike[str], name: str | None = None, *, missions: Sequence[str] | None = None, product: str | None = None, beams: Sequence[str] | None = None, fields: Iterable[Any] | None = None, quality_filter: bool = True, bbox: Sequence[float] | None = None, max_points: int | None = DEFAULT_MAX_POINTS, color_by: str | None = None, colormap: str = 'viridis', class_count: int = 7, scheme: str = 'quantile', **style: Any) -> tuple[dict[str, Any], SpaceborneLidarResult]

Build a GeoJSON point layer from an ICESat-2 or GEDI granule.

The layer matches one added through the app's Add Data → ICESat-2 / GEDI: small points, graduated colors on the product's main field (or color_by), and metadata.sourceKind == "spaceborne-lidar".

Parameters:

Name Type Description Default
source str | PathLike[str]

Path to the HDF5 granule.

 required
name str | None

Layer name; "<product> <file name>" by default.

 None
missions Sequence[str] | None

Accepted missions ("ICESat-2", "GEDI"); any when None.

 None
product str | None

Product id; detected from the granule when omitted. See read_spaceborne_lidar.

 None
beams Sequence[str] | None

Beams to read; see read_spaceborne_lidar.

 None
fields Iterable[Any] | None

Fields to read; see read_spaceborne_lidar.

 None
quality_filter bool

Drop low-quality footprints; see read_spaceborne_lidar.

 True
bbox Sequence[float] | None

Bounding box filter; see read_spaceborne_lidar.

 None
max_points int | None

Point cap; see read_spaceborne_lidar.

 DEFAULT_MAX_POINTS
color_by str | None

Field to color by; the product's main field by default. Pass "" for a single color.

 None
colormap str

Color ramp for the graduated colors.

 'viridis'
class_count int

Number of color classes.

 7
scheme str

"quantile" or "equal-interval".

 'quantile'
**style Any

Style overrides (e.g. circleRadius, fillColor).

 {}

Returns:

Type Description
tuple[dict[str, Any], SpaceborneLidarResult]

The layer dict and the read result.

Raises:

Type Description
ValueError

For a granule of another mission, or no footprints kept.