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.
-
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
-
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
-
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.
-
classmethod
-
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.
-
-
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
-
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.
-
property
-
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.
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 not1
,2
, or3
Note
If the units represent a square (e.g. “square meters”), the
dimension
parameter should be2
. If it’s cubic (e.g. “cubic meters”),dimension
should be3
. 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
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
-
property
-
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.
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.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
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.