1## @class Geo::GDAL 2# @brief GDAL utility functions and a root class for raster classes. 3# @details Geo::GDAL wraps many GDAL utility functions and is as a root class 4# for all GDAL raster classes. A "raster" is an object, whose core is 5# a rectagular grid of cells, called a "band" in GDAL. Each cell 6# contains a numeric value of a specific data type. 7 8## @ignore FileFromMemBuffer 9## @ignore GDALDestroyDriverManager 10## @ignore HasThreadSupport 11## @ignore TermProgress 12## @ignore TermProgress_nocb 13 14## @ignore PopErrorHandler 15## @ignore PushErrorHandler 16## @ignore SetErrorHandler 17## @ignore Error 18## @ignore ErrorReset 19## @ignore GetLastErrorMsg 20## @ignore GetLastErrorNo 21## @ignore GetLastErrorType 22 23## @ignore last_error 24## @ignore error 25## @ignore named_parameters 26 27## @ignore i2s 28## @ignore s2i 29## @ignore keep 30## @ignore note 31## @ignore unkeep 32## @ignore unnote 33## @ignore parent 34## @ignore s_exists 35 36## @ignore GeneralCmdLineProcessor 37## @ignore ParseCommandLine 38 39## @ignore GetDataTypeName 40## @ignore GetDataTypeByName 41## @ignore GetColorInterpretationName 42## @ignore GetPaletteInterpretationName 43 44## @ignore VSIFOpenL 45## @ignore VSIFWriteL 46## @ignore VSIFCloseL 47## @ignore VSIFReadL 48## @ignore VSIFSeekL 49## @ignore VSIFTellL 50## @ignore VSIFTruncateL 51## @ignore Mkdir 52## @ignore ReadDir 53## @ignore ReadDirRecursive 54## @ignore Rename 55## @ignore Rmdir 56## @ignore Stat 57## @ignore Unlink 58## @ignore VSIStdoutSetRedirection 59## @ignore VSIStdoutUnsetRedirection 60## @ignore Debug 61 62## @ignore FillNodata 63## @ignore ContourGenerate 64## @ignore RegenerateOverviews 65## @ignore RegenerateOverview 66 67## @ignore ApplyGeoTransform 68## @ignore InvGeoTransform 69## @ignore GCPsToGeoTransform 70 71## @ignore make_processing_options 72 73## @ignore_class Geo::GDAL::GDALDEMProcessingOptions 74## @ignore wrapper_GDALDEMProcessing 75 76## @ignore_class Geo::GDAL::GDALGridOptions 77## @ignore wrapper_GDALGrid 78 79## @ignore_class Geo::GDAL::GDALNearblackOptions 80## @ignore wrapper_GDALNearblackDestDS 81## @ignore wrapper_GDALNearblackDestName 82 83## @ignore_class Geo::GDAL::GDALRasterizeOptions 84## @ignore wrapper_GDALRasterizeDestDS 85## @ignore wrapper_GDALRasterizeDestName 86 87## @ignore_class Geo::GDAL::GDALTranslateOptions 88## @ignore wrapper_GDALTranslate 89 90## @ignore_class Geo::GDAL::GDALVectorTranslateOptions 91## @ignore wrapper_GDALVectorTranslateDestDS 92## @ignore wrapper_GDALVectorTranslateDestName 93 94## @ignore_class Geo::GDAL::GDALWarpAppOptions 95## @ignore wrapper_GDALWarpDestDS 96## @ignore wrapper_GDALWarpDestName 97 98## @ignore_class Geo::GDAL::GDALInfoOptions 99## @ignore GDALInfo 100 101## @ignore_class Geo::GDAL::GDALBuildVRTOptions 102## @ignore wrapper_GDALBuildVRT_objects 103## @ignore wrapper_GDALBuildVRT_names 104 105## @ignore ComputeMedianCutPCT 106## @ignore DitherRGB2PCT 107## @ignore ReprojectImage 108## @ignore AutoCreateWarpedVRT 109## @ignore ComputeProximity 110## @ignore RasterizeLayer 111## @ignore Polygonize 112## @ignore FPolygonize 113## @ignore SieveFilter 114 115##### XML is in its own class 116 117## @ignore NodeTypes 118## @ignore NodeType 119## @ignore ParseXMLString 120## @ignore NodeData 121## @ignore Children 122## @ignore Child 123## @ignore SerializeXMLTree 124 125 126## @sub UseExceptions 127# Use the Perl exception mechanism for GDAL messages (failures are 128# confessed and warnings are warned) and collect the messages 129# into \@Geo::GDAL::error. This is the default. 130 131## @sub DontUseExceptions 132# Do not use the Perl exception mechanism for GDAL messages. Instead 133# the messages are printed to standard error. 134 135## @sub $errstr 136# Clear the error stack and return all generated GDAL error messages in one (possibly multiline) string. 137# @return the chomped error stack joined with newlines. 138 139## @sub $VersionInfo($request = 'VERSION_NUM') 140# @param request A string specifying the request. Currently either 141# "VERSION_NUM", "RELEASE_DATE", "RELEASE_NAME", or 142# "--version". Default is "VERSION_NUM". 143# @return Requested information. 144 145## @sub PushFinderLocation($path) 146# Add a path to the set of paths from where GDAL support files are 147# sought. Note that GDAL puts initially into the finder the current 148# directory and value of GDAL_DATA environment variable (if it 149# exists), installation directory (prepended with '/share/gdal' or 150# '/Resources/gdal'), or '/usr/local/share/gdal'. It is usually only 151# needed to add paths to the finder if using an alternate set of data 152# files or a non-installed GDAL is used (as in testing). 153 154## @sub PopFinderLocation() 155# Remove the latest addition from the set of support file search 156# paths. Note that calling this subroutine may remove paths GDAL put 157# into the finder. 158 159## @sub FinderClean() 160# Clear the set of support file search paths. 161 162## @sub $FindFile($basename) 163# Search for GDAL support files. 164# 165# An example: 166# \code 167# use Geo::GDAL; 168# $a = Geo::GDAL::FindFile('pcs.csv'); 169# print STDERR "$a\n"; 170# \endcode 171# Prints (for example): 172# \code 173# c:\msys\1.0\local\share\gdal\pcs.csv 174# \endcode 175# 176# @param basename The name of the file to search for. For example 177# 'pcs.csv'. 178# @return the path to the searched file or undef. 179 180## @sub SetConfigOption($key, $value) 181# @param key A GDAL config option. Consult <a 182# href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL 183# documentation</a> for available options and their use. 184# @param value A value for the option, typically 'YES', 'NO', 185# undef, path, numeric value, or a filename. 186 187## @sub $GetConfigOption($key) 188# @param key A GDAL config option. Consult <a 189# href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL 190# documentation</a> for available options and their use. 191# @return the value of the GDAL config option. 192 193## @sub $GetCacheMax() 194# @return maximum amount of memory (as bytes) for caching within GDAL. 195 196## @sub SetCacheMax($Bytes) 197# @param Bytes New maximum amount of memory for caching within GDAL. 198 199## @sub $GetCacheUsed() 200# @return the amount of memory currently used for caching within GDAL. 201 202## @sub @DataTypes() 203# @return a list of GDAL raster cell data types. These are currently: 204# +list Geo::GDAL::Const GDT_ TypeCount 205 206## @sub $GetDataTypeSize($DataType) 207# @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes). 208# @return the size as the number of bits. 209 210## @sub @DataTypeValueRange($DataType) 211# @param DataType Data type (one of those listed by Geo::GDAL::DataTypes). 212# @note Some returned values are inaccurate. 213# 214# @return the minimum, maximum range of the data type. 215 216## @sub $DataTypeIsComplex($DataType) 217# @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes). 218# @return true if the data type is a complex number. 219 220## @sub @OpenFlags() 221# @return a list of GDAL data set open modes. These are currently: 222# +list Geo::GDAL::Const OF_ 223 224## @sub @ResamplingTypes() 225# @return a list of GDAL resampling methods. These are currently: 226# +list Geo::GDAL::Const GRA_ 227 228## @sub @RIOResamplingTypes() 229# @return a list of GDAL raster IO resampling methods. These are currently: 230# +list Geo::GDAL::Const GRIORA_ 231 232## @sub $DecToDMS($angle, $axis, $precision=2) 233# Convert decimal degrees to degrees, minutes, and seconds string 234# @param angle A number 235# @param axis A string specifying latitude or longitude ('Long'). 236# @param precision 237# @return a string nndnn'nn.nn'"L where n is a number and L is either 238# N or E 239 240## @sub $PackedDMSToDec($packed) 241# @param packed DMS as a number DDDMMMSSS.SS 242# @return decimal degrees 243 244## @sub $DecToPackedDMS($dec) 245# @param dec Decimal degrees 246# @return packed DMS, i.e., a number DDDMMMSSS.SS 247 248## @ignore GetDriverCount 249## @ignore GetDriver 250## @ignore GetDriverByName 251## @ignore GetDriverNames 252 253## @sub @Drivers() 254# @note Use Geo::OGR::Drivers for vector drivers. 255# @return a list of all available GDAL raster drivers. 256 257## @sub @DriverNames() 258# Available raster format drivers. 259# \code 260# perl -MGeo::GDAL -e '@d=Geo::GDAL::DriverNames;print "@d\n"' 261# \endcode 262# @note Use Geo::OGR::DriverNames for vector drivers. 263# @return a list of the short names of all available GDAL raster drivers. 264 265## @sub Geo::GDAL::Driver Driver($Name) 266# Access a format driver. 267# @param Name The short name of the driver. One of 268# Geo::GDAL::DriverNames or Geo::OGR::DriverNames. 269# @note This subroutine is imported into the main namespace if Geo::GDAL 270# is used with qw/:all/. 271# @return a Geo::GDAL::Driver object. 272 273## @sub Geo::GDAL::Driver IdentifyDriver($path, $siblings) 274# @param path a dataset path. 275# @param siblings [optional] A list of names of files that belong to the data format. 276# @return a Geo::GDAL::Driver. 277 278## @sub $PackCharacter($DataType) 279# Get the character that is needed for Perl's pack and unpack when 280# they are used with Geo::GDAL::Band::ReadRaster and 281# Geo::GDAL::Band::WriteRaster. Note that Geo::GDAL::Band::ReadTile 282# and Geo::GDAL::Band::WriteTile have simpler interfaces that do not 283# require pack and unpack. 284# @param DataType A GDAL raster cell data type, typically from $band->DataType. 285# @return a character which can be used in Perl's pack and unpack. 286 287## @ignore AccessTypes 288 289## @sub Geo::GDAL::Dataset Open(%params) 290# Open a dataset. 291# An example, which opens an existing raster dataset for editing: 292# \code 293# use Geo::GDAL qw/:all/; 294# $ds = Open(Name => 'existing.tiff', Access => 'Update'); 295# \endcode 296# @param params Named parameters: 297# - \a Name Dataset string (typically a filename). Default is '.'. 298# - \a Access Access type, either 'ReadOnly' or 'Update'. Default is 'ReadOnly'. 299# - \a Type Dataset type, either 'Raster', 'Vector', or 'Any'. Default is 'Any'. 300# - \a Options A hash of GDAL open options passed to candidate drivers. Default is {}. 301# - \a Files A list of names of files that are auxiliary to the main file. Default is []. 302# 303# @note This subroutine is imported into the main namespace if Geo::GDAL 304# is use'd with qw/:all/. 305# 306# @note Some datasets / dataset strings do not explicitly imply the 307# dataset type (for example a PostGIS database). If the type is not 308# specified in such a case the returned dataset may be of either type. 309# 310# @return a new Geo::GDAL::Dataset object if success. 311 312## @ignore OpenShared 313 314## @sub Geo::GDAL::Dataset OpenEx(%params) 315# The generic dataset open method, used internally by all Open and OpenShared methods. 316# @param params Named parameters: 317# - \a Name The name of the data set or source to open. (Default is '.') 318# - \a Flags A list of access mode flags. Available flags are listed by Geo::GDAL::OpenFlags(). (Default is []) 319# - \a Drivers A list of short names of drivers that may be used. Empty list means all. (Default is []) 320# - \a Options A hash of GDAL open options passed to candidate drivers. (Default is {}) 321# - \a Files A list of names of files that are auxiliary to the main file. (Default is []) 322# 323# An example 324# \code 325# $ds = Geo::GDAL::OpenEx(Name => 'existing.tiff', Flags => [qw/RASTER UPDATE/]); 326# \endcode 327# @return a new Geo::GDAL::Dataset object. 328 329 330 331## @class Geo::GDAL::XML 332# @brief A simple XML parser 333# @details 334 335## @method new($string) 336# @param string String containing XML. 337# @return A new Geo::GDAL::XML object, which is a reference to an anonymous array. 338 339## @method traverse(coderef subroutine) 340# @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. 341 342## @method serialize() 343# @return The XML serialized into a string. 344 345 346 347## @class Geo::GDAL::AsyncReader 348# @brief Enable asynchronous requests. 349# @details This class is not yet documented nor tested in the GDAL Perl wrappers 350# @isa (Geo::GDAL) 351# @todo Test and document. 352 353 354 355## @class Geo::GDAL::MajorObject 356# @brief An object, which holds meta data. 357# @details 358# @isa (Geo::GDAL) 359 360## @sub Domains 361# @return the class specific DOMAINS list 362 363## @method $Description($description) 364# @param description [optional] 365# @return the description in a non-void context. 366 367## @method $GetDescription() 368# @return 369 370## @method SetDescription($NewDesc) 371# @param NewDesc 372# 373 374## @ignore SetMetadataItem 375## @ignore GetMetadataItem 376 377## @method \%Metadata(hashref metadata = undef, $domain = '') 378# @param metadata 379# @param domain 380# @return the metadata in a non-void context. 381 382## @method \%GetMetadata($domain = "") 383# @note see Metadata 384# @param domain 385# @return 386 387## @method SetMetadata(hashref metadata, $domain = "") 388# @note see Metadata 389# @param metadata 390# @param domain 391# 392 393 394 395 396## @class Geo::GDAL::Driver 397# @brief A driver for a specific dataset format. 398# @details 399# @isa (Geo::GDAL::MajorObject Geo::GDAL) 400 401## @method Open 402# The same as Geo::GDAL::Open except that only this driver is allowed. 403 404## @ignore Register 405## @ignore Deregister 406 407## @attr ShortName 408# $driver->{ShortName} 409 410## @attr LongName 411# $driver->{LongName} 412 413## @attr HelpTopic 414# $driver->{HelpTopic} 415 416## @method Rename($NewName, $OldName) 417# Rename (move) a GDAL dataset. 418# @param NewName String. 419# @param OldName String. 420 421## @method CopyFiles($NewName, $OldName) 422# Copy the files of a dataset. 423# @param NewName String. 424# @param OldName String. 425 426# @method $Name 427# @return The short name of the driver. 428 429## @method @Capabilities() 430# @return A list of capabilities. When executed as a package subroutine 431# returns a list of all potential capabilities a driver may have. When 432# executed as an object method returns a list of all capabilities the 433# driver has. 434# 435# Currently capabilities are: 436# +list Geo::GDAL::Const DCAP_ 437# 438# Examples. 439# \code 440# @all_capabilities = Geo::GDAL::Driver::Capabilities; 441# @capabilities_of_the_geotiff_driver = Geo::GDAL::Driver('GTiff')->Capabilities; 442# \endcode 443 444## @method $TestCapability($cap) 445# Test whether the driver has the specified capability. 446# @param cap A capability string (one of those returned by Capabilities). 447# @return a boolean value. 448 449## @method $Extension() 450# @note The returned extension does not contain a '.' prefix. 451# @return a suggested single extension or a list of extensions (in 452# list context) for datasets. 453 454## @method $MIMEType() 455# @return a suggested MIME type for datasets. 456 457## @method @CreationOptionList() 458# @return a list of options, each option is a hashref, the keys are 459# name, type and description or Value. Value is a listref. 460 461## @method @CreationDataTypes() 462# @return a list of data types that can be used for new datasets of this format. A subset of Geo::GDAL::DataTypes 463 464## @ignore CreateDataset 465 466## @method Geo::GDAL::Dataset Create(%params) 467# Create a raster dataset using this driver. 468# @note a.k.a. CreateDataset 469# 470# @param params Named parameters: 471# - \a Name The name for the dataset (default is 'unnamed') or an object, which implements write and close. 472# - \a Width The width for the raster dataset (default is 256). 473# - \a Height The height for the raster dataset (default is 256). 474# - \a Bands The number of bands to create into the raster dataset (default is 1). 475# - \a Type The data type for the raster cells (default is 'Byte'). One of Geo::GDAL::Driver::CreationDataTypes. 476# - \a Options Driver creation options as a reference to a hash (default is {}). 477# 478# @return A new Geo::GDAL::Dataset object. 479 480## @ignore CreateCopy 481 482## @method Geo::GDAL::Dataset Copy(%params) 483# Create a new raster Geo::GDAL::Dataset as a copy of an existing dataset. 484# @note a.k.a. CreateCopy 485# 486# @param params Named parameters: 487# - \a Name name for the new raster dataset. 488# - \a Src the source Geo::GDAL::Dataset object. 489# - \a Strict 1 (default) if the copy must be strictly equivalent, or 0 if the copy may adapt. 490# - \a Options an anonymous hash of driver specific options. 491# - \a Progress [optional] a reference to a subroutine, which will 492# be called with parameters (number progress, string msg, progress_data). 493# - \a ProgressData [optional] 494# @return a new Geo::GDAL::Dataset object. 495 496## @method Delete($name) 497# @param name 498 499 500 501 502## @class Geo::GDAL::GCP 503# @brief A ground control point for georeferencing rasters. 504# @details 505# @isa (Geo::GDAL) 506 507## @cmethod $new($x = 0.0, $y = 0.0, $z = 0.0, $column = 0.0, $row = 0.0, $info = "", $id = "") 508# @param x projection coordinate 509# @param y projection coordinate 510# @param z projection coordinate 511# @param column cell x coordinate 512# @param row cell y coordinate 513# @param info informational message 514# @param id unique identifier (string) 515# @return a new Geo::GDAL::GCP object 516 517## @attr X 518# projection coordinate (access as $gcp->{X}) 519 520## @attr Y 521# projection coordinate (access as $gcp->{Y}) 522 523## @attr Z 524# projection coordinate (access as $gcp->{Z}) 525 526## @attr Column 527# cell x coordinate (access as $gcp->{Column}) 528 529## @attr Row 530# cell y coordinate (access as $gcp->{Row}) 531 532## @attr Info 533# informational message (access as $gcp->{Info}) 534 535## @attr Id 536# unique identifier (string) (access as $gcp->{Id}) 537 538 539 540 541## @class Geo::GDAL::Dataset 542# @brief A set of associated raster bands or vector layer source. 543# @details 544# @isa (Geo::GDAL::MajorObject Geo::GDAL) 545 546## @sub Geo::GDAL::Dataset Open 547# The same as Geo::GDAL::Open 548 549## @sub Geo::GDAL::Dataset OpenShared 550# The same as Geo::GDAL::OpenShared 551 552## @ignore FlushCache 553## @ignore stdout_redirection_wrapper 554 555## @attr RasterXSize 556# scalar (access as $dataset->{RasterXSize}) 557 558## @attr RasterYSize 559# scalar (access as $dataset->{RasterYSize}) 560 561## @attr RasterCount 562# scalar (access as $dataset->{RasterCount}) 563 564## @method @GetFileList() 565# @return list of files GDAL believes to be part of this dataset. 566 567## @method @Size() 568# @return (width, height) 569 570## @method Geo::GDAL::Driver Driver() 571# @note a.k.a. GetDriver 572# @return a Geo::GDAL::Driver object that was used to open or create this dataset. 573 574## @ignore GetRasterBand 575 576## @method Geo::GDAL::Band Band($index) 577# Create a band object for the band within the dataset. 578# @note a.k.a. GetRasterBand 579# @param index 1...RasterCount, default is 1. 580# @return a new Geo::GDAL::Band object 581 582## @method @Bands() 583# @return a list of new Geo::GDAL::Band objects 584 585## @ignore GetLayerByIndex 586## @ignore GetLayerByName 587## @ignore Layer 588 589## @method Geo::OGR::Layer GetLayer($name) 590# @param name the name of the requested layer. If not given, then 591# returns the first layer in the data source. 592# @return a new Geo::OGR::Layer object that represents the layer 593# in the data source. 594 595## @ignore GetLayerCount 596## @ignore Layers 597 598## @method @GetLayerNames() 599# @note Delivers the functionality of undocumented method GetLayerCount. 600# @return a list of the names of the layers this data source provides. 601 602## @method Geo::OGR::Layer CreateLayer(%params) 603# @brief Create a new vector layer into this dataset. 604# 605# @param %params Named parameters: 606# - \a Name (scalar) name for the new layer. 607# - \a Fields (array reference) a list of (scalar and geometry) field definitions as in 608# Geo::OGR::Layer::CreateField. 609# - \a ApproxOK (boolean value, default is true) a flag, which is forwarded to Geo::OGR::Layer::CreateField. 610# - \a Options (hash reference) driver specific hash of layer creation options. 611# - \a Schema (hash reference, deprecated, use \a Fields and \a Name) may contain keys Name, Fields, GeomFields, GeometryType. 612# - \a SRS (scalar) the spatial reference for the default geometry field. 613# - \a GeometryType (scalar) the type of the default geometry field 614# (if only one geometry field). Default is 'Unknown'. 615# 616# @note If Fields or Schema|Fields is not given, a default geometry 617# field (Name => '', GeometryType => 'Unknown') is created. If it is 618# given and it contains spatial fields, both GeometryType and SRS are 619# ignored. The type can be also set with the named parameter. 620# 621# Example: 622# \code 623# my $roads = Geo::OGR::Driver('Memory')->Create('road')-> 624# CreateLayer( 625# Fields => [ { Name => 'class', 626# Type => 'Integer' }, 627# { Name => 'geom', 628# Type => 'LineString25D' } ] ); 629# \endcode 630# 631# @note Many formats allow only one spatial field, which currently 632# requires the use of GeometryType. 633# 634# @return a new Geo::OGR::Layer object. 635 636## @method Geo::OGR::Layer CopyLayer($layer, $name, hashref options = undef) 637# @param layer A Geo::OGR::Layer object to be copied. 638# @param name A name for the new layer. 639# @param options A ref to a hash of format specific options. 640# @return a new Geo::OGR::Layer object. 641 642## @method DeleteLayer($name) 643# Deletes a layer from the data source. Note that if there is a layer 644# object for the deleted layer, it becomes unusable. 645# @param name name of the layer to delete. 646 647## @method Geo::OGR::Layer ExecuteSQL($statement, $geom = undef, $dialect = "") 648# @param statement A SQL statement. 649# @param geom A Geo::OGR::Geometry object. 650# @param dialect 651# @return a new Geo::OGR::Layer object. The data source object will 652# exist as long as the layer object exists. 653 654## @method ReleaseResultSet($layer) 655# @param layer A layer the has been created with ExecuteSQL. 656# @note There is no need to call this method. The result set layer is 657# released in the destructor of the layer that was created with SQL. 658 659## @ignore GetProjectionRef 660## @ignore GetProjection 661## @ignore SetProjection 662## @ignore Projection 663 664## @method Geo::OSR::SpatialReference SpatialReference(Geo::OSR::SpatialReference sr) 665# Get or set the projection of this dataset. 666# @param sr [optional] a Geo::OSR::SpatialReference object, 667# which replaces the existing projection definition of this dataset. 668# @return a Geo::OSR::SpatialReference object, which represents the 669# projection of this dataset. 670# @note Methods GetProjection, SetProjection, and Projection return WKT strings. 671 672## @ignore GetGeoTransform 673## @ignore SetGeoTransform 674 675## @method Geo::GDAL::GeoTransform GeoTransform(Geo::GDAL::GeoTransform $geo_transform) 676# Transformation from cell coordinates (column,row) to projection 677# coordinates (x,y) 678# \code 679# x = geo_transform[0] + column*geo_transform[1] + row*geo_transform[2] 680# y = geo_transform[3] + column*geo_transform[4] + row*geo_transform[5] 681# \endcode 682# @param geo_transform [optional] 683# @return the geo transform in a non-void context. 684 685## @method BuildOverviews($resampling, arrayref overviews, coderef progress, $progress_data) 686# @param resampling the resampling method, one of Geo::GDAL::RIOResamplingTypes. 687# @param overviews The list of overview decimation factors to 688# build. For example [2,4,8]. 689# @param progress [optional] a reference to a subroutine, which will 690# be called with parameters (number progress, string msg, progress_data) 691# @param progress_data [optional] 692 693## @ignore GetGCPCount 694## @ignore GetGCPs 695## @ignore SetGCPs 696 697## @method @GCPs(@GCPs, Geo::OSR::SpatialReference sr) 698# Get or set the GCPs and their projection. 699# @param GCPs [optional] a list of Geo::GDAL::GCP objects 700# @param sr [optional] the projection of the GCPs. 701# @return a list of Geo::GDAL::GCP objects followed by a Geo::OSR::SpatialReference object. 702 703## @method $GetGCPProjection() 704# @return projection string. 705 706## @method Geo::GDAL::Extent Extent(@params) 707# @param params nothing, or a list ($xoff, $yoff, $w, $h) 708# @return A new Geo::GDAL::Extent object that represents the area that 709# this raster or the specified tile covers. 710 711## @method Tile(Geo::GDAL::Extent e) 712# Compute the top left cell coordinates and width and height of the 713# tile that covers the given extent. 714# @param e The extent whose tile is needed. 715# @note Requires that the raster is a strictly north up one. 716# @return A list ($xoff, $yoff, $xsize, $ysize). 717 718## @method FlushCache() 719# Write cached data to disk. There is usually no need to call this 720# method. 721 722## @method AddBand($datatype = 'Byte', hashref options = {}) 723# Add a new band to the dataset. The driver must support the action. 724# @param datatype GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes). 725# @param options reference to a hash of format specific options. 726# @return The added band. 727 728## @method WriteRaster(%params) 729# Write data into the dataset. 730# 731# @param params Named parameters: 732# - \a XOff x offset (cell coordinates) (default is 0) 733# - \a YOff y offset (cell coordinates) (default is 0) 734# - \a XSize width of the area to write (default is the width of the dataset) 735# - \a YSize height of the area to write (default is the height of the dataset) 736# - \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. 737# - \a BufXSize (default is undef, i.e., the same as XSize) 738# - \a BufYSize (default is undef, i.e., the same as YSize) 739# - \a BufType data type of the buffer (default is the data type of the first band) 740# - \a BandList a reference to an array of band indices (default is [1]) 741# - \a BufPixelSpace (default is 0) 742# - \a BufLineSpace (default is 0) 743# - \a BufBandSpace (default is 0) 744# 745# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a> 746 747## @method $ReadRaster(%params) 748# Read data from the dataset. 749# 750# @param params Named parameters: 751# - \a XOff x offset (cell coordinates) (default is 0) 752# - \a YOff y offset (cell coordinates) (default is 0) 753# - \a XSize width of the area to read (default is the width of the dataset) 754# - \a YSize height of the area to read (default is the height of the dataset) 755# - \a BufXSize (default is undef, i.e., the same as XSize) 756# - \a BufYSize (default is undef, i.e., the same as YSize) 757# - \a BufType data type of the buffer (default is the data type of the first band) 758# - \a BandList a reference to an array of band indices (default is [1]) 759# - \a BufPixelSpace (default is 0) 760# - \a BufLineSpace (default is 0) 761# - \a BufBandSpace (default is 0) 762# - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'), 763# - \a Progress reference to a progress function (default is undef) 764# - \a ProgressData (default is undef) 765# 766# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a> 767# @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter. 768 769## @method CreateMaskBand() 770# Add a mask band to the dataset. 771 772## @method Geo::GDAL::Dataset DEMProcessing($Dest, $Processing, $ColorFilename, hashref Options, coderef progress, $progress_data) 773# Apply a DEM processing to this dataset. 774# @param Dest Destination raster dataset definition string (typically filename) or an object, which implements write and close. 775# @param Processing Processing to apply, one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", or "Roughness". 776# @param ColorFilename The color palette for color-relief. 777# @param Options See section \ref index_processing_options. 778# @param progress [optional] A reference to a subroutine, which will 779# be called with parameters (number progress, string msg, progress_data). 780# @param progress_data [optional] 781# 782 783## @method Geo::GDAL::Dataset Nearblack($Dest, hashref Options, coderef progress, $progress_data) 784# Convert nearly black/white pixels to black/white. 785# @param Dest Destination raster dataset definition string (typically 786# filename), destination dataset to which to add an alpha or mask 787# band, or an object, which implements write and close. 788# @param Options See section \ref index_processing_options. 789# @return Dataset if destination dataset definition string was given, 790# otherwise a boolean for success/fail but the method croaks if there 791# was an error. 792 793## @method Geo::GDAL::Dataset Translate($Dest, hashref Options, coderef progress, $progress_data) 794# Convert this dataset into another format. 795# @param Dest Destination dataset definition string (typically 796# filename) or an object, which implements write and close. 797# @param Options See section \ref index_processing_options. 798# @return New dataset object if destination dataset definition 799# string was given, otherwise a boolean for success/fail but the 800# method croaks if there was an error. 801 802## @method Geo::GDAL::Dataset Warped(%params) 803# Create a virtual warped dataset from this dataset. 804# 805# @param params Named parameters: 806# - \a SrcSRS Override the spatial reference system of this dataset if there is one (default is undef). 807# - \a DstSRS The target spatial reference system of the result (default is undef). 808# - \a ResampleAlg The resampling algorithm (default is 'NearestNeighbour'). 809# - \a MaxError Maximum error measured in input cellsize that is allowed in approximating the transformation (default is 0 for exact calculations). 810# 811# # <a href="http://www.gdal.org/gdalwarper_8h.html">Documentation for GDAL warper.</a> 812# 813# @return a new Geo::GDAL::Dataset object 814 815## @method Geo::GDAL::Dataset Warp($Dest, hashref Options, coderef progress, $progress_data) 816# Reproject this dataset. 817# @param Dest Destination raster dataset definition string (typically 818# filename) or an object, which implements write and close. 819# @param Options See section \ref index_processing_options. 820# @note This method can be run as a package subroutine with a list of 821# datasets as the first argument to mosaic several datasets. 822 823## @method Geo::GDAL::Dataset Grid($Dest, hashref Options) 824# Creates a regular raster grid from this data source. 825# This is equivalent to the gdal_grid utility. 826# @param Dest Destination raster dataset definition string (typically 827# filename) or an object, which implements write and close. 828# @param Options See section \ref index_processing_options. 829 830## @method Geo::GDAL::Dataset Rasterize($Dest, hashref Options, coderef progress, $progress_data) 831# Render data from this data source into a raster. 832# @param Dest Destination raster dataset definition string (typically 833# filename), destination dataset, or an object, which implements write and close. 834# @param Options See section \ref index_processing_options. 835# @return Dataset if destination dataset definition string was given, 836# otherwise a boolean for success/fail but the method croaks if there 837# was an error. 838# 839 840## @method Geo::GDAL::Dataset BuildVRT($Dest, arrayref Sources, hashref Options, coderef progress, $progress_data) 841# Build a virtual dataset from a set of datasets. 842# @param Dest Destination raster dataset definition string (typically 843# filename), or an object, which implements write and close. 844# @param Sources A list of filenames of input datasets or a list of 845# dataset objects. 846# @param Options See section \ref index_processing_options. 847# @return Dataset object 848# 849# @note This subroutine is imported into the main namespace if Geo::GDAL 850# is use'd with qw/:all/. 851 852## @method $Info(hashref Options) 853# Information about this dataset. 854# @param Options See section \ref index_processing_options. 855 856## @method Geo::GDAL::ColorTable ComputeColorTable(%params) 857# Compute a color table from an RGB image 858# @param params Named parameters: 859# - \a Red The red band, the default is to use the red band of this dataset. 860# - \a Green The green band, the default is to use the green band of this dataset. 861# - \a Blue The blue band, the default is to use the blue band of this dataset. 862# - \a NumColors The number of colors in the computed color table. Default is 256. 863# - \a Progress reference to a progress function (default is undef) 864# - \a ProgressData (default is undef) 865# - \a Method The computation method. The default and currently only option is the median cut algorithm. 866# 867# @return a new color table object. 868 869## @method Geo::GDAL::Band Dither(%params) 870# Compute one band with color table image from an RGB image 871# @params params Named parameters: 872# - \a Red The red band, the default is to use the red band of this dataset. 873# - \a Green The green band, the default is to use the green band of this dataset. 874# - \a Blue The blue band, the default is to use the blue band of this dataset. 875# - \a Dest The destination band. If this is not defined, a new in-memory band (and a dataset) will be created. 876# - \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. 877# - \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. 878# - \a ProgressData (default is undef) 879# 880# @return the destination band. 881# 882# Usage example. This code converts an RGB JPEG image into a one band PNG image with a color table. 883\code 884my $d = Geo::GDAL::Open('pic.jpg'); 885Geo::GDAL::Driver('PNG')->Copy(Name => 'test.png', Src => $d->Dither->Dataset); 886\endcode 887 888 889 890 891## @class Geo::GDAL::Extent 892# @brief A rectangular area in projection coordinates: xmin, ymin, xmax, ymax. 893 894## @sub Geo::GDAL::Extent new(@params) 895# @param params nothing, a list ($xmin, $ymin, $xmax, $ymax), or an Extent object 896# @return A new Extent object (empty if no parameters, a copy of the parameter if it is an Extent object). 897 898## @sub @Size() 899# @return A list ($width, $height). 900 901## @sub $Overlaps($extent) 902# @param extent Another Geo::GDAL::Extent object. 903# @return True if this extent overlaps the other extent, false otherwise. 904 905## @sub $Overlap($extent) 906# @param extent Another Geo::GDAL::Extent object. 907# @return A new, possibly empty, Geo::GDAL::Extent object, which 908# represents the joint area of the two extents. 909 910## @sub ExpandToInclude($extent) 911# Extends this extent to include the other extent. 912# @param extent Another Geo::GDAL::Extent object. 913 914 915 916 917## @class Geo::GDAL::Band 918# @brief A raster band. 919# @details 920# @isa ( Geo::GDAL::MajorObject Geo::GDAL ) 921 922## @sub ColorInterpretations 923# @return a list of types of color interpretation for raster 924# bands. These are currently: 925# +list Geo::GDAL::Const GCI_ 926 927## @attr XSize 928# Object attribute. 929# scalar (access as $band->{XSize}) 930 931## @attr YSize 932# Object attribute. 933# scalar (access as $band->{YSize}) 934 935## @ignore GetDataset 936 937## @method Geo::GDAL::Dataset Dataset() 938# @return The dataset which this band belongs to. 939 940## @ignore GetBand 941 942## @method $GetBandNumber() 943# @return The index of this band in the parent dataset list of bands. 944 945## @method $DataType() 946# @return The data type of this band. One of Geo::GDAL::DataTypes. 947 948## @method $PackCharacter() 949# @return The character to use in Perl pack and unpack for the data of this band. 950 951## @method @Size() 952# @return The size of the band as a list (width, height). 953 954## @method @BlockSize() 955# A.k.a GetBlockSize 956# @return The size of a preferred i/o raster block size as a list 957# (width, height). 958 959## @ignore GetRasterColorInterpretation 960## @ignore SetRasterColorInterpretation 961## @ignore GetColorInterpretation 962## @ignore SetColorInterpretation 963 964## @method $ColorInterpretation($color_interpretation) 965# @note a.k.a. GetRasterColorInterpretation and GetColorInterpretation 966# (get only and returns an integer), SetRasterColorInterpretation and 967# SetColorInterpretation (set only and requires an integer) 968# @param color_interpretation [optional] new color interpretation, one 969# of Geo::GDAL::Band::ColorInterpretations. 970# @return The color interpretation of this band. One of Geo::GDAL::Band::ColorInterpretations. 971 972## @ignore GetNoDataValue 973## @ignore SetNoDataValue 974 975## @method $DeleteNoDataValue() 976 977## @method $NoDataValue($NoDataValue) 978# Get or set the "no data" value. 979# @param NoDataValue [optional] 980# @note $band->NoDataValue(undef) sets the NoData value to the 981# Posix floating point maximum. Use Geo::GDAL::Band::DeleteNoDataValue 982# to stop this band using a NoData value. 983# @return The NoData value or undef in scalar context. An undef 984# value indicates that there is no NoData value associated with this 985# band. 986 987## @ignore GetUnitType 988## @ignore SetUnitType 989 990## @method Unit($type) 991# @param type [optional] the unit (a string). 992# @note $band->Unit(undef) sets the unit value to an empty string. 993# @return the unit (a string). 994# @since version 1.9 of the bindings. 995 996## @ignore GetScale 997## @ignore SetScale 998## @ignore GetOffset 999## @ignore SetOffset 1000 1001## @method ScaleAndOffset($scale, $offset) 1002# Scale and offset are used to transform raw cell values into the 1003# units returned by GetUnits(). The conversion function is: 1004# \code 1005# Units value = (raw value * scale) + offset 1006# \endcode 1007# @return a list ($scale, $offset), the values are undefined if they 1008# are not set. 1009# @since version 1.9 of the bindings. 1010 1011## @method hashref ClassCounts($classifier, $progress = undef, $progress_data = undef) 1012# Compute the counts of cell values or number of cell values in ranges. 1013# @note Classifier is required only for float bands. 1014# @note NoData values are counted similar to other values when 1015# classifier is not defined for integer rasters. 1016# 1017# @param classifier Anonymous array of format [ $comparison, 1018# $classifier ], where $comparison is a string '<', '<=', '>', or '>=' 1019# and $classifier is an anonymous array of format [ $value, 1020# $value|$classifier, $value|$classifier ], where $value is a numeric 1021# value against which the reclassified value is compared to. If the 1022# comparison returns true, then the second $value or $classifier is 1023# applied, and if not then the third $value or $classifier. 1024# 1025# In the example below, the line is divided into ranges 1026# [-inf..3), [3..5), and [5..inf], i.e., three ranges with class 1027# indexes 0, 1, and 2. Note that the indexes are used as keys for 1028# class counts and not the class values (here 1.0, 2.0, and 3.0), 1029# which are used in Geo::GDAL::Band::Reclassify. 1030# \code 1031# $classifier = [ '<', [5.0, [3.0, 1.0, 2.0], 3.0] ]; 1032# # Howto create this $classifier from @class_boundaries: 1033# my $classifier = ['<=']; 1034# my $tree = [$class_boundaries[0], 0, 1]; 1035# for my $i (1 .. $#class_boundaries) { 1036# $tree = [$class_boundaries[$i], [@$tree], $i+1]; 1037# } 1038# push @$classifier, $tree; 1039# \endcode 1040# @return a reference to an anonymous hash, which contains the class 1041# values (indexes) as keys and the number of cells with that value or 1042# in that range as values. If the subroutine is user terminated an 1043# error is raised. 1044 1045## @method Reclassify($classifier, $progress = undef, $progress_data = undef) 1046# Reclassify the cells in the band. 1047# @note NoData values in integer rasters are reclassified if 1048# explicitly specified in the hash classifier. However, they are not 1049# reclassified to the default value, if one is specified. In real 1050# valued rasters nodata cells are not reclassified. 1051# @note If the subroutine is user terminated or the classifier is 1052# incorrect, already reclassified cells will stay reclassified but an 1053# error is raised. 1054# @param classifier For integer rasters an anonymous hash, which 1055# contains old class values as keys and new class values as values, or 1056# an array classifier as in Geo::GDAL::Band::ClassCounts. In a hash 1057# classifier a special key '*' (star) can be used as default, to act 1058# as a fallback new class value. For real valued rasters the 1059# classifier is as in Geo::GDAL::Band::ClassCounts. 1060 1061## @method ComputeRasterMinMax($approx_ok = 0) 1062# @return arrayref MinMax = [min, max] 1063 1064## @method ComputeBandStats($samplestep = 1) 1065# @param samplestep the row increment in computing the statistics. 1066# @note Returns uncorrected sample standard deviation. 1067# 1068# See also Geo::GDAL::Band::ComputeStatistics. 1069# @return a list (mean, stddev). 1070 1071## @method $GetMinimum() 1072# @note Call Geo::GDAL::Band::ComputeStatistics before calling 1073# GetMinimum to make sure the value is computed. 1074# 1075# @return statistical minimum of the band or undef if statistics are 1076# not kept or computed in scalar context. In list context returns the 1077# minimum value or a (kind of) minimum value supported by the data 1078# type and a boolean value, which indicates which is the case (true is 1079# first, false is second). 1080 1081## @method $GetMaximum() 1082# @note Call Geo::GDAL::Band::ComputeStatistics before calling 1083# GetMaximum to make sure the value is computed. 1084# 1085# @return statistical minimum of the band or undef if statistics are 1086# not kept or computed in scalar context. In list context returns the 1087# maximum value or a (kind of) maximum value supported by the data 1088# type and a boolean value, which indicates which is the case (true is 1089# first, false is second). 1090 1091## @method @ComputeStatistics($approx_ok, $progress = undef, $progress_data = undef) 1092# @param approx_ok Whether it is allowed to compute the statistics 1093# based on overviews or similar. 1094# @note Returns uncorrected sample standard deviation. 1095# 1096# See also Geo::GDAL::Band::ComputeBandStats. 1097# @return a list ($min, $max, $mean, $stddev). 1098 1099## @method @GetStatistics($approx_ok, $force) 1100# @param approx_ok Whether it is allowed to compute the statistics 1101# based on overviews or similar. 1102# @param force Whether to force scanning of the whole raster. 1103# @note Uses Geo::GDAL::Band::ComputeStatistics internally. 1104# 1105# @return a list ($min, $max, $mean, $stddev). 1106 1107## @method SetStatistics($min, $max, $mean, $stddev) 1108# Save the statistics of the band if possible (the format can save 1109# arbitrary metadata). 1110# @param min 1111# @param max 1112# @param mean 1113# @param stddev 1114 1115## @method $GetOverviewCount() 1116# @return the number of overviews available of the band. 1117 1118## @method Geo::GDAL::Band GetOverview($index) 1119# @param index 0..GetOverviewCount-1 1120# @return a Geo::GDAL::Band object, which represents the internal 1121# overview band, or undef. if the index is out of bounds. 1122 1123## @method HasArbitraryOverviews() 1124# @return true or false. 1125 1126## @method $Checksum($xoff = 0, $yoff = 0, $xsize = undef, $ysize = undef) 1127# Computes a checksum from the raster or a part of it. 1128# @param xoff 1129# @param yoff 1130# @param xsize 1131# @param ysize 1132# @return the checksum. 1133 1134## @method Fill($real_part, $imag_part = 0.0) 1135# Fill the band with a constant value. 1136# @param real_part Real component of fill value. 1137# @param imag_part Imaginary component of fill value. 1138# 1139 1140## @method Piddle($piddle, $xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>, $xdim, $ydim) 1141# Read or write band data from/into a piddle. 1142# 1143# \note The PDL module must be available for this method to work. Also, you 1144# should 'use PDL' in the code that you use this method. 1145# 1146# @param piddle [only when writing] The piddle from which to read the data to be written into the band. 1147# @param xoff, yoff The offset for data in the band, default is top left (0, 0). 1148# @param xsize, ysize [optional] The size of the window in the band. 1149# @param xdim, ydim [optional, only when reading from a band] The size of the piddle to create. 1150# @return A new piddle when reading from a band (no not use when writing into a band). 1151 1152## @method WriteTile($data, $xoff = 0, $yoff = 0) 1153# Write band data from a Perl array. 1154# 1155# \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle. 1156# 1157# @param data A two-dimensional Perl array, organizes as data->[y][x], y = 1158# 0..height-1, x = 0..width-1. 1159# @param xoff 1160# @param yoff 1161# 1162 1163## @method \@ReadTile($xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>) 1164# Read band data into a Perl array. 1165# 1166# \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle. 1167# 1168# Usage example (print the data from a band): 1169# \code 1170# print "@$_\n" for ( @{ $band->ReadTile() } ); 1171# \endcode 1172# Another usage example (process the data of a large dataset that has one band): 1173# \code 1174# my($W,$H) = $dataset->Band()->Size(); 1175# my($xoff,$yoff,$w,$h) = (0,0,200,200); 1176# while (1) { 1177# if ($xoff >= $W) { 1178# $xoff = 0; 1179# $yoff += $h; 1180# last if $yoff >= $H; 1181# } 1182# my $data = $dataset->Band(1)->ReadTile($xoff,$yoff,min($W-$xoff,$w),min($H-$yoff,$h)); 1183# # add your data processing code here 1184# $dataset->Band(1)->WriteTile($data,$xoff,$yoff); 1185# $xoff += $w; 1186# } 1187# 1188# sub min { 1189# return $_[0] < $_[1] ? $_[0] : $_[1]; 1190# } 1191# \endcode 1192# @param xoff Number of cell to skip before starting to read from a row. Pixels are read from left to right. 1193# @param yoff Number of cells to skip before starting to read from a column. Pixels are read from top to bottom. 1194# @param xsize Number of cells to read from each row. 1195# @param ysize Number of cells to read from each column. 1196# @return a two-dimensional Perl array, organizes as data->[y][x], y = 1197# 0..height-1, x = 0..width-1. I.e., y is row and x is column. 1198 1199## @method WriteRaster(%params) 1200# Write data into the band. 1201# 1202# @param params Named parameters: 1203# - \a XOff x offset (cell coordinates) (default is 0) 1204# - \a YOff y offset (cell coordinates) (default is 0) 1205# - \a XSize width of the area to write (default is the width of the band) 1206# - \a YSize height of the area to write (default is the height of the band) 1207# - \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. 1208# - \a BufXSize (default is undef, i.e., the same as XSize) 1209# - \a BufYSize (default is undef, i.e., the same as YSize) 1210# - \a BufType data type of the buffer (default is the data type of the band) 1211# - \a BufPixelSpace (default is 0) 1212# - \a BufLineSpace (default is 0) 1213# 1214# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a> 1215 1216## @method $ReadRaster(%params) 1217# Read data from the band. 1218# 1219# @param params Named parameters: 1220# - \a XOff x offset (cell coordinates) (default is 0) 1221# - \a YOff y offset (cell coordinates) (default is 0) 1222# - \a XSize width of the area to read (default is the width of the band) 1223# - \a YSize height of the area to read (default is the height of the band) 1224# - \a BufXSize (default is undef, i.e., the same as XSize) 1225# - \a BufYSize (default is undef, i.e., the same as YSize) 1226# - \a BufType data type of the buffer (default is the data type of the band) 1227# - \a BufPixelSpace (default is 0) 1228# - \a BufLineSpace (default is 0) 1229# - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'), 1230# - \a Progress reference to a progress function (default is undef) 1231# - \a ProgressData (default is undef) 1232# 1233# <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a> 1234# @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter. 1235 1236## @method @GetHistogram(%parameters) 1237# Compute histogram from the raster. 1238# @param parameters Named parameters: 1239# - \a Min the lower bound, default is -0.5 1240# - \a Max the upper bound, default is 255.5 1241# - \a Buckets the number of buckets in the histogram, default is 256 1242# - \a IncludeOutOfRange whether to use the first and last values in the returned list 1243# for out of range values, default is false; 1244# the bucket size is (Max-Min) / Buckets if this is false and 1245# (Max-Min) / (Buckets-2) if this is true 1246# - \a ApproxOK if histogram can be computed from overviews, default is false 1247# - \a Progress an optional progress function, the default is undef 1248# - \a ProgressData data for the progress function, the default is undef 1249# @note Histogram counts are treated as strings in the bindings to be 1250# able to use large integers (if GUIntBig is larger than Perl IV). In 1251# practice this is only important if you have a 32 bit machine and 1252# very large bucket counts. In those cases it may also be necessary to 1253# use Math::BigInt. 1254# @return a list which contains the count of values in each bucket 1255 1256## @method @GetDefaultHistogram($force = 1, coderef progress = undef, $progress_data = undef) 1257# @param force true to force the computation 1258# @param progress [optional] a reference to a subroutine, which will 1259# be called with parameters (number progress, string msg, progress_data) 1260# @param progress_data [optional] 1261# @note See Note in Geo::GDAL::Band::GetHistogram. 1262# @return a list: ($min, $max, arrayref histogram). 1263 1264## @method @SetDefaultHistogram($min, $max, $histogram) 1265# @param min 1266# @param max 1267# @note See Note in Geo::GDAL::Band::GetHistogram. 1268# @param histogram reference to an array containing the histogram 1269 1270## @method FlushCache() 1271# Write cached data to disk. There is usually no need to call this 1272# method. 1273 1274## @ignore GetRasterColorTable 1275## @ignore SetRasterColorTable 1276## @ignore GetColorTable 1277## @ignore SetColorTable 1278 1279## @method Geo::GDAL::ColorTable ColorTable($ColorTable) 1280# Get or set the color table of this band. 1281# @param ColorTable [optional] a Geo::GDAL::ColorTable object 1282# @return A new Geo::GDAL::ColorTable object which represents the 1283# internal color table associated with this band. Returns undef this 1284# band does not have an associated color table. 1285 1286## @sub @MaskFlags 1287# @return the list of mask flags. These are 1288# - \a AllValid: There are no invalid cell, all mask values will be 255. 1289# When used this will normally be the only flag set. 1290# - \a PerDataset: The mask band is shared between all bands on the dataset. 1291# - \a Alpha: The mask band is actually an alpha band and may have values 1292# other than 0 and 255. 1293# - \a NoData: Indicates the mask is actually being generated from NoData values. 1294# (mutually exclusive of Alpha). 1295 1296## @method CreateMaskBand(@flags) 1297# @note May invalidate any previous mask band obtained with Geo::GDAL::Band::GetMaskBand. 1298# 1299# @param flags one or more mask flags. The flags are Geo::GDAL::Band::MaskFlags. 1300 1301## @method Geo::GDAL::Band GetMaskBand() 1302# @return the mask band associated with this 1303# band. 1304 1305## @method @GetMaskFlags() 1306# @return the mask flags of the mask band associated with this 1307# band. The flags are one or more of Geo::GDAL::Band::MaskFlags. 1308 1309## @ignore GetRasterCategoryNames 1310## @ignore SetRasterCategoryNames 1311## @ignore GetCategoryNames 1312## @ignore SetCategoryNames 1313 1314## @method @CategoryNames(@names) 1315# @param names [optional] 1316# @return 1317 1318## @ignore SetDefaultRAT 1319## @ignore GetDefaultRAT 1320 1321## @method Geo::GDAL::RasterAttributeTable AttributeTable($AttributeTable) 1322# @param AttributeTable [optional] A Geo::GDAL::RasterAttributeTable object. 1323# @return a new Geo::GDAL::RasterAttributeTable object, whose data is 1324# contained within the band. 1325 1326## @method Geo::OGR::Layer Polygonize(%params) 1327# Polygonize this raster band. 1328# 1329# @param params Named parameters: 1330# - \a Mask A raster band, which is used as a mask to select polygonized areas. Default is undef. 1331# - \a OutLayer A vector layer into which the polygons are written. If not given, an in-memory layer 'polygonized' is created and returned. 1332# - \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'. 1333# - \a Options Hash or list of options. Connectedness can be set to 8 1334to use 8-connectedness, otherwise 4-connectedness is 1335used. ForceIntPixel can be set to 1 to force using a 32 bit int buffer 1336for cell values in the process. If this is not set and the data type 1337of this raster does not fit into a 32 bit int buffer, a 32 bit float 1338buffer is used. 1339# - \a Progress Progress function. 1340# - \a ProgressData Additional parameter for the progress function. 1341# 1342# @return Output vector layer. 1343 1344## @ignore ContourGenerate 1345 1346## @method Geo::OGR::Layer Contours($DataSource, hashref LayerConstructor, $ContourInterval, $ContourBase, arrayref FixedLevels, $NoDataValue, $IDField, $ElevField, coderef Progress, $ProgressData) 1347# Generate contours for this raster band. This method can also be used with named parameters. 1348# @note This method is a wrapper for ContourGenerate. 1349# 1350# An example: 1351# \code 1352# use Geo::GDAL; 1353# $dem = Geo::GDAL::Open('dem.gtiff'); 1354# $contours = $dem->Band->Contours(ContourInterval => 10, ElevField => 'z'); 1355# $n = $contours->GetFeatureCount; 1356# \endcode 1357# 1358# @param DataSource a Geo::OGR::DataSource object, default is a Memory data source 1359# @param LayerConstructor data for Geo::OGR::DataSource::CreateLayer, default is {Name => 'contours'} 1360# @param ContourInterval default is 100 1361# @param ContourBase default is 0 1362# @param FixedLevels a reference to a list of fixed contour levels, default is [] 1363# @param NoDataValue default is undef 1364# @param IDField default is '', i.e., no field (the field is created if this is given) 1365# @param ElevField default is '', i.e., no field (the field is created if this is given) 1366# @param progress [optional] a reference to a subroutine, which will 1367# be called with parameters (number progress, string msg, progress_data) 1368# @param progress_data [optional] 1369# @return 1370 1371## @ignore FillNodata 1372 1373## @method FillNoData($mask, $max_search_dist, $smoothing_iterations, $options, coderef progress, $progress_data) 1374# Interpolate values for cells in this raster. The cells to fill 1375# should be marked in the mask band with zero. 1376# 1377# @param mask [optional] a mask band indicating cells to be interpolated (zero valued) (default is to get it with Geo::GDAL::Band::GetMaskBand). 1378# @param max_search_dist [optional] the maximum number of cells to 1379# search in all directions to find values to interpolate from (default is 10). 1380# @param smoothing_iterations [optional] the number of 3x3 smoothing filter passes to run (0 or more) (default is 0). 1381# @param options [optional] A reference to a hash. No options have been defined so far for this algorithm (default is {}). 1382# @param progress [optional] a reference to a subroutine, which will 1383# be called with parameters (number progress, string msg, progress_data) (default is undef). 1384# @param progress_data [optional] (default is undef). 1385# 1386# <a href="http://www.gdal.org/gdal__alg_8h.html">Documentation for GDAL algorithms</a> 1387 1388## @method RegenerateOverviews(arrayref overviews, $resampling, coderef progress, $progress_data) 1389# @todo This is not yet available 1390# 1391# @param overviews a list of Geo::GDAL::Band objects for the overviews. 1392# @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average). 1393# @param progress [optional] a reference to a subroutine, which will 1394# be called with parameters (number progress, string msg, progress_data) 1395# @param progress_data [optional] 1396 1397## @method RegenerateOverview(Geo::GDAL::Band overview, $resampling, coderef progress, $progress_data) 1398# @param overview a Geo::GDAL::Band object for the overview. 1399# @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average). 1400# @param progress [optional] a reference to a subroutine, which will 1401# be called with parameters (number progress, string msg, progress_data) 1402# @param progress_data [optional] 1403 1404## @method Geo::GDAL::Band Sieve(%params) 1405# Remove small areas by merging them into the largest neighbour area. 1406# @param params Named parameters: 1407# - \a Mask A raster band, which is used as a mask to select sieved areas. Default is undef. 1408# - \a Dest A raster band into which the result is written. If not given, an new in-memory raster band is created and returned. 1409# - \a Threshold The smallest area size (in number of cells) which are not sieved away. 1410# - \a Options Hash or list of options. {Connectedness => 4} can be specified to use 4-connectedness, otherwise 8-connectedness is used. 1411# - \a Progress Progress function. 1412# - \a ProgressData Additional parameter for the progress function. 1413# 1414# @return The filtered raster band. 1415 1416## @method Geo::GDAL::Band Distance(%params) 1417# Compute distances to specific cells of this raster. 1418# @param params Named parameters: 1419# - \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. 1420# - \a Options Hash of options. Options are: 1421# - \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. 1422# - \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. 1423# - \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. 1424# - \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). 1425# - \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. 1426# - \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. 1427# - \a DataType The data type for the result if it is not given. 1428# - \a Progress Progress function. 1429# - \a ProgressData Additional parameter for the progress function. 1430# 1431# @note This GDAL function behind this API is called GDALComputeProximity. 1432# 1433# @return The distance raster. 1434 1435 1436 1437## @class Geo::GDAL::ColorTable 1438# @brief A color table from a raster band or a color table, which can be used for a band. 1439# @details 1440# @isa ( Geo::GDAL::MajorObject Geo::GDAL ) 1441 1442## @cmethod Geo::GDAL::ColorTable new($GDALPaletteInterp = 'RGB') 1443# Create a new empty color table. 1444# @return a new Geo::GDAL::ColorTable object 1445 1446## @method Geo::GDAL::ColorTable Clone() 1447# Clone an existing color table. 1448# @return a new Geo::GDAL::ColorTable object 1449 1450## @method $GetPaletteInterpretation() 1451# @return palette interpretation (string) 1452 1453## @method $GetCount() 1454# @return The number of colors in this color table. 1455 1456## @ignore ColorEntries 1457## @ignore ColorTable 1458 1459## @method @Colors(@colors) 1460# Get or set the colors in this color table. 1461# @note The color table will expand to the size of the input list but 1462# it will not shrink. 1463# @param colors [optional] A list of all colors (a list of lists) for this color table. 1464# @return A list of colors (a list of lists). 1465 1466## @ignore GetColorEntry 1467## @ignore GetColorEntryAsRGB 1468## @ignore SetColorEntry 1469## @ignore ColorEntry 1470 1471## @method @Color($index, @color) 1472# Get or set a color in this color table. 1473# @param index The index of the color in the table. Note that the 1474# color table may expand if the index is larger than the current max 1475# index of this table and a color is given. An attempt to retrieve a 1476# color out of the current size of the table causes an error. 1477# @param color [optional] The color, either a list or a reference to a 1478# list. If the list is too short or has undef values, the undef values 1479# are taken as 0 except for alpha, which is taken as 255. 1480# @note A color is an array of four integers having a value between 0 1481# and 255: (gray, red, cyan or hue; green, magenta, or lightness; 1482# blue, yellow, or saturation; alpha or blackband) 1483# @return A color, in list context a list and in scalar context a reference to an anonymous array. 1484 1485## @method CreateColorRamp($start_index, arrayref start_color, $end_index, arrayref end_color) 1486# @param start_index 1487# @param start_color 1488# @param end_index 1489# @param end_color 1490 1491 1492 1493 1494## @class Geo::GDAL::RasterAttributeTable 1495# @brief An attribute table in a raster band. 1496# @details 1497# @isa = ( Geo::GDAL::MajorObject Geo::GDAL ) 1498 1499## @cmethod Geo::GDAL::RasterAttributeTable new() 1500# @return a new Geo::GDAL::RasterAttributeTable object 1501 1502## @sub @FieldTypes() 1503# @return 1504 1505## @sub @FieldUsages() 1506# @return 1507 1508## @method Geo::GDAL::RasterAttributeTable Clone() 1509# @return a new Geo::GDAL::RasterAttributeTable object 1510 1511## @method SetRowCount($count) 1512# @param count 1513# 1514 1515## @method $GetRowCount() 1516 1517## @method %Columns(%columns) 1518# A get/set method for the columns of the RAT 1519# @param columns optional, a the keys are column names and the values are anonymous 1520# hashes with keys Type and Usage 1521# @return a hash similar to the optional input parameter 1522 1523## @method CreateColumn($name, $type, $usage) 1524# @param name 1525# @param type one of FieldTypes 1526# @param usage one of FieldUsages 1527 1528## @method $GetColumnCount() 1529# @return 1530 1531## @method $GetNameOfCol($column) 1532# @param column 1533# @return 1534 1535## @method $GetUsageOfCol($column) 1536# @param column 1537# @return 1538 1539## @method $GetTypeOfCol($column) 1540# @param column 1541# @return 1542 1543## @method $GetColOfUsage($usage) 1544# @param usage 1545# @return 1546 1547## @method $GetRowOfValue($value) 1548# @param value a cell value 1549# @return row index or -1 1550 1551## @method $Value($row, $column, $value) 1552# @param row 1553# @param column 1554# @param value [optional] 1555# @return 1556 1557## @method $GetValueAsString($row, $column) 1558# @param row 1559# @param column 1560# @return 1561 1562## @method $GetValueAsInt($row, $column) 1563# @param row 1564# @param column 1565# @return 1566 1567## @method $GetValueAsDouble($row, $column) 1568# @param row 1569# @param column 1570# @return 1571 1572## @method SetValueAsString($row, $column, $value) 1573# @param row 1574# @param column 1575# @param value 1576# 1577 1578## @method SetValueAsInt($row, $column, $value) 1579# @param row 1580# @param column 1581# @param value 1582# 1583 1584## @method SetValueAsDouble($row, $column, $value) 1585# @param row 1586# @param column 1587# @param value 1588# 1589 1590## @ignore GetLinearBinning 1591## @ignore SetLinearBinning 1592 1593## @method LinearBinning($Row0MinIn, $BinSizeIn) 1594# @param Row0MinIn [optional] the lower bound (cell value) of the first category. 1595# @param BinSizeIn [optional] the width of each category (in cell value units). 1596# @return ($Row0MinIn, $BinSizeIn) or an empty list if LinearBinning is not set. 1597 1598 1599 1600 1601## @class Geo::GDAL::Transformer 1602# @brief 1603# @details This class is not yet documented for the GDAL Perl bindings. 1604# @todo Test and document. 1605 1606 1607 1608 1609## @class Geo::GDAL::VSIF 1610# @brief A GDAL virtual file system. 1611# @details 1612# @isa = ( Geo::GDAL ) 1613 1614## @sub Geo::GDAL::VSIF Open($filename, $mode) 1615# @param filename Name of the file to open. For example "/vsimem/x". 1616# @param mode Access mode. 'r', 'r+', 'w', etc. 1617# @return A file handle on success. 1618 1619## @method Close() 1620 1621## @method $Read($count) 1622# @param count The number of bytes to read from the file. 1623# @return A byte string. 1624 1625## @method Write($scalar) 1626# @param scalar The byte string to write to the file. 1627# @return Number of bytes written into the file. 1628 1629## @method Seek($offset, $whence) 1630 1631## @method $Tell() 1632 1633## @method Truncate($new_size) 1634 1635## @sub @ReadDir($dir) 1636# @return Contents of a directory in an anonymous array or as a list. 1637 1638## @sub $ReadDirRecursive($dir) 1639# @note Give the directory in the form '/vsimem', i.e., without trailing '/'. 1640# @return Contents of a directory tree in an anonymous array. 1641 1642## @sub @Stat($filename) 1643# @return ($filemode, $filesize). filemode is f for a plain file, d 1644# for a directory, l for a symbolic link, p for a named pipe (FIFO), S 1645# for a socket, b for a block special file, and c for a character 1646# special file. 1647 1648## @sub Unlink($filename) 1649# @param filename The file to delete. 1650# @return 0 on success and -1 on an error. 1651 1652## @ignore Mkdir 1653 1654## @sub MkDir($path) 1655# Make a directory. 1656# @param path The directory to make. 1657# @note The name of this method is VSIMkdir in GDAL. 1658 1659## @ignore Rmdir 1660 1661## @sub RmDir($path) 1662# Remove a directory. 1663# @note The name of this method is VSIRmdir in GDAL. 1664 1665## @sub Rename($old, $new) 1666# Rename a file. 1667# @note The name of this method is VSIRename in GDAL. 1668 1669 1670 1671 1672## @class Geo::GDAL::GeoTransform 1673# @brief An array of affine transformation coefficients. 1674# @details The geo transformation has the form 1675# \code 1676x = a + column * b + row * c 1677y = d + column * e + row * f 1678# \endcode 1679# where 1680# (column,row) is the location in cell coordinates, and 1681# (x,y) is the location in projection coordinates, or vice versa. 1682# A Geo::GDAL::GeoTransform object is a reference to an anonymous array [a,b,c,d,e,f]. 1683# @isa = ( Geo::GDAL ) 1684 1685## @cmethod new(@params) 1686# @param params nothing, a reference to an array [a,b,c,d,e,f], a list 1687# (a,b,c,d,e,f), or named parameters 1688# - \a GCPs A reference to an array of Geo::GDAL::GCP objects. 1689# - \a ApproxOK Minimize the error in the coefficients (integer, default is 1 (true), used with GCPs). 1690# - \a Extent A Geo::GDAL::Extent object used to obtain the coordinates of the up left corner position. 1691# - \a CellSize The cell size (width and height) (default is 1, used with Extent). 1692# 1693# @note When Extent is specified, the created geo transform will be 1694# north up, have square cells, and coefficient f will be -1 times the 1695# cell size (image y - row - will increase downwards and projection y 1696# will increase upwards). 1697# @return a new Geo::GDAL::GeoTransform object. 1698 1699## @ignore FromGCPs 1700## @ignore FromExtentAndCellSize 1701## @ignore Extent 1702 1703## @method Apply($x, $y) 1704# @param x Column or x, or a reference to an array of columns or x's 1705# @param y Row or y, or a reference to an array of rows or y's 1706# @return a list (x, y), where x and y are the transformed coordinates 1707# or references to arrays of transformed coordinates. 1708 1709## @method Inv 1710# @return a new Geo::GDAL::GeoTransform object, which is the inverse 1711# of this one (in void context changes this object). 1712
