Skip to main content

dem.prepare_dem_for_snap()

Return an external DEM prepared for SNAP’s sampling and height conventions.

Usage

Source

dem.prepare_dem_for_snap(
    dem,
    *,
    source_crs=None,
    download_missing_grids=False,
    cache_dir=None,
    snap_bin=None
)

The output geotransform is shifted by half a pixel because SNAP interprets an external DEM’s origin as the center of its first pixel, and so samples the file half a pixel south-east of where its georeferencing places it [1]. SNAP fixed that in the 14.0.2 update of its snap-dem module, so the shift is applied only for an installation older than that, and for one whose version cannot be determined. When source_crs is supplied, elevations are also transformed from that compound horizontal and vertical CRS to WGS 84 ellipsoidal heights (EPSG:4979). SNAP cannot do that conversion itself: the only geoid it knows is EGM96, which it applies even to the Copernicus DEM, whose heights are referenced to EGM2008 [2].

The result is correct only when read by the SNAP installation it was prepared for, and must only be passed as an externalDEMFile. Set SNAP’s externalDEMApplyEGM parameter to False. Prepared copies are cached by source content and conversion settings.

Parameters

dem: str | Path

Local DEM to prepare.

source_crs: str | None = None

Compound CRS describing the DEM’s horizontal and orthometric references, for example "EPSG:4326+3855" for Copernicus GLO-30. If omitted, elevations pass through unchanged.

download_missing_grids: bool = False

Download required open-license PROJ grids when they are not installed.

cache_dir: Path | None = None

Directory for prepared copies. Defaults to SNAP_DEM_CACHE (~/.s1bursts/dem).

snap_bin: Path | None = None
A SNAP installation’s bin directory, which decides whether the half-pixel shift is needed. Defaults to SNAP_BIN, then gpt discovered on PATH.

Returns

Path
Path to the prepared copy.

Raises

FileNotFoundError

If dem does not exist.

ValueError

If the source CRS is invalid or inconsistent with the DEM.

TransformationGridError

If no exact vertical transformation is available, because a PROJ grid it needs is missing or could not be downloaded.

pyproj.exceptions.ProjError

If any DEM pixel falls outside the selected transformation’s valid area.

ConfigurationError
If snap_bin is given but contains no gpt executable.

References

  1. [1] External DEM is sampled half a pixel off. ESA STEP forum. https://forum.step.esa.int/t/external-dem-is-sampled-half-a-pixel-off/46042
  2. [2] Copernicus DEM built-in path applies EGM96 while the data is EGM2008. ESA STEP forum. https://forum.step.esa.int/t/copernicus-dem-built-in-path-applies-egm96-while-the-data-is-egm2008/46041