Dox, nicer naming

qgis · Dec 10, 2019 · 3ae1b27 · 3ae1b27
1 parent d804de0
commit 3ae1b27
Show file tree

Hide file tree

Showing 10 changed files with 56 additions and 27 deletions.
diff --git a/src/core/pal/costcalculator.h b/src/core/pal/costcalculator.h
@@ -75,6 +75,9 @@ namespace pal
     public:
       explicit PolygonCostCalculator( LabelPosition *lp );
 
+      /**
+       * Updates cost.
+       */
       void update( const pal::PointSet *pset );
 
       double getCost();

diff --git a/src/core/pal/labelposition.cpp b/src/core/pal/labelposition.cpp
@@ -433,15 +433,15 @@ void LabelPosition::removeFromIndex( QgsGenericSpatialIndex<LabelPosition> &inde
   double amin[2];
   double amax[2];
   getBoundingBox( amin, amax );
-  index.deleteData( this, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
+  index.remove( this, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
 }
 
 void LabelPosition::insertIntoIndex( QgsGenericSpatialIndex<LabelPosition> &index )
 {
   double amin[2];
   double amax[2];
   getBoundingBox( amin, amax );
-  index.insertData( this, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
+  index.insert( this, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
 }
 
 double LabelPosition::getDistanceToPoint( double xp, double yp ) const

diff --git a/src/core/pal/labelposition.h b/src/core/pal/labelposition.h
@@ -336,9 +336,6 @@ namespace pal
 
       LabelPosition::Quadrant quadrant;
 
-      bool isInConflictSinglePart( const LabelPosition *lp ) const;
-      bool isInConflictMultiPart( const LabelPosition *lp ) const;
-
     private:
       double mCost;
       bool mHasObstacleConflict;
@@ -358,6 +355,9 @@ namespace pal
        */
       double polygonIntersectionCostForParts( PointSet *polygon ) const;
 
+      bool isInConflictSinglePart( const LabelPosition *lp ) const;
+      bool isInConflictMultiPart( const LabelPosition *lp ) const;
+
   };
 
 } // end namespace

diff --git a/src/core/pal/layer.cpp b/src/core/pal/layer.cpp
@@ -260,7 +260,7 @@ void Layer::addFeaturePart( FeaturePart *fpart, const QString &labelText )
   mFeatureParts << fpart;
 
   // add to r-tree for fast spatial access
-  mFeatureIndex.insertData( fpart, fpart->boundingBox() );
+  mFeatureIndex.insert( fpart, fpart->boundingBox() );
 
   // add to hashtable with equally named feature parts
   if ( mMergeLines && !labelText.isEmpty() )
@@ -275,7 +275,7 @@ void Layer::addObstaclePart( FeaturePart *fpart )
   mObstacleParts.append( fpart );
 
   // add to obstacle r-tree
-  mObstacleIndex.insertData( fpart, fpart->boundingBox() );
+  mObstacleIndex.insert( fpart, fpart->boundingBox() );
 }
 
 static FeaturePart *_findConnectedPart( FeaturePart *partCheck, const QVector<FeaturePart *> &otherParts )
@@ -328,11 +328,11 @@ void Layer::joinConnectedFeatures()
         if ( otherPart->mergeWithFeaturePart( partCheck ) )
         {
           // remove the parts we are joining from the index
-          mFeatureIndex.deleteData( partCheck, checkPartBoundsBefore );
-          mFeatureIndex.deleteData( otherPart, otherPartBoundsBefore ) ;
+          mFeatureIndex.remove( partCheck, checkPartBoundsBefore );
+          mFeatureIndex.remove( otherPart, otherPartBoundsBefore ) ;
 
           // reinsert merged line to r-tree (probably not needed)
-          mFeatureIndex.insertData( otherPart, otherPart->boundingBox() );
+          mFeatureIndex.insert( otherPart, otherPart->boundingBox() );
 
           mConnectedFeaturesIds.insert( partCheck->featureId(), connectedFeaturesId );
           mConnectedFeaturesIds.insert( otherPart->featureId(), connectedFeaturesId );
@@ -399,7 +399,7 @@ void Layer::chopFeaturesAtRepeatDistance()
 
     if ( shouldChop )
     {
-      mFeatureIndex.deleteData( fpart.get(), fpart->boundingBox() );
+      mFeatureIndex.remove( fpart.get(), fpart->boundingBox() );
 
       const GEOSCoordSequence *cs = GEOSGeom_getCoordSeq_r( geosctxt, geom );
 
@@ -459,7 +459,7 @@ void Layer::chopFeaturesAtRepeatDistance()
           GEOSGeometry *newgeom = GEOSGeom_createLineString_r( geosctxt, cooSeq );
           FeaturePart *newfpart = new FeaturePart( fpart->feature(), newgeom );
           newFeatureParts.append( newfpart );
-          mFeatureIndex.insertData( newfpart, newfpart->boundingBox() );
+          mFeatureIndex.insert( newfpart, newfpart->boundingBox() );
           repeatParts.push_back( newfpart );
 
           break;
@@ -483,7 +483,7 @@ void Layer::chopFeaturesAtRepeatDistance()
         GEOSGeometry *newgeom = GEOSGeom_createLineString_r( geosctxt, cooSeq );
         FeaturePart *newfpart = new FeaturePart( fpart->feature(), newgeom );
         newFeatureParts.append( newfpart );
-        mFeatureIndex.insertData( newfpart, newfpart->boundingBox() );
+        mFeatureIndex.insert( newfpart, newfpart->boundingBox() );
         part.clear();
         part.push_back( p );
         repeatParts.push_back( newfpart );

diff --git a/src/core/pal/pal.cpp b/src/core/pal/pal.cpp
@@ -156,7 +156,7 @@ std::unique_ptr<Problem> Pal::extract( const QgsRectangle &extent, const QgsGeom
       // Holes of the feature are obstacles
       for ( int i = 0; i < featurePart->getNumSelfObstacles(); i++ )
       {
-        obstacles.insertData( featurePart->getSelfObstacle( i ), featurePart->getSelfObstacle( i )->boundingBox() );
+        obstacles.insert( featurePart->getSelfObstacle( i ), featurePart->getSelfObstacle( i )->boundingBox() );
 
         if ( !featurePart->getSelfObstacle( i )->getHoleOf() )
         {
@@ -219,7 +219,7 @@ std::unique_ptr<Problem> Pal::extract( const QgsRectangle &extent, const QgsGeom
         return false; // do not continue searching
 
       // insert into obstacles
-      obstacles.insertData( featurePart, featurePart->boundingBox() );
+      obstacles.insert( featurePart, featurePart->boundingBox() );
       obstacleCount++;
       return true;
     } );

diff --git a/src/core/pal/problem.cpp b/src/core/pal/problem.cpp
@@ -218,7 +218,7 @@ void Problem::init_sol_falp()
       }
       return true;
     } );
-    mActiveCandidatesIndex.insertData( lp, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
+    mActiveCandidatesIndex.insert( lp, QgsRectangle( amin[0], amin[1], amax[0], amax[1] ) );
   }
 
   if ( mDisplayAll )

diff --git a/src/core/qgsgenericspatialindex.cpp b/src/core/qgsgenericspatialindex.cpp
@@ -79,7 +79,7 @@ template<typename T>
 QgsGenericSpatialIndex<T>::~QgsGenericSpatialIndex() = default;
 
 template<typename T>
-bool QgsGenericSpatialIndex<T>::insertData( const T *data, const QgsRectangle &bounds )
+bool QgsGenericSpatialIndex<T>::insert( const T *data, const QgsRectangle &bounds )
 {
   SpatialIndex::Region r( QgsSpatialIndexUtils::rectangleToRegion( bounds ) );
 
@@ -112,7 +112,7 @@ bool QgsGenericSpatialIndex<T>::insertData( const T *data, const QgsRectangle &b
 }
 
 template<typename T>
-bool QgsGenericSpatialIndex<T>::deleteData( const T *data, const QgsRectangle &bounds )
+bool QgsGenericSpatialIndex<T>::remove( const T *data, const QgsRectangle &bounds )
 {
   SpatialIndex::Region r = QgsSpatialIndexUtils::rectangleToRegion( bounds );
 
@@ -130,10 +130,10 @@ bool QgsGenericSpatialIndex<T>::deleteData( const T *data, const QgsRectangle &b
 }
 
 template<typename T>
-bool QgsGenericSpatialIndex<T>::intersects( const QgsRectangle &rectangle, const std::function<bool ( const T * )> &callback ) const
+bool QgsGenericSpatialIndex<T>::intersects( const QgsRectangle &bounds, const std::function<bool ( const T * )> &callback ) const
 {
   GenericIndexVisitor<T> visitor( callback, mIdToData );
-  SpatialIndex::Region r = QgsSpatialIndexUtils::rectangleToRegion( rectangle );
+  SpatialIndex::Region r = QgsSpatialIndexUtils::rectangleToRegion( bounds );
 
   QMutexLocker locker( &mMutex );
   mRTree->intersectsWithQuery( r, visitor );

diff --git a/src/core/qgsgenericspatialindex.h b/src/core/qgsgenericspatialindex.h
@@ -28,19 +28,45 @@
 
 class QgsRectangle;
 
+/**
+ * \ingroup core
+ * \class QgsGenericSpatialIndex
+ *
+ * A generic rtree spatial index based on a libspatialindex backend.
+ *
+ * \note Not available in Python bindings.
+ * \since QGIS 3.12
+ */
 template <typename T>
 class CORE_EXPORT QgsGenericSpatialIndex
 {
   public:
 
     QgsGenericSpatialIndex();
-
     ~QgsGenericSpatialIndex();
 
-    bool insertData( const T *data, const QgsRectangle &bounds );
-    bool deleteData( const T *data, const QgsRectangle &bounds );
-
-    bool intersects( const QgsRectangle &rectangle, const std::function< bool( const T *data )> &callback ) const;
+    /**
+     * Inserts new \a data into the spatial index, with the specified \a bounds.
+     *
+     * Ownership of \a data is not transferred, and it is the caller's responsibility to ensure that
+     * it exists for the lifetime of the spatial index.
+     */
+    bool insert( const T *data, const QgsRectangle &bounds );
+
+    /**
+     * Removes existing \a data from the spatial index, with the specified \a bounds.
+     *
+     * \a data is not deleted, and it is the caller's responsibility to ensure that
+     * it is appropriately cleaned up.
+     */
+    bool remove( const T *data, const QgsRectangle &bounds );
+
+    /**
+     * Performs an intersection check against the index, for data intersecting the specified \a bounds.
+     *
+     * The \a callback function will be called once for each matching data object encountered.
+     */
+    bool intersects( const QgsRectangle &bounds, const std::function< bool( const T *data )> &callback ) const;
 
   private:
 

diff --git a/src/core/qgslabelsearchtree.cpp b/src/core/qgslabelsearchtree.cpp
@@ -90,7 +90,7 @@ bool QgsLabelSearchTree::insertLabel( pal::LabelPosition *labelPos, QgsFeatureId
   QgsGeometry labelGeometry( QgsGeometry::fromPolygonXY( QVector<QgsPolylineXY>() << cornerPoints ) );
   std::unique_ptr< QgsLabelPosition > newEntry = qgis::make_unique< QgsLabelPosition >( featureId, labelPos->getAlpha() + mMapSettings.rotation(), cornerPoints, bounds,
       labelPos->getWidth(), labelPos->getHeight(), layerName, labeltext, labelfont, labelPos->getUpsideDown(), diagram, pinned, providerId, labelGeometry, isUnplaced );
-  mSpatialIndex.insertData( newEntry.get(), bounds );
+  mSpatialIndex.insert( newEntry.get(), bounds );
   mOwnedPositions.emplace_back( std::move( newEntry ) );
 
   if ( pal::LabelPosition *next = labelPos->getNextPart() )

diff --git a/src/core/qgsspatialindexutils.h b/src/core/qgsspatialindexutils.h
@@ -39,7 +39,7 @@ namespace SpatialIndex
 
 /**
  * \ingroup core
- * \class QgsSpatialIndex
+ * \class QgsSpatialIndexUtils
  *
  * Contains utility functions for working with spatial indexes.
  *