Tile Extraction

`aoi_from_scene`	Get processing AOIs for a SAR scene.
`aoi_from_tile`	Extract one or multiple MGRS tiles from the global Sentinel-2 tiling grid and return it as a `Vector` object.
`description2dict`	Convert the HTML description field of the MGRS tile KML file to a dictionary.
`multipolygon2polygon`	Convert a MultiPolygon WKT with one Polygon to a simple Polygon WKT.
`tile_from_aoi`	Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest.
`wkt2vector_regrid`	Convert a WKT geometry to a `spatialist.vector.Vector` object and optionally reproject and regrid it.

s1ard.tile_extraction.aoi_from_scene(scene, multi=True, percent=1)[source]

Get processing AOIs for a SAR scene. The MGRS grid requires a SAR scene to be geocoded to multiple UTM zones depending on the overlapping MGRS tiles and their projection. This function returns the following for each UTM zone group:

the extent in WGS84 coordinates (key extent)
the extent in UTM coordinates (key extent_utm)
the EPSG code of the UTM zone (key epsg)

A minimum overlap of the AOIs with the SAR scene is ensured by buffering the AOIs if necessary. The minimum overlap can be controlled with parameter percent.

Parameters:

scene (pyroSAR.drivers.ID) – the SAR scene object
multi (bool) – split into multiple AOIs per overlapping UTM zone or just one AOI covering the whole scene. In the latter case the best matching UTM zone is auto-detected (using function spatialist.auxil.utm_autodetect()).
percent (int or float) – the minimum overlap in percent of each AOI with the SAR scene. See function s1ard.ancillary.buffer_min_overlap().

Returns:

a list of dictionaries with keys extent, extent_utm, epsg

Return type:

list[dict]

s1ard.tile_extraction.aoi_from_tile(tile)[source]

Extract one or multiple MGRS tiles from the global Sentinel-2 tiling grid and return it as a Vector object.

Parameters:: tile (str or list[str]) – The MGRS tile ID(s) that should be extracted and returned as a vector object. Can also be expressed as <tile ID>_<EPSG code> (e.g. 33TUN_32632). In this case the geometry of the tile is reprojected to the target EPSG code, its corner coordinates rounded to multiples of 10, and a new Vector object created.
Returns:: either a single object or a list depending on tile
Return type:: spatialist.vector.Vector or list[spatialist.vector.Vector]

s1ard.tile_extraction.description2dict(description)[source]

Convert the HTML description field of the MGRS tile KML file to a dictionary.

Parameters:: description (str) – The plain text of the Description field
Returns:: attrib – A dictionary with keys ‘TILE_ID’, ‘EPSG’, ‘MGRS_REF’, ‘UTM_WKT’ and ‘LL_WKT’. The value of field ‘EPSG’ is of type integer, all others are strings.
Return type:: dict

s1ard.tile_extraction.multipolygon2polygon(wkt)[source]

Convert a MultiPolygon WKT with one Polygon to a simple Polygon WKT. The Sentinel-2 KML grid file stores all geometries as MultiPolygons. This function simply converts the geometries to simple Polygons. Not all geometries in the KML file have been checked. In case there are ever multiple Polygons in one MultiPolygon, an RuntimeError is raised. All other geometries are returned as is.

Parameters:: wkt (str) – A geometry WKT representation.
Returns:: the output WKT geometry. Either the original geometry or a Polygon extracted from a single-Polygon MultiPolygon.
Return type:: str

s1ard.tile_extraction.tile_from_aoi(vector, epsg=None, strict=True, return_geometries=False, tilenames=None)[source]

Return a list of MGRS tile IDs or vector objects overlapping one or multiple areas of interest.

Parameters:

vector (spatialist.vector.Vector or list[spatialist.vector.Vector]) – The vector object(s) to read. CRS must be EPSG:4236.
epsg (int or list[int] or None) – Define which EPSG code(s) are allowed for the tile selection. If None, all tile IDs are returned regardless of projection.
strict (bool) – Strictly only return the names/geometries of the overlapping tiles in the target projection or also allow reprojection of neighbouring tiles? In the latter case a tile name takes the form <tile ID>_<EPSG code>, e.g. 33TUN_32632. Only applies if argument epsg is of type int or a list with one element.
return_geometries (bool) – return a list of spatialist.vector.Vector geometry objects (or just the tile names)?
tilenames (list[str] or None) – an optional list of MGRS tile names to limit the selection

Returns:

tiles – A list of unique MGRS tile IDs or spatialist.vector.Vector objects with an attribute mgrs containing the tile ID.

Return type:

list[str or spatialist.vector.Vector]

s1ard.tile_extraction.wkt2vector_regrid(wkt, epsg_in, epsg_out=None)[source]

Convert a WKT geometry to a spatialist.vector.Vector object and optionally reproject and regrid it.

Parameters:

wkt (str) – the WKT string
epsg_in (int) – the EPSG code for the CRS of wkt
epsg_out (int or None) – and optional target CRS to reproject the geometry

Returns:

the geometry object

Return type:

spatialist.vector.Vector