gpf.tools.geometry module

The geometry module contains functions that help working with Esri geometries.

exception gpf.tools.geometry.GeometryError[source]

Bases: ValueError

If the ShapeBuilder cannot create the desired output geometry, a GeometryError is raised.

class gpf.tools.geometry.ShapeBuilder(*args)[source]

Bases: object

Helper class to create Esri geometry objects from arcpy Point or Array objects or coordinate values.

Examples:

>>> # instantiate a 2D PointGeometry
>>> ShapeBuilder(6.5, 2.8).as_point()
<PointGeometry object at 0x19fcbdf0[0x19fcbd80]>

>>> # instantiate a 3D PointGeometry
>>> ShapeBuilder(6.5, 2.8, 5.3).as_point(has_z=True)
<PointGeometry object at 0x6b96210[0x19fcbbe0]>

>>> # make_path a 2D line (append technique)
>>> shp = ShapeBuilder()
>>> shp.append(1.0, 2.0)
>>> shp.append(1.5, 3.0)
>>> shp.as_polyline()
<Polyline object at 0x6a9bb70[0x6fe2540]>

>>> # make_path a 3D polygon from 2D coordinates
>>> shp = ShapeBuilder([(1.0, 2.0), (1.5, 3.0), (2.0, 2.0)])
>>> polygon = shp.as_polygon(has_z=True)
>>> # Z values are added and set to 0
>>> polygon.firstPoint
<Point (1.00012207031, 2.00012207031, 0.0, #)>
>>> # note that the "open" polygons will be closed automatically
>>> polygon.firstPoint == polygon.lastPoint
True
>>> # calling as_point() on a ShapeBuilder with multiple coordinates will return a centroid
>>> shp.as_point()
<Point (1.50012207031, 2.33345540365, #, #)>
append(*args)[source]

Adds a coordinate or coordinate array to the geometry. Valid objects are another ShapeBuilder instance, an ArcPy Point or Array instance, or numeric X, Y, (Z, M, ID) values.

Parameters:args (float, int, arcpy.Point, arcpy.Array, ShapeBuilder) – A valid coordinate object.
Raises:ValueError – If the coordinate object is invalid and cannot be added.

See also

https://desktop.arcgis.com/en/arcmap/latest/analyze/arcpy-classes/point.htm

extend(values: Iterable)[source]

Adds multiple coordinates to the geometry.

Parameters:values (tuple, list) – An iterable of numeric coordinate values, Point, Array or ShapeBuilder objects.
Raises:ValueError – If the values argument is not an iterable.
num_coords

Returns the total number of coordinates in the ShapeBuilder. Note that this does not always return the same value as calling len() on the ShapeBuilder, because num_coords() also counts the coordinates in nested geometry arrays.

as_point(spatial_reference: Union[str, int, arcpy.arcobjects.arcobjects.SpatialReference, None] = None, has_z: bool = False, has_m: bool = False) → arcpy.arcobjects.geometries.PointGeometry[source]

Returns the constructed geometry as an Esri PointGeometry. Note that if the ShapeBuilder holds more than 1 coordinate, a centroid point is returned.

Parameters:
  • spatial_reference (str, int, arcpy.SpatialReference) – An optional spatial reference. Defaults to ‘Unknown’.
  • has_z – If True, the geometry is Z aware. Defaults to False.
  • has_m – If True, the geometry is M aware. Defaults to False.
Raises:

GeometryError – If there is less than 1 coordinate.
as_multipoint(spatial_reference: Union[str, int, arcpy.arcobjects.arcobjects.SpatialReference, None] = None, has_z: bool = False, has_m: bool = False) → arcpy.arcobjects.geometries.Multipoint[source]

Returns the constructed geometry as an Esri Multipoint.

Parameters:
  • spatial_reference (str, int, arcpy.SpatialReference) – An optional spatial reference. Defaults to ‘Unknown’.
  • has_z – If True, the geometry is Z aware. Defaults to False.
  • has_m – If True, the geometry is M aware. Defaults to False.
Raises:

GeometryError – If there are less than 2 coordinates.
as_polyline(spatial_reference: Union[str, int, arcpy.arcobjects.arcobjects.SpatialReference, None] = None, has_z: bool = False, has_m: bool = False) → arcpy.arcobjects.geometries.Polyline[source]

Returns the constructed geometry as an Esri Polyline.

Parameters:
  • spatial_reference (str, int, arcpy.SpatialReference) – An optional spatial reference. Defaults to ‘Unknown’.
  • has_z – If True, the geometry is Z aware. Defaults to False.
  • has_m – If True, the geometry is M aware. Defaults to False.
Raises:

GeometryError – If there are less than 2 coordinates.
as_polygon(spatial_reference: Union[str, int, arcpy.arcobjects.arcobjects.SpatialReference, None] = None, has_z: bool = False, has_m: bool = False) → arcpy.arcobjects.geometries.Polygon[source]

Returns the constructed geometry as an Esri Polygon. If the polygon is not closed, the first coordinate will be added as the last coordinate automatically in order to properly close it.

Parameters:
  • spatial_reference – An optional spatial reference. Defaults to ‘Unknown’.
  • has_z – If True, the geometry is Z aware. Defaults to False.
  • has_m – If True, the geometry is M aware. Defaults to False.
Raises:

ValueError – If there are less than 3 coordinates.
gpf.tools.geometry.get_xyz(*args) → Tuple[float][source]

Returns a floating point coordinate XYZ tuple for a given coordinate. Valid input includes EsriJSON, ArcPy Point or PointGeometry instances or a minimum of 2 floating point values. If the geometry is not Z aware, the Z value in the output tuple will be set to None.

Parameters:args – A tuple of floating point values, an EsriJSON dictionary, an ArcPy Point or PointGeometry instance.

Note

For Point geometries, M and ID values are ignored.

gpf.tools.geometry.get_vertices(geometry) → Generator[source]

Returns a generator of coordinate tuples (x, y[, z] floats) for all vertices in an Esri Geometry. If the geometry is not Z aware, the coordinate tuples will only hold 2 values (X and Y).

Parameters:geometry – The Esri Geometry (e.g. Polygon, Polyline etc.) for which to extract all vertices.