ArborX / Spatial indexes / ArborX::BVH

ArborX::BVH<MemorySpace>::query()

template <typename ExecutionSpace, typename Predicates, typename Callback>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Callback const& callback) const; // (1)

template <typename ExecutionSpace, typename Predicates, typename Indices,
          typename Offsets>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Indices& indices,
           Offsets& offsets) const; // (2)

template <typename ExecutionSpace, typename Predicates, typename Callback,
          typename Values, typename Offsets>
void query(ExecutionSpace const& space,
           Predicates const& predicates,
           Callback const& callback,
           Values& values,
           Offsets& offsets) const; // (3)

  1. Executes callbacks on all found results

For spatial predicates, the call finds all primitives meeting the passed predicates, invoking the callback when a primitive meets a predicate. Conceptually equivalent to

for (auto predicate : predicates)
  for (auto primitive : primitives)
    if (predicate(primitive))
      callback(predicate, primitive);

For nearest predicates, the call finds the specified number of the nearest primitives for each predicate, and invokes callback on those results. Conceptually equivalent to

for (auto predicate : predicates)
  for (auto primitive : k_nearest_primitives_of_predicate)
    callback(predicate, primitive);

  1. Finds all primitives meeting the predicates and record results in {indices, offsets}.

indices stores the indices of the objects that satisfy the predicates. offsets stores the locations in the indices view that start a predicate, that is, predicates(i) is satisfied by primitives(indices(j)) for offsets(i) <= j < offsets(i+1). Following the usual convention, offsets(n) == indices.size(), where n is the number of queries that were performed and indices.size() is the total number of collisions. 3. TODO

Parameters

space

-

execution space that specifies where to execute code

predicates

-

predicates to check against the primitives

callback

-

callable function object to invoke when a primitive satisfies a predicate

indices

-

position of the primitives that satisfy the predicates

offsets

-

predicate offsets in indices

Type requirements

  • MemorySpace must be accessible from ExecutionSpace. (Kokkos::SpaceAccessibility<ExecutionSpace, MemorySpace>::accessible must be true.)

  • A specialization of ArborX::AccessTraits must match the Predicates as first template argument and ArborX::PredicatesTag as second argument.

  • The member type ArborX::AccessTraits<Predicates,ArborX::PredicatesTag>::memory_space must be accessible from ExecutionSpace.

  • The static member function ArborX::AccessTraits<Predicates,ArborX::PredicatesTag>::get() return type must decay to a valid ArborX predicate.

    Such predicate may be generated by one of the functions listed below: * ArborX::nearest() * ArborX::intersects()

  • TODO Callback

  • Indices and Offsets must be (managed) Kokkos views of integral types accessibles from ExecutionSpace.

Return value

(none)

Complexity

O(M log N) where M is the number of predicates (i.e. the value returned by ArborX::AccessTraits<Predicates,ArborX::PredicatesTag>::size(predicates)) and N is the number of primitives stored in the data structure (this->size()).

Exceptions

Memory allocation with Kokkos may throw.

Notes

Example

See also