GEOS 3.11.2
TemplateSTRtree.h
1/**********************************************************************
2 *
3 * GEOS - Geometry Engine Open Source
4 * http://geos.osgeo.org
5 *
6 * Copyright (C) 2020-2021 Daniel Baston
7 *
8 * This is free software; you can redistribute and/or modify it under
9 * the terms of the GNU Lesser General Public Licence as published
10 * by the Free Software Foundation.
11 * See the COPYING file for more information.
12 *
13 **********************************************************************/
14
15#pragma once
16
17#include <geos/geom/Geometry.h>
18#include <geos/index/SpatialIndex.h> // for inheritance
19#include <geos/index/chain/MonotoneChain.h>
20#include <geos/index/ItemVisitor.h>
21#include <geos/util.h>
22
23#include <geos/index/strtree/TemplateSTRNode.h>
24#include <geos/index/strtree/TemplateSTRNodePair.h>
25#include <geos/index/strtree/TemplateSTRtreeDistance.h>
26#include <geos/index/strtree/Interval.h>
27
28#include <vector>
29#include <queue>
30#include <mutex>
31
32namespace geos {
33namespace index {
34namespace strtree {
35
56template<typename ItemType, typename BoundsTraits>
58public:
59 using Node = TemplateSTRNode<ItemType, BoundsTraits>;
60 using NodeList = std::vector<Node>;
61 using NodeListIterator = typename NodeList::iterator;
62 using BoundsType = typename BoundsTraits::BoundsType;
63
64 class Iterator {
65 public:
66 using iterator_category = std::forward_iterator_tag;
67 using value_type = ItemType;
68 using difference_type = typename NodeList::const_iterator::difference_type;
69 using pointer = ItemType*;
70 using reference = ItemType&;
71
72 Iterator(typename NodeList::const_iterator&& iter,
73 typename NodeList::const_iterator&& end) : m_iter(iter), m_end(end) {
74 skipDeleted();
75 }
76
77 const ItemType& operator*() const {
78 return m_iter->getItem();
79 }
80
81 Iterator& operator++() {
82 m_iter++;
83 skipDeleted();
84 return *this;
85 }
86
87 friend bool operator==(const Iterator& a, const Iterator& b) {
88 return a.m_iter == b.m_iter;
89 }
90
91 friend bool operator!=(const Iterator& a, const Iterator& b) {
92 return a.m_iter != b.m_iter;
93 }
94
95 private:
96 void skipDeleted() {
97 while(m_iter != m_end && m_iter->isDeleted()) {
98 m_iter++;
99 }
100 }
101
102 typename NodeList::const_iterator m_iter;
103 typename NodeList::const_iterator m_end;
104 };
105
106 class Items {
107 public:
108 explicit Items(TemplateSTRtreeImpl& tree) : m_tree(tree) {}
109
110 Iterator begin() {
111 return Iterator(m_tree.nodes.cbegin(),
112 std::next(m_tree.nodes.cbegin(), static_cast<long>(m_tree.numItems)));
113 }
114
115 Iterator end() {
116 return Iterator(std::next(m_tree.nodes.cbegin(), static_cast<long>(m_tree.numItems)),
117 std::next(m_tree.nodes.cbegin(), static_cast<long>(m_tree.numItems)));
118 }
119 private:
120 TemplateSTRtreeImpl& m_tree;
121 };
122
125
130 explicit TemplateSTRtreeImpl(size_t p_nodeCapacity = 10) :
131 root(nullptr),
132 nodeCapacity(p_nodeCapacity),
133 numItems(0)
134 {}
135
141 TemplateSTRtreeImpl(size_t p_nodeCapacity, size_t itemCapacity) :
142 root(nullptr),
143 nodeCapacity(p_nodeCapacity),
144 numItems(0) {
145 auto finalSize = treeSize(itemCapacity);
146 nodes.reserve(finalSize);
147 }
148
153 root(other.root),
154 nodeCapacity(other.nodeCapacity),
155 numItems(other.numItems) {
156 nodes = other.nodes;
157 }
158
160 {
161 root = other.root;
162 nodeCapacity = other.nodeCapacity;
163 numItems = other.numItems;
164 nodes = other.nodes;
165 return *this;
166 }
167
171
173 void insert(ItemType&& item) {
174 insert(BoundsTraits::fromItem(item), std::forward<ItemType>(item));
175 }
176
178 void insert(const ItemType& item) {
179 insert(BoundsTraits::fromItem(item), item);
180 }
181
183 void insert(const BoundsType& itemEnv, ItemType&& item) {
184 if (!BoundsTraits::isNull(itemEnv)) {
185 createLeafNode(std::forward<ItemType>(item), itemEnv);
186 }
187 }
188
190 void insert(const BoundsType& itemEnv, const ItemType& item) {
191 if (!BoundsTraits::isNull(itemEnv)) {
192 createLeafNode(item, itemEnv);
193 }
194 }
195
199
201 template<typename ItemDistance>
202 std::pair<ItemType, ItemType> nearestNeighbour(ItemDistance& distance) {
203 return nearestNeighbour(*this, distance);
204 }
205
207 template<typename ItemDistance>
208 std::pair<ItemType, ItemType> nearestNeighbour() {
209 ItemDistance id;
210 return nearestNeighbour(*this);
211 }
212
214 template<typename ItemDistance>
216 ItemDistance & distance) {
217 if (!getRoot() || !other.getRoot()) {
218 return { nullptr, nullptr };
219 }
220
221 TemplateSTRtreeDistance<ItemType, BoundsTraits, ItemDistance> td(distance);
222 return td.nearestNeighbour(*root, *other.root);
223 }
224
226 template<typename ItemDistance>
227 std::pair<ItemType, ItemType> nearestNeighbour(TemplateSTRtreeImpl<ItemType, BoundsTraits>& other) {
228 ItemDistance id;
229 return nearestNeighbour(other, id);
230 }
231
232 template<typename ItemDistance>
233 ItemType nearestNeighbour(const BoundsType& env, const ItemType& item, ItemDistance& itemDist) {
234 build();
235
236 if (getRoot() == nullptr) {
237 return nullptr;
238 }
239
240 TemplateSTRNode<ItemType, BoundsTraits> bnd(item, env);
241 TemplateSTRNodePair<ItemType, BoundsTraits, ItemDistance> pair(*getRoot(), bnd, itemDist);
242
243 TemplateSTRtreeDistance<ItemType, BoundsTraits, ItemDistance> td(itemDist);
244 return td.nearestNeighbour(pair).first;
245 }
246
247 template<typename ItemDistance>
248 ItemType nearestNeighbour(const BoundsType& env, const ItemType& item) {
249 ItemDistance id;
250 return nearestNeighbour(env, item, id);
251 }
252
256
257 // Query the tree using the specified visitor. The visitor must be callable
258 // either with a single argument of `const ItemType&` or with the
259 // arguments `(const BoundsType&, const ItemType&).
260 // The visitor need not return a value, but if it does return a value,
261 // false values will be taken as a signal to stop the query.
262 template<typename Visitor>
263 void query(const BoundsType& queryEnv, Visitor &&visitor) {
264 if (!built()) {
265 build();
266 }
267
268 if (root && root->boundsIntersect(queryEnv)) {
269 if (root->isLeaf()) {
270 visitLeaf(visitor, *root);
271 } else {
272 query(queryEnv, *root, visitor);
273 }
274 }
275 }
276
277 // Query the tree and collect items in the provided vector.
278 void query(const BoundsType& queryEnv, std::vector<ItemType>& results) {
279 query(queryEnv, [&results](const ItemType& x) {
280 results.push_back(x);
281 });
282 }
283
287 Items items() {
288 build();
289 return Items(*this);
290 }
291
296 template<typename F>
297 void iterate(F&& func) {
298 auto n = built() ? numItems : nodes.size();
299 for (size_t i = 0; i < n; i++) {
300 if (!nodes[i].isDeleted()) {
301 func(nodes[i].getItem());
302 }
303 }
304 }
305
309
310 bool remove(const BoundsType& itemEnv, const ItemType& item) {
311 build();
312
313 if (root == nullptr) {
314 return false;
315 }
316
317 if (root->isLeaf()) {
318 if (!root->isDeleted() && root->getItem() == item) {
319 root->removeItem();
320 return true;
321 }
322 return false;
323 }
324
325 return remove(itemEnv, *root, item);
326 }
327
331
333 bool built() const {
334 return root != nullptr;
335 }
336
338 const Node* getRoot() {
339 build();
340 return root;
341 }
342
344
346 void build() {
347 std::lock_guard<std::mutex> lock(lock_);
348
349 if (built()) {
350 return;
351 }
352
353 if (nodes.empty()) {
354 return;
355 }
356
357 numItems = nodes.size();
358
359 // compute final size of tree and set it aside in a single
360 // block of memory
361 auto finalSize = treeSize(numItems);
362 nodes.reserve(finalSize);
363
364 // begin and end define a range of nodes needing parents
365 auto begin = nodes.begin();
366 auto number = static_cast<size_t>(std::distance(begin, nodes.end()));
367
368 while (number > 1) {
369 createParentNodes(begin, number);
370 std::advance(begin, static_cast<long>(number)); // parents just added become children in the next round
371 number = static_cast<size_t>(std::distance(begin, nodes.end()));
372 }
373
374 assert(finalSize == nodes.size());
375
376 root = &nodes.back();
377 }
378
379protected:
380 std::mutex lock_;
381 NodeList nodes; //**< a list of all leaf and branch nodes in the tree. */
382 Node* root; //**< a pointer to the root node, if the tree has been built. */
383 size_t nodeCapacity; //*< maximum number of children of each node */
384 size_t numItems; //*< total number of items in the tree, if it has been built. */
385
386 // Prevent instantiation of base class.
387 // ~TemplateSTRtreeImpl() = default;
388
389 void createLeafNode(ItemType&& item, const BoundsType& env) {
390 nodes.emplace_back(std::forward<ItemType>(item), env);
391 }
392
393 void createLeafNode(const ItemType& item, const BoundsType& env) {
394 nodes.emplace_back(item, env);
395 }
396
397 void createBranchNode(const Node *begin, const Node *end) {
398 assert(nodes.size() < nodes.capacity());
399 nodes.emplace_back(begin, end);
400 }
401
402 // calculate what the tree size will be when it is build. This is simply
403 // a version of createParentNodes that doesn't actually create anything.
404 size_t treeSize(size_t numLeafNodes) {
405 size_t nodesInTree = numLeafNodes;
406
407 size_t nodesWithoutParents = numLeafNodes;
408 while (nodesWithoutParents > 1) {
409 auto numSlices = sliceCount(nodesWithoutParents);
410 auto nodesPerSlice = sliceCapacity(nodesWithoutParents, numSlices);
411
412 size_t parentNodesAdded = 0;
413 for (size_t j = 0; j < numSlices; j++) {
414 auto nodesInSlice = std::min(nodesWithoutParents, nodesPerSlice);
415 nodesWithoutParents -= nodesInSlice;
416
417 parentNodesAdded += static_cast<size_t>(std::ceil(
418 static_cast<double>(nodesInSlice) / static_cast<double>(nodeCapacity)));
419 }
420
421 nodesInTree += parentNodesAdded;
422 nodesWithoutParents = parentNodesAdded;
423 }
424
425 return nodesInTree;
426 }
427
428 void createParentNodes(const NodeListIterator& begin, size_t number) {
429 // Arrange child nodes in two dimensions.
430 // First, divide them into vertical slices of a given size (left-to-right)
431 // Then create nodes within those slices (bottom-to-top)
432 auto numSlices = sliceCount(number);
433 std::size_t nodesPerSlice = sliceCapacity(number, numSlices);
434
435 // We could sort all of the nodes here, but we don't actually need them to be
436 // completely sorted. They need to be sorted enough for each node to end up
437 // in the right vertical slice, but their relative position within the slice
438 // doesn't matter. So we do a partial sort for each slice below instead.
439 auto end = begin + static_cast<long>(number);
440 sortNodesX(begin, end);
441
442 auto startOfSlice = begin;
443 for (decltype(numSlices) j = 0; j < numSlices; j++) {
444 // end iterator is being invalidated at each iteration
445 end = begin + static_cast<long>(number);
446 auto nodesRemaining = static_cast<size_t>(std::distance(startOfSlice, end));
447 auto nodesInSlice = std::min(nodesRemaining, nodesPerSlice);
448 auto endOfSlice = std::next(startOfSlice, static_cast<long>(nodesInSlice));
449
450 // Make sure that every node that should be in this slice ends up somewhere
451 // between startOfSlice and endOfSlice. We don't require any ordering among
452 // nodes between startOfSlice and endOfSlice.
453 //partialSortNodes(startOfSlice, endOfSlice, end);
454
455 addParentNodesFromVerticalSlice(startOfSlice, endOfSlice);
456
457 startOfSlice = endOfSlice;
458 }
459 }
460
461 void addParentNodesFromVerticalSlice(const NodeListIterator& begin, const NodeListIterator& end) {
462 if (BoundsTraits::TwoDimensional::value) {
463 sortNodesY(begin, end);
464 }
465
466 // Arrange the nodes vertically and full up parent nodes sequentially until they're full.
467 // A possible improvement would be to rework this such so that if we have 81 nodes we
468 // put 9 into each parent instead of 10 or 1.
469 auto firstChild = begin;
470 while (firstChild != end) {
471 auto childrenRemaining = static_cast<size_t>(std::distance(firstChild, end));
472 auto childrenForNode = std::min(nodeCapacity, childrenRemaining);
473 auto lastChild = std::next(firstChild, static_cast<long>(childrenForNode));
474
475 //partialSortNodes(firstChild, lastChild, end);
476
477 // Ideally we would be able to store firstChild and lastChild instead of
478 // having to convert them to pointers, but I wasn't sure how to access
479 // the NodeListIterator type from within Node without creating some weird
480 // circular dependency.
481 const Node *ptr_first = &*firstChild;
482 const Node *ptr_end = ptr_first + childrenForNode;
483
484 createBranchNode(ptr_first, ptr_end);
485 firstChild = lastChild;
486 }
487 }
488
489 void sortNodesX(const NodeListIterator& begin, const NodeListIterator& end) {
490 std::sort(begin, end, [](const Node &a, const Node &b) {
491 return BoundsTraits::getX(a.getBounds()) < BoundsTraits::getX(b.getBounds());
492 });
493 }
494
495 void sortNodesY(const NodeListIterator& begin, const NodeListIterator& end) {
496 std::sort(begin, end, [](const Node &a, const Node &b) {
497 return BoundsTraits::getY(a.getBounds()) < BoundsTraits::getY(b.getBounds());
498 });
499 }
500
501 // Helper function to visit an item using a visitor that has no return value.
502 // In this case, we will always return true, indicating that querying should
503 // continue.
504 template<typename Visitor,
505 typename std::enable_if<std::is_void<decltype(std::declval<Visitor>()(std::declval<ItemType>()))>::value, std::nullptr_t>::type = nullptr >
506 bool visitLeaf(Visitor&& visitor, const Node& node)
507 {
508 visitor(node.getItem());
509 return true;
510 }
511
512 // MSVC 2015 does not implement C++11 expression SFINAE and considers this a
513 // redefinition of a previous method
514#if !defined(_MSC_VER) || _MSC_VER >= 1910
515 template<typename Visitor,
516 typename std::enable_if<std::is_void<decltype(std::declval<Visitor>()(std::declval<BoundsType>(), std::declval<ItemType>()))>::value, std::nullptr_t>::type = nullptr >
517 bool visitLeaf(Visitor&& visitor, const Node& node)
518 {
519 visitor(node.getBounds(), node.getItem());
520 return true;
521 }
522#endif
523
524 // If the visitor function does return a value, we will use this to indicate
525 // that querying should continue.
526 template<typename Visitor,
527 typename std::enable_if<!std::is_void<decltype(std::declval<Visitor>()(std::declval<ItemType>()))>::value, std::nullptr_t>::type = nullptr>
528 bool visitLeaf(Visitor&& visitor, const Node& node)
529 {
530 return visitor(node.getItem());
531 }
532
533 // MSVC 2015 does not implement C++11 expression SFINAE and considers this a
534 // redefinition of a previous method
535#if !defined(_MSC_VER) || _MSC_VER >= 1910
536 template<typename Visitor,
537 typename std::enable_if<!std::is_void<decltype(std::declval<Visitor>()(std::declval<BoundsType>(), std::declval<ItemType>()))>::value, std::nullptr_t>::type = nullptr>
538 bool visitLeaf(Visitor&& visitor, const Node& node)
539 {
540 return visitor(node.getBounds(), node.getItem());
541 }
542#endif
543
544 template<typename Visitor>
545 bool query(const BoundsType& queryEnv,
546 const Node& node,
547 Visitor&& visitor) {
548
549 assert(!node.isLeaf());
550
551 for (auto *child = node.beginChildren(); child < node.endChildren(); ++child) {
552 if (child->boundsIntersect(queryEnv)) {
553 if (child->isLeaf()) {
554 if (!child->isDeleted()) {
555 if (!visitLeaf(visitor, *child)) {
556 return false; // abort query
557 }
558 }
559 } else {
560 if (!query(queryEnv, *child, visitor)) {
561 return false; // abort query
562 }
563 }
564 }
565 }
566 return true; // continue searching
567 }
568
569 bool remove(const BoundsType& queryEnv,
570 const Node& node,
571 const ItemType& item) {
572
573 assert(!node.isLeaf());
574
575 for (auto *child = node.beginChildren(); child < node.endChildren(); ++child) {
576 if (child->boundsIntersect(queryEnv)) {
577 if (child->isLeaf()) {
578 if (!child->isDeleted() && child->getItem() == item) {
579 // const cast is ugly, but alternative seems to be to remove all
580 // const qualifiers in Node and open up mutability everywhere?
581 auto mutableChild = const_cast<Node*>(child);
582 mutableChild->removeItem();
583 return true;
584 }
585 } else {
586 bool removed = remove(queryEnv, *child, item);
587 if (removed) {
588 return true;
589 }
590 }
591 }
592 }
593
594 return false;
595 }
596
597 size_t sliceCount(size_t numNodes) const {
598 double minLeafCount = std::ceil(static_cast<double>(numNodes) / static_cast<double>(nodeCapacity));
599
600 return static_cast<size_t>(std::ceil(std::sqrt(minLeafCount)));
601 }
602
603 static size_t sliceCapacity(size_t numNodes, size_t numSlices) {
604 return static_cast<size_t>(std::ceil(static_cast<double>(numNodes) / static_cast<double>(numSlices)));
605 }
606};
607
608struct EnvelopeTraits {
609 using BoundsType = geom::Envelope;
610 using TwoDimensional = std::true_type;
611
612 static bool intersects(const BoundsType& a, const BoundsType& b) {
613 return a.intersects(b);
614 }
615
616 static double size(const BoundsType& a) {
617 return a.getArea();
618 }
619
620 static double distance(const BoundsType& a, const BoundsType& b) {
621 return a.distance(b);
622 }
623
624 static BoundsType empty() {
625 return {};
626 }
627
628 template<typename ItemType>
629 static const BoundsType& fromItem(const ItemType& i) {
630 return *(i->getEnvelopeInternal());
631 }
632
633 template<typename ItemType>
634 static const BoundsType& fromItem(ItemType&& i) {
635 return *(i->getEnvelopeInternal());
636 }
637
638 static double getX(const BoundsType& a) {
639 return a.getMinX() + a.getMaxX();
640 }
641
642 static double getY(const BoundsType& a) {
643 return a.getMinY() + a.getMaxY();
644 }
645
646 static void expandToInclude(BoundsType& a, const BoundsType& b) {
647 a.expandToInclude(b);
648 }
649
650 static bool isNull(const BoundsType& a) {
651 return a.isNull();
652 }
653};
654
655struct IntervalTraits {
656 using BoundsType = Interval;
657 using TwoDimensional = std::false_type;
658
659 static bool intersects(const BoundsType& a, const BoundsType& b) {
660 return a.intersects(&b);
661 }
662
663 static double size(const BoundsType& a) {
664 return a.getWidth();
665 }
666
667 static double getX(const BoundsType& a) {
668 return a.getMin() + a.getMax();
669 }
670
671 static double getY(const BoundsType& a) {
672 return a.getMin() + a.getMax();
673 }
674
675 static void expandToInclude(BoundsType& a, const BoundsType& b) {
676 a.expandToInclude(&b);
677 }
678
679 static bool isNull(const BoundsType& a) {
680 (void) a;
681 return false;
682 }
683};
684
685
686template<typename ItemType, typename BoundsTraits = EnvelopeTraits>
687class TemplateSTRtree : public TemplateSTRtreeImpl<ItemType, BoundsTraits> {
688public:
689 using TemplateSTRtreeImpl<ItemType, BoundsTraits>::TemplateSTRtreeImpl;
690};
691
692// When ItemType is a pointer and our bounds are geom::Envelope, adopt
693// the SpatialIndex interface which requires queries via an envelope
694// and items to be representable as void*.
695template<typename ItemType>
696class TemplateSTRtree<ItemType*, EnvelopeTraits> : public TemplateSTRtreeImpl<ItemType*, EnvelopeTraits>, public SpatialIndex {
697public:
698 using TemplateSTRtreeImpl<ItemType*, EnvelopeTraits>::TemplateSTRtreeImpl;
699 using TemplateSTRtreeImpl<ItemType*, EnvelopeTraits>::insert;
700 using TemplateSTRtreeImpl<ItemType*, EnvelopeTraits>::query;
701 using TemplateSTRtreeImpl<ItemType*, EnvelopeTraits>::remove;
702
703 // The SpatialIndex methods only work when we are storing a pointer type.
704 void query(const geom::Envelope* queryEnv, std::vector<void*>& results) override {
705 query(*queryEnv, [&results](const ItemType* x) {
706 results.push_back(const_cast<void*>(static_cast<const void*>(x)));
707 });
708 }
709
710 void query(const geom::Envelope* queryEnv, ItemVisitor& visitor) override {
711 query(*queryEnv, [&visitor](const ItemType* x) {
712 visitor.visitItem(const_cast<void*>(static_cast<const void*>(x)));
713 });
714 }
715
716 bool remove(const geom::Envelope* itemEnv, void* item) override {
717 return remove(*itemEnv, static_cast<ItemType*>(item));
718 }
719
720 void insert(const geom::Envelope* itemEnv, void* item) override {
721 insert(*itemEnv, std::move(static_cast<ItemType*>(item)));
722 }
723};
724
725
726}
727}
728}
A function method which computes the distance between two ItemBoundables in an STRtree....
Definition: ItemDistance.h:33
A query-only R-tree created using the Sort-Tile-Recursive (STR) algorithm. For one- or two-dimensiona...
Definition: TemplateSTRtree.h:57
void build()
Definition: TemplateSTRtree.h:346
std::pair< ItemType, ItemType > nearestNeighbour(TemplateSTRtreeImpl< ItemType, BoundsTraits > &other)
Definition: TemplateSTRtree.h:227
std::pair< ItemType, ItemType > nearestNeighbour()
Definition: TemplateSTRtree.h:208
std::pair< ItemType, ItemType > nearestNeighbour(TemplateSTRtreeImpl< ItemType, BoundsTraits > &other, ItemDistance &distance)
Definition: TemplateSTRtree.h:215
std::pair< ItemType, ItemType > nearestNeighbour(ItemDistance &distance)
Definition: TemplateSTRtree.h:202
TemplateSTRtreeImpl(size_t p_nodeCapacity=10)
Definition: TemplateSTRtree.h:130
TemplateSTRtreeImpl(size_t p_nodeCapacity, size_t itemCapacity)
Definition: TemplateSTRtree.h:141
TemplateSTRtreeImpl(const TemplateSTRtreeImpl &other)
Definition: TemplateSTRtree.h:152
void insert(const BoundsType &itemEnv, const ItemType &item)
Definition: TemplateSTRtree.h:190
void insert(const ItemType &item)
Definition: TemplateSTRtree.h:178
void insert(ItemType &&item)
Definition: TemplateSTRtree.h:173
void insert(const BoundsType &itemEnv, ItemType &&item)
Definition: TemplateSTRtree.h:183
bool built() const
Definition: TemplateSTRtree.h:333
const Node * getRoot()
Definition: TemplateSTRtree.h:338
void iterate(F &&func)
Definition: TemplateSTRtree.h:297
Items items()
Definition: TemplateSTRtree.h:287
Basic namespace for all GEOS functionalities.
Definition: geos.h:39