[gdal-dev] GDALWarpOptions vs GDALWarpAppOptions

[Even Rouault]

Simeon,

Le 31/01/2024 à 21:38, Fitch, Simeon via gdal-dev a écrit :
> I'm on the `georust/gdal` bindings team, working on the warp routines, 
> and trying to understand the relationship between GDALWarpOptions vs 
> GDALWarpAppOptions.
>
> I'm not seeing any way to create a GDALWarpOptions from a 
> GDALWarpAppOptions or vice versa. Are functions needing 
> GDALWarpOptions in a completely different universe from ones 
> needing GDALWarpAppOptions?

Yes. GDALWarpOptions is for the lower level API from gdalwarper.h


> GDALWarpOptions seems clear, with requisite C functions for 
> manipulating it, whereas GDALWarpAppOptions seems to only accept 
> key/value pairs via GDALWarpAppOptionsSetWarpOption, which seems quite 
> limiting.

GDALWarpAppOptions is for the higher level gdalwarp C API. Actually most 
of the options are to be provided through the papszArgv parameter of the 
GDALWarpAppOptionsNew() function.  I'm not sure to remember why the 
GDALWarpAppOptionsSetWarpOption() function was added, since it is 
redundant to passing "-wo", "{KEY}={VALUE}" as papszArgv values.

I recognize that key/value pairs or strings are admittedly not super 
structured, but they are easily extensible in a way that is compatible 
of a stable C API/ABI.


>
> I was hoping to provide users a single entry point for specifying warp 
> options, but wanted some expert advice before going down a dead end.

I guess both API could be mapped.  GDALWarp() is probably easier for 
most users as it combines different low level methods, like calling 
GDALSuggestedWarpOutput2() to find the target extent and resolution, 
creating the new dataset, etc. If you look at gdalwarp_lib.cpp, you'll 
find there are lots of heuristics there.

Nothing prevents you to provide a more Rustacean API than the 
string-based one of GDALWarp(). The Python bindings for examples provide 
a way of providing the options as keyword options:


WarpOptions(options=None, format=None, srcBands=None, dstBands=None, 
outputBounds=None, outputBoundsSRS=None, xRes=None, yRes=None, 
targetAlignedPixels=False, width=0, height=0, srcSRS=None, dstSRS=None, 
coordinateOperation=None, srcAlpha=None, dstAlpha=False, 
warpOptions=None, errorThreshold=None, warpMemoryLimit=None, 
creationOptions=None, outputType=0, workingType=0, resampleAlg=None, 
srcNodata=None, dstNodata=None, multithread=False, tps=False, rpc=False, 
geoloc=False, polynomialOrder=None, transformerOptions=None, 
cutlineDSName=None, cutlineLayer=None, cutlineWhere=None, 
cutlineSQL=None, cutlineBlend=None, cropToCutline=False, 
copyMetadata=True, metadataConflictValue=None, 
setColorInterpretation=False, overviewLevel='AUTO', callback=None, 
callback_data=None)
     Create a WarpOptions() object that can be passed to gdal.Warp()

     Parameters
     ----------
     options:
         can be be an array of strings, a string or let empty and filled 
from other keywords.
     format:
         output format ("GTiff", etc...)
     srcBands:
         list of source band numbers (between 1 and the number of input 
bands)
     dstBands:
         list of output band numbers
     outputBounds:
         output bounds as (minX, minY, maxX, maxY) in target SRS
     outputBoundsSRS:
         SRS in which output bounds are expressed, in the case they are 
not expressed in dstSRS
     xRes:
         output resolution in target SRS
     yRes:
         output resolution in target SRS
     targetAlignedPixels:
         whether to force output bounds to be multiple of output resolution
     width:
         width of the output raster in pixel
     height:
         height of the output raster in pixel
     srcSRS:
         source SRS
     dstSRS:
         output SRS
     coordinateOperation:
         coordinate operation as a PROJ string or WKT string
     srcAlpha:
         whether to force the last band of the input dataset to be 
considered as an alpha band.
         If set to False, source alpha warping will be disabled.
     dstAlpha:
         whether to force the creation of an output alpha band
     outputType:
         output type (gdalconst.GDT_Byte, etc...)
     workingType:
         working type (gdalconst.GDT_Byte, etc...)
     warpOptions:
         list or dict of warping options
     errorThreshold:
         error threshold for approximation transformer (in pixels)
     warpMemoryLimit:
         size of working buffer in MB
     resampleAlg:
         resampling mode
     creationOptions:
         list or dict of creation options
     srcNodata:
         source nodata value(s)
     dstNodata:
         output nodata value(s)
     multithread:
         whether to multithread computation and I/O operations
     tps:
         whether to use Thin Plate Spline GCP transformer
     rpc:
         whether to use RPC transformer
     geoloc:
         whether to use GeoLocation array transformer
     polynomialOrder:
         order of polynomial GCP interpolation
     transformerOptions:
         list or dict of transformer options
     cutlineDSName:
         cutline dataset name
     cutlineLayer:
         cutline layer name
     cutlineWhere:
         cutline WHERE clause
     cutlineSQL:
         cutline SQL statement
     cutlineBlend:
         cutline blend distance in pixels
     cropToCutline:
         whether to use cutline extent for output bounds
     copyMetadata:
         whether to copy source metadata
     metadataConflictValue:
         metadata data conflict value
     setColorInterpretation:
         whether to force color interpretation of input bands to output 
bands
     overviewLevel:
         To specify which overview level of source files must be used
     callback:
         callback method
     callback_data:
         user data for callback


Even

-- 
http://www.spatialys.com
My software is free, but my time generally not.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/gdal-dev/attachments/20240131/298bdc1b/attachment.htm>