easysnowdata.sar.sentinel1.local_incidence_angle#

easysnowdata.sar.sentinel1.local_incidence_angle(aoi: Any = None, time: Any = None, *, source: str | None = None, relative_orbit: int | None = None, orbit_state: str | None = None, incidence_angle: float | DataArray | None = None, resolution: float | None = None, crs: Any = 'utm', dem: DataArray | None = None, mask: bool = True, chunks: Any = 'easysnowdata-default', **kwargs: Any) → Dataset[source]#

Local incidence angle (and, where available, the layover/shadow mask).

The local incidence angle is a property of one acquisition geometry, not of a place: it depends on which relative orbit (track) the scene came from, whether the pass was ascending or descending, and where in the swath a pixel sits (the ellipsoidal incidence angle runs from about 29° at near range to 46° at far range in IW mode). Rasters of different tracks are therefore never fused. With relative_orbit= the result is one (y, x) raster for that track; without it, one raster per track that crosses the AOI, stacked along a relative_orbit dimension with sat:orbit_state (and, on the computed routes, platform_heading and look_azimuth) as coordinates along it. An INFO log line says so.

The three routes trade exactness for access:

"opera-static" (default, Earthdata Login)

The published answer. OPERA’s RTC-S1-STATIC layers carry the local incidence angle, the ellipsoidal incidence angle and the layover/shadow mask per burst, computed from the orbit state vectors and the Copernicus DEM. The bursts of one track are mosaicked; bursts of different tracks go to different relative_orbit slices.

"dem" (no account)

An approximation from a DEM. The geometry of each track is taken from a representative Planetary Computer RTC scene: the platform heading from the scene footprint’s along-track edge, the look azimuth from the heading and the look side, and the ellipsoidal incidence angle as a field that grows linearly from the near-range edge to the far-range edge of the swath. Every pass of a relative orbit is assumed to share this geometry (the same assumption the standalone LIA tool at egagli/generate_sentinel1_local_incidence_angle_maps makes; that tool computes the exact geometry from the GRD orbit file with sarsen, at the price of a SAFE download per track). The result is within a few degrees of OPERA’s on open slopes and does not know about layover or shadow. When no RTC scene of a requested track or pass can be found over the AOI the route raises ValueError rather than guess: the heading varies with latitude and the incidence angle with the position in the swath, so there is no defensible default.

"gee" (Earth Engine)

The COPERNICUS/S1_GRD angle band — the real per-pixel ellipsoidal incidence angle of each track — combined with the Copernicus DEM and the same footprint-derived heading.

Parameters:

  • aoi – The area, and (OPERA route) a time window for the search.

  • time – The area, and (OPERA route) a time window for the search.

  • source – "opera-static", "dem" or "gee".

  • relative_orbit – The Sentinel-1 track (sat:relative_orbit) to compute or select. None (default) returns every track over aoi along a relative_orbit dimension.

  • orbit_state – "ascending" or "descending" restricts the tracks to one pass direction on the "dem" and "gee" routes; None (default) keeps both. Ignored when relative_orbit is given (a track has one pass direction) and on the OPERA route.

  • incidence_angle – Override for the ellipsoidal incidence angle on the "dem" route: a scalar for the whole AOI or a raster aligned with the DEM.

  • dem – A DEM to use instead of fetching the Copernicus DEM ("dem" route).

Returns:

xarray.Dataset – local_incidence_angle and incidence_angle in degrees, plus the categorical mask on the OPERA route. With relative_orbit the geometry used is in the attrs (relative_orbit, orbit_state, platform_heading, look_azimuth, incidence_angle_model); without it, the per-track values are coordinates along relative_orbit.

Examples using easysnowdata.sar.sentinel1.local_incidence_angle#

Sentinel-1 RTC backscatter and local incidence angle

Sentinel-1 RTC backscatter and local incidence angle