`gws.lib.shape`¶

Shapes.

A shape (gws.Shape) is a geo-referenced geometry: a Shapely geometry together with a gws.Crs. Shapes are used for feature geometries, search geometries and map extents throughout the application.

The package is a single module. It provides:

constructors that create a Shape from WKT and EWKT, WKB and EWKB (binary or hex), SQLAlchemy/GeoAlchemy WKB elements, GeoJSON geometries, shape props or dicts, extents, gws.Bounds and x/y coordinates,
the Shape class, which implements the gws.Shape interface: conversion to WKB, WKT, GeoJSON and props, spatial predicates, union and intersection, type conversions, buffering with a tolerance and transformation to other CRS,
the Props class for shapes sent to and from the client.

Constructors raise Error if the input cannot be parsed or has no CRS. EWKT and EWKB inputs carry their own SRID; for plain WKT and WKB a default CRS must be given. GeoJSON inputs and extents are expected in the axis order of the CRS, unless always_xy is set. Circles ({"type": "Circle", "center": ..., "radius": ...}), as sent by the client, are converted to polygons.

Binary predicates and set operations transform the other shape to the CRS of this shape first. to_geojson transforms to WGS84 unless asked to keep the CRS.

Example:

import gws.lib.shape
import gws.lib.crs

shape = gws.lib.shape.from_wkt('POINT(10 20)', gws.lib.crs.WGS84)
area = shape.tolerance_polygon(5).transformed_to(gws.lib.crs.WEBMERCATOR)
ewkt = area.to_ewkt()

other = gws.lib.shape.from_wkt('SRID=4326;POLYGON((0 0,30 0,30 30,0 30,0 0))')
print(other.contains(shape))

Source code: gws.lib.shape

Package Contents¶

exception gws.lib.shape.Error¶

Bases: gws.Error

Invalid geometry or CRS.

gws.lib.shape.from_bounds(bounds: gws.Bounds) → gws.Shape¶

Create a polygon shape from a Bounds object.

Parameters:: bounds – A Bounds object.
Returns:: A Shape object.

gws.lib.shape.from_dict(d: dict) → gws.Shape¶

Create a shape from a dictionary.

Parameters:: d – A dictionary with the keys crs and geometry (a GeoJSON geometry dict).
Returns:: A Shape object.
Raises:: Error – If the CRS or the geometry is invalid.

gws.lib.shape.from_extent(extent: gws.Extent, crs: gws.Crs, always_xy=False) → gws.Shape¶

Create a polygon shape from an extent.

Parameters:

extent – An extent.
crs – A Crs object.
always_xy – If True, the extent is assumed to be in the XY (lon/lat) order, otherwise in the axis order of the CRS.

Returns:

A Shape object.

gws.lib.shape.from_geojson(geojson: dict, crs: gws.Crs, always_xy=False) → gws.Shape¶

Create a shape from a GeoJSON geometry dict.

Parses a dict as a GeoJSON geometry object (https://www.rfc-editor.org/rfc/rfc7946#section-3.1). A Circle geometry with center and radius is converted to a polygon. The coordinates are assumed to be in the axis order of the CRS, unless always_xy is True.

Parameters:

geojson – A GeoJSON geometry dict.
crs – A Crs object.
always_xy – If True, coordinates are assumed to be in the XY (lon/lat) order.

Returns:

A Shape object.

Raises:

Error – If the geometry is invalid.

gws.lib.shape.from_props(props: gws.Props) → gws.Shape¶

Create a shape from a properties object.

Parameters:: props – A properties object with crs and geometry (a GeoJSON geometry dict).
Returns:: A Shape object.
Raises:: Error – If the CRS or the geometry is invalid.

gws.lib.shape.from_wkb(wkb: bytes, default_crs: gws.Crs = None) → gws.Shape¶

Create a shape from a WKB or EWKB byte string.

Parameters:

wkb – A WKB or EWKB byte string.
default_crs – CRS to use if the data has no SRID.

Returns:

A Shape object.

Raises:

Error – If the data is invalid or there is no CRS.

gws.lib.shape.from_wkb_element(element: gws.lib.sa.geo.WKBElement, default_crs: gws.Crs = None)¶

Create a shape from a GeoAlchemy WKB element.

The CRS is taken from the EWKB data, then from the SRID of the element, then from default_crs.

Parameters:

element – A WKB element, with binary or hex-encoded data.
default_crs – CRS to use if neither the data nor the element has a valid SRID.

Returns:

A Shape object.

Raises:

Error – If the data is invalid or there is no CRS.

gws.lib.shape.from_wkb_hex(wkb: str, default_crs: gws.Crs = None) → gws.Shape¶

Create a shape from a hex-encoded WKB or EWKB string.

Parameters:

wkb – A hex-encoded WKB or EWKB string.
default_crs – CRS to use if the data has no SRID.

Returns:

A Shape object.

Raises:

Error – If the data is invalid or there is no CRS.

gws.lib.shape.from_wkt(wkt: str, default_crs: gws.Crs = None) → gws.Shape¶

Create a shape from a WKT or EWKT string.

Parameters:

wkt – A WKT or EWKT string.
default_crs – CRS to use if the string has no SRID.

Returns:

A Shape object.

Raises:

Error – If the string is invalid or there is no CRS.

gws.lib.shape.from_xy(x: float, y: float, crs: gws.Crs) → gws.Shape¶

Create a point shape from coordinates.

Parameters:

x – X coordinate (lon/easting).
y – Y coordinate (lat/northing).
crs – A Crs object.

Returns:

A Shape object.

class gws.lib.shape.Props(*args, **kwargs)¶

Bases: gws.Props

Shape properties object.

crs: str¶

geometry: dict¶

class gws.lib.shape.Shape(geom, crs: gws.Crs)¶

Bases: gws.Shape

Shape implemented with a Shapely geometry.

crs¶: CRS of this shape.

geom: shapely.geometry.base.BaseGeometry¶: Shapely geometry.

type¶: Geometry type.

x¶: X-coordinate for Point geometries, None otherwise.

y¶: Y-coordinate for Point geometries, None otherwise.

area()¶

Compute the area of the geometry.

Returns:: The area in CRS units, 0 for geometries without an area.

bounds()¶

Compute the bounds of this shape.

Returns:: A Bounds object in the CRS of this shape.

center()¶

Compute the coordinates of the centroid.

Returns:: A tuple (x, y).

centroid()¶

Compute the centroid of this shape.

Returns:: A Point shape.

contains(other)¶

Check if this shape contains the other.

Parameters:: other – Another shape.
Returns:: True if this shape contains the other.

covered_by(other)¶

Check if this shape is covered by the other.

Parameters:: other – Another shape.
Returns:: True if this shape is covered by the other.

covers(other)¶

Check if this shape covers the other.

Parameters:: other – Another shape.
Returns:: True if this shape covers the other.

crosses(other)¶

Check if this shape crosses the other.

Parameters:: other – Another shape.
Returns:: True if this shape crosses the other.

disjoint(other)¶

Check if this shape does not intersect the other.

Parameters:: other – Another shape.
Returns:: True if the shapes have no point in common.

equals(other)¶

Check if this shape is spatially equal to the other.

The other shape is transformed to the CRS of this shape. The same applies to all binary predicates.

Parameters:: other – Another shape.
Returns:: True if the shapes are equal.

intersection(*others)¶

Compute the intersection of this shape and other shapes.

Parameters:: *others – Other shapes, transformed to the CRS of this shape.
Returns:: A new shape, or this shape if no others are given.

intersects(other)¶

Check if this shape intersects the other.

Parameters:: other – Another shape.
Returns:: True if the shapes have at least one point in common.

is_empty()¶

Check if this shape is empty.

Returns:: True if this shape is empty.

is_ring()¶

Check if this shape is a closed and simple line.

Returns:: True if this shape is a ring.

is_simple()¶

Check if this shape is simple, that is, has no self-intersections.

Returns:: True if this shape is simple.

is_valid()¶

Check if this shape is valid.

Returns:: True if this shape is valid.

overlaps(other)¶

Check if this shape overlaps the other.

Parameters:: other – Another shape.
Returns:: True if this shape overlaps the other.

to_2d()¶

Convert this shape to 2 dimensions.

Returns:: A 2D shape, or this shape if it is already 2D.

to_ewkb()¶

Convert this shape to EWKB, which includes the SRID.

Returns:: EWKB bytes.

to_ewkb_hex()¶

Convert this shape to hex-encoded EWKB, which includes the SRID.

Returns:: A hex string.

to_ewkt(trim=False, rounding_precision=-1, output_dimension=3)¶

Convert this shape to EWKT, which is WKT prefixed with SRID=<srid>;.

Parameters:

trim – Remove trailing zeros from the coordinates.
rounding_precision – Number of decimal places, -1 for full precision.
output_dimension – Max. number of dimensions to output.

Returns:

An EWKT string.

to_geojson(keep_crs=False)¶

Convert this shape to a GeoJSON geometry dict.

Parameters:: keep_crs – Keep the CRS of this shape, otherwise transform the coordinates to WGS84.
Returns:: A GeoJSON geometry dict.

to_multi()¶

Convert a single geometry shape to a multi-geometry one.

Returns:: A multi-geometry shape for a point, a line string or a polygon, otherwise this shape.

to_precision(prec: int)¶

Create a copy of this shape with coordinates snapped to the given precision.

Parameters:: prec – Number of decimal places.
Returns:: A new shape.

to_props()¶

Convert this shape to props, with the EPSG code and a GeoJSON geometry in the CRS of this shape.

Returns:: Shape props.

to_type(new_type: gws.GeometryType)¶

Convert this shape to another geometry type.

Only the conversion from a single to the respective multi-geometry is supported.

Parameters:: new_type – Target geometry type. geometry and the current type return this shape.
Returns:: A converted shape.
Raises:: gws.Error – If the conversion is not supported.

to_wkb()¶

Convert this shape to WKB.

Returns:: WKB bytes.

to_wkb_hex()¶

Convert this shape to hex-encoded WKB.

Returns:: A hex string.

to_wkt(trim=False, rounding_precision=-1, output_dimension=3)¶

Convert this shape to WKT.

Whitespace around commas and parentheses is removed.

Parameters:

trim – Remove trailing zeros from the coordinates.
rounding_precision – Number of decimal places, -1 for full precision.
output_dimension – Max. number of dimensions to output.

Returns:

A WKT string.

tolerance_polygon(tolerance=None, quad_segs=None)¶

Build a buffer polygon around this shape.

Polygons without a tolerance are returned as is. Other shapes always get a buffer, with a small minimal radius if no tolerance is given. Shapes in a geographic CRS are buffered in Web Mercator.

Parameters:

tolerance – Buffer radius in CRS units, or in meters for geographic CRS.
quad_segs – Number of segments per quarter circle.

Returns:

A polygon shape.

touches(other)¶

Check if this shape touches the other.

Parameters:: other – Another shape.
Returns:: True if this shape touches the other.

transformed_to(crs)¶

Transform this shape to another CRS.

Parameters:: crs – Target CRS.
Returns:: A transformed shape, or this shape if the CRS is the same.

union(others)¶

Compute the union of this shape and other shapes.

Parameters:: others – Other shapes, transformed to the CRS of this shape.
Returns:: A new shape, or this shape if others is empty.

within(other)¶

Check if this shape is within the other.

Parameters:: other – Another shape.
Returns:: True if this shape is within the other.

`gws.lib.shape`¶

Package Contents¶

Table of Contents

Previous topic

Next topic

gws.lib.shape¶

Package Contents¶

`gws.lib.shape`¶