Branch data     Line data    Source code

       1                 :            : /***************************************************************************
       2                 :            :                          qgsrasterdataprovidertemporalcapabilities.h
       3                 :            :                          ---------------
       4                 :            :     begin                : February 2020
       5                 :            :     copyright            : (C) 2020 by Samweli Mwakisambwe
       6                 :            :     email                : samweli at kartoza dot com
       7                 :            :  ***************************************************************************/
       8                 :            : 
       9                 :            : /***************************************************************************
      10                 :            :  *                                                                         *
      11                 :            :  *   This program is free software; you can redistribute it and/or modify  *
      12                 :            :  *   it under the terms of the GNU General Public License as published by  *
      13                 :            :  *   the Free Software Foundation; either version 2 of the License, or     *
      14                 :            :  *   (at your option) any later version.                                   *
      15                 :            :  *                                                                         *
      16                 :            :  ***************************************************************************/
      17                 :            : 
      18                 :            : #ifndef QGSRASTERDATAPROVIDERTEMPORALCAPABILITIES_H
      19                 :            : #define QGSRASTERDATAPROVIDERTEMPORALCAPABILITIES_H
      20                 :            : 
      21                 :            : #include "qgis_core.h"
      22                 :            : #include "qgis_sip.h"
      23                 :            : #include "qgsrange.h"
      24                 :            : #include "qgsinterval.h"
      25                 :            : #include "qgsdataprovidertemporalcapabilities.h"
      26                 :            : 
      27                 :            : /**
      28                 :            :  * \class QgsRasterDataProviderTemporalCapabilities
      29                 :            :  * \ingroup core
      30                 :            :  * \brief Implementation of data provider temporal properties for QgsRasterDataProviders.
      31                 :            :  *
      32                 :            :  * Data provider temporal capabilities reflect the temporal capabilities of a QgsDataProvider.
      33                 :            :  * Unlike QgsMapLayerTemporalProperties, these settings are not user-configurable,
      34                 :            :  * and should only be set by the QgsDataProvider itself.
      35                 :            :  *
      36                 :            :  * \since QGIS 3.14
      37                 :            :  */
      38                 :          0 : class CORE_EXPORT QgsRasterDataProviderTemporalCapabilities : public QgsDataProviderTemporalCapabilities
      39                 :            : {
      40                 :            :   public:
      41                 :            : 
      42                 :            :     /**
      43                 :            :      * Constructor for QgsRasterDataProviderTemporalProperties.
      44                 :            :      *
      45                 :            :      * The \a enabled argument specifies whether the data provider has temporal capabilities.
      46                 :            :      */
      47                 :            :     QgsRasterDataProviderTemporalCapabilities( bool enabled = false );
      48                 :            : 
      49                 :            :     /**
      50                 :            :      * Method to use when resolving a temporal range to a data provider layer or band.
      51                 :            :      **/
      52                 :            :     enum IntervalHandlingMethod
      53                 :            :     {
      54                 :            :       MatchUsingWholeRange, //!< Use an exact match to the whole temporal range
      55                 :            :       MatchExactUsingStartOfRange, //!< Match the start of the temporal range to a corresponding layer or band, and only use exact matching results
      56                 :            :       MatchExactUsingEndOfRange, //!< Match the end of the temporal range to a corresponding layer or band, and only use exact matching results
      57                 :            :       FindClosestMatchToStartOfRange, //! Match the start of the temporal range to the least previous closest datetime.
      58                 :            :       FindClosestMatchToEndOfRange //! Match the end of the temporal range to the least previous closest datetime.
      59                 :            :     };
      60                 :            :     // TODO -- add other methods
      61                 :            : 
      62                 :            :     /**
      63                 :            :      * Returns the desired method to use when resolving a temporal interval to matching
      64                 :            :      * layers or bands in the data provider.
      65                 :            :      *
      66                 :            :      *\see setIntervalHandlingMethod()
      67                 :            :     **/
      68                 :            :     IntervalHandlingMethod intervalHandlingMethod() const;
      69                 :            : 
      70                 :            :     /**
      71                 :            :      * Sets the desired \a method to use when resolving a temporal interval to matching
      72                 :            :      * layers or bands in the data provider.
      73                 :            :      *
      74                 :            :      *\see intervalHandlingMethod()
      75                 :            :     **/
      76                 :            :     void setIntervalHandlingMethod( IntervalHandlingMethod method );
      77                 :            : 
      78                 :            :     /**
      79                 :            :      * Sets the overall datetime \a range extent from which temporal data is available from the provider.
      80                 :            :      *
      81                 :            :      * \see availableTemporalRange()
      82                 :            :     */
      83                 :            :     void setAvailableTemporalRange( const QgsDateTimeRange &range );
      84                 :            : 
      85                 :            :     /**
      86                 :            :      * Returns the overall datetime range extent from which temporal data is available from the provider.
      87                 :            :      *
      88                 :            :      * \see setAvailableTemporalRange()
      89                 :            :     */
      90                 :            :     const QgsDateTimeRange &availableTemporalRange() const;
      91                 :            : 
      92                 :            :     /**
      93                 :            :      * Sets a list of all valid datetime \a ranges for which temporal data is available from the provider.
      94                 :            :      *
      95                 :            :      * As opposed to setAvailableTemporalRange(), this method is useful when a provider
      96                 :            :      * contains a set of non-contiguous datetime ranges.
      97                 :            :      *
      98                 :            :      * \see allAvailableTemporalRanges()
      99                 :            :      * \see setAvailableTemporalRange()
     100                 :            :      * \since QGIS 3.20
     101                 :            :     */
     102                 :            :     void setAllAvailableTemporalRanges( const QList< QgsDateTimeRange > &ranges );
     103                 :            : 
     104                 :            :     /**
     105                 :            :      * Returns a list of all valid datetime ranges for which temporal data is available from the provider.
     106                 :            :      *
     107                 :            :      * As opposed to availableTemporalRange(), this method is useful when a provider
     108                 :            :      * contains a set of non-contiguous datetime ranges.
     109                 :            :      *
     110                 :            :      * \see setAllAvailableTemporalRanges()
     111                 :            :      * \see availableTemporalRange()
     112                 :            :      * \since QGIS 3.20
     113                 :            :     */
     114                 :            :     QList< QgsDateTimeRange > allAvailableTemporalRanges() const;
     115                 :            : 
     116                 :            :     /**
     117                 :            :      * Sets the available reference datetime \a range. This is to be used for
     118                 :            :      * bi-temporal based data. Where data can have both nominal and reference times.
     119                 :            :      *
     120                 :            :      * \see availableReferenceTemporalRange()
     121                 :            :     */
     122                 :            :     void setAvailableReferenceTemporalRange( const QgsDateTimeRange &range );
     123                 :            : 
     124                 :            :     /**
     125                 :            :      * Returns the available reference datetime range, which indicates the maximum
     126                 :            :      * extent of datetime values available for reference temporal ranges from the provider.
     127                 :            :      *
     128                 :            :      * \see setAvailableReferenceTemporalRange()
     129                 :            :     */
     130                 :            :     const QgsDateTimeRange &availableReferenceTemporalRange() const;
     131                 :            : 
     132                 :            :     /**
     133                 :            :      * Returns the requested temporal range.
     134                 :            :      * Intended to be used by the provider in fetching data.
     135                 :            :     */
     136                 :            :     const QgsDateTimeRange &requestedTemporalRange() const;
     137                 :            : 
     138                 :            :     /**
     139                 :            :      * Returns the default time step interval corresponding to the available
     140                 :            :      * datetime values for the provider.
     141                 :            :      *
     142                 :            :      * \see setDefaultInterval()
     143                 :            :      * \since QGIS 3.20
     144                 :            :      */
     145                 :            :     QgsInterval defaultInterval() const;
     146                 :            : 
     147                 :            :     /**
     148                 :            :      * Sets the default time step \a interval corresponding to the available
     149                 :            :      * datetime values for the provider.
     150                 :            :      *
     151                 :            :      * \see defaultInterval()
     152                 :            :      * \since QGIS 3.20
     153                 :            :      */
     154                 :            :     void setDefaultInterval( const QgsInterval &interval );
     155                 :            : 
     156                 :            :   private:
     157                 :            : 
     158                 :            :     /**
     159                 :            :      * Sets the requested temporal \a range to retrieve when
     160                 :            :      * returning data from the associated data provider.
     161                 :            :      *
     162                 :            :      * \note this is not normally manually set, and is intended for use by
     163                 :            :      * QgsRasterLayerRenderer to automatically set the requested temporal range
     164                 :            :      * on a clone of the data provider during a render job.
     165                 :            :      *
     166                 :            :      * \see requestedTemporalRange()
     167                 :            :     */
     168                 :            :     void setRequestedTemporalRange( const QgsDateTimeRange &range );
     169                 :            : 
     170                 :            :     /**
     171                 :            :      * Represents available data provider datetime range.
     172                 :            :      *
     173                 :            :      * This is for determining the providers lower and upper datetime bounds,
     174                 :            :      * any updates on the mRange should get out the range bound defined
     175                 :            :      * by this member.
     176                 :            :      *
     177                 :            :      */
     178                 :            :     QgsDateTimeRange mAvailableTemporalRange;
     179                 :            : 
     180                 :            :     /**
     181                 :            :      * A list of all valid temporal ranges for the provider. Used when a provider
     182                 :            :      * has a non-contiguous set of available temporal ranges.
     183                 :            :      */
     184                 :            :     QList< QgsDateTimeRange > mAllAvailableTemporalRanges;
     185                 :            : 
     186                 :            :     //! Represents the requested temporal range.
     187                 :            :     QgsDateTimeRange mRequestedRange;
     188                 :            : 
     189                 :            :     /**
     190                 :            :      * Stores the available reference temporal range
     191                 :            :      */
     192                 :            :     QgsDateTimeRange mAvailableReferenceRange;
     193                 :            : 
     194                 :            :     QgsInterval mDefaultInterval;
     195                 :            : 
     196                 :            :     //! Interval handling method
     197                 :            :     IntervalHandlingMethod mIntervalMatchMethod = MatchUsingWholeRange;
     198                 :            : 
     199                 :            :     friend class QgsRasterLayerRenderer;
     200                 :            :     friend class TestQgsRasterDataProviderTemporalCapabilities;
     201                 :            : 
     202                 :            : };
     203                 :            : 
     204                 :            : #endif // QGSRASTERDATAPROVIDERTEMPORALCAPABILITIES_H