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