Ambiguities associated to the KdTree Sampling construction scheme

[nmellado]

The KdTree class offers construction methods on a subset of the input point clouds.
This is called sampling: the caller provides a raw buffer of point and a vector of indices. The tree is built by iterating over the indices list.

As for non-sampling cases, the indices used to construct the IndexQueries (meaning I want the closest points of the I-th vertex) and their results (the closest points are at indices ....) are indices in the raw buffer frame: the query caller doesn't need to know if the KdTree is built with sampling or not.

There are several issues with this design:

• The IndexQueries semantics is ambiguous when using subsampling: some users might expect to use indices expressed in the sampling vector frame. The implemented behavior is not described in the documentation.
• Also, it is bit weird to be able to use an InputIndex of a point that is not in the KdTree (and thus, somehow, does not have an index).
• The KnnGraph queries are ambiguous when using KdTree sampling: users can in theory call the graph only from the sampled points. If we respect the IndexQuery formalism, the caller uses the Index in the raw buffer frame: this index needs to be checked, and the query construction aborted if the point is not in the sampling set.

Positive aspects of this design:

• The input point coordinates are never duplicated, and several KdTrees can be built on multiple subsets of points.

Question

Considering the aforementioned aspects, do you have any comment or suggestion to fix/modify/extend the API ?