gdalwarper.h

Go to the documentation of this file.

/******************************************************************************
 * $Id$
 *
 * Project:  GDAL High Performance Warper
 * Purpose:  Prototypes, and definitions for warping related work.
 * Author:   Frank Warmerdam, warmerdam@pobox.com
 *
 ******************************************************************************
 * Copyright (c) 2003, Frank Warmerdam
 * Copyright (c) 2009-2012, Even Rouault <even dot rouault at spatialys.com>
 *
 * SPDX-License-Identifier: MIT
 ****************************************************************************/
 
#ifndef GDALWARPER_H_INCLUDED
#define GDALWARPER_H_INCLUDED

 
#include "gdal_alg.h"
#include "cpl_minixml.h"
#include "cpl_multiproc.h"
 
CPL_C_START
 
/* Note: values are selected to be consistent with GDALRIOResampleAlg of
 * gcore/gdal.h */
typedef enum
{ GRA_NearestNeighbour =
        0, GRA_Bilinear = 1, GRA_Cubic = 2, GRA_CubicSpline = 3, GRA_Lanczos = 4,
    GRA_Average = 5,
    GRA_Mode = 6,
    /*  GRA_Gauss=7 reserved. */ GRA_Max =
        8, GRA_Min =
        9, GRA_Med =
        10,
    GRA_Q1 = 11,
    GRA_Q3 = 12,
    GRA_Sum = 13,
    GRA_RMS = 14,
    GRA_LAST_VALUE = GRA_RMS
} GDALResampleAlg;

typedef int (*GDALMaskFunc)(void *pMaskFuncArg, int nBandCount,
                            GDALDataType eType, int nXOff, int nYOff,
                            int nXSize, int nYSize, GByte **papabyImageData,
                            int bMaskIsFloat, void *pMask);
 
CPLErr CPL_DLL GDALWarpNoDataMasker(void *pMaskFuncArg, int nBandCount,
                                    GDALDataType eType, int nXOff, int nYOff,
                                    int nXSize, int nYSize,
                                    GByte **papabyImageData, int bMaskIsFloat,
                                    void *pValidityMask, int *pbOutAllValid);
 
CPLErr CPL_DLL GDALWarpDstAlphaMasker(void *pMaskFuncArg, int nBandCount,
                                      GDALDataType eType, int nXOff, int nYOff,
                                      int nXSize, int nYSize,
                                      GByte ** /*ppImageData */,
                                      int bMaskIsFloat, void *pValidityMask);
CPLErr CPL_DLL GDALWarpSrcAlphaMasker(void *pMaskFuncArg, int nBandCount,
                                      GDALDataType eType, int nXOff, int nYOff,
                                      int nXSize, int nYSize,
                                      GByte ** /*ppImageData */,
                                      int bMaskIsFloat, void *pValidityMask,
                                      int *pbOutAllOpaque);
 
CPLErr CPL_DLL GDALWarpSrcMaskMasker(void *pMaskFuncArg, int nBandCount,
                                     GDALDataType eType, int nXOff, int nYOff,
                                     int nXSize, int nYSize,
                                     GByte ** /*ppImageData */,
                                     int bMaskIsFloat, void *pValidityMask);
 
CPLErr CPL_DLL GDALWarpCutlineMasker(void *pMaskFuncArg, int nBandCount,
                                     GDALDataType eType, int nXOff, int nYOff,
                                     int nXSize, int nYSize,
                                     GByte ** /* ppImageData */,
                                     int bMaskIsFloat, void *pValidityMask);
 
/* GCMVF stands for GDALWARP_CUTLINE_MASKER_VALIDITY_FLAG */
#define GCMVF_PARTIAL_INTERSECTION 0
#define GCMVF_NO_INTERSECTION 1
#define GCMVF_CHUNK_FULLY_WITHIN_CUTLINE 2
CPLErr CPL_DLL GDALWarpCutlineMaskerEx(void *pMaskFuncArg, int nBandCount,
                                       GDALDataType eType, int nXOff, int nYOff,
                                       int nXSize, int nYSize,
                                       GByte ** /* ppImageData */,
                                       int bMaskIsFloat, void *pValidityMask,
                                       int *pnValidityFlag);


typedef enum
{
    /* Choose the first value encountered */ GWKTS_First = 1,
    /* Choose the minimal value */ GWKTS_Min = 2,
    /* Choose the maximum value */ GWKTS_Max = 3,
} GWKTieStrategy;
 
/************************************************************************/
/*                           GDALWarpOptions                            */
/************************************************************************/

typedef struct
{
 
    char **papszWarpOptions;

    double dfWarpMemoryLimit;

    GDALResampleAlg eResampleAlg;

    GDALDataType eWorkingDataType;

    GDALDatasetH hSrcDS;

    GDALDatasetH hDstDS;

    int nBandCount;

    int *panSrcBands;

    int *panDstBands;

    int nSrcAlphaBand;

    int nDstAlphaBand;

    double *padfSrcNoDataReal;
    double *padfSrcNoDataImag;

    double *padfDstNoDataReal;
    double *padfDstNoDataImag;

    GDALProgressFunc pfnProgress;

    void *pProgressArg;

    GDALTransformerFunc pfnTransformer;

    void *pTransformerArg;

    GDALMaskFunc *papfnSrcPerBandValidityMaskFunc;
    void **papSrcPerBandValidityMaskFuncArg;

    GDALMaskFunc pfnSrcValidityMaskFunc;
    void *pSrcValidityMaskFuncArg;

    GDALMaskFunc pfnSrcDensityMaskFunc;
    void *pSrcDensityMaskFuncArg;

    GDALMaskFunc pfnDstDensityMaskFunc;
    void *pDstDensityMaskFuncArg;

    GDALMaskFunc pfnDstValidityMaskFunc;
    void *pDstValidityMaskFuncArg;

    CPLErr (*pfnPreWarpChunkProcessor)(void *pKern, void *pArg);
    void *pPreWarpProcessorArg;

    CPLErr (*pfnPostWarpChunkProcessor)(void *pKern, void *pArg);
    void *pPostWarpProcessorArg;

    void *hCutline;

    double dfCutlineBlendDist;

    GWKTieStrategy eTieStrategy;
} GDALWarpOptions;
 
const char CPL_DLL *GDALWarpGetOptionList(void);
 
GDALWarpOptions CPL_DLL *CPL_STDCALL GDALCreateWarpOptions(void);
void CPL_DLL CPL_STDCALL GDALDestroyWarpOptions(GDALWarpOptions *);
GDALWarpOptions CPL_DLL *CPL_STDCALL
GDALCloneWarpOptions(const GDALWarpOptions *);
 
void CPL_DLL CPL_STDCALL GDALWarpInitDstNoDataReal(GDALWarpOptions *,
                                                   double dNoDataReal);
 
void CPL_DLL CPL_STDCALL GDALWarpInitSrcNoDataReal(GDALWarpOptions *,
                                                   double dNoDataReal);
 
void CPL_DLL CPL_STDCALL GDALWarpInitNoDataReal(GDALWarpOptions *,
                                                double dNoDataReal);
 
void CPL_DLL CPL_STDCALL GDALWarpInitDstNoDataImag(GDALWarpOptions *,
                                                   double dNoDataImag);
 
void CPL_DLL CPL_STDCALL GDALWarpInitSrcNoDataImag(GDALWarpOptions *,
                                                   double dNoDataImag);
 
void CPL_DLL CPL_STDCALL GDALWarpResolveWorkingDataType(GDALWarpOptions *);
 
void CPL_DLL CPL_STDCALL GDALWarpInitDefaultBandMapping(GDALWarpOptions *,
                                                        int nBandCount);

CPLXMLNode CPL_DLL *CPL_STDCALL
GDALSerializeWarpOptions(const GDALWarpOptions *);
GDALWarpOptions CPL_DLL *CPL_STDCALL GDALDeserializeWarpOptions(CPLXMLNode *);
 
/************************************************************************/
/*                         GDALReprojectImage()                         */
/************************************************************************/
 
CPLErr CPL_DLL CPL_STDCALL GDALReprojectImage(
    GDALDatasetH hSrcDS, const char *pszSrcWKT, GDALDatasetH hDstDS,
    const char *pszDstWKT, GDALResampleAlg eResampleAlg,
    double dfWarpMemoryLimit, double dfMaxError, GDALProgressFunc pfnProgress,
    void *pProgressArg, GDALWarpOptions *psOptions);
 
CPLErr CPL_DLL CPL_STDCALL GDALCreateAndReprojectImage(
    GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstFilename,
    const char *pszDstWKT, GDALDriverH hDstDriver, char **papszCreateOptions,
    GDALResampleAlg eResampleAlg, double dfWarpMemoryLimit, double dfMaxError,
    GDALProgressFunc pfnProgress, void *pProgressArg,
    GDALWarpOptions *psOptions);
 
/************************************************************************/
/*                           VRTWarpedDataset                           */
/************************************************************************/
 
GDALDatasetH CPL_DLL CPL_STDCALL
GDALAutoCreateWarpedVRT(GDALDatasetH hSrcDS, const char *pszSrcWKT,
                        const char *pszDstWKT, GDALResampleAlg eResampleAlg,
                        double dfMaxError, const GDALWarpOptions *psOptions);
 
GDALDatasetH CPL_DLL CPL_STDCALL GDALAutoCreateWarpedVRTEx(
    GDALDatasetH hSrcDS, const char *pszSrcWKT, const char *pszDstWKT,
    GDALResampleAlg eResampleAlg, double dfMaxError,
    const GDALWarpOptions *psOptions, CSLConstList papszTransformerOptions);
 
GDALDatasetH CPL_DLL CPL_STDCALL
GDALCreateWarpedVRT(GDALDatasetH hSrcDS, int nPixels, int nLines,
                    const double *padfGeoTransform, GDALWarpOptions *psOptions);
 
CPLErr CPL_DLL CPL_STDCALL GDALInitializeWarpedVRT(GDALDatasetH hDS,
                                                   GDALWarpOptions *psWO);
 
CPL_C_END
 
#if defined(__cplusplus) && !defined(CPL_SUPRESS_CPLUSPLUS)
 
#include <vector>
#include <utility>
 
bool GDALGetWarpResampleAlg(const char *pszResampling,
                            GDALResampleAlg &eResampleAlg, bool bThrow = false);
 
/************************************************************************/
/*                            GDALWarpKernel                            */
/*                                                                      */

#define WARP_EXTRA_ELTS 1

class CPL_DLL GDALWarpKernel
{
    CPL_DISALLOW_COPY_ASSIGN(GDALWarpKernel)
 
  public:
    char **papszWarpOptions;

    GDALResampleAlg eResample;
    GDALDataType eWorkingDataType;
    int nBands;

    int nSrcXSize;
    int nSrcYSize;
    double dfSrcXExtraSize;
    double dfSrcYExtraSize;
    GByte **papabySrcImage;

    GUInt32 **papanBandSrcValid;
    GUInt32 *panUnifiedSrcValid;
    float *pafUnifiedSrcDensity;

    int nDstXSize;
    int nDstYSize;
    GByte **papabyDstImage;
    GUInt32 *panDstValid;
    float *pafDstDensity;

    double dfXScale;
    double dfYScale;
    double dfXFilter;
    double dfYFilter;
    int nXRadius;
    int nYRadius;
    int nFiltInitX;
    int nFiltInitY;

    int nSrcXOff;
    int nSrcYOff;

    int nDstXOff;
    int nDstYOff;

    GDALTransformerFunc pfnTransformer;
    void *pTransformerArg;

    GDALProgressFunc pfnProgress;
    void *pProgress;

    double dfProgressBase;
    double dfProgressScale;

    double *padfDstNoDataReal;

    void *psThreadData;
 
    bool bApplyVerticalShift = false;
 
    double dfMultFactorVerticalShift = 1.0;
 
    // Tuples of values (e.g. "<R>,<G>,<B>" or "(<R1>,<G1>,<B1>),(<R2>,<G2>,<B2>)") that must
    // be ignored as contributing source pixels during resampling. Only taken into account by
    // Average currently
    std::vector<std::vector<double>> m_aadfExcludedValues{};
 
    GWKTieStrategy eTieStrategy;
 
    bool bWarnedAboutDstNoDataReplacement = false;

 
    GDALWarpKernel();
    ~GDALWarpKernel();
 
    CPLErr Validate();
    CPLErr PerformWarp();
};

void *GWKThreadsCreate(char **papszWarpOptions,
                       GDALTransformerFunc pfnTransformer,
                       void *pTransformerArg);
void GWKThreadsEnd(void *psThreadDataIn);
 
/************************************************************************/
/*                         GDALWarpOperation()                          */
/*                                                                      */
/*      This object is application created, or created by a higher      */
/*      level convenience function.  It is responsible for              */
/*      subdividing the operation into chunks, loading and saving       */
/*      imagery, and establishing the various validity and density      */
/*      masks.  Actual resampling is done by the GDALWarpKernel.        */
/************************************************************************/

typedef struct _GDALWarpChunk GDALWarpChunk;
 
struct GDALTransformerUniquePtrReleaser
{
    void operator()(void *p)
    {
        GDALDestroyTransformer(p);
    }
};


using GDALTransformerArgUniquePtr =
    std::unique_ptr<void, GDALTransformerUniquePtrReleaser>;
 
class CPL_DLL GDALWarpOperation final
{
 
    CPL_DISALLOW_COPY_ASSIGN(GDALWarpOperation)
 
  private:
    GDALWarpOptions *psOptions = nullptr;
    GDALTransformerArgUniquePtr m_psOwnedTransformerArg{nullptr};
 
    void WipeOptions();
    int ValidateOptions();
 
    bool ComputeSourceWindowTransformPoints(
        int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize, bool bUseGrid,
        bool bAll, int nStepCount, bool bTryWithCheckWithInvertProj,
        double &dfMinXOut, double &dfMinYOut, double &dfMaxXOut,
        double &dfMaxYOut, int &nSamplePoints, int &nFailedCount);
 
    void ComputeSourceWindowStartingFromSource(int nDstXOff, int nDstYOff,
                                               int nDstXSize, int nDstYSize,
                                               double *padfSrcMinX,
                                               double *padfSrcMinY,
                                               double *padfSrcMaxX,
                                               double *padfSrcMaxY);
 
    static CPLErr CreateKernelMask(GDALWarpKernel *, int iBand,
                                   const char *pszType);
 
    CPLMutex *hIOMutex = nullptr;
    CPLMutex *hWarpMutex = nullptr;
 
    int nChunkListCount = 0;
    int nChunkListMax = 0;
    GDALWarpChunk *pasChunkList = nullptr;
 
    bool bReportTimings = false;
    unsigned long nLastTimeReported = 0;
 
    void *psThreadData = nullptr;
 
    // Coordinates a few special points in target image space, to determine
    // if ComputeSourceWindow() must use a grid based sampling.
    std::vector<std::pair<double, double>> aDstXYSpecialPoints{};
 
    bool m_bIsTranslationOnPixelBoundaries = false;
 
    void WipeChunkList();
    CPLErr CollectChunkListInternal(int nDstXOff, int nDstYOff, int nDstXSize,
                                    int nDstYSize);
    void CollectChunkList(int nDstXOff, int nDstYOff, int nDstXSize,
                          int nDstYSize);
    void ReportTiming(const char *);
 
  public:
    GDALWarpOperation();
    ~GDALWarpOperation();
 
    CPLErr Initialize(const GDALWarpOptions *psNewOptions,
                      GDALTransformerFunc pfnTransformer = nullptr,
                      GDALTransformerArgUniquePtr psOwnedTransformerArg =
                          GDALTransformerArgUniquePtr{nullptr});
    void *CreateDestinationBuffer(int nDstXSize, int nDstYSize,
                                  int *pbWasInitialized = nullptr);
    CPLErr InitializeDestinationBuffer(void *pDstBuffer, int nDstXSize,
                                       int nDstYSize,
                                       int *pbWasInitialized = nullptr) const;
    static void DestroyDestinationBuffer(void *pDstBuffer);
 
    const GDALWarpOptions *GetOptions();
 
    CPLErr ChunkAndWarpImage(int nDstXOff, int nDstYOff, int nDstXSize,
                             int nDstYSize);
    CPLErr ChunkAndWarpMulti(int nDstXOff, int nDstYOff, int nDstXSize,
                             int nDstYSize);
    CPLErr WarpRegion(int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize,
                      int nSrcXOff = 0, int nSrcYOff = 0, int nSrcXSize = 0,
                      int nSrcYSize = 0, double dfProgressBase = 0.0,
                      double dfProgressScale = 1.0);
    CPLErr WarpRegion(int nDstXOff, int nDstYOff, int nDstXSize, int nDstYSize,
                      int nSrcXOff, int nSrcYOff, int nSrcXSize, int nSrcYSize,
                      double dfSrcXExtraSize, double dfSrcYExtraSize,
                      double dfProgressBase, double dfProgressScale);
    CPLErr WarpRegionToBuffer(int nDstXOff, int nDstYOff, int nDstXSize,
                              int nDstYSize, void *pDataBuf,
                              GDALDataType eBufDataType, int nSrcXOff = 0,
                              int nSrcYOff = 0, int nSrcXSize = 0,
                              int nSrcYSize = 0, double dfProgressBase = 0.0,
                              double dfProgressScale = 1.0);
    CPLErr WarpRegionToBuffer(int nDstXOff, int nDstYOff, int nDstXSize,
                              int nDstYSize, void *pDataBuf,
                              GDALDataType eBufDataType, int nSrcXOff,
                              int nSrcYOff, int nSrcXSize, int nSrcYSize,
                              double dfSrcXExtraSize, double dfSrcYExtraSize,
                              double dfProgressBase, double dfProgressScale);
 
  protected:
    friend class VRTWarpedDataset;
    CPLErr ComputeSourceWindow(int nDstXOff, int nDstYOff, int nDstXSize,
                               int nDstYSize, int *pnSrcXOff, int *pnSrcYOff,
                               int *pnSrcXSize, int *pnSrcYSize,
                               double *pdfSrcXExtraSize,
                               double *pdfSrcYExtraSize,
                               double *pdfSrcFillRatio);
 
    double GetWorkingMemoryForWindow(int nSrcXSize, int nSrcYSize,
                                     int nDstXSize, int nDstYSize) const;
};
 
#endif /* def __cplusplus */
 
CPL_C_START

typedef void *GDALWarpOperationH;
 
GDALWarpOperationH CPL_DLL GDALCreateWarpOperation(const GDALWarpOptions *);
void CPL_DLL GDALDestroyWarpOperation(GDALWarpOperationH);
CPLErr CPL_DLL GDALChunkAndWarpImage(GDALWarpOperationH, int, int, int, int);
CPLErr CPL_DLL GDALChunkAndWarpMulti(GDALWarpOperationH, int, int, int, int);
CPLErr CPL_DLL GDALWarpRegion(GDALWarpOperationH, int, int, int, int, int, int,
                              int, int);
CPLErr CPL_DLL GDALWarpRegionToBuffer(GDALWarpOperationH, int, int, int, int,
                                      void *, GDALDataType, int, int, int, int);
 
/************************************************************************/
/*      Warping kernel functions                                        */
/************************************************************************/

int GWKGetFilterRadius(GDALResampleAlg eResampleAlg);
 
typedef double (*FilterFuncType)(double dfX);
FilterFuncType GWKGetFilterFunc(GDALResampleAlg eResampleAlg);
 
// TODO(schwehr): Can padfVals be a const pointer?
typedef double (*FilterFunc4ValuesType)(double *padfVals);
FilterFunc4ValuesType GWKGetFilterFunc4Values(GDALResampleAlg eResampleAlg);
 
CPL_C_END
 
#endif /* ndef GDAL_ALG_H_INCLUDED */