Spatial Operators

This module defines a Comparator class for use with geometry and geography objects.

This is where spatial operators, like &&, &<, are defined. Spatial operators very often apply to the bounding boxes of geometries. For example, geom1 && geom2 indicates if geom1’s bounding box intersects geom2’s.

Examples

Select the objects whose bounding boxes are to the left of the bounding box of POLYGON((-5 45,5 45,5 -45,-5 -45,-5 45)):

select([table]).where(table.c.geom.to_left(
    'POLYGON((-5 45,5 45,5 -45,-5 -45,-5 45))'))

The << and >> operators are a bit specific, because they have corresponding Python operator (__lshift__ and __rshift__). The above SELECT expression can thus be rewritten like this:

select([table]).where(
    table.c.geom << 'POLYGON((-5 45,5 45,5 -45,-5 -45,-5 45))')

Operators can also be used when using the ORM. For example:

Session.query(Cls).filter(
    Cls.geom << 'POLYGON((-5 45,5 45,5 -45,-5 -45,-5 45))')

Now some other examples with the <#> operator.

Select the ten objects that are the closest to POINT(0 0) (typical closed neighbors problem):

select([table]).order_by(table.c.geom.distance_box('POINT(0 0)')).limit(10)

Using the ORM:

Session.query(Cls).order_by(Cls.geom.distance_box('POINT(0 0)')).limit(10)

class geoalchemy2.comparator.BaseComparator(expr: ColumnElement[_CT])

Bases: Comparator

A custom comparator base class.

It adds the ability to call spatial functions on columns that use this kind of comparator. It also defines functions that map to operators supported by Geometry, Geography and Raster columns.

This comparator is used by the geoalchemy2.types.Raster.

__weakref__

list of weak references to the object

intersects(other: str | WKBElement | WKTElement) → ColumnElement

The && operator. A’s BBOX intersects B’s.

overlaps_or_to_left(other: str | WKBElement | WKTElement) → ColumnElement

The &< operator. A’s BBOX overlaps or is to the left of B’s.

overlaps_or_to_right(other: str | WKBElement | WKTElement) → ColumnElement

The &> operator. A’s BBOX overlaps or is to the right of B’s.

class geoalchemy2.comparator.Comparator(expr: ColumnElement[_CT])

Bases: BaseComparator

A custom comparator class.

Used in geoalchemy2.types.Geometry and geoalchemy2.types.Geography.

This is where spatial operators like << and <-> are defined.

__lshift__(other: str | WKBElement | WKTElement) → ColumnElement

The << operator.

A’s BBOX is strictly to the left of B’s.

Same as to_left, so:

table.c.geom << 'POINT(1 2)'

is the same as:

table.c.geom.to_left('POINT(1 2)')

__rshift__(other: str | WKBElement | WKTElement) → ColumnElement

The >> operator.

A’s BBOX is strictly to the left of B’s.

Same as to_`right`, so:

table.c.geom >> 'POINT(1 2)'

is the same as:

table.c.geom.to_right('POINT(1 2)')

above(other: str | WKBElement | WKTElement) → ColumnElement

The |>> operator.

A’s BBOX is strictly above B’s.

below(other: str | WKBElement | WKTElement) → ColumnElement

The <<| operator.

A’s BBOX is strictly below B’s.

contained(other: str | WKBElement | WKTElement) → ColumnElement

The @ operator.

A’s BBOX is contained by B’s.

contains(other: str | WKBElement | WKTElement, **kw) → ColumnElement

The ~ operator.

A’s BBOX contains B’s.

distance_box(other: str | WKBElement | WKTElement) → ColumnElement

The <#> operator.

The distance between bounding box of two geometries.

distance_centroid(other: str | WKBElement | WKTElement) → ColumnElement

The <-> operator.

The distance between two points.

intersects_nd(other: str | WKBElement | WKTElement) → ColumnElement

The &&& operator.

This operator returns TRUE if the n-D bounding box of geometry A intersects the n-D bounding box of geometry B.

overlaps_or_above(other: str | WKBElement | WKTElement) → ColumnElement

The |&> operator.

A’s BBOX overlaps or is above B’s.

overlaps_or_below(other: str | WKBElement | WKTElement) → ColumnElement

The &<| operator.

A’s BBOX overlaps or is below B’s.

same(other: str | WKBElement | WKTElement) → ColumnElement

The ~= operator.

A’s BBOX is the same as B’s.

to_left(other: str | WKBElement | WKTElement) → ColumnElement

The << operator.

A’s BBOX is strictly to the left of B’s.

to_right(other: str | WKBElement | WKTElement) → ColumnElement

The >> operator.

A’s BBOX is strictly to the right of B’s.