/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsspatialindex.h                                           *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/









class QgsSpatialIndex : QgsFeatureSink
{
%Docstring(signature="appended")
A spatial index for :py:class:`QgsFeature` objects.

:py:class:`QgsSpatialIndex` objects are implicitly shared and can be
inexpensively copied.

.. note::

   While the underlying libspatialindex is not thread safe on some platforms, the :py:class:`QgsSpatialIndex`
   class implements its own locks and accordingly, a single :py:class:`QgsSpatialIndex` object can safely
   be used across multiple threads.

.. seealso:: :py:class:`QgsSpatialIndexKDBush` which is an optimised non-mutable index for point geometries only.

.. seealso:: :py:class:`QgsMeshSpatialIndex` which is for mesh faces
%End

%TypeHeaderCode
#include "qgsspatialindex.h"
%End
  public:


    enum Flag /BaseType=IntEnum/
    {
      FlagStoreFeatureGeometries,
    };
    typedef QFlags<QgsSpatialIndex::Flag> Flags;


    QgsSpatialIndex( QgsSpatialIndex::Flags flags = QgsSpatialIndex::Flags() );
%Docstring
Constructor for QgsSpatialIndex. Creates an empty R-tree index.
%End

    explicit QgsSpatialIndex( const QgsFeatureIterator &fi, QgsFeedback *feedback = 0, QgsSpatialIndex::Flags flags = QgsSpatialIndex::Flags() );
%Docstring
Constructor - creates R-tree and bulk loads it with features from the
iterator. This is much faster approach than creating an empty index and
then inserting features one by one.

The optional ``feedback`` object can be used to allow cancellation of
bulk feature loading. Ownership of ``feedback`` is not transferred, and
callers must take care that the lifetime of feedback exceeds that of the
spatial index construction.
%End


    explicit QgsSpatialIndex( const QgsFeatureSource &source, QgsFeedback *feedback = 0, QgsSpatialIndex::Flags flags = QgsSpatialIndex::Flags() );
%Docstring
Constructor - creates R-tree and bulk loads it with features from the
source. This is much faster approach than creating an empty index and
then inserting features one by one.

The optional ``feedback`` object can be used to allow cancellation of
bulk feature loading. Ownership of ``feedback`` is not transferred, and
callers must take care that the lifetime of feedback exceeds that of the
spatial index construction.
%End

    QgsSpatialIndex( const QgsSpatialIndex &other );

    ~QgsSpatialIndex();



 bool insertFeature( const QgsFeature &feature ) /Deprecated/;
%Docstring
Adds a ``feature`` to the index.

.. deprecated:: 3.40

   Use :py:func:`~QgsSpatialIndex.addFeature` instead.
%End

    virtual bool addFeature( QgsFeature &feature, QgsFeatureSink::Flags flags = QgsFeatureSink::Flags() );

%Docstring
Adds a ``feature`` to the index.

The ``flags`` argument is ignored.

.. versionadded:: 3.4
%End

    virtual bool addFeatures( QgsFeatureList &features, QgsFeatureSink::Flags flags = QgsFeatureSink::Flags() );

%Docstring
Adds a list of ``features`` to the index.

The ``flags`` argument is ignored.

.. seealso:: :py:func:`addFeature`
%End

 bool insertFeature( QgsFeatureId id, const QgsRectangle &bounds ) /Deprecated/;
%Docstring
Add a feature ``id`` to the index with a specified bounding box.

:return: ``True`` if feature was successfully added to index.

.. deprecated:: 3.40

   Use :py:func:`~QgsSpatialIndex.addFeature` instead.
%End

    bool addFeature( QgsFeatureId id, const QgsRectangle &bounds );
%Docstring
Add a feature ``id`` to the index with a specified bounding box.

:return: ``True`` if feature was successfully added to index.

.. versionadded:: 3.4
%End

    bool deleteFeature( const QgsFeature &feature );
%Docstring
Removes a ``feature`` from the index.
%End

    bool deleteFeature( QgsFeatureId id, const QgsRectangle &bounds );
%Docstring
Removes a feature from the index by ``id`` and ``bounds``.

.. versionadded:: 3.36
%End


    QList<QgsFeatureId> intersects( const QgsRectangle &rectangle ) const;
%Docstring
Returns a list of features with a bounding box which intersects the
specified ``rectangle``.

.. note::

   The intersection test is performed based on the feature bounding boxes only, so for non-point
   geometry features it is necessary to manually test the returned features for exact geometry intersection
   when required.
%End

    QList<QgsFeatureId> nearestNeighbor( const QgsPointXY &point, int neighbors = 1, double maxDistance = 0 ) const;
%Docstring
Returns nearest neighbors to a ``point``. The number of neighbors
returned is specified by the ``neighbors`` argument.

If the ``maxDistance`` argument is greater than 0, then only features
within the specified distance of ``point`` will be considered.

Note that in some cases the number of returned features may differ from
the requested number of ``neighbors``. E.g. if not enough features exist
within the ``maxDistance`` of the search point. If multiple features are
equidistant from the search ``point`` then the number of returned
feature IDs may exceed ``neighbors``.

.. warning::

   If this QgsSpatialIndex object was not constructed with the FlagStoreFeatureGeometries flag,
   then the nearest neighbor test is performed based on the feature bounding boxes ONLY, so for non-point
   geometry features this method is not guaranteed to return the actual closest neighbors.
%End

    QList<QgsFeatureId> nearestNeighbor( const QgsGeometry &geometry, int neighbors = 1, double maxDistance = 0 ) const;
%Docstring
Returns nearest neighbors to a ``geometry``. The number of neighbors
returned is specified by the ``neighbors`` argument.

If the ``maxDistance`` argument is greater than 0, then only features
within the specified distance of ``point`` will be considered.

Note that in some cases the number of returned features may differ from
the requested number of ``neighbors``. E.g. if not enough features exist
within the ``maxDistance`` of the search point. If multiple features are
equidistant from the search ``point`` then the number of returned
feature IDs may exceed ``neighbors``.

.. warning::

   If this QgsSpatialIndex object was not constructed with the FlagStoreFeatureGeometries flag,
   then the nearest neighbor test is performed based on the feature bounding boxes ONLY, so for non-point
   geometry features this method is not guaranteed to return the actual closest neighbors.

.. versionadded:: 3.8
%End


    SIP_PYOBJECT geometry( QgsFeatureId id ) const /TypeHint="QgsGeometry"/;
%Docstring
Returns the stored geometry for the indexed feature with matching
``id``.

Geometry is only stored if the QgsSpatialIndex was created with the
FlagStoreFeatureGeometries flag.

:raises KeyError: if no geometry with the specified feature id exists in
                  the index.

.. versionadded:: 3.6
%End
%MethodCode
    std::unique_ptr< QgsGeometry > g = std::make_unique< QgsGeometry >( sipCpp->geometry( a0 ) );
    if ( g->isNull() )
    {
      PyErr_SetString( PyExc_KeyError, QStringLiteral( "No geometry with feature id %1 exists in the index." ).arg( a0 ).toUtf8().constData() );
      sipIsErr = 1;
    }
    else
    {
      sipRes = sipConvertFromType( g.release(), sipType_QgsGeometry, Py_None );
    }
%End


    int  refs() const;
%Docstring
Gets reference count - just for debugging!
%End

};

QFlags<QgsSpatialIndex::Flag> operator|(QgsSpatialIndex::Flag f1, QFlags<QgsSpatialIndex::Flag> f2);


/************************************************************************
 * This file has been generated automatically from                      *
 *                                                                      *
 * src/core/qgsspatialindex.h                                           *
 *                                                                      *
 * Do not edit manually ! Edit header and run scripts/sipify.py again   *
 ************************************************************************/
