sentinelhub.geometry

Module implementing geometry classes.

class sentinelhub.geometry.BBox(bbox, crs)[source]

Bases: _BaseGeometry

Class representing a bounding box in a given CRS.

Throughout the sentinelhub package this class serves as the canonical representation of a bounding box. It can be initialized from multiple representations:

  1. ((min_x, min_y), (max_x, max_y))

  2. (min_x, min_y, max_x, max_y)

  3. {“min_x”: min_x, “max_x”: max_x, “min_y”: min_y, “max_y”: max_y}

In the above Note that BBox coordinate system depends on crs parameter:

  • In case of constants.CRS.WGS84 axis x represents longitude and axis y represents latitude.

  • In case of constants.CRS.POP_WEB axis x represents easting and axis y represents northing.

  • In case of constants.CRS.UTM_* axis x represents easting and axis y represents northing.

Parameters:
  • bbox (BBoxInputType) – A bbox in any valid representation

  • crs (CRS) – Coordinate reference system of the bounding box

property lower_left: tuple[float, float]

Returns the lower left vertex of the bounding box

Returns:

min_x, min_y

property upper_right: tuple[float, float]

Returns the upper right vertex of the bounding box

Returns:

max_x, max_y

property middle: tuple[float, float]

Returns the middle point of the bounding box

Returns:

middle point

reverse()[source]

Returns a new BBox object where x and y coordinates are switched

Returns:

New BBox object with switched coordinates

Return type:

BBox

transform(crs, always_xy=True)[source]

Transforms BBox from current CRS to target CRS

This transformation will take lower left and upper right corners of the bounding box, transform these 2 points and define a new bounding box with them. The resulting bounding box might not completely cover the original bounding box but at least the transformation is reversible.

Parameters:
  • crs (CRS) – target CRS

  • always_xy (bool) – Parameter that is passed to pyproj.Transformer object and defines axis order for transformation. The default value True is in most cases the correct one.

Returns:

Bounding box in target CRS

Return type:

BBox

transform_bounds(crs, always_xy=True)[source]

Alternative way to transform BBox from current CRS to target CRS.

This transformation will transform the bounding box geometry to another CRS as a geometric object, and then define a new bounding box from boundaries of that geometry. The resulting bounding box might be larger than original bounding box, but it will always completely cover it.

Parameters:
  • crs (CRS) – target CRS

  • always_xy (bool) – Parameter that is passed to pyproj.Transformer object and defines axis order for transformation. The default value True is in most cases the correct one.

Returns:

Bounding box in target CRS

Return type:

BBox

apply(operation)[source]

Applies a function to lower left and upper right pairs of coordinates of the bounding box to create a new bounding box.

Parameters:

operation (Callable[[float, float], tuple[float, float]]) –

Return type:

BBox

buffer(buffer, *, relative=True)[source]

Provides a new bounding box with a size that is changed either by a relative or an absolute buffer.

Parameters:
  • buffer (float | tuple[float, float]) – The buffer can be provided either as a single number or a tuple of 2 numbers, one for buffer in horizontal direction and one for buffer in vertical direction. The buffer can also be negative as long as this doesn’t reduce the bounding box into nothing.

  • relative (bool) – If True the given buffer values will be interpreted as a percentage of distance between bounding box center point and its side edge (not to distance between opposite sides!). If False the given buffer will be interpreted as an absolute buffer measured in bounding box coordinate units.

Returns:

A new bounding box of buffered size.

Return type:

BBox

get_polygon(reverse=False)[source]

Returns a tuple of coordinates of 5 points describing a polygon. Points are listed in clockwise order, first point is the same as the last.

Parameters:

reverse (bool) – True if x and y coordinates should be switched and False otherwise

Returns:

((x_1, y_1), … , (x_5, y_5))

Return type:

tuple[tuple[float, float], …]

property geometry: Polygon

Returns polygon geometry in shapely format

Returns:

A polygon in shapely format

get_partition(num_x=None, num_y=None, size_x=None, size_y=None)[source]

Partitions bounding box into smaller bounding boxes of the same size.

If num_x and num_y are specified, the total number of BBoxes is know but not the size. If size_x and size_y are provided, the BBox size is fixed but the number of BBoxes is not known in advance. In the latter case, the generated bounding boxes might cover an area larger than the parent BBox.

Parameters:
  • num_x (int | None) – Number of parts BBox will be horizontally divided into.

  • num_y (int | None) – Number of parts BBox will be vertically divided into.

  • size_x (float | None) – Physical dimension of BBox along easting coordinate

  • size_y (float | None) – Physical dimension of BBox along northing coordinate

Returns:

Two-dimensional list of smaller bounding boxes. Their location is

Return type:

list[list[sentinelhub.geometry.BBox]]

get_transform_vector(resx, resy)[source]

Given resolution it returns a transformation vector

Parameters:
  • resx (float) – Resolution in x direction

  • resy (float) – Resolution in y direction

Returns:

A tuple with 6 numbers representing transformation vector

Return type:

tuple[float, float, float, float, float, float]

class sentinelhub.geometry.Geometry(geometry, crs)[source]

Bases: _BaseGeometry

A class that combines shapely geometry with coordinate reference system. It currently supports polygons and multipolygons.

It can be initialized with any of the following geometry representations: - shapely.geometry.Polygon or shapely.geometry.MultiPolygon - A GeoJSON dictionary with (multi)polygon coordinates - A WKT string with (multi)polygon coordinates

Parameters:
  • geometry (Polygon | MultiPolygon | dict | str) – A polygon or multipolygon in any valid representation

  • crs (CRS) – Coordinate reference system of the geometry

reverse()[source]

Returns a new Geometry object where x and y coordinates are switched

Returns:

New Geometry object with switched coordinates

Return type:

Geometry

transform(crs, always_xy=True)[source]

Transforms Geometry from current CRS to target CRS

Parameters:
  • crs (CRS) – target CRS

  • always_xy (bool) – Parameter that is passed to pyproj.Transformer object and defines axis order for transformation. The default value True is in most cases the correct one.

Returns:

Geometry in target CRS

Return type:

Geometry

apply(operation)[source]

Applies a function to each pair of vertex coordinates of the geometry to create a new geometry.

Parameters:

operation (Callable[[float, float], tuple[float, float]]) –

Return type:

Geometry

classmethod from_geojson(geojson, crs=None)[source]

Create Geometry object from geojson. It will parse crs from geojson (if info is available), otherwise it will be set to crs (WGS84 if parameter is empty)

Parameters:
  • geojson (dict) – geojson geometry (single feature)

  • crs (CRS | None) – crs to be used if not available in geojson, CRS.WGS84 if not provided

Returns:

Geometry object

Return type:

Geometry

property geometry: Polygon | MultiPolygon

Returns shapely object representing geometry in this class

Returns:

A polygon or a multipolygon in shapely format

property bbox: BBox

Returns BBox object representing bounding box around the geometry

Returns:

A bounding box, with same CRS