API Documentation

djio.errors

Did something go wrong? It did? Use something from this module to deal with it.

exception djio.errors.DjioException(message: str, inner: Exception = None)

Bases: Exception

This is a common base class for all custom djio exceptions.

__init__(message: str, inner: Exception = None)

Parameters:

• message – the exception message
• inner – the exception that caused this exception

inner

Get the inner exception that caused this exception. :return: the inner exception

message

Get the exception message. :return: the exception message

djio.geometry

Working with geometries? Need help? Here it is!

class djio.geometry.Envelope(min_x: float, min_y: float, max_x: float, max_y: float, spatial_reference: djio.geometry.SpatialReference)

Bases: djio.geometry.Polygon

An envelope represents the minimum bounding rectangle (minimum x and y values, along with maximum x and y values) defined by coordinate pairs of a geometry. All coordinates for the geometry fall within the envelope.

__init__(min_x: float, min_y: float, max_x: float, max_y: float, spatial_reference: djio.geometry.SpatialReference)

Parameters:

• min_x – the minimum X coordinate
• min_y – the minimum Y coordinate
• max_x – the maximum X coordinate
• max_y – the maximum Y coordinate
• spatial_reference – the spatial reference (or spatial reference ID) in which the coordinates are expressed

class djio.geometry.Geometry(shapely_geometry: <MagicMock id='140116819991240'>, spatial_reference: djio.geometry.SpatialReference = None)

Bases: object

This is the common base class for all of the geometry types.

__init__(shapely_geometry: <MagicMock id='140116819991240'>, spatial_reference: djio.geometry.SpatialReference = None)

Parameters:

• shapely_geometry – a Shapely geometry
• spatial_reference – the geometry’s spatial reference

dimensions

How many dimensions does this geometry occupy? For example: a point is zero-dimensional (0); a line is one-dimensional (1); and a polygon is two-dimensional (2).

Returns:the dimensionality of the geometry

djiohash()

Get this geometry’s hash value.

Returns:the hash value

envelope

Get the envelope (bounding box) of the geometry.

Returns:the geometry’s envelope

flip_coordinates() → djio.geometry.Geometry

Create a geometry based on this one, but with the X and Y axis reversed.

Returns:a new Geometry with reversed ordinals.

static from_ewkt() → djio.geometry.Geometry

Create a geometry from EWKT, a PostGIS-specific format that includes the spatial reference system identifier an up to four (4) ordinate values (XYZM). For example: SRID=4326;POINT(-44.3 60.1) to locate a longitude/latitude coordinate using the WGS 84 reference coordinate system.

Parameters:ewkt – the extended well-known text (EWKT) Returns:the geometry

static from_geoalchemy2(spatial_reference: djio.geometry.SpatialReference) → djio.geometry.Geometry

static from_gml() → djio.geometry.Geometry

static from_ogr(spatial_reference: djio.geometry.SpatialReference = None) → djio.geometry.Geometry

Create a djio geometry from an OGR geometry.

Parameters:

• ogr_geom – the OGR geometry
• spatial_reference – the spatial reference

Returns:

a djio geometry based on the OGR geometry

Raises:

GeometryException – if the OGR has no spatial reference and no spatial reference is supplied

static from_shapely(spatial_reference: djio.geometry.SpatialReference) → djio.geometry.Geometry

Create a new geometry based on a Shapely BaseGeometry.

Parameters:

• shapely_geometry – the Shapely base geometry
• spatial_reference – the spatial reference (or spatial reference ID)

Returns:

the new geometry

Seealso:

Point

Seealso:

Polyline

Seealso:

Polygon

static from_wkb(spatial_reference: djio.geometry.SpatialReference) → djio.geometry.Geometry

static from_wkt(spatial_reference: djio.geometry.SpatialReference) → djio.geometry.Geometry

geometry_type

Get this geometry’s type.

Returns:the geometry’s type

get_point_tuples() → Iterable[djio.geometry.PointTuple]

Get an ordered iteration of all the coordinates in the geometry as point tuples. :return: an enumeration of point tuples

iter_coords() → Iterable[Tuple[float, float]]

Retrieve the coordinates that define this geometry as a flattened, ordered iteration.

Returns:and ordered iteration of tuples that describe the geometry’s coordinates

project(preferred_spatial_reference: djio.geometry.SpatialReference = None, fallback_spatial_reference: djio.geometry.SpatialReference = 3857) → djio.geometry.Geometry

Project (or re-project) this geometry.

Parameters:

• preferred_spatial_reference – the preferred spatial reference
• fallback_spatial_reference – a spatial reference that may be used as a “fallback” if the preferred spatial reference is not provided and a suitable projected spatial reference system isn’t available

Returns:

a new, projected, geometry

See also

Projector

representative_point

shapely_geometry

Get the Shapely geometry underlying this geometry object.

Returns:the Shapely geometry

spatial_reference

Get the geometry’s spatial reference.

Returns:the geometry’s spatial reference

to_gml(version: int = 3) → str

Export the geometry to GML.

Parameters:version – the desired GML version Returns:the GML representation of the geometry

to_ogr

Get the OGR geometry equivalent of this geometry.

Returns:the OGR geometry equivalent

transform(spatial_reference: djio.geometry.SpatialReference) → djio.geometry.Geometry

Create a new geometry based on this geometry but in another spatial reference.

Parameters:spatial_reference – the target spatial reference Returns:the new transformed geometry

transform_to_utm() → djio.geometry.Geometry

Transform this geometry to an appropriate UTM coordinate system based on its location.

Returns:the new geometry

exception djio.geometry.GeometryException(message: str, inner: Exception = None)

Bases: djio.errors.DjioException

Raised when something goes wrong with a geometry.

class djio.geometry.GeometryType

Bases: enum.IntFlag

These are the supported geometric data types.

POINT = 1

POLYGON = 4

POLYLINE = 2

UNKNOWN = 0

class djio.geometry.LatLonTuple

Bases: tuple

This is a lightweight tuple that represents a specific latitude and longitude

latitude

Alias for field number 0

longitude

Alias for field number 1

class djio.geometry.LateralSides

Bases: enum.Enum

This is a simple enumeration that identifies the lateral side of line (left or right).

LEFT = 'left'

the left side of the line

RIGHT = 'right'

the right side of the line

class djio.geometry.Point(shapely_geometry: <MagicMock id='140116820719488'>, spatial_reference: djio.geometry.SpatialReference = None)

Bases: djio.geometry.Geometry

In modern mathematics, a point refers usually to an element of some set called a space. More specifically, in Euclidean geometry, a point is a primitive notion upon which the geometry is built, meaning that a point cannot be defined in terms of previously defined objects. That is, a point is defined only by some properties, called axioms, that it must satisfy. In particular, the geometric points do not have any length, area, volume or any other dimensional attribute. A common interpretation is that the concept of a point is meant to capture the notion of a unique location in Euclidean space.

__init__(shapely_geometry: <MagicMock id='140116820719488'>, spatial_reference: djio.geometry.SpatialReference = None)

Parameters:

• shapely_geometry – a Shapely geometry
• spatial_reference – the geometry’s spatial reference

dimensions

A point is zero-dimensional (0) :return: zero (0)

flip_coordinates() → djio.geometry.Point

Create a point based on this one, but with the X and Y axis reversed.

Returns:a new Geometry with reversed ordinals.

static from_coordinates(y: float, spatial_reference: djio.geometry.SpatialReference, z: Union[float, NoneType] = None)

Create a point from its coordinates.

Parameters:

• x – the X coordinate
• y – the Y coordinate
• spatial_reference – the spatial reference (or spatial reference ID)
• z – the Z coordinate

Returns:

the new Point

static from_lat_lon(longitude: float) → djio.geometry.Point

Create a geometry from a set of latitude, longitude coordinates.

Parameters:

• latitude – the latitude
• longitude – the longitude

Returns:

Point

static from_latlon_tuple() → djio.geometry.Point

Create a point from a latitude/longitude tuple.

Parameters:latlon_tuple – the latitude/longitude tuple Returns:the new point

static from_point_tuple() → djio.geometry.Point

Create a point from a point tuple.

Parameters:point_tuple – the point tuple Returns:the new point

static from_shapely(srid: int) → djio.geometry.Point

Create a new point based on a Shapely point.

Parameters:

• shapely – the Shapely point
• srid – the spatial reference ID

Returns:

the new geometry

Seealso:

Geometry.from_shapely()

geometry_type

Get the geometry type.

Returns:GeometryType.POINT

iter_coords() → Iterable[Tuple[float, float]]

Retrieve the coordinates that define this geometry. For a Point, the iteration shall contain a single set of coordinates. :return: an iteration containing a single tuple containing this point’s coordinates

to_latlon_tuple() → djio.geometry.LatLonTuple

Get a lightweight latitude/longitude tuple representation of this point.

Returns:the latitude/longitude tuple representation of this point

to_point_tuple() → djio.geometry.PointTuple

Get a lightweight tuple representation of this point.

Returns:the tuple representation of the point

x

Get the X coordinate.

Returns:the X coordinate

y

Get the Y coordinate.

Returns:the Y coordinate

z

Get the Z coordinate.

Returns:the Z coordinate

class djio.geometry.PointTuple

Bases: tuple

This is a lightweight tuple that represents a point.

srid

Alias for field number 3

x

Alias for field number 0

y

Alias for field number 1

z

Alias for field number 2

class djio.geometry.Polygon(shapely_geometry: <MagicMock id='140116820067496'>, spatial_reference: djio.geometry.SpatialReference = None)

Bases: djio.geometry.Geometry

In elementary geometry, a polygon is a plane figure that is bounded by a finite chain of straight line segments closing in a loop to form a closed polygonal chain or circuit. These segments are called its edges or sides, and the points where two edges meet are the polygon’s vertices (singular: vertex) or corners. The interior of the polygon is sometimes called its body.

__init__(shapely_geometry: <MagicMock id='140116820067496'>, spatial_reference: djio.geometry.SpatialReference = None)

Parameters:

• shapely_geometry – a Shapely geometry
• spatial_reference – the geometry’s spatial reference

dimensions

A polygon is two-dimensional (2). :return: two (2)

geometry_type

Get the geometry type.

Returns:GeometryType.POLYGON

get_area(spatial_reference: Union[djio.geometry.SpatialReference, NoneType] = None) → <MagicMock id='140116820699400'>

iter_coords() → Iterable[Tuple[float, float]]

Retrieve the polygon’s coordinates as a flattened enumeration. :return: an iteration containing the polyline’s coordinates

class djio.geometry.Polyline(shapely_geometry: <MagicMock id='140116844616112'>, spatial_reference: djio.geometry.SpatialReference = None)

Bases: djio.geometry.Geometry

In geometry, a polygonal chain is a connected series of line segments. More formally, a polygonal chain P is a curve specified by a sequence of points (A1 , A2, … , An ) called its vertices. The curve itself consists of the line segments connecting the consecutive vertices. A polygonal chain may also be called a polygonal curve, polygonal path, polyline, piecewise linear curve, broken line or, in geographic information systems (that’s us), a linestring or linear ring.

__init__(shapely_geometry: <MagicMock id='140116844616112'>, spatial_reference: djio.geometry.SpatialReference = None)

Parameters:

• shapely_geometry – a Shapely geometry
• spatial_reference – the geometry’s spatial reference

dimensions

A polyline is one-dimensional (1) :return: one (1)

geometry_type

Get the geometry type.

Returns:GeometryType.POLYLINE

iter_coords() → Iterable[Tuple[float, float]]

Retrieve the coordinates that define this line. :return: an iteration containing the polyline’s coordinates

class djio.geometry.Projector

Bases: object

Use a projector to get a projected version of a geographic geometry, or to re-project a projected geometry.

static get_instance() → djio.geometry.Projector

Get the shared projector instance. :return: the shared projector instance

static project(preferred_spatial_reference: djio.geometry.SpatialReference = None, fallback_spatial_reference: djio.geometry.SpatialReference = 3857) → djio.geometry.Geometry

Project a geometry. :param geometry: the original geometry :param preferred_spatial_reference: the preferred spatial reference (If no preferred spatial reference is supplied, the projector will attempt to select an appropriate metric projection.) :param fallback_spatial_reference: the fallback spatial reference (if your preferred spatial reference isn’t available) :return: the projected geometry

static set_instance()

Set the shared projector instance. :param projector: the shared projector

class djio.geometry.ProtoGeometry(spatial_reference: djio.geometry.SpatialReference = 4326, projector: djio.geometry.Projector = None)

Bases: object

Use a proto-geometry build up a new geometry from individual coordinates.

__init__(spatial_reference: djio.geometry.SpatialReference = 4326, projector: djio.geometry.Projector = None)

Initialize self. See help(type(self)) for accurate signature.

add(p: djio.geometry.Point)

Add a point to the prototype’s exterior :param p: the new coordinate you want to add

clear()

Clear the current contents.

to_polygon() → djio.geometry.Polygon

Create a Polygon from the contents of this proto-geometry. :return: the Polygon

to_polyline() → djio.geometry.Polyline

Create a Polyline from the contents of this proto-geometry. :return: the Polyline

class djio.geometry.SpatialReference(srid: int)

Bases: object

A spatial reference system (SRS) or coordinate reference system (CRS) is a coordinate-based local, regional or global system used to locate geographical entities. A spatial reference system defines a specific map projection, as well as transformations between different spatial reference systems.

See also

https://en.wikipedia.org/wiki/Spatial_reference_system

__init__(srid: int)

Parameters:srid – the well-known spatial reference ID

static from_srid() → djio.geometry.SpatialReference

static get_utm_for_zone() → djio.geometry.SpatialReference

Get the UTM (Universal Trans-Mercator) spatial reference for a given zone. :param zone: the UTM zone :return: the UTM spatial reference :raises SpatialReferenceException: if the UTM zone has no supported spatial reference

static get_utm_from_longitude() → djio.geometry.SpatialReference

Get the UTM (Universal Trans-Mercator) spatial reference for a given longitude. :param longitude: the longitude :return: the UTM spatial reference :raises SpatialReferenceException: if the UTM zone has no supported spatial reference

is_geographic

Is this spatial reference geographic?

Returns:true if this is a geographic spatial reference, otherwise false

is_metric

Is this a projected spatial reference system that measures linear units in single meters?

Returns:true if this is a projected spatial reference system that measures linear units in single meters

is_projected

Is this spatial reference projected?

Returns:true if this is a projected spatial reference, otherwise false

is_same_as(other: djio.geometry.SpatialReference) → bool

Test a spatial reference or SRID to see if it represents this spatial reference. :param other: the other spatial reference (or SRID) :return: True if the other parameter represents the same spatial reference, otherwise False

is_utm

ogr_sr

Get the OGR spatial reference.

Returns:the OGR spatial reference

srid

Get the spatial reference’s well-known ID (srid).

Returns:the well-known spatial reference ID

utm_zone

Get the UTM (Universal Trans-Mercator) zone associated with this spatial reference. :return: the associated UTM zone

exception djio.geometry.SpatialReferenceException(message: str, inner: Exception = None)

Bases: djio.errors.DjioException

Raised when something goes wrong with a spatial reference.

djio.hashing

Need to know at a glance if two geometries are the same?

djio.hashing.bytes_to_int(b: bytes)

Convert a byte array to an integer.

Parameters:b – the byte array Returns:the integer

djio.hashing.djiohash_v1(geometry_type_code: int, srid: int, coordinates: Iterable[Tuple[float, float]], precision: int = 4) → bytearray

This is the first version of the djio hashing algorithm.

Parameters:

• geometry_type_code – an integer indicating the type of the geometry
• srid – the numeric spatial reference ID
• coordinates – a flattened, ordered iteration of coordinates in the geometry expressed as tuples
• precision – the maximum precision (points behind decimal places) to consider in the supplied coordinates

Returns:

a hash value for the geometry

See also

djio.geometry.GeometryType

djio.hashing.int_to_bytes(i: int, width: int, unsigned: bool = False, as_iterable: bool = False) → bytearray

Convert an integer to a fixed-width byte array.

Parameters:

• i – the integer
• width – the number of bytes in the array
• unsigned – True if the sign of the int may be disregarded, otherwise False
• as_iterable – when True the function returns a list of byte-sized int`s instead of a `bytearray.

Returns:

the byte array