API conventions¶

gometry uses a few naming conventions so you can predict how an unfamiliar operation works.

Calls and results¶

Properties, methods, and functions¶

Facts are properties, unary operations are methods, and binary relationships are free functions:

import gometry as gm

point = gm.Point(1, 2)
print(point.area)
print(point.buffer(1).geometry_type)
print(gm.distance(point, gm.Point(4, 6)))

0.0
Polygon
5.0

Without a CRS, distances and buffers use raw coordinate units.

Immutable values and conversions¶

with_<field> returns a changed copy, to_<format> serializes, and from_<format> parses. with_crs assigns metadata; to_crs transforms coordinates. force_2d and force_3d change coordinate dimensions.

Whole-collection operations¶

union_all combines an entire sequence. Array methods operate row by row: arr.polygonize() polygonizes each row, while polygonize_all(arr) pools their linework into one graph.

Ragged results¶

Groups preserves the association between source rows and ragged results. A missing row is None; a present row with no results is an empty group.

Output options¶

Options such as CRS.to_projjson(as_dict=True) keep related outputs under one name. Type annotations narrow the result when you choose an option explicitly.

Scalar and array inputs¶

For example, from_wkt accepts one string or a sequence. Binary operations broadcast a scalar against an array, or pair equal-length arrays row by row. Unequal array lengths are an error.

Type annotations¶

Annotations track geometry kind, missing values, and scalar versus array results. A point's buffer is a polygon; buffering an array with missing rows preserves those missing rows.

Candidates and exact matches¶

SpatialIndex.candidates returns bounding-box matches; query refines them with an exact predicate. Grid covers likewise select cells, not exact geometry membership. Use a predicate on the source geometry when membership matters.

Python protocols¶

Geometry values support a & b, str(geom), formatting, pattern matching, hashing, and equality. Arrays support indexing, slicing, and iteration. NumPy, Arrow, and dataframe adapters provide bulk interchange.

Constructors and grid names¶

Classes construct individual values; plural functions construct arrays: Point and points, LineString and line_strings.

Grid functions use h3_, s2_, geohash_, and tile_ prefixes. Their granularity parameters retain the familiar domain names: resolution, level, precision, and zoom, respectively.

Equality and comparison¶

The migration cheatsheet maps familiar Shapely, pyproj, H3, S2, and rtree operations to gometry.

For comparisons, choose the meaning you need:

equals: the same occupied point set.
equals_exact: coordinates within a tolerance, in compatible frames.
equals_identical: the same coordinates, CRS, and epoch. Python == uses this value equality.

GeometryArray == GeometryArray compares whole arrays and returns one bool. Use equals_identical(left, right) for elementwise comparison. For CRS values, == compares stored definitions; CRS.same_as tests operational equivalence.

NumPy-native bulk outputs¶

Dense numeric results are read-only NumPy arrays, geometry results are GeometryArray, and ragged results are Groups. Text and diagnostics use lists where no dense shape fits. See Arrays & performance.

Errors¶

Geometry errors derive from GeometryError, itself a ValueError. More specific exceptions let you distinguish malformed input, CRS conflicts, transformation failures, and invalid geometry. Ordinary Python protocol errors retain their built-in types. See Errors & exceptions.

Z and M layouts¶

XY, XYZ, XYM, and XYZM are supported. Whether an operation preserves, computes, or drops Z/M depends on the operation; see Geometry & dimensions. Interchange formats also differ: WKT/WKB preserve M but not coordinate epochs, whereas GeoArrow can preserve both. Text & binary formats explains the choices.

Overlay linework and point-set presentation¶

Overlay joins linework through degree-two nodes and splits at genuine junctions. A line clipped by a covering polygon therefore remains one line. line_merge applies the same rule to independent linework.

The Arrow / GeoArrow boundary¶

Homogeneous geometry arrays use GeoArrow-compatible coordinate buffers. Mixed types, collections, or layouts without a native representation use WKB fallback. Dataframes and databases remain separate from the geometry engine; see Arrow & storage.

For parsing and resource limits, see Security & untrusted input. Bundled-component notices are covered by License.