Source: https://gometry.monicz.dev/about/design/

# 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:

```python
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)))
```

```text
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`](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.with_crs "with_crs") assigns metadata;
[`to_crs`](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.to_crs "to_crs") transforms coordinates.
[`force_2d`](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.force_2d "force_2d") and
[`force_3d`](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.force_3d "force_3d") change coordinate dimensions.

### Whole-collection operations

[`union_all`](https://gometry.monicz.dev/api/toplevel/overlay-dissolve/#gometry.union_all "union_all") combines an entire sequence.
Array methods operate row by row: `arr.polygonize()` polygonizes each row,
while [`polygonize_all(arr)`](https://gometry.monicz.dev/api/toplevel/constructive-validation/#gometry.polygonize_all "polygonize_all") pools their linework
into one graph.

### Ragged results

[`Groups`](https://gometry.monicz.dev/api/geometry/coordinates/#gometry.Groups "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)`](https://gometry.monicz.dev/api/crs/#gometry.CRS.to_projjson "to_projjson")
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`](https://gometry.monicz.dev/api/toplevel/io-interop/#gometry.from_wkt "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`](https://gometry.monicz.dev/api/spatial-index/#gometry.SpatialIndex.candidates "candidates") returns bounding-box
matches; [`query`](https://gometry.monicz.dev/api/spatial-index/#gometry.SpatialIndex.query "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`](https://gometry.monicz.dev/ecosystem/numpy/), [Arrow](https://gometry.monicz.dev/ecosystem/arrow/), and
[dataframe adapters](https://gometry.monicz.dev/ecosystem/dataframes/) provide bulk interchange.

## Constructors and grid names

Classes construct individual values; plural functions construct arrays:
[`Point`](https://gometry.monicz.dev/api/geometry/geometry-types/#gometry.Point "Point") and [`points`](https://gometry.monicz.dev/api/toplevel/constructors-bulk-factories/#gometry.points "points"),
[`LineString`](https://gometry.monicz.dev/api/geometry/geometry-types/#gometry.LineString "LineString") and [`line_strings`](https://gometry.monicz.dev/api/toplevel/constructors-bulk-factories/#gometry.line_strings "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](https://gometry.monicz.dev/migrating/cheatsheet/) maps familiar Shapely,
pyproj, H3, S2, and rtree operations to gometry.

For comparisons, choose the meaning you need:

- [`equals`](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.equals "equals"): the same occupied point set.
- [`equals_exact`](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.equals_exact "equals_exact"): coordinates within a tolerance,
  in compatible frames.
- [`equals_identical`](https://gometry.monicz.dev/api/toplevel/predicates/#gometry.equals_identical "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`](https://gometry.monicz.dev/api/crs/#gometry.CRS.same_as "same_as") tests operational equivalence.

## NumPy-native bulk outputs

Dense numeric results are read-only NumPy arrays, geometry results are
[`GeometryArray`](https://gometry.monicz.dev/api/geometry/geometryarray/#gometry.GeometryArray "GeometryArray"), and ragged results are
[`Groups`](https://gometry.monicz.dev/api/geometry/coordinates/#gometry.Groups "Groups"). Text and diagnostics use lists where no dense
shape fits. See [Arrays & performance](https://gometry.monicz.dev/guide/arrays/).

## Errors

Geometry errors derive from [`GeometryError`](https://gometry.monicz.dev/api/errors/#gometry.GeometryError "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](https://gometry.monicz.dev/guide/errors/).

## 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](https://gometry.monicz.dev/guide/geometry/#zm-under-operations).
Interchange formats also differ: WKT/WKB preserve M but not coordinate epochs,
whereas GeoArrow can preserve both. [Text & binary formats](https://gometry.monicz.dev/ecosystem/text-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`](https://gometry.monicz.dev/api/geometry/geometry/#gometry.Geometry.line_merge "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](https://gometry.monicz.dev/ecosystem/arrow/).

For parsing and resource limits, see [Security & untrusted input](https://gometry.monicz.dev/about/security/).
Bundled-component notices are covered by [License](https://gometry.monicz.dev/about/license/).