sentinelhub.areas

Module for working with large geographical areas

class sentinelhub.areas.AreaSplitter(shape_list, crs, reduce_bbox_sizes=False)[source]

Bases: object

Abstract class for splitter classes. It implements common methods used for splitting large area into smaller parts.

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • reduce_bbox_sizes (bool) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given geometry in shape_list.

get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)[source]

Returns a list of bounding boxes that are the result of the split

Parameters:
  • crs (CRS | None) – Coordinate reference system in which the bounding boxes should be returned. If None the CRS will be the default CRS of the splitter.

  • buffer (None | float | tuple[float, float]) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.

  • reduce_bbox_sizes (bool | None) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given geometry in shape_list. This overrides the same parameter from constructor

Returns:

List of bounding boxes

Return type:

list[sentinelhub.geometry.BBox]

get_geometry_list()[source]

For each bounding box an intersection with the shape of entire given area is calculated. CRS of the returned shapes is the same as CRS of the given area.

Returns:

List of polygons or multipolygons corresponding to the order of bounding boxes

Return type:

list[shapely.geometry.polygon.Polygon | shapely.geometry.multipolygon.MultiPolygon]

get_info_list()[source]

Returns a list of dictionaries containing information about bounding boxes obtained in split. The order in the list matches the order of the list of bounding boxes.

Returns:

List of dictionaries

Return type:

list[dict[str, object]]

get_area_shape()[source]

Returns a single shape of entire area described with shape_list parameter

Returns:

A multipolygon which is a union of shapes describing the area

Return type:

MultiPolygon

get_area_bbox(crs=None)[source]

Returns a bounding box of the entire area

Parameters:

crs (CRS | None) – Coordinate reference system in which the bounding box should be returned. If None the CRS will be the default CRS of the splitter.

Returns:

A bounding box of the area defined by the shape_list

Return type:

BBox

class sentinelhub.areas.BBoxSplitter(shape_list, crs, split_shape=None, split_size=None, **kwargs)[source]

Bases: AreaSplitter

A tool that splits the given area into smaller parts. Given the area it calculates its bounding box and splits it into smaller bounding boxes of equal size. Then it filters out the bounding boxes that do not intersect the area. If specified by user it can also reduce the sizes of the remaining bounding boxes to best fit the area.

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • split_shape (None | int | tuple[int, int]) – Parameter that describes the shape in which the area bounding box will be split. It can be a tuple of the form (n, m) which means the area bounding box will be split into n columns and m rows. It can also be a single integer n which is the same as (n, n).

  • split_size (None | int | tuple[int, int]) – Parameter that describes the size of patches (in the same Unit of Measure of the CRS) into which the area bounding box will be split. It can be a tuple of the form (width, height) which means the area bounding box will be split into patches of size (width, height). It can also be a single integer size which is the same as (size, size).

  • reduce_bbox_sizes – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given area geometry from shape_list.

  • kwargs (Any) –

class sentinelhub.areas.OsmSplitter(shape_list, crs, zoom_level, **kwargs)[source]

Bases: AreaSplitter

A tool that splits the given area into smaller parts. For the splitting it uses Open Street Map (OSM) grid on the specified zoom level. It calculates bounding boxes of all OSM tiles that intersect the area. If specified by user it can also reduce the sizes of the remaining bounding boxes to best fit the area.

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • zoom_level (int) – A zoom level defined by OSM. Level 0 is entire world, level 1 splits the world into 4 parts, etc.

  • reduce_bbox_sizes – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given area geometry from shape_list.

  • kwargs (Any) –

get_world_bbox()[source]

Creates a bounding box of the entire world in EPSG: 3857

Returns:

Bounding box of entire world

Return type:

BBox

class sentinelhub.areas.TileSplitter(shape_list, crs, time_interval, data_collection, tile_split_shape=1, config=None, **kwargs)[source]

Bases: AreaSplitter

A splitter that uses Sentinel Hub Catalog API to obtain geometries of the original tiling grid of a given data collection. Additionally, it can further split these geometries into smaller parts.

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • time_interval (tuple[str, str]) – Interval with start and end date of the form YYYY-MM-DDThh:mm:ss or YYYY-MM-DD

  • data_collection (DataCollection) – A satellite data collection

  • tile_split_shape (int | tuple[int, int]) – Parameter that describes the shape in which the satellite tile bounding boxes will be split. It can be a tuple of the form (n, m) which means the tile bounding boxes will be split into n columns and m rows. It can also be a single integer n which is the same as (n, n).

  • config (SHConfig | None) – A custom instance of config class to override parameters from the saved configuration.

  • kwargs (Any) – Parameters that are propagated to the base AreaSplitter class

class sentinelhub.areas.CustomGridSplitter(shape_list, crs, bbox_grid, bbox_split_shape=1, **kwargs)[source]

Bases: AreaSplitter

Splitting class which can split according to given custom collection of bounding boxes

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • bbox_grid (Iterable[BBox]) – A collection of bounding boxes defining a grid of splitting. All of them have to be in the same CRS.

  • bbox_split_shape (int | tuple[int, int]) – Parameter that describes the shape in which each of the bounding boxes in the given grid will be split. It can be a tuple of the form (n, m) which means the tile bounding boxes will be split into n columns and m rows. It can also be a single integer n which is the same as (n, n).

  • reduce_bbox_sizes – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given geometry in shape_list.

  • kwargs (Any) –

class sentinelhub.areas.BaseUtmSplitter(shape_list, crs, bbox_size, offset=None)[source]

Bases: AreaSplitter

Base splitter that returns bboxes of fixed size aligned to UTM zones or UTM grid tiles as defined by the MGRS

The generated bounding box grid will have coordinates in form of (N * bbox_size_x + offset_x, M * bbox_size_y + offset_y)

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • bbox_size (float | tuple[float, float]) – A size of generated bounding boxes in horizontal and vertical directions in meters. If a single value is given that will be interpreted as (value, value).

  • offset (tuple[float, float] | None) – Bounding box offset in horizontal and vertical directions in meters.

get_bbox_list(buffer=None)[source]

Get list of bounding boxes.

The CRS is fixed to the computed UTM CRS. This BBox splitter does not support reducing size of output bounding boxes

Parameters:

buffer (None | float | tuple[float, float]) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.

Returns:

List of bounding boxes

Return type:

list[sentinelhub.geometry.BBox]

class sentinelhub.areas.UtmGridSplitter(shape_list, crs, bbox_size, offset=None)[source]

Bases: BaseUtmSplitter

Splitter that returns bounding boxes of fixed size aligned to the UTM MGRS grid

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • bbox_size (float | tuple[float, float]) – A size of generated bounding boxes in horizontal and vertical directions in meters. If a single value is given that will be interpreted as (value, value).

  • offset (tuple[float, float] | None) – Bounding box offset in horizontal and vertical directions in meters.

class sentinelhub.areas.UtmZoneSplitter(shape_list, crs, bbox_size, offset=None)[source]

Bases: BaseUtmSplitter

Splitter that returns bounding boxes of fixed size aligned to the equator and the UTM zones.

Parameters:
  • shape_list (Iterable[Polygon | MultiPolygon | _BaseGeometry]) – A list of geometrical shapes describing the area of interest

  • crs (CRS) – Coordinate reference system of the shapes in shape_list

  • bbox_size (float | tuple[float, float]) – A size of generated bounding boxes in horizontal and vertical directions in meters. If a single value is given that will be interpreted as (value, value).

  • offset (tuple[float, float] | None) – Bounding box offset in horizontal and vertical directions in meters.

LNG_MIN = -180
LNG_MAX = 180
LNG_UTM = 6
LAT_MIN = -80
LAT_MAX = 84
LAT_EQ = 0
class sentinelhub.areas.BatchSplitter(*, request_id=None, batch_request=None, config=None)[source]

Bases: AreaSplitter

A splitter that obtains split bounding boxes from Sentinel Hub Batch API

Parameters:
  • request_id (str | None) – An ID of a batch request

  • batch_request (BatchRequest | None) – A batch request object. It is an alternative to the request_id parameter

  • config (SHConfig | None) – A configuration object with credentials and information about which service deployment to use.