areas

Module for working with large geographical areas

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

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 (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – A list of geometrical shapes describing the area of interest
  • crs (CRS) – Coordinate reference system of the shapes in shape_list
  • split_shape (int or (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).
  • reduce_bbox_sizes (bool) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given area geometry from shape_list.
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)

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

Parameters:
  • crs (CRS or 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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
  • 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. This overrides the same parameter from constructor
Returns:

List of bounding boxes

Return type:

list(BBox)

get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.OsmSplitter(shape_list, crs, zoom_level, **kwargs)[source]

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 (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – 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 (bool) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given area geometry from shape_list.
get_world_bbox()[source]

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

Returns:Bounding box of entire world
Return type:BBox
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)

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

Parameters:
  • crs (CRS or 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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
  • 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. This overrides the same parameter from constructor
Returns:

List of bounding boxes

Return type:

list(BBox)

get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.TileSplitter(shape_list, crs, time_interval, tile_split_shape=1, data_collection=None, config=None, data_source=None, **kwargs)[source]

A tool that splits the given area into smaller parts. Given the area, time interval and data collection it collects info from Sentinel Hub WFS service about all satellite tiles intersecting the area. For each of them it calculates bounding box and if specified it splits these bounding boxes into smaller bounding boxes. Then it filters out the ones 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 (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – A list of geometrical shapes describing the area of interest
  • crs (CRS) – Coordinate reference system of the shapes in shape_list
  • time_interval ((str, str)) – Interval with start and end date of the form YYYY-MM-DDThh:mm:ss or YYYY-MM-DD
  • tile_split_shape – 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).
  • data_collection (DataCollection) – A satellite data collection
  • config (SHConfig or None) – A custom instance of config class to override parameters from the saved configuration.
  • reduce_bbox_sizes (bool) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given area geometry from shape_list.
  • data_source (DataCollection) – A deprecated alternative of data_collection
get_tile_dict()[source]

Returns the dictionary of satellite tiles intersecting the area geometry. For each tile they contain info about their bounding box and lists of acquisitions and geometries

Returns:Dictionary containing info about tiles intersecting the area
Return type:dict
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)

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

Parameters:
  • crs (CRS or 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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
  • 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. This overrides the same parameter from constructor
Returns:

List of bounding boxes

Return type:

list(BBox)

get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.CustomGridSplitter(shape_list, crs, bbox_grid, bbox_split_shape=1, **kwargs)[source]

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

Parameters:
  • shape_list (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – A list of geometrical shapes describing the area of interest
  • crs (CRS) – Coordinate reference system of the shapes in shape_list
  • bbox_grid (list(BBox) or BBoxCollection) – A collection of bounding boxes defining a grid of splitting. All of them have to be in the same CRS.
  • bbox_split_shape (int or (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 (bool) – If True it will reduce the sizes of bounding boxes so that they will tightly fit the given geometry in shape_list.
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)

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

Parameters:
  • crs (CRS or 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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
  • 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. This overrides the same parameter from constructor
Returns:

List of bounding boxes

Return type:

list(BBox)

get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.UtmGridSplitter(shape_list, crs, bbox_size, offset=None)[source]

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

Parameters:
  • shape_list (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – A list of geometrical shapes describing the area of interest
  • crs (CRS) – Coordinate reference system of the shapes in shape_list
  • bbox_size (int or (int, int) or float or (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 ((int, int) or (float, float) or None) – Bounding box offset in horizontal and vertical directions in meters.
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(buffer=None)

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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
Returns:List of bounding boxes
Return type:list(BBox)
get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.UtmZoneSplitter(shape_list, crs, bbox_size, offset=None)[source]

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

Parameters:
  • shape_list (list(shapely.geometry.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)) – A list of geometrical shapes describing the area of interest
  • crs (CRS) – Coordinate reference system of the shapes in shape_list
  • bbox_size (int or (int, int) or float or (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 ((int, int) or (float, float) or None) – Bounding box offset in horizontal and vertical directions in meters.
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(buffer=None)

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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
Returns:List of bounding boxes
Return type:list(BBox)
get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)
class sentinelhub.areas.BatchSplitter(*, request_id=None, batch_request=None, config=None)[source]

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

Parameters:
  • request_id (str or None) – An ID of a batch request
  • batch_request (BatchRequest or None) – A batch request object. It is an alternative to the request_id parameter
  • config (SHConfig or None) – A configuration object with credentials and information about which service deployment to use.
get_area_bbox(crs=None)

Returns a bounding box of the entire area

Parameters:crs (CRS or 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
get_area_shape()

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:shapely.geometry.multipolygon.MultiPolygon
get_bbox_list(crs=None, buffer=None, reduce_bbox_sizes=None)

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

Parameters:
  • crs (CRS or 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 (float or None) – A percentage of each BBox size increase. This will cause neighbouring bounding boxes to overlap.
  • 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. This overrides the same parameter from constructor
Returns:

List of bounding boxes

Return type:

list(BBox)

get_geometry_list()

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.multipolygon.MultiPolygon or shapely.geometry.polygon.Polygon)
get_info_list()

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(BBox)