Predicates
==========
Defined in header `<ArborX_Predicates.hpp> <https://github.com/arborx/ArborX/blob/master/src/spatial/detail/ArborX_Predicates.hpp>`_

A predicate describes what a spatial index ``query()`` should look for.
Predicates are not created directly: they are generated by the functions
listed below, and have an unspecified type.

.. list-table::
   :header-rows: 1
   :widths: 30 20 50

   * - Function
     - Kind
     - Selects
   * - :doc:`intersects <predicates/intersects>`
     - spatial
     - all the values whose indexable intersects a geometry
   * - :doc:`nearest <predicates/nearest>`
     - nearest
     - the ``k`` values whose indexables are the closest to a geometry
   * - ``Experimental::ordered_intersects``
     - ordered spatial (experimental)
     - all the values whose indexable intersects a geometry, visited by
       increasing distance from that geometry

The kind of a predicate determines how the search is performed and which
:doc:`callbacks <Callbacks>` are valid.

* A *spatial* predicate selects every value that satisfies a spatial relation
  with a geometry, in no particular order.
* A *nearest* predicate selects a fixed number of values based on their
  distance to a geometry.
* An *ordered spatial* predicate selects the same values as its spatial
  counterpart, but the callback is invoked on them by increasing distance from
  the geometry.
  Combined with an early exit from the callback, this makes it possible to stop
  at the first values found, e.g., along a ray.
  This kind is experimental and its interface may change.

.. note::

   :cpp:func:`intersects` is currently the only spatial predicate provided.
   Other spatial relations could be supported in the future, such as the
   ``contains``, ``within``, or ``covered_by`` relations found in
   `Boost.Geometry <https://www.boost.org/doc/libs/release/libs/geometry/doc/html/geometry/reference/algorithms.html>`_.

Using predicates
----------------
A set of predicates is passed to ``query()`` through
:cpp:struct:`AccessTraits`: the specialization provides the number of
predicates and gets the ``i``-th one.
For the common case where the predicates are derived from a set of geometries,
the pages above document helper functions that generate the whole set at once,
e.g., ``ArborX::Experimental::make_intersects(geometries)``.
An equivalent ``ArborX::Experimental::make_ordered_intersects(geometries)``
exists for ordered spatial predicates.

.. toctree::
   :hidden:

   predicates/intersects
   predicates/nearest

See also
--------
* :cpp:func:`BoundingVolumeHierarchy::query`
* :doc:`Callbacks <Callbacks>`
* :doc:`AccessTraits <AccessTraits>`