Geometry object definitions (sarpy.geometry.geometry_elements)

This module provides basic geometry elements generally geared towards (geo)json usage.

class sarpy.geometry.geometry_elements.Jsonable

Bases: object

Abstract class for json serializability.

property type

The type identifier.

Return type:

str

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

copy()

Make a deep copy of the item.

replicate()

Make a replica of the item, where uid has not been copied.

class sarpy.geometry.geometry_elements.Feature(uid=None, geometry=None, properties=None)

Bases: Jsonable

Generic feature class - basic geojson functionality. Should generally be extended to coherently handle properties for specific use case.

property uid

The feature unique identifier.

Return type:

str

property geometry

The geometry object.

Return type:

GeometryObject|GeometryCollection

property properties: None | int | float | str | list | dict | Jsonable

The properties.

Returns:

None|int|float|str|dict|list|Jsonable

Return type:

The properties.

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_to_kml(doc, coord_transform, parent=None)

Add this feature to the kml document. Note that coordinates or transformed coordinates are assumed to be WGS-84 coordinates in longitude, latitude order. Currently only the first two (i.e. longitude and latitude) are used in this export.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • coord_transform (None|callable) – If callable, the the transform will be applied to the coordinates before adding to the document.

  • parent (None|minidom.Element) – The parent node.

Return type:

None

replicate()

Make a replica of the item, where uid has not been copied.

copy()

Make a deep copy of the item.

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.FeatureCollection(features=None)

Bases: Jsonable

Generic FeatureCollection class - basic geojson functionality. Should generally be extended to coherently handle specific Feature extension.

property features

The features list.

Return type:

List[Feature]

get_integer_index(feature_id)

Gets the integer index for the given feature id.

Parameters:

feature_id (str) –

Return type:

int

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_feature(feature)

Add a feature.

Parameters:

feature (Feature) –

Return type:

None

export_to_kml(file_name, coord_transform=None, **params)

Export to a kml document. Note that underlying geometry coordinates or transformed coordinates are assumed in longitude, latitude order. Currently only the first two (i.e. longitude and latitude) are used in this export.

Parameters:

  • file_name (str|zipfile.ZipFile|file like) –

  • coord_transform (None|callable) – The coordinate transform function.

  • params (dict) –

Return type:

None

replicate()

Make a replica of the item, where uid has not been copied.

copy()

Make a deep copy of the item.

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.Geometry

Bases: Jsonable

Abstract Geometry base class.

classmethod from_dict(geometry)

Deserialize from json.

Parameters:

geometry (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method)

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

Geometry

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

property is_collection

Is this a collection object?

Type:

bool

copy()

Make a deep copy of the item.

replicate()

Make a replica of the item, where uid has not been copied.

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.GeometryCollection(geometries=None)

Bases: Geometry

Geometry collection - following the geojson structure

property geometries: List[Geometry]

The geometry collection.

Type:

List[Geometry]

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

classmethod from_dict(geometry: None | Dict) → GeometryCollection

Deserialize from json.

Parameters:

geometry (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method)

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

classmethod assemble_from_collection(*args)

Assemble a geometry collection from the input constituents.

Parameters:

args – A list of input GeometryObjects

Return type:

GeometryCollection

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.GeometryObject

Bases: Geometry

Abstract geometry object class - mirrors basic geojson functionality

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

classmethod from_dict(geometry: Dict) → GeometryObject

Deserialize from json.

Parameters:

geometry (Dict) –

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method)

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.Point(coordinates=None)

Bases: GeometryObject

A geometric point.

property coordinates

The coordinate array.

Type:

numpy.ndarray

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

classmethod from_dict(geometry: Dict) → Point

Deserialize from json.

Parameters:

geometry (Dict) –

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → Point

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.MultiPoint(coordinates=None)

Bases: GeometryObject

A collection of geometric points.

property points: List[Point]

The point collection.

Type:

List[Point]

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

classmethod from_dict(geometry: Dict) → MultiPoint

Deserialize from json.

Parameters:

geometry (Dict) –

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → MultiPoint

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

classmethod assemble_from_collection(*args)

Assemble a multipoint collection from input constituents.

Parameters:

args – A list of input Point and MultiPoint objects.

Return type:

MultiPoint

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.LineString(coordinates=None)

Bases: GeometryObject

A geometric line.

property coordinates: ndarray

The coordinate array.

Type:

numpy.ndarray

self_intersection()

Does this self intersect?

Return type:

bool

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

classmethod from_dict(geometry: dict) → LineString

Deserialize from json.

Parameters:

geometry (Dict) –

get_length()

Gets the length of the line.

Return type:

None|float

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → LineString

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.MultiLineString(coordinates=None)

Bases: GeometryObject

A collection of geometric lines.

property lines: List[LineString]

The line collection.

Type:

List[LineString]

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

classmethod from_dict(geometry: Dict) → MultiLineString

Deserialize from json.

Parameters:

geometry (Dict) –

get_length()

Gets the length of the lines.

Return type:

None|float

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → MultiLineString

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

classmethod assemble_from_collection(*args)

Assemble a multiline collection from input constituents.

Parameters:

args – A list of input LineString and MultiLineString objects.

Return type:

MultiLineString

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.LinearRing(coordinates=None)

Bases: LineString

This is not directly a valid geojson member, but plays the role of a single polygonal element, and is only used as a Polygon constituent.

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

property orientation

+1 for positive orientation (counter-clockwise) and -1 for negative orientation (clockwise).

Type:

int

property bounding_box

The bounding box of the form [[x_min, x_max], [y_min, y_max]]. Note that would be extremely misleading for a naively constructed lat/lon polygon crossing the boundary of discontinuity and/or surrounding a pole.

Return type:

numpy.ndarray

get_perimeter()

Gets the perimeter of the linear ring.

Return type:

float

get_area()

Gets the area of the polygon. If a polygon is self-intersecting, then this result may be pathological. A positive value represents a polygon with positive orientation, while a negative value represents a polygon with negative orientation.

Return type:

float

get_centroid()

Gets the centroid of the polygon - note that this may not actually lie in the polygon interior for non-convex polygon. This will result in an undefined value if the polygon is degenerate.

Return type:

numpy.ndarray

property coordinates

Gets the coordinates array.

Return type:

numpy.ndarray

contain_coordinates(pts_x, pts_y, block_size=None)

Determines inclusion of the given points in the interior of the polygon. The methodology here is based on the Jordan curve theorem approach.

** Warning - This method may provide erroneous results for a lat/lon polygon crossing the bound of discontinuity and/or surrounding a pole.**

Note - If the points constitute an x/y grid, then the grid contained method will be much more performant.

Parameters:

  • pts_x (numpy.ndarray|list|tuple|float|int) –

  • pts_y (numpy.ndarray|list|tuple|float|int) –

  • block_size (None|int) – If provided, processing block size. The minimum value used will be 50,000.

Returns:

boolean array indicating inclusion.

Return type:

numpy.ndarray|bool

grid_contained(grid_x, grid_y)

Determines inclusion of a coordinate grid inside the polygon. The coordinate grid is defined by the two one-dimensional coordinate arrays grid_x and grid_y.

Parameters:

  • grid_x (numpy.ndarray) –

  • grid_y (numpy.ndarray) –

Returns:

boolean mask for point inclusion of the grid. Output is of shape (grid_x.size, grid_y.size).

Return type:

numpy.ndarray

apply_projection(proj_method: callable) → LinearRing

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

to_dict(parent_dict=None)

Serialize the LinearRing to json.

Note that the geojson standard requires that the serialized object has positive orientation. In the case of an LinearRing defined with negative orientation, the orientation of the object and the serialized object will be reversed.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

copy()

Make a deep copy of the item.

classmethod from_dict(geometry: dict) → LineString

Deserialize from json.

Parameters:

geometry (Dict) –

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_length()

Gets the length of the line.

Return type:

None|float

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

self_intersection()

Does this self intersect?

Return type:

bool

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.Polygon(coordinates=None)

Bases: GeometryObject

A polygon object consisting of an outer LinearRing, and some collection of interior LinearRings representing holes or voids.

self_intersection()

Does this Polygon self intersect?

Return type:

bool

property outer_ring

The outer ring.

Type:

LinearRing

property inner_rings

The inner rings.

Type:

None|List[LinearRing]

classmethod from_dict(geometry: Dict) → Polygon

Deserialize from json.

Parameters:

geometry (Dict) –

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

set_outer_ring(coordinates)

Set the outer ring for the Polygon.

Parameters:

coordinates (LinearRing|numpy.ndarray|list) –

Return type:

None

get_perimeter()

Gets the perimeter of the linear ring.

Return type:

None|float

get_area()

Gets the area of the polygon.

Return type:

None|float

get_centroid()

Gets the centroid of the outer ring of the polygon - note that this may not actually lie in the polygon interior for non-convex polygon. This will result in an undefined value if the polygon is degenerate.

Return type:

numpy.ndarray

contain_coordinates(pts_x, pts_y, block_size=None)

Determines inclusion of the given points in the interior of the polygon. The methodology here is based on the Jordan curve theorem approach.

** Warning - This method may provide erroneous results for a lat/lon polygon crossing the bound of discontinuity and/or surrounding a pole.**

Note - If the points constitute an x/y grid, then the grid contained method will be much more performant.

Parameters:

  • pts_x (numpy.ndarray|list|tuple|float|int) –

  • pts_y (numpy.ndarray|list|tuple|float|int) –

  • block_size (None|int) – If provided, processing block size. The minimum value used will be 50,000.

Returns:

boolean array indicating inclusion.

Return type:

numpy.ndarray|bool

grid_contained(grid_x, grid_y)

Determines inclusion of a coordinate grid inside the polygon. The coordinate grid is defined by the two one-dimensional coordinate arrays grid_x and grid_y.

Parameters:

  • grid_x (numpy.ndarray) –

  • grid_y (numpy.ndarray) –

Returns:

boolean mask for point inclusion of the grid. Output is of shape (grid_x.size, grid_y.size).

Return type:

numpy.ndarray

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → Polygon

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.geometry.geometry_elements.MultiPolygon(coordinates=None)

Bases: GeometryObject

A collection of polygon objects.

copy()

Make a deep copy of the item.

property is_collection

Is this a collection object?

Type:

bool

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

property polygons: List[Polygon]

The polygon collection.

Type:

List[Polygon]

get_bbox()

Get the bounding box list.

Returns:

Of the form [min coord 0, min coord 1, …, max coord 0, max coord 1, …]/

Return type:

None|List

classmethod from_dict(geometry: Dict) → MultiPolygon

Deserialize from json.

Parameters:

geometry (Dict) –

get_coordinate_list()

The geojson style coordinate list.

Return type:

List

get_perimeter()

Gets the perimeter of the linear ring.

Return type:

None|float

get_area()

Gets the area of the polygon.

Return type:

None|float

contain_coordinates(pts_x, pts_y, block_size=None)

Determines inclusion of the given points in the interior of the polygon. The methodology here is based on the Jordan curve theorem approach.

** Warning - This method may provide erroneous results for a lat/lon polygon crossing the bound of discontinuity and/or surrounding a pole.**

Note - If the points constitute an x/y grid, then the grid contained method will be much more performant.

Parameters:

  • pts_x (numpy.ndarray|list|tuple|float|int) –

  • pts_y (numpy.ndarray|list|tuple|float|int) –

  • block_size (None|int) – If provided, processing block size. The minimum value used will be 50,000.

Returns:

boolean array indicating inclusion.

Return type:

numpy.ndarray|bool

grid_contained(grid_x, grid_y)

Determines inclusion of a coordinate grid inside the polygon. The coordinate grid is defined by the two one-dimensional coordinate arrays grid_x and grid_y.

Parameters:

  • grid_x (numpy.ndarray) –

  • grid_y (numpy.ndarray) –

Returns:

boolean mask for point inclusion of the grid. Output is of shape (grid_x.size, grid_y.size).

Return type:

numpy.ndarray

add_to_kml(doc, parent, coord_transform)

Add the geometry to the kml document. Note that coordinates or transformed coordinates are assumed in longitude, latitude order.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • parent (xml.dom.minidom.Element) –

  • coord_transform (None|callable) –

Return type:

None

apply_projection(proj_method: callable) → MultiPolygon

Gets a new version after applying a transform method.

Parameters:

proj_method (callable) –

Return type:

GeometryObject

get_minimum_distance(point)

Get the minimum distance from the point, to the point or line segments of the given geometrical shape. This just assumes two-dimensional coordinates.

Parameters:

point (Point|numpy.ndarray|tuple|list) –

Return type:

float

classmethod assemble_from_collection(*args)

Assemble a multipolygon collection from input constituents.

Parameters:

args – A list of input Polygon and MultiPolygon objects.

Return type:

MultiPolygon

sarpy.geometry.geometry_elements.basic_assemble_from_collection(*args)

Assemble the most suitable (flat) collective type from the input collection.

Parameters:

args – The input geometry objects.

Return type:

GeometryCollection|MultiPoint|MultiLineString|MultiPolygon