## @class Geo::GDAL
# @brief GDAL utility functions and a root class for raster classes.
# @details Geo::GDAL wraps many GDAL utility functions and is as a root class
# for all GDAL raster classes. A "raster" is an object, whose core is
# a rectagular grid of cells, called a "band" in GDAL. Each cell
# contains a numeric value of a specific data type.
## @ignore FileFromMemBuffer
## @ignore GDALDestroyDriverManager
## @ignore HasThreadSupport
## @ignore TermProgress
## @ignore TermProgress_nocb
## @ignore PopErrorHandler
## @ignore PushErrorHandler
## @ignore SetErrorHandler
## @ignore Error
## @ignore ErrorReset
## @ignore GetLastErrorMsg
## @ignore GetLastErrorNo
## @ignore GetLastErrorType
## @ignore last_error
## @ignore error
## @ignore named_parameters
## @ignore string2int
## @ignore GeneralCmdLineProcessor
## @ignore ParseCommandLine
## @ignore GetDataTypeName
## @ignore GetDataTypeByName
## @ignore GetColorInterpretationName
## @ignore GetPaletteInterpretationName
## @ignore VSIFOpenL
## @ignore VSIFWriteL
## @ignore VSIFCloseL
## @ignore VSIFReadL
## @ignore VSIFSeekL
## @ignore VSIFTellL
## @ignore VSIFTruncateL
## @ignore Mkdir
## @ignore ReadDir
## @ignore ReadDirRecursive
## @ignore Rename
## @ignore Rmdir
## @ignore Stat
## @ignore Unlink
## @ignore VSIStdoutSetRedirection
## @ignore VSIStdoutUnsetRedirection
## @ignore Debug
## @ignore FillNodata
## @ignore ContourGenerate
## @ignore RegenerateOverviews
## @ignore RegenerateOverview
## @ignore ApplyGeoTransform
## @ignore InvGeoTransform
## @ignore GCPsToGeoTransform
## @ignore make_processing_options
## @ignore_class Geo::GDAL::GDALDEMProcessingOptions
## @ignore wrapper_GDALDEMProcessing
## @ignore_class Geo::GDAL::GDALGridOptions
## @ignore wrapper_GDALGrid
## @ignore_class Geo::GDAL::GDALNearblackOptions
## @ignore wrapper_GDALNearblackDestDS
## @ignore wrapper_GDALNearblackDestName
## @ignore_class Geo::GDAL::GDALRasterizeOptions
## @ignore wrapper_GDALRasterizeDestDS
## @ignore wrapper_GDALRasterizeDestName
## @ignore_class Geo::GDAL::GDALTranslateOptions
## @ignore wrapper_GDALTranslate
## @ignore_class Geo::GDAL::GDALVectorTranslateOptions
## @ignore wrapper_GDALVectorTranslateDestDS
## @ignore wrapper_GDALVectorTranslateDestName
## @ignore_class Geo::GDAL::GDALWarpAppOptions
## @ignore wrapper_GDALWarpDestDS
## @ignore wrapper_GDALWarpDestName
## @ignore_class Geo::GDAL::GDALInfoOptions
## @ignore GDALInfo
## @ignore_class Geo::GDAL::GDALBuildVRTOptions
## @ignore wrapper_GDALBuildVRT_objects
## @ignore wrapper_GDALBuildVRT_names
## @ignore ComputeMedianCutPCT
## @ignore DitherRGB2PCT
## @ignore ReprojectImage
## @ignore AutoCreateWarpedVRT
## @ignore ComputeProximity
## @ignore RasterizeLayer
## @ignore Polygonize
## @ignore FPolygonize
## @ignore SieveFilter
##### XML is in its own class
## @ignore NodeTypes
## @ignore NodeType
## @ignore ParseXMLString
## @ignore NodeData
## @ignore Children
## @ignore Child
## @ignore SerializeXMLTree
## @sub UseExceptions
# Use the Perl exception mechanism for GDAL messages (failures are
# confessed and warnings are warned) and collect the messages
# into \@Geo::GDAL::error. This is the default.
## @sub DontUseExceptions
# Do not use the Perl exception mechanism for GDAL messages. Instead
# the messages are printed to standard error.
## @sub $errstr
# Clear the error stack and return all generated GDAL error messages in one (possibly multiline) string.
# @return the chomped error stack joined with newlines.
## @sub $VersionInfo($request = 'VERSION_NUM')
# @param request A string specifying the request. Currently either
# "VERSION_NUM", "RELEASE_DATE", "RELEASE_NAME", or
# "--version". Default is "VERSION_NUM".
# @return Requested information.
## @sub PushFinderLocation($path)
# Add a path to the set of paths from where GDAL support files are
# sought. Note that GDAL puts initially into the finder the current
# directory and value of GDAL_DATA environment variable (if it
# exists), installation directory (prepended with '/share/gdal' or
# '/Resources/gdal'), or '/usr/local/share/gdal'. It is usually only
# needed to add paths to the finder if using an alternate set of data
# files or a non-installed GDAL is used (as in testing).
## @sub PopFinderLocation()
# Remove the latest addition from the set of support file search
# paths. Note that calling this subroutine may remove paths GDAL put
# into the finder.
## @sub FinderClean()
# Clear the set of support file search paths.
## @sub $FindFile($basename)
# Search for GDAL support files.
#
# An example:
# \code
# use Geo::GDAL;
# $a = Geo::GDAL::FindFile('pcs.csv');
# print STDERR "$a\n";
# \endcode
# Prints (for example):
# \code
# c:\msys\1.0\local\share\gdal\pcs.csv
# \endcode
#
# @param basename The name of the file to search for. For example
# 'pcs.csv'.
# @return the path to the searched file or undef.
## @sub SetConfigOption($key, $value)
# @param key A GDAL config option. Consult <a
# href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL
# documentation</a> for available options and their use.
# @param value A value for the option, typically 'YES', 'NO',
# undef, path, numeric value, or a filename.
## @sub $GetConfigOption($key)
# @param key A GDAL config option. Consult <a
# href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL
# documentation</a> for available options and their use.
# @return the value of the GDAL config option.
## @sub $GetCacheMax()
# @return maximum amount of memory (as bytes) for caching within GDAL.
## @sub SetCacheMax($Bytes)
# @param Bytes New maximum amount of memory for caching within GDAL.
## @sub $GetCacheUsed()
# @return the amount of memory currently used for caching within GDAL.
## @sub @DataTypes()
# @return a list of GDAL raster cell data types. These are currently:
# +list Geo::GDAL::Const GDT_ TypeCount
## @sub $GetDataTypeSize($DataType)
# @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
# @return the size as the number of bits.
## @sub @DataTypeValueRange($DataType)
# @param DataType Data type (one of those listed by Geo::GDAL::DataTypes).
# @note Some returned values are inaccurate.
#
# @return the minimum, maximum range of the data type.
## @sub $DataTypeIsComplex($DataType)
# @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
# @return true if the data type is a complex number.
## @sub @OpenFlags()
# @return a list of GDAL data set open modes. These are currently:
# +list Geo::GDAL::Const OF_
## @sub @ResamplingTypes()
# @return a list of GDAL resampling methods. These are currently:
# +list Geo::GDAL::Const GRA_
## @sub @RIOResamplingTypes()
# @return a list of GDAL raster IO resampling methods. These are currently:
# +list Geo::GDAL::Const GRIORA_
## @sub $DecToDMS($angle, $axis, $precision=2)
# Convert decimal degrees to degrees, minutes, and seconds string
# @param angle A number
# @param axis A string specifying latitude or longitude ('Long').
# @param precision
# @return a string nndnn'nn.nn'"L where n is a number and L is either
# N or E
## @sub $PackedDMSToDec($packed)
# @param packed DMS as a number DDDMMMSSS.SS
# @return decimal degrees
## @sub $DecToPackedDMS($dec)
# @param dec Decimal degrees
# @return packed DMS, i.e., a number DDDMMMSSS.SS
## @ignore GetDriverCount
## @ignore GetDriver
## @ignore GetDriverByName
## @ignore GetDriverNames
## @sub @Drivers()
# @note Use Geo::OGR::Drivers for vector drivers.
# @return a list of all available GDAL raster drivers.
## @sub @DriverNames()
# Available raster format drivers.
# @note Use Geo::OGR::DriverNames for vector drivers.
# @return a list of the short names of all available GDAL raster drivers.
## @sub Geo::GDAL::Driver Driver($Name)
# Access a format driver.
# @param Name The short name of the driver. One of
# Geo::GDAL::DriverNames or Geo::OGR::DriverNames.
# @note This subroutine is imported into the main namespace if Geo::GDAL
# is used with qw/:all/.
# @return a Geo::GDAL::Driver object.
## @sub Geo::GDAL::Driver IdentifyDriver($path, $siblings)
# @param path a dataset path.
# @param siblings [optional] A list of names of files that belong to the data format.
# @return a Geo::GDAL::Driver.
## @sub $PackCharacter($DataType)
# Get the character that is needed for Perl's pack and unpack when
# they are used with Geo::GDAL::Band::ReadRaster and
# Geo::GDAL::Band::WriteRaster. Note that Geo::GDAL::Band::ReadTile
# and Geo::GDAL::Band::WriteTile have simpler interfaces that do not
# require pack and unpack.
# @param DataType A GDAL raster cell data type, typically from $band->DataType.
# @return a character which can be used in Perl's pack and unpack.
## @ignore AccessTypes
## @sub Geo::GDAL::Dataset Open(%params)
# Open a dataset.
# An example, which opens an existing raster dataset for editing:
# \code
# use Geo::GDAL qw/:all/;
# $ds = Open(Name => 'existing.tiff', Access => 'Update');
# \endcode
# @param params Named parameters:
# - \a Name Dataset string (typically a filename). Default is '.'.
# - \a Access Access type, either 'ReadOnly' or 'Update'. Default is 'ReadOnly'.
# - \a Type Dataset type, either 'Raster', 'Vector', or 'Any'. Default is 'Any'.
# - \a Options A hash of GDAL open options passed to candidate drivers. Default is {}.
# - \a Files A list of names of files that are auxiliary to the main file. Default is [].
#
# @note This subroutine is imported into the main namespace if Geo::GDAL
# is use'd with qw/:all/.
#
# @note Some datasets / dataset strings do not explicitly imply the
# dataset type (for example a PostGIS database). If the type is not
# specified in such a case the returned dataset may be of either type.
#
# @return a new Geo::GDAL::Dataset object if success.
## @sub Geo::GDAL::Dataset OpenShared($name, $access = 'ReadOnly')
# Open a raster dataset in shared mode.
# @param name Raster dataset string (typically a filename).
# @param access Access type, either 'ReadOnly' (the default) or 'Update'.
# @return a new Geo::GDAL::Dataset object or undef.
## @sub Geo::GDAL::Dataset OpenEx(%params)
# The generic dataset open method, used internally by all Open and OpenShared methods.
# @param params Named parameters:
# - \a Name The name of the data set or source to open. (Default is '.')
# - \a Flags A list of access mode flags. Available flags are listed by Geo::GDAL::OpenFlags(). (Default is [])
# - \a Drivers A list of short names of drivers that may be used. Empty list means all. (Default is [])
# - \a Options A hash of GDAL open options passed to candidate drivers. (Default is {})
# - \a Files A list of names of files that are auxiliary to the main file. (Default is [])
#
# An example
# \code
# $ds = Geo::GDAL::OpenEx(Name => 'existing.tiff', Flags => [qw/RASTER UPDATE/]);
# \endcode
# @return a new Geo::GDAL::Dataset object.
## @class Geo::GDAL::XML
# @brief A simple XML parser
# @details
## @method new($string)
# @param string String containing XML.
# @return A new Geo::GDAL::XML object, which is a reference to an anonymous array.
## @method traverse(coderef subroutine)
# @param subroutine Code reference, which will be called for each node in the XML with parameters: node, node_type, node_value. Node type is either Attribute, Comment, Element, Literal, or Text.
## @method serialize()
# @return The XML serialized into a string.
## @class Geo::GDAL::AsyncReader
# @brief Enable asynchronous requests.
# @details This class is not yet documented nor tested in the GDAL Perl wrappers
# @isa (Geo::GDAL)
# @todo Test and document.
## @class Geo::GDAL::MajorObject
# @brief An object, which holds meta data.
# @details
# @isa (Geo::GDAL)
## @sub Domains
# @return the class specific DOMAINS list
## @method $Description($description)
# @param description [optional]
# @return the description in a non-void context.
## @method $GetDescription()
# @return
## @method SetDescription($NewDesc)
# @param NewDesc
#
## @ignore SetMetadataItem
## @ignore GetMetadataItem
## @method \%Metadata(hashref metadata = undef, $domain = '')
# @param metadata
# @param domain
# @return the metadata in a non-void context.
## @method \%GetMetadata($domain = "")
# @note see Metadata
# @param domain
# @return
## @method SetMetadata(hashref metadata, $domain = "")
# @note see Metadata
# @param metadata
# @param domain
#
## @class Geo::GDAL::Driver
# @brief A driver for a specific dataset format.
# @details
# @isa (Geo::GDAL::MajorObject Geo::GDAL)
## @method Open
# The same as Geo::GDAL::Open except that only this driver is allowed.
## @ignore Register
## @ignore Deregister
## @attr ShortName
# $driver->{ShortName}
## @attr LongName
# $driver->{LongName}
## @attr HelpTopic
# $driver->{HelpTopic}
## @method Rename($NewName, $OldName)
# Rename (move) a GDAL dataset.
# @param NewName String.
# @param OldName String.
## @method CopyFiles($NewName, $OldName)
# Copy the files of a dataset.
# @param NewName String.
# @param OldName String.
# @method $Name
# @return The short name of the driver.
## @method @Capabilities()
# @return A list of capabilities. When executed as a package subroutine
# returns a list of all potential capabilities a driver may have. When
# executed as an object method returns a list of all capabilities the
# driver has.
#
# Currently capabilities are:
# +list Geo::GDAL::Const DCAP_
#
# Examples.
# \code
# @all_capabilities = Geo::GDAL::Driver::Capabilities;
# @capabilities_of_the_geotiff_driver = Geo::GDAL::Driver('GTiff')->Capabilities;
# \endcode
## @method $TestCapability($cap)
# Test whether the driver has the specified capability.
# @param cap A capability string (one of those returned by Capabilities).
# @return a boolean value.
## @method $Extension()
# @note The returned extension does not contain a '.' prefix.
# @return a suggested single extension or a list of extensions (in
# list context) for datasets.
## @method $MIMEType()
# @return a suggested MIME type for datasets.
## @method @CreationOptionList()
# @return a list of options, each option is a hashref, the keys are
# name, type and description or Value. Value is a listref.
## @method @CreationDataTypes()
# @return a list of data types that can be used for new datasets of this format. A subset of Geo::GDAL::DataTypes
## @ignore CreateDataset
## @method Geo::GDAL::Dataset Create(%params)
# Create a raster dataset using this driver.
# @note a.k.a. CreateDataset
#
# @param params Named parameters:
# - \a Name The name for the dataset (default is 'unnamed') or an object, which implements write and close.
# - \a Width The width for the raster dataset (default is 256).
# - \a Height The height for the raster dataset (default is 256).
# - \a Bands The number of bands to create into the raster dataset (default is 1).
# - \a Type The data type for the raster cells (default is 'Byte'). One of Geo::GDAL::Driver::CreationDataTypes.
# - \a Options Driver creation options as a reference to a hash (default is {}).
#
# @return A new Geo::GDAL::Dataset object.
## @ignore CreateCopy
## @method Geo::GDAL::Dataset Copy(%params)
# Create a new raster Geo::GDAL::Dataset as a copy of an existing dataset.
# @note a.k.a. CreateCopy
#
# @param params Named parameters:
# - \a Name name for the new raster dataset.
# - \a Src the source Geo::GDAL::Dataset object.
# - \a Strict 1 (default) if the copy must be strictly equivalent, or 0 if the copy may adapt.
# - \a Options an anonymous hash of driver specific options.
# - \a Progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data).
# - \a ProgressData [optional]
# @return a new Geo::GDAL::Dataset object.
## @method Delete($name)
# @param name
## @class Geo::GDAL::GCP
# @brief A ground control point for georeferencing rasters.
# @details
# @isa (Geo::GDAL)
## @cmethod $new($x = 0.0, $y = 0.0, $z = 0.0, $column = 0.0, $row = 0.0, $info = "", $id = "")
# @param x projection coordinate
# @param y projection coordinate
# @param z projection coordinate
# @param column cell x coordinate
# @param row cell y coordinate
# @param info informational message
# @param id unique identifier (string)
# @return a new Geo::GDAL::GCP object
## @attr X
# projection coordinate (access as $gcp->{X})
## @attr Y
# projection coordinate (access as $gcp->{Y})
## @attr Z
# projection coordinate (access as $gcp->{Z})
## @attr Column
# cell x coordinate (access as $gcp->{Column})
## @attr Row
# cell y coordinate (access as $gcp->{Row})
## @attr Info
# informational message (access as $gcp->{Info})
## @attr Id
# unique identifier (string) (access as $gcp->{Id})
## @class Geo::GDAL::Dataset
# @brief A set of associated raster bands or vector layer source.
# @details
# @isa (Geo::GDAL::MajorObject Geo::GDAL)
## @sub Geo::GDAL::Dataset Open
# The same as Geo::GDAL::Open
## @sub Geo::GDAL::Dataset OpenShared
# The same as Geo::GDAL::OpenShared
## @ignore FlushCache
## @ignore stdout_redirection_wrapper
## @attr RasterXSize
# scalar (access as $dataset->{RasterXSize})
## @attr RasterYSize
# scalar (access as $dataset->{RasterYSize})
## @attr RasterCount
# scalar (access as $dataset->{RasterCount})
## @method @GetFileList()
# @return list of files GDAL believes to be part of this dataset.
## @method @Size()
# @return (width, height)
## @method Geo::GDAL::Driver GetDriver()
# @return a Geo::GDAL::Driver object that was used to open or create this dataset.
## @ignore GetRasterBand
## @method Geo::GDAL::Band Band($index)
# Create a band object for the band within the dataset.
# @note a.k.a. GetRasterBand
# @param index 1...RasterCount, default is 1.
# @return a new Geo::GDAL::Band object
## @method @Bands()
# @return a list of new Geo::GDAL::Band objects
## @ignore GetLayerByIndex
## @ignore GetLayerByName
## @ignore Layer
## @method Geo::OGR::Layer GetLayer($name)
# @param name the name of the requested layer. If not given, then
# returns the first layer in the data source.
# @return a new Geo::OGR::Layer object that represents the layer
# in the data source.
## @ignore GetLayerCount
## @ignore Layers
## @method @GetLayerNames()
# @note Delivers the functionality of undocumented method GetLayerCount.
# @return a list of the names of the layers this data source provides.
## @method Geo::OGR::Layer CreateLayer(%params)
# @brief Create a new vector layer into this dataset.
#
# @param %params Named parameters:
# - \a Name (scalar) name for the new layer.
# - \a Fields (array reference) a list of (scalar and geometry) field definitions as in
# Geo::OGR::Layer::CreateField.
# - \a ApproxOK (boolean value, default is true) a flag, which is forwarded to Geo::OGR::Layer::CreateField.
# - \a Options (hash reference) driver specific hash of layer creation options.
# - \a Schema (hash reference, deprecated, use \a Fields and \a Name) may contain keys Name, Fields, GeomFields, GeometryType.
# - \a SRS (scalar) the spatial reference for the default geometry field.
# - \a GeometryType (scalar) the type of the default geometry field
# (if only one geometry field). Default is 'Unknown'.
#
# @note If Fields or Schema|Fields is not given, a default geometry
# field (Name => '', GeometryType => 'Unknown') is created. If it is
# given and it contains spatial fields, GeometryType is ignored. The
# type can be also set with the named parameter.
#
# Example:
# \code
# my $roads = Geo::OGR::Driver('Memory')->Create('road')->
# CreateLayer(
# Fields => [ { Name => 'class',
# Type => 'Integer' },
# { Name => 'geom',
# Type => 'LineString25D' } ] );
# \endcode
#
# @note Many formats allow only one spatial field, which currently
# requires the use of GeometryType.
#
# @return a new Geo::OGR::Layer object.
## @method Geo::OGR::Layer CopyLayer($layer, $name, hashref options = undef)
# @param layer A Geo::OGR::Layer object to be copied.
# @param name A name for the new layer.
# @param options A ref to a hash of format specific options.
# @return a new Geo::OGR::Layer object.
## @method DeleteLayer($name)
# Deletes a layer from the data source. Note that if there is a layer
# object for the deleted layer, it becomes unusable.
# @param name name of the layer to delete.
## @method Geo::OGR::Layer ExecuteSQL($statement, $geom = undef, $dialect = "")
# @param statement A SQL statement.
# @param geom A Geo::OGR::Geometry object.
# @param dialect
# @return a new Geo::OGR::Layer object. The data source object will
# exist as long as the layer object exists.
## @method ReleaseResultSet($layer)
# @param layer A layer the has been created with ExecuteSQL.
# @note There is no need to call this method. The result set layer is
# released in the destructor of the layer that was created with SQL.
## @ignore GetProjectionRef
## @ignore GetProjection
## @ignore SetProjection
## @ignore Projection
## @method Geo::OSR::SpatialReference SpatialReference(Geo::OSR::SpatialReference sr)
# Get or set the projection of this dataset.
# @param sr [optional] a Geo::OSR::SpatialReference object,
# which replaces the existing projection definition of this dataset.
# @return a Geo::OSR::SpatialReference object, which represents the
# projection of this dataset.
# @note Methods GetProjection, SetProjection, and Projection return WKT strings.
## @ignore GetGeoTransform
## @ignore SetGeoTransform
## @method Geo::GDAL::GeoTransform GeoTransform(Geo::GDAL::GeoTransform $geo_transform)
# Transformation from cell coordinates (column,row) to projection
# coordinates (x,y)
# \code
# x = geo_transform[0] + column*geo_transform[1] + row*geo_transform[2]
# y = geo_transform[3] + column*geo_transform[4] + row*geo_transform[5]
# \endcode
# @param geo_transform [optional]
# @return the geo transform in a non-void context.
## @method BuildOverviews($resampling, arrayref overviews, coderef progress, $progress_data)
# @param resampling the resampling method, one of Geo::GDAL::RIOResamplingTypes.
# @param overviews The list of overview decimation factors to
# build. For example [2,4,8].
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data)
# @param progress_data [optional]
## @ignore GetGCPCount
## @ignore GetGCPs
## @ignore SetGCPs
## @method @GCPs(@GCPs, Geo::OSR::SpatialReference sr)
# Get or set the GCPs and their projection.
# @param GCPs [optional] a list of Geo::GDAL::GCP objects
# @param sr [optional] the projection of the GCPs.
# @return a list of Geo::GDAL::GCP objects followed by a Geo::OSR::SpatialReference object.
## @method $GetGCPProjection()
# @return projection string.
## @method FlushCache()
# Write cached data to disk. There is usually no need to call this
# method.
## @method AddBand($datatype = 'Byte', hashref options = {})
# Add a new band to the dataset. The driver must support the action.
# @param datatype GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
# @param options reference to a hash of format specific options.
# @return The added band.
## @method WriteRaster(%params)
# Write data into the dataset.
#
# @param params Named parameters:
# - \a XOff x offset (cell coordinates) (default is 0)
# - \a YOff y offset (cell coordinates) (default is 0)
# - \a XSize width of the area to write (default is the width of the dataset)
# - \a YSize height of the area to write (default is the height of the dataset)
# - \a Buf a buffer (or a reference to a buffer) containing the data. Create the buffer with \a pack function of Perl. See Geo::GDAL::Band::PackCharacter.
# - \a BufXSize (default is undef, i.e., the same as XSize)
# - \a BufYSize (default is undef, i.e., the same as YSize)
# - \a BufType data type of the buffer (default is the data type of the first band)
# - \a BandList a reference to an array of band indices (default is [1])
# - \a BufPixelSpace (default is 0)
# - \a BufLineSpace (default is 0)
# - \a BufBandSpace (default is 0)
#
# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
## @method $ReadRaster(%params)
# Read data from the dataset.
#
# @param params Named parameters:
# - \a XOff x offset (cell coordinates) (default is 0)
# - \a YOff y offset (cell coordinates) (default is 0)
# - \a XSize width of the area to read (default is the width of the dataset)
# - \a YSize height of the area to read (default is the height of the dataset)
# - \a BufXSize (default is undef, i.e., the same as XSize)
# - \a BufYSize (default is undef, i.e., the same as YSize)
# - \a BufType data type of the buffer (default is the data type of the first band)
# - \a BandList a reference to an array of band indices (default is [1])
# - \a BufPixelSpace (default is 0)
# - \a BufLineSpace (default is 0)
# - \a BufBandSpace (default is 0)
# - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'),
# - \a Progress reference to a progress function (default is undef)
# - \a ProgressData (default is undef)
#
# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
# @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter.
## @method CreateMaskBand()
# Add a mask band to the dataset.
## @method Geo::GDAL::Dataset DEMProcessing($Dest, $Processing, $ColorFilename, $Options, coderef progress, $progress_data)
# Apply a DEM processing to this dataset.
# @param Dest Destination raster dataset definition string (typically filename) or an object, which implements write and close.
# @param Processing Processing to apply, one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", or "Roughness".
# @param ColorFilename The color palette for color-relief.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { of => 'PNG'
# } to set the output format. For a list the options are given as for
# the command line utility. See <a
# href="http://www.gdal.org/gdaldem.html">gdaldem</a> for all options.
# @param progress [optional] A reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data).
# @param progress_data [optional]
#
## @method Geo::GDAL::Dataset Nearblack($Dest, $Options, coderef progress, $progress_data)
# Convert nearly black/white pixels to black/white.
# @param Dest Destination raster dataset definition string (typically
# filename), destination dataset to which to add an alpha or mask
# band, or an object, which implements write and close.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { of => 'PNG'
# } to set the output format. For a list the options are given as for
# the command line utility. See <a
# href="http://www.gdal.org/nearblack.html">nearblack</a> for all
# options.
# @return Dataset if destination dataset definition string was given,
# otherwise a boolean for success/fail but the method croaks if there
# was an error.
## @method Geo::GDAL::Dataset Translate($Dest, $Options, coderef progress, $progress_data)
# Convert this dataset into another format.
# @param Dest Destination dataset definition string (typically
# filename) or an object, which implements write and close.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { of => 'PNG'
# } to set the output format and ['-tr', 10, 10] to set the target
# resolution. For a list the options are given as for the command line
# utility. See <a
# href="http://www.gdal.org/gdal_translate.html">gdal_translate</a>
# and <a href="http://www.gdal.org/ogr2ogr.html">ogr2ogr</a> for all
# options.
# @return New dataset object if destination dataset definition
# string was given, otherwise a boolean for success/fail but the
# method croaks if there was an error.
## @method Geo::GDAL::Dataset Warped(%params)
# Create a virtual warped dataset from this dataset.
#
# @param params Named parameters:
# - \a SrcSRS Override the spatial reference system of this dataset if there is one (default is undef).
# - \a DstSRS The target spatial reference system of the result (default is undef).
# - \a ResampleAlg The resampling algorithm (default is 'NearestNeighbour').
# - \a MaxError Maximum error measured in input cellsize that is allowed in approximating the transformation (default is 0 for exact calculations).
#
# # <a href="http://www.gdal.org/gdalwarper_8h.html">Documentation for GDAL warper.</a>
#
# @return a new Geo::GDAL::Dataset object
## @method Geo::GDAL::Dataset Warp($Dest, $Options, coderef progress, $progress_data)
# Reproject this dataset.
# @param Dest Destination raster dataset definition string (typically
# filename) or an object, which implements write and close.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { of => 'PNG'
# } to set the output format and ['-tr', 10, 10] to set the target
# resolution. For a list the options are given as for the command line
# utility. See <a
# href="http://www.gdal.org/gdalwarp.html">gdalwarp</a> for all
# options.
# @note This method can be run as a package subroutine with a list of
# datasets as the first argument to mosaic several datasets.
## @method Geo::GDAL::Dataset Grid($Dest, $Options)
# Creates a regular raster grid from this data source.
# This is equivalent to the gdal_grid utility.
# @param Dest Destination raster dataset definition string (typically
# filename) or an object, which implements write and close.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { of => 'PNG'
# } to set the output format and ['-txe', 10, 10] to set the
# georeferenced X extents. You must specify at least layer name (key =
# l) or SQL to create a layer (key = sql). For a list the options are
# given as for the command line utility. See <a
# href="http://www.gdal.org/gdal_grid.html">gdal_grid</a> for a
# complete list of options.
## @method Geo::GDAL::Dataset Rasterize($Dest, $Options, coderef progress, $progress_data)
# Render data from this data source into a raster.
# @param Dest Destination raster dataset definition string (typically
# filename), destination dataset, or an object, which implements write and close.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-' and the values must be
# strings. For example give { of => 'PNG' } to set the output format
# and ['-tr', 10, 10] to set the target resolution. You must specify
# at least layer name (key = l) or SQL to create a layer (key =
# sql). To create a new raster, you need to specify either target
# resolution (tr => xres,yres) or target file size (ts =>
# width,height). For a list the options are given as for the command
# line utility.See <a
# href="http://www.gdal.org/gdal_rasterize.html">gdal_rasterize</a>
# for a complete list of options.
# @return Dataset if destination dataset definition string was given,
# otherwise a boolean for success/fail but the method croaks if there
# was an error.
#
## @method Geo::GDAL::Dataset BuildVRT($Dest, arrayref Sources, $Options, coderef progress, $progress_data)
# Build a virtual dataset from a set of datasets.
# @param Dest Destination raster dataset definition string (typically
# filename), or an object, which implements write and close.
# @param Sources A list of filenames of input datasets or a list of
# dataset objects.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-' and the values must be
# strings. For example give { r => 'cubic' } to select a resampling
# algorithm and ['-tr', 10, 10] to set the target resolution. For a
# list the options are given as for the command line utility. See <a
# href="http://www.gdal.org/gdalbuildvrt.html">gdalbuildvrt</a> for a
# complete list of options.
# @return Dataset object
#
# @note This subroutine is imported into the main namespace if Geo::GDAL
# is use'd with qw/:all/.
## @method $Info($Options)
# Information about this dataset.
# @param Options A reference to a hash or list of options. For a hash
# the keys are without the prefix '-'. For example give { JSON => 1 }
# to set the output format to JSON. For a list the options are given
# as for the command line utility. See <a
# href="http://www.gdal.org/gdalinfo.html">gdalinfo</a> for all
# options.
## @method Geo::GDAL::ColorTable ComputeColorTable(%params)
# Compute a color table from an RGB image
# @param params Named parameters:
# - \a Red The red band, the default is to use the red band of this dataset.
# - \a Green The green band, the default is to use the green band of this dataset.
# - \a Blue The blue band, the default is to use the blue band of this dataset.
# - \a NumColors The number of colors in the computed color table. Default is 256.
# - \a Progress reference to a progress function (default is undef)
# - \a ProgressData (default is undef)
# - \a Method The computation method. The default and currently only option is the median cut algorithm.
#
# @return a new color table object.
## @method Geo::GDAL::Band Dither(%params)
# Compute one band with color table image from an RGB image
# @params params Named parameters:
# - \a Red The red band, the default is to use the red band of this dataset.
# - \a Green The green band, the default is to use the green band of this dataset.
# - \a Blue The blue band, the default is to use the blue band of this dataset.
# - \a Dest The destination band. If this is not defined, a new in-memory band (and a dataset) will be created.
# - \a ColorTable The color table for the result. If this is not defined, and the destination band does not contain one, it will be computed with the ComputeColorTable method.
# - \a Progress Reference to a progress function (default is undef). Note that if ColorTable is computed using ComputeColorTable method, the progress will run twice from 0 to 1.
# - \a ProgressData (default is undef)
#
# @return the destination band.
#
# Usage example. This code converts an RGB JPEG image into a one band PNG image with a color table.
\code
my $d = Geo::GDAL::Open('pic.jpg');
Geo::GDAL::Driver('PNG')->Copy(Name => 'test.png', Src => $d->Dither->Dataset);
\endcode
## @class Geo::GDAL::Band
# @brief A raster band.
# @details
# @isa ( Geo::GDAL::MajorObject Geo::GDAL )
## @sub ColorInterpretations
# @return a list of types of color interpretation for raster
# bands. These are currently:
# +list Geo::GDAL::Const GCI_
## @attr XSize
# Object attribute.
# scalar (access as $band->{XSize})
## @attr YSize
# Object attribute.
# scalar (access as $band->{YSize})
## @ignore GetDataset
## @method Geo::GDAL::Dataset Dataset()
# @return The dataset which this band belongs to.
## @ignore GetBand
## @method $GetBandNumber()
# @return The index of this band in the parent dataset list of bands.
## @method $DataType()
# @return The data type of this band. One of Geo::GDAL::DataTypes.
## @method $PackCharacter()
# @return The character to use in Perl pack and unpack for the data of this band.
## @method @Size()
# @return The size of the band as a list (width, height).
## @method @GetBlockSize()
# @return The size of a preferred i/o raster blocks as a list (width,
# height).
## @ignore GetRasterColorInterpretation
## @ignore SetRasterColorInterpretation
## @ignore GetColorInterpretation
## @ignore SetColorInterpretation
## @method $ColorInterpretation($color_interpretation)
# @note a.k.a. GetRasterColorInterpretation and GetColorInterpretation
# (get only and returns an integer), SetRasterColorInterpretation and
# SetColorInterpretation (set only and requires an integer)
# @param color_interpretation [optional] new color interpretation, one
# of Geo::GDAL::Band::ColorInterpretations.
# @return The color interpretation of this band. One of Geo::GDAL::Band::ColorInterpretations.
## @ignore GetNoDataValue
## @ignore SetNoDataValue
## @method $DeleteNoDataValue()
## @method $NoDataValue($NoDataValue)
# Remove no data value from this band.
# @param NoDataValue [optional]
# Get or set the "no data" value.
# @note $band->NoDataValue(undef) sets the "no data" value to the
# Posix floating point maximum. Use Geo::GDAL::Band::DeleteNoDataValue
# to remove no data value from this band.
# @return The "no data" value or undef in scalar context. An undef
# value indicates that there is no no data value associated with this
# band.
## @ignore GetUnitType
## @ignore SetUnitType
## @method Unit($type)
# @param type [optional] the unit (a string).
# @note $band->Unit(undef) sets the unit value to an empty string.
# @return the unit (a string).
# @since version 1.9 of the bindings.
## @ignore GetScale
## @ignore SetScale
## @ignore GetOffset
## @ignore SetOffset
## @method ScaleAndOffset($scale, $offset)
# Scale and offset are used to transform raw cell values into the
# units returned by GetUnits(). The conversion function is:
# \code
# Units value = (raw value * scale) + offset
# \endcode
# @return a list ($scale, $offset), the values are undefined if they
# are not set.
# @since version 1.9 of the bindings.
## @method ComputeRasterMinMax($approx_ok = 0)
# @return arrayref MinMax = [min, max]
## @method ComputeBandStats($samplestep = 1)
# @param samplestep the row increment in computing the statistics.
# @note Returns uncorrected sample standard deviation.
#
# See also Geo::GDAL::Band::ComputeStatistics.
# @return a list (mean, stddev).
## @method $GetMinimum()
# @note Call Geo::GDAL::Band::ComputeStatistics before calling
# GetMinimum to make sure the value is computed.
#
# @return statistical minimum of the band or undef if statistics are
# not kept or computed in scalar context. In list context returns the
# minimum value or a (kind of) minimum value supported by the data
# type and a boolean value, which indicates which is the case (true is
# first, false is second).
## @method $GetMaximum()
# @note Call Geo::GDAL::Band::ComputeStatistics before calling
# GetMaximum to make sure the value is computed.
#
# @return statistical minimum of the band or undef if statistics are
# not kept or computed in scalar context. In list context returns the
# maximum value or a (kind of) maximum value supported by the data
# type and a boolean value, which indicates which is the case (true is
# first, false is second).
## @method @ComputeStatistics($approx_ok, $progress = undef, $progress_data = undef)
# @param approx_ok Whether it is allowed to compute the statistics
# based on overviews or similar.
# @note Returns uncorrected sample standard deviation.
#
# See also Geo::GDAL::Band::ComputeBandStats.
# @return a list ($min, $max, $mean, $stddev).
## @method @GetStatistics($approx_ok, $force)
# @param approx_ok Whether it is allowed to compute the statistics
# based on overviews or similar.
# @param force Whether to force scanning of the whole raster.
# @note Uses Geo::GDAL::Band::ComputeStatistics internally.
#
# @return a list ($min, $max, $mean, $stddev).
## @method SetStatistics($min, $max, $mean, $stddev)
# Save the statistics of the band if possible (the format can save
# arbitrary metadata).
# @param min
# @param max
# @param mean
# @param stddev
## @method $GetOverviewCount()
# @return the number of overviews available of the band.
## @method Geo::GDAL::Band GetOverview($index)
# @param index 0..GetOverviewCount-1
# @return a Geo::GDAL::Band object, which represents the internal
# overview band, or undef. if the index is out of bounds.
## @method HasArbitraryOverviews()
# @return true or false.
## @method $Checksum($xoff = 0, $yoff = 0, $xsize = undef, $ysize = undef)
# Computes a checksum from the raster or a part of it.
# @param xoff
# @param yoff
# @param xsize
# @param ysize
# @return the checksum.
## @method Fill($real_part, $imag_part = 0.0)
# Fill the band with a constant value.
# @param real_part Real component of fill value.
# @param imag_part Imaginary component of fill value.
#
## @method Piddle($piddle, $xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>, $xdim, $ydim)
# Read or write band data from/into a piddle.
#
# \note The PDL module must be available for this method to work. Also, you
# should 'use PDL' in the code that you use this method.
#
# @param piddle [only when writing] The piddle from which to read the data to be written into the band.
# @param xoff, yoff The offset for data in the band, default is top left (0, 0).
# @param xsize, ysize [optional] The size of the window in the band.
# @param xdim, ydim [optional, only when reading from a band] The size of the piddle to create.
# @return A new piddle when reading from a band (no not use when writing into a band).
## @method WriteTile($data, $xoff = 0, $yoff = 0)
# Write band data from a Perl array.
#
# \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle.
#
# @param data A two-dimensional Perl array, organizes as data->[y][x], y =
# 0..height-1, x = 0..width-1.
# @param xoff
# @param yoff
#
## @method \@ReadTile($xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>)
# Read band data into a Perl array.
#
# \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle.
#
# Usage example (print the data from a band):
# \code
# print "@$_\n" for ( @{ $band->ReadTile() } );
# \endcode
# Another usage example (process the data of a large dataset that has one band):
# \code
# my($W,$H) = $dataset->Band()->Size();
# my($xoff,$yoff,$w,$h) = (0,0,200,200);
# while (1) {
# if ($xoff >= $W) {
# $xoff = 0;
# $yoff += $h;
# last if $yoff >= $H;
# }
# my $data = $dataset->Band(1)->ReadTile($xoff,$yoff,min($W-$xoff,$w),min($H-$yoff,$h));
# # add your data processing code here
# $dataset->Band(1)->WriteTile($data,$xoff,$yoff);
# $xoff += $w;
# }
#
# sub min {
# return $_[0] < $_[1] ? $_[0] : $_[1];
# }
# \endcode
# @param xoff Number of cell to skip before starting to read from a row. Pixels are read from left to right.
# @param yoff Number of cells to skip before starting to read from a column. Pixels are read from top to bottom.
# @param xsize Number of cells to read from each row.
# @param ysize Number of cells to read from each column.
# @return a two-dimensional Perl array, organizes as data->[y][x], y =
# 0..height-1, x = 0..width-1. I.e., y is row and x is column.
## @method WriteRaster(%params)
# Write data into the band.
#
# @param params Named parameters:
# - \a XOff x offset (cell coordinates) (default is 0)
# - \a YOff y offset (cell coordinates) (default is 0)
# - \a XSize width of the area to write (default is the width of the band)
# - \a YSize height of the area to write (default is the height of the band)
# - \a Buf a buffer (or a reference to a buffer) containing the data. Create the buffer with \a pack function of Perl. See Geo::GDAL::Band::PackCharacter.
# - \a BufXSize (default is undef, i.e., the same as XSize)
# - \a BufYSize (default is undef, i.e., the same as YSize)
# - \a BufType data type of the buffer (default is the data type of the band)
# - \a BufPixelSpace (default is 0)
# - \a BufLineSpace (default is 0)
#
# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
## @method $ReadRaster(%params)
# Read data from the band.
#
# @param params Named parameters:
# - \a XOff x offset (cell coordinates) (default is 0)
# - \a YOff y offset (cell coordinates) (default is 0)
# - \a XSize width of the area to read (default is the width of the band)
# - \a YSize height of the area to read (default is the height of the band)
# - \a BufXSize (default is undef, i.e., the same as XSize)
# - \a BufYSize (default is undef, i.e., the same as YSize)
# - \a BufType data type of the buffer (default is the data type of the band)
# - \a BufPixelSpace (default is 0)
# - \a BufLineSpace (default is 0)
# - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'),
# - \a Progress reference to a progress function (default is undef)
# - \a ProgressData (default is undef)
#
# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
# @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter.
## @method @GetHistogram(%parameters)
# Compute histogram from the raster.
# @param parameters Named parameters:
# - \a Min the lower bound, default is -0.5
# - \a Max the upper bound, default is 255.5
# - \a Buckets the number of buckets in the histogram, default is 256
# - \a IncludeOutOfRange whether to use the first and last values in the returned list
# for out of range values, default is false;
# the bucket size is (Max-Min) / Buckets if this is false and
# (Max-Min) / (Buckets-2) if this is true
# - \a ApproxOK if histogram can be computed from overviews, default is false
# - \a Progress an optional progress function, the default is undef
# - \a ProgressData data for the progress function, the default is undef
# @note Histogram counts are treated as strings in the bindings to be
# able to use large integers (if GUIntBig is larger than Perl IV). In
# practice this is only important if you have a 32 bit machine and
# very large bucket counts. In those cases it may also be necessary to
# use Math::BigInt.
# @return a list which contains the count of values in each bucket
## @method @GetDefaultHistogram($force = 1, coderef progress = undef, $progress_data = undef)
# @param force true to force the computation
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data)
# @param progress_data [optional]
# @note See Note in Geo::GDAL::Band::GetHistogram.
# @return a list: ($min, $max, arrayref histogram).
## @method @SetDefaultHistogram($min, $max, $histogram)
# @param min
# @param max
# @note See Note in Geo::GDAL::Band::GetHistogram.
# @param histogram reference to an array containing the histogram
## @method FlushCache()
# Write cached data to disk. There is usually no need to call this
# method.
## @ignore GetRasterColorTable
## @ignore SetRasterColorTable
## @ignore GetColorTable
## @ignore SetColorTable
## @method Geo::GDAL::ColorTable ColorTable($ColorTable)
# Get or set the color table of this band.
# @param ColorTable [optional] a Geo::GDAL::ColorTable object
# @return A new Geo::GDAL::ColorTable object which represents the
# internal color table associated with this band. Returns undef this
# band does not have an associated color table.
## @sub @MaskFlags
# @return the list of mask flags. These are
# - \a AllValid: There are no invalid cell, all mask values will be 255.
# When used this will normally be the only flag set.
# - \a PerDataset: The mask band is shared between all bands on the dataset.
# - \a Alpha: The mask band is actually an alpha band and may have values
# other than 0 and 255.
# - \a NoData: Indicates the mask is actually being generated from nodata values.
# (mutually exclusive of Alpha).
## @method CreateMaskBand(@flags)
# @note May invalidate any previous mask band obtained with Geo::GDAL::Band::GetMaskBand.
#
# @param flags one or more mask flags. The flags are Geo::GDAL::Band::MaskFlags.
## @method Geo::GDAL::Band GetMaskBand()
# @return the mask band associated with this
# band.
## @method @GetMaskFlags()
# @return the mask flags of the mask band associated with this
# band. The flags are one or more of Geo::GDAL::Band::MaskFlags.
## @ignore GetRasterCategoryNames
## @ignore SetRasterCategoryNames
## @ignore GetCategoryNames
## @ignore SetCategoryNames
## @method @CategoryNames(@names)
# @param names [optional]
# @return
## @ignore SetDefaultRAT
## @ignore GetDefaultRAT
## @method Geo::GDAL::RasterAttributeTable AttributeTable($AttributeTable)
# @param AttributeTable [optional] A Geo::GDAL::RasterAttributeTable object.
# @return a new Geo::GDAL::RasterAttributeTable object, whose data is
# contained within the band.
## @method Geo::OGR::Layer Polygonize(%params)
# Polygonize this raster band.
#
# @param params Named parameters:
# - \a Mask A raster band, which is used as a mask to select polygonized areas. Default is undef.
# - \a OutLayer A vector layer into which the polygons are written. If not given, an in-memory layer 'polygonized' is created and returned.
# - \a PixValField The name of the field in the output layer into which the cell value of the polygon area is stored. Default is 'val'.
# - \a Options Hash or list of options. Connectedness can be set to 8
to use 8-connectedness, otherwise 4-connectedness is
used. ForceIntPixel can be set to 1 to force using a 32 bit int buffer
for cell values in the process. If this is not set and the data type
of this raster does not fit into a 32 bit int buffer, a 32 bit float
buffer is used.
# - \a Progress Progress function.
# - \a ProgressData Additional parameter for the progress function.
#
# @return Output vector layer.
## @ignore ContourGenerate
## @method Geo::OGR::Layer Contours($DataSource, hashref LayerConstructor, $ContourInterval, $ContourBase, arrayref FixedLevels, $NoDataValue, $IDField, $ElevField, coderef Progress, $ProgressData)
# Generate contours for this raster band. This method can also be used with named parameters.
# @note This method is a wrapper for ContourGenerate.
#
# An example:
# \code
# use Geo::GDAL;
# $dem = Geo::GDAL::Open('dem.gtiff');
# $contours = $dem->Band->Contours(ContourInterval => 10, ElevField => 'z');
# $n = $contours->GetFeatureCount;
# \endcode
#
# @param DataSource a Geo::OGR::DataSource object, default is a Memory data source
# @param LayerConstructor data for Geo::OGR::DataSource::CreateLayer, default is {Name => 'contours'}
# @param ContourInterval default is 100
# @param ContourBase default is 0
# @param FixedLevels a reference to a list of fixed contour levels, default is []
# @param NoDataValue default is undef
# @param IDField default is '', i.e., no field (the field is created if this is given)
# @param ElevField default is '', i.e., no field (the field is created if this is given)
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data)
# @param progress_data [optional]
# @return
## @ignore FillNodata
## @method FillNoData($mask, $max_search_dist, $smoothing_iterations, $options, coderef progress, $progress_data)
# Interpolate values for cells in this raster. The cells to fill
# should be marked in the mask band with zero.
#
# @param mask [optional] a mask band indicating cells to be interpolated (zero valued) (default is to get it with Geo::GDAL::Band::GetMaskBand).
# @param max_search_dist [optional] the maximum number of cells to
# search in all directions to find values to interpolate from (default is 10).
# @param smoothing_iterations [optional] the number of 3x3 smoothing filter passes to run (0 or more) (default is 0).
# @param options [optional] A reference to a hash. No options have been defined so far for this algorithm (default is {}).
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data) (default is undef).
# @param progress_data [optional] (default is undef).
#
# <a href="http://www.gdal.org/gdal__alg_8h.html">Documentation for GDAL algorithms</a>
## @method RegenerateOverviews(arrayref overviews, $resampling, coderef progress, $progress_data)
# @todo This is not yet available
#
# @param overviews a list of Geo::GDAL::Band objects for the overviews.
# @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average).
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data)
# @param progress_data [optional]
## @method RegenerateOverview(Geo::GDAL::Band overview, $resampling, coderef progress, $progress_data)
# @param overview a Geo::GDAL::Band object for the overview.
# @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average).
# @param progress [optional] a reference to a subroutine, which will
# be called with parameters (number progress, string msg, progress_data)
# @param progress_data [optional]
## @method Geo::GDAL::Band Sieve(%params)
# Remove small areas by merging them into the largest neighbour area.
# @param params Named parameters:
# - \a Mask A raster band, which is used as a mask to select sieved areas. Default is undef.
# - \a Dest A raster band into which the result is written. If not given, an new in-memory raster band is created and returned.
# - \a Threshold The smallest area size (in number of cells) which are not sieved away.
# - \a Options Hash or list of options. {Connectedness => 4} can be specified to use 4-connectedness, otherwise 8-connectedness is used.
# - \a Progress Progress function.
# - \a ProgressData Additional parameter for the progress function.
#
# @return The filtered raster band.
## @method Geo::GDAL::Band Distance(%params)
# Compute distances to specific cells of this raster.
# @param params Named parameters:
# - \a Distance A raster band, into which the distances are computed. If not given, a not given, a new in-memory raster band is created and returned. The data type of the raster can be given in the options.
# - \a Options Hash of options. Options are:
# - \a Values A list of cell values in this band to measure the distance from. If this option is not provided, the distance will be computed to non-zero pixel values. Currently pixel values are internally processed as integers.
# - \a DistUnits=PIXEL|GEO Indicates whether distances will be computed in cells or in georeferenced units. The default is pixel units. This also determines the interpretation of MaxDist.
# - \a MaxDist=n The maximum distance to search. Distances greater than this value will not be computed. Instead output cells will be set to a nodata value.
# - \a NoData=n The nodata value to use on the distance band for cells that are beyond MaxDist. If not provided, the distance band will be queried for a nodata value. If one is not found, 65535 will be used (255 if the type is Byte).
# - \a Use_Input_NoData=YES|NO If this option is set, the nodata value of this band will be respected. Leaving nodata cells in the input as nodata pixels in the distance raster.
# - \a Fixed_Buf_Val=n If this option is set, all cells within the MaxDist threshold are set to this value instead of the distance value.
# - \a DataType The data type for the result if it is not given.
# - \a Progress Progress function.
# - \a ProgressData Additional parameter for the progress function.
#
# @note This GDAL function behind this API is called GDALComputeProximity.
#
# @return The distance raster.
## @class Geo::GDAL::ColorTable
# @brief A color table from a raster band or a color table, which can be used for a band.
# @details
# @isa ( Geo::GDAL::MajorObject Geo::GDAL )
## @cmethod Geo::GDAL::ColorTable new($GDALPaletteInterp = 'RGB')
# Create a new empty color table.
# @return a new Geo::GDAL::ColorTable object
## @method Geo::GDAL::ColorTable Clone()
# Clone an existing color table.
# @return a new Geo::GDAL::ColorTable object
## @method $GetPaletteInterpretation()
# @return palette interpretation (string)
## @method $GetCount()
# @return The number of colors in this color table.
## @ignore ColorEntries
## @ignore ColorTable
## @method @Colors(@colors)
# Get or set the colors in this color table.
# @note The color table will expand to the size of the input list but
# it will not shrink.
# @param colors [optional] A list of all colors (a list of lists) for this color table.
# @return A list of colors (a list of lists).
## @ignore GetColorEntry
## @ignore GetColorEntryAsRGB
## @ignore SetColorEntry
## @ignore ColorEntry
## @method @Color($index, @color)
# Get or set a color in this color table.
# @param index The index of the color in the table. Note that the
# color table may expand if the index is larger than the current max
# index of this table and a color is given. An attempt to retrieve a
# color out of the current size of the table causes an error.
# @param color [optional] The color, either a list or a reference to a
# list. If the list is too short or has undef values, the undef values
# are taken as 0 except for alpha, which is taken as 255.
# @note A color is an array of four integers having a value between 0
# and 255: (gray, red, cyan or hue; green, magenta, or lightness;
# blue, yellow, or saturation; alpha or blackband)
# @return A color, in list context a list and in scalar context a reference to an anonymous array.
## @method CreateColorRamp($start_index, arrayref start_color, $end_index, arrayref end_color)
# @param start_index
# @param start_color
# @param end_index
# @param end_color
## @class Geo::GDAL::RasterAttributeTable
# @brief An attribute table in a raster band.
# @details
# @isa = ( Geo::GDAL::MajorObject Geo::GDAL )
## @cmethod Geo::GDAL::RasterAttributeTable new()
# @return a new Geo::GDAL::RasterAttributeTable object
## @sub @FieldTypes()
# @return
## @sub @FieldUsages()
# @return
## @method Geo::GDAL::RasterAttributeTable Clone()
# @return a new Geo::GDAL::RasterAttributeTable object
## @method SetRowCount($count)
# @param count
#
## @method $GetRowCount()
## @method %Columns(%columns)
# A get/set method for the columns of the RAT
# @param columns optional, a the keys are column names and the values are anonymous
# hashes with keys Type and Usage
# @return a hash similar to the optional input parameter
## @method CreateColumn($name, $type, $usage)
# @param name
# @param type one of FieldTypes
# @param usage one of FieldUsages
## @method $GetColumnCount()
# @return
## @method $GetNameOfCol($column)
# @param column
# @return
## @method $GetUsageOfCol($column)
# @param column
# @return
## @method $GetTypeOfCol($column)
# @param column
# @return
## @method $GetColOfUsage($usage)
# @param usage
# @return
## @method $GetRowOfValue($value)
# @param value a cell value
# @return row index or -1
## @method $Value($row, $column, $value)
# @param row
# @param column
# @param value [optional]
# @return
## @method $GetValueAsString($row, $column)
# @param row
# @param column
# @return
## @method $GetValueAsInt($row, $column)
# @param row
# @param column
# @return
## @method $GetValueAsDouble($row, $column)
# @param row
# @param column
# @return
## @method SetValueAsString($row, $column, $value)
# @param row
# @param column
# @param value
#
## @method SetValueAsInt($row, $column, $value)
# @param row
# @param column
# @param value
#
## @method SetValueAsDouble($row, $column, $value)
# @param row
# @param column
# @param value
#
## @ignore GetLinearBinning
## @ignore SetLinearBinning
## @method LinearBinning($Row0MinIn, $BinSizeIn)
# @param Row0MinIn [optional] the lower bound (cell value) of the first category.
# @param BinSizeIn [optional] the width of each category (in cell value units).
# @return ($Row0MinIn, $BinSizeIn) or an empty list if LinearBinning is not set.
## @class Geo::GDAL::Transformer
# @brief
# @details This class is not yet documented for the GDAL Perl bindings.
# @todo Test and document.
## @class Geo::GDAL::VSIF
# @brief A GDAL virtual file system.
# @details
# @isa = ( Geo::GDAL )
## @sub Geo::GDAL::VSIF Open($filename, $mode)
# @param filename Name of the file to open. For example "/vsimem/x".
# @param mode Access mode. 'r', 'r+', 'w', etc.
# @return A file handle on success.
## @method Close()
## @method $Read($count)
# @param count The number of bytes to read from the file.
# @return A byte string.
## @method Write($scalar)
# @param scalar The byte string to write to the file.
# @return Number of bytes written into the file.
## @method Seek($offset, $whence)
## @method $Tell()
## @method Truncate($new_size)
## @sub @ReadDir($dir)
# @return Contents of a directory in an anonymous array or as a list.
## @sub $ReadDirRecursive($dir)
# @note Give the directory in the form '/vsimem', i.e., without trailing '/'.
# @return Contents of a directory tree in an anonymous array.
## @sub @Stat($filename)
# @return ($filemode, $filesize). filemode is f for a plain file, d
# for a directory, l for a symbolic link, p for a named pipe (FIFO), S
# for a socket, b for a block special file, and c for a character
# special file.
## @sub Unlink($filename)
# @param filename The file to delete.
# @return 0 on success and -1 on an error.
## @ignore Mkdir
## @sub MkDir($path)
# Make a directory.
# @param path The directory to make.
# @note The name of this method is VSIMkdir in GDAL.
## @ignore Rmdir
## @sub RmDir($path)
# Remove a directory.
# @note The name of this method is VSIRmdir in GDAL.
## @sub Rename($old, $new)
# Rename a file.
# @note The name of this method is VSIRename in GDAL.
## @class Geo::GDAL::GeoTransform
# @brief An array of affine transformation coefficients.
# @details The geo transformation has the form
# \code
x = a + column * b + row * c
y = d + column * e + row * f
# \endcode
# where
# (column,row) is the location in cell coordinates, and
# (x,y) is the location in projection coordinates, or vice versa.
# A Geo::GDAL::GeoTransform object is a reference to an anonymous array [a,b,c,d,e,f].
# @isa = ( Geo::GDAL )
## @cmethod new(@coeffs)
# @return a new Geo::GDAL::GeoTransform object.
## @method FromGCPs(@GCPs, $ApproxOK)
# Compute transformation coefficients from a list of Geo::GDAL::GCP
# objects
# @param GCPs A list of Geo::GDAL::GCP objects.
# @param ApproxOK [optional] Minimize the error in the coefficient (integer, default is true).
# @return a new Geo::GDAL::GeoTransform object.
## @method Apply($x, $y)
# @param x Column or x, or a reference to an array of columns or x's
# @param y Row or y, or a reference to an array of columns or y's
# @return a list (x, y), where x and y are the transformed coordinates
# or references to arrays of transformed coordinates.
## @method Inv
# @return a new Geo::GDAL::GeoTransform object, which is the inverse
# of this one (in void context changes this object).