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 initialize itself 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_y,max_x,max_y],

  4. [[min_x, min_y],[max_x,max_y]],

  5. [(min_x, min_y),(max_x,max_y)],

  6. ([min_x, min_y],[max_x,max_y]),

  7. 'min_x,min_y,max_x,max_y',

  8. {'min_x':min_x, 'max_x':max_x, 'min_y':min_y, 'max_y':max_y},

  9. bbox, where bbox is an instance of BBox.

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 (Union[BBox, tuple, list, dict, str, BaseGeometry]) – 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 (Union[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 (Optional[int]) – Number of parts BBox will be horizontally divided into.

  • num_y (Optional[int]) – Number of parts BBox will be vertically divided into.

  • size_x (Optional[float]) – Physical dimension of BBox along easting coordinate

  • size_y (Optional[float]) – Physical dimension of BBox along northing coordinate

Returns

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

Return type

List[List[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 (Union[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 (Optional[CRS]) – crs to be used if not available in geojson, CRS.WGS84 if not provided

Returns

Geometry object

Return type

Geometry

property geometry: Union[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

class sentinelhub.geometry.BBoxCollection(bbox_list)[source]

Bases: _BaseGeometry

A collection of bounding boxes

Parameters

bbox_list (Union[BBoxCollection, List[BBox]]) – A list of BBox objects which have to be in the same CRS

property bbox_list: List[BBox]

Returns the list of bounding boxes from collection

Returns

The list of bounding boxes

property geometry: MultiPolygon

Returns shapely object representing geometry

Returns

A multipolygon of bounding boxes

property bbox: BBox

Returns BBox object representing bounding box around the geometry

Returns

A bounding box, with same CRS

reverse()[source]

Returns a new BBoxCollection object where all x and y coordinates are switched

Returns

New Geometry object with switched coordinates

Return type

BBoxCollection

transform(crs, always_xy=True)[source]

Transforms BBoxCollection 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

BBoxCollection in target CRS

Return type

BBoxCollection

apply(operation)[source]

Applies a function to lower-left and upper-right pairs of coordinates of each bounding box in the collection to create a new collection of modified bounding boxes.

Parameters

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

Return type

BBoxCollection