API Documentation

shapeit.geometry.base

Geometries start here.

shapeit.geometry.base.PREFERRED_METRIC_PROJECTION = <MetricProjections.WEB_MERCATOR: 'web_mercator'>

the preferred metric projection

class shapeit.geometry.base.SrGeometry(base_geometry: Union[shapely.geometry.base.BaseGeometry, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.xchg.Exportable

Represents a spatially referenced geometry by combining a Shapely base geometry with a spatial reference.

as_metric(metric_projection: shapeit.srs.MetricProjections = None)[source]

Get this geometry in one of the defined metric projections.

Parameters

metric_projection – the preferred type of metric coordinate system

Returns

the geometry in one of the defined projections

Raises

UnsupportedMetricProjectionException – if the metric_projection argument is not supported

as_usm() → shapeit.geometry.base.SrGeometry[source]

Get this geometry in the US National Atlas coordinate system.

Returns

an equivalent geometry in a US National Atlas coordinate system (or the original object if it is already in the US National Atlas coordinate system)

Note

If the geometry is already in the US National Atlas coordinate system, the method may return the original object.

as_utm() → shapeit.geometry.base.SrGeometry[source]

Get this geometry in the regional UTM projection.

Returns

an equivalent geometry in a UTM coordinate system (or the original object if it is already in a UTM coordinate system)

Note

If the geometry is already in a UTM coordinate system, the method may return the original object.

as_wgs84() → shapeit.geometry.base.SrGeometry[source]

Get this geometry as a WGS84 geometry.

Returns

an equivalent geometry in the WGS-84 coordinate system (or the original object if it is already in the WGS-84 coordinate system)

Note

If the geometry is already in the WGS84 coordinate system, the method may return the original object.

as_wm() → shapeit.geometry.base.SrGeometry[source]

Get this geometry in the Web Mercator coordinate system.

Returns

an equivalent geometry in the web mercator coordinate system (or the original object if it is already in web mercator)

Note

If the geometry is already in the US National Atlas coordinate system, the method may return the original object.

property base_geometry

Get the base geometry.

buffer(n: int, units: shapeit.measure.Units = <Units.METERS: 'meters'>, resolution: int = 64, metric_projection: shapeit.srs.MetricProjections = None) → shapeit.geometry.base.SrPolygon[source]

Buffer the geometry by n meters.

Parameters

  • n – the radius

  • units – the radius distance units

  • resolution – the number of segments used to approximate a quarter circle around a point

  • metric_projection – the preferred metric projection to use

Returns

the buffered geometry

export() → Mapping[str, Any][source]

Export the instance as a mapping of simple types.

Returns

the mapping

hash_
classmethod load(data: Mapping[str, Any]) → shapeit.geometry.base.SrGeometry[source]

Create an instance from a mapping.

Parameters

data – the data

Returns

the instance

location() → shapeit.geometry.base.SrPoint[source]

Get a single point that best represents the location of this geometry as a single point.

Returns

the point

mapping() → Mapping[str, Any][source]

Get a GeoJSON-like mapping of the base geometry.

Returns

the mapping

property sr

Get the spatial reference.

property srid

Get the SRID of the spatial reference (SR).

transform(sr: shapeit.srs.Sr) → shapeit.geometry.base.SrGeometry[source]

Transform this geometry to

Parameters

sr – the target spatial reference

Returns

an SrGeometry in the target spatial reference

class shapeit.geometry.base.SrGeometry1D(base_geometry: Union[shapely.geometry.base.BaseGeometry, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry, abc.ABC

Extend this class to implement SrGeometry subclasses that represent 1-dimensional geometries.

See also

SrPolyline

hash_
length(units: shapeit.measure.Units = <Units.METERS: 'meters'>, metric_projection: shapeit.srs.MetricProjections = None) → float[source]

Get the length of the polyline in the specified units.

Parameters

  • units – the units in which the length should be expressed

  • metric_projection – the preferred metric projection

Returns

the length

class shapeit.geometry.base.SrGeometry2D(base_geometry: Union[shapely.geometry.base.BaseGeometry, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry, abc.ABC

Extend this class to implement SrGeometry subclasses that represent 2-dimensional geometries.

See also

SrPolygon

area(units: shapeit.measure.Units = <Units.METERS: 'meters'>, metric_projection: shapeit.srs.MetricProjections = None) → float[source]

Get the area of the polygon in the specified units (squared).

Parameters

  • units – the units in which the area should be expressed

  • metric_projection – the preferred metric projection

Returns

the area

hash_
shapeit.geometry.base.SrLinestring

This is an alias for SrPolyline

alias of shapeit.geometry.base.SrPolyline

class shapeit.geometry.base.SrPoint(base_geometry: Union[shapely.geometry.point.Point, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry

A spatially referenced point geometry.

classmethod from_coords(x: float, y: float, sr: int) → shapeit.geometry.base.SrPoint[source]

Create a point from a set of coordinates and a spatial reference.

Parameters

  • x – the X coordinate

  • y – the Y coordinate

  • sr – the spatial reference ID (SRID) or an Sr that represents the spatial reference

Returns

the point

classmethod from_lat_lon(lat: float, lon: float)[source]

Create a point from a latitude and longitude.

Parameters

  • lat – the latitude

  • lon – the longitude

Returns

the point

See also

shapeit.sr.WGS_84

hash_
location() → shapeit.geometry.base.SrPoint[source]

Get a single point that best represents the location of this geometry as a single point.

Returns

the current instance

property point

Get the base geometry as a shapely.geometry.Point.

property x

Get the X coordinate.

property y

Get the Y coordinate.

class shapeit.geometry.base.SrPolygon(base_geometry: Union[shapely.geometry.polygon.Polygon, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry2D

A spatially referenced polygon geometry.

hash_
property polygon

Get the base geometry as a shapely.geometry.Polygon.

class shapeit.geometry.base.SrPolyline(base_geometry: Union[shapely.geometry.linestring.LineString, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry1D

A spatially referenced polyline geometry.

hash_
property linestring

Get the base geometry as a shapely.geometry.LineString.

location() → shapeit.geometry.base.SrPoint[source]

Get a single point that best represents the location of this geometry as a single point.

Returns

the point

shapeit.geometry.base.sr_shape(base_geometry: Union[shapely.geometry.base.BaseGeometry, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg')) → shapeit.geometry.base.SrGeometry[source]

Create a SrGeometry from a Shapely geometry (or mapping).

Parameters

  • base_geometry – the base geometry (or mapping)

  • sr – the spatial reference

Returns

the SrGeometry

Note

The returned depends on the type of Shapely base geometry the base_geometry parameter describes.

shapeit.geometry.base.update_geometry_type_map(shapely: type, shapeit: type)[source]

Update the geometry type map.

Parameters

  • shapely – the Shapely BaseGeometry type

  • shapeit – the shapeit SrGeometry type

shapeit.geometry.multi

This module contains multipart geometry objects.

shapeit.geometry.multi.SrMultiLinestring

This is an alias for SrMultiPolyline

alias of shapeit.geometry.multi.SrMultiPolyline

class shapeit.geometry.multi.SrMultiPoint(base_geometry: Union[shapely.geometry.multipoint.MultiPoint, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry

A spatially referenced mutlipoint geometry.

hash_
property multipoint

Get the base geometry as a shapely.geometry.MultiPoint.

class shapeit.geometry.multi.SrMultiPolygon(base_geometry: Union[shapely.geometry.multipolygon.MultiPolygon, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry2D

A spatially referenced multipolygon geometry.

property dissolve

Get a representation of the union of the the polygons.

Returns

the dissolved polygon

hash_
property multipolygon

Get the base geometry as a shapely.geometry.MultiPolygon.

class shapeit.geometry.multi.SrMultiPolyline(base_geometry: Union[shapely.geometry.multilinestring.MultiLineString, Mapping], sr: shapeit.srs.Sr = Sr(srid=4326, authority='epsg'))[source]

Bases: shapeit.geometry.base.SrGeometry1D

A spatially referenced polyline geometry.

hash_
property multilinestring

Get the base geometry as a shapely.geometry.Polygon.

shapeit.errors

Sometimes things go wrong.

exception shapeit.errors.ShapeitException(message: str, inner: Exception = None)[source]

Bases: Exception

This is the base exception for other exceptions defined in this library.

property inner

Get the exception that caused this exception.

property message

Get the exception message.

shapeit.measure

This module deals with linear distance measurements.

class shapeit.measure.Units[source]

Bases: enum.Enum

These are common distance units.

KILOMETERS = 'kilometers'

kilometers

METERS = 'meters'

meters

shapeit.measure.convert(n: float, units: shapeit.measure.Units, to: shapeit.measure.Units, dimension: int = 1) → float[source]

Convert a quantity defined in one unit to its equivalent quantity in another unit.

Parameters

  • n – the quantity

  • units – the units

  • to – the conversion units

  • dimension – the dimensionality of n

Returns

the equivalent units

Raises

ValueError – if the dimension parameter is not 1, 2, or 3

Note

If the units represent a square (e.g. “square meters”), the dimension parameter should be 2. If it’s cubic (e.g. “cubic meters”), dimension should be 3. For linear distances, use the default (1).

shapeit.measure.meters(n: float, units: shapeit.measure.Units, dimension: int = 1) → float[source]

Convert a linear distance to its equivalent in meters.

Parameters

  • n – the quantity

  • units – the units in which the distance is expressed

  • dimension – the dimensions of the measurement

Returns

the equivalent quantity in meters

See also

Units

shapeit.srs

If you’re dealing with spatial references (SR), look in here!

class shapeit.srs.Authorities[source]

Bases: enum.Enum

Spatial Reference Authorities

EPSG = 'epsg'

European Petroleum Survey Group

exception shapeit.srs.InvalidSrException(message: str, inner: Exception = None)[source]

Bases: shapeit.errors.ShapeitException

Raised in response to attempts to create or use invalid spatial references.

class shapeit.srs.LatLon[source]

Bases: tuple

Represents a latitude/longitude pair.

property lat

the latitude

property lon

the longitude

class shapeit.srs.MetricProjections[source]

Bases: enum.Enum

Well-known standard projections that use meters for linear measurement.

US_NAEA = 'us_naea'

US National Atlas Equal Area

UTM = 'utm'

indicates one of the UTM coordinate systems

WEB_MERCATOR = 'web_mercator'

WGS-84 Pseudo Mercator (Web Mercator)

class shapeit.srs.Sr[source]

Bases: tuple

Represents a spatial reference.

property authority

the spatial reference authority

property proj

Get a pyproj.Proj object that represents this spatial reference (SR).

property srid

the spatial reference identifier

shapeit.srs.US_NAEA = Sr(srid=2163, authority='epsg')

US National Atlas Equal Area

exception shapeit.srs.UnsupportedMetricProjectionException(message: str, inner: Exception = None)[source]

Bases: shapeit.errors.ShapeitException

Raised in response to attempts to use a metric projection in a context that doesn’t support it.

shapeit.srs.WEB_MERCATOR = Sr(srid=3857, authority='epsg')

the WGS-84 Pseudo-Mercator spatial reference

shapeit.srs.WGS_84 = Sr(srid=4326, authority='epsg')

the WGS-84 spatial reference

shapeit.srs.by_srid(srid: int, authority: Union[shapeit.srs.Authorities, str] = 'EPSG', validate: bool = True) → shapeit.srs.Sr[source]

Get a spatial reference (Sr) by its SRID and, optionally, the authority (if it isn’t an EPSG spatial reference).

Parameters

  • srid – the SRID

  • authority – the authority (The default is `epsg`)

  • validate – True to validate the Sr

Returns

the SRID

Raises

InvalidProjectionException – if there is no valid projection defined for the spatial reference

shapeit.srs.sr(srid: int, authority: str = <Authorities.EPSG: 'epsg'>) → shapeit.srs.Sr[source]

Get a spatial reference (Sr).

Parameters

  • srid –

    the SRID

  • authority – the authority

Returns

a spatial reference (SR) instance

shapeit.srs.transform_fn(from_: shapeit.srs.Sr, to: shapeit.srs.Sr) → Callable[source]

Get a transformation function for a pair of spatial references (SR).

Parameters

  • from – the spatial reference (SR) of the geometry to be transformed

  • to – the spatial reference (SR) into which the geometry shall be transformed

Returns

a transformation function that can be used with the shapely.ops.transform function

shapeit.srs.utm(lat: float, lon: float) → shapeit.srs.Sr[source]

Get the spatial reference (SR) of the UTM zone that contains a geographic coordinate.

Parameters

  • lat – the latitude

  • lon – the longitude

Returns

the spatial reference (SR) of the UTM zone

shapeit.types

If you’re dealing with Python types, deal here.

exception shapeit.types.InvalidTypeException(message: str, inner: Exception = None)[source]

Bases: shapeit.errors.ShapeitException

Raised when an attempt is made to retrieve an non-existent type from a fully-qualified name.

See also

pycls

shapeit.types.pycls(fqn_: str) → TypeVar[source]

Get the class to which a fully-qualified name (FQN) refers.

Parameters

fqn – the fully-qualified name of the class

Returns

the class described by the fully-qualified name (FQN)

shapeit.types.pyfqn(obj) → str[source]

Get the fully-qualified name (FQN) of an object’s type.

Parameters

obj – the object

Returns

the fully-qualified type name

shapeit.version

This module contains project version information.

shapeit.xchg

Document exchange… data exchange… it all starts here!

class shapeit.xchg.Exportable[source]

Bases: abc.ABC

Objects that can be exported as and loaded from simple data types should extend Exportable to make their intentions clear and their methods consistent.

abstract export() → Mapping[str, Any][source]

Export the instance as a mapping of simple types.

Returns

the mapping

abstract classmethod load(data: Mapping[str, Any]) → Any[source]

Create an instance from a mapping.

Parameters

data – the data

Returns

the instance