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.
10 #** @method ApplyVerticalShiftGrid()
12 sub ApplyVerticalShiftGrid {
15 #** @method BuildVRT()
18 for (keys %Geo::GDAL::Const::) {
20 push(@DATA_TYPES, $1), next
if /^GDT_(\w+)/;
21 push(@OPEN_FLAGS, $1), next
if /^OF_(\w+)/;
22 push(@RESAMPLING_TYPES, $1), next
if /^GRA_(\w+)/;
23 push(@RIO_RESAMPLING_TYPES, $1), next
if /^GRIORA_(\w+)/;
24 push(@NODE_TYPES, $1), next
if /^CXT_(\w+)/;
26 for my $string (@DATA_TYPES) {
27 my $int = eval
"\$Geo::GDAL::Const::GDT_$string";
28 $S2I{data_type}{$string} = $int;
29 $I2S{data_type}{$int} = $string;
31 for my $string (@OPEN_FLAGS) {
32 my $int = eval
"\$Geo::GDAL::Const::OF_$string";
33 $S2I{open_flag}{$string} = $int;
35 for my $string (@RESAMPLING_TYPES) {
36 my $int = eval
"\$Geo::GDAL::Const::GRA_$string";
37 $S2I{resampling}{$string} = $int;
38 $I2S{resampling}{$int} = $string;
40 for my $string (@RIO_RESAMPLING_TYPES) {
41 my $int = eval
"\$Geo::GDAL::Const::GRIORA_$string";
42 $S2I{rio_resampling}{$string} = $int;
43 $I2S{rio_resampling}{$int} = $string;
45 for my $string (@NODE_TYPES) {
46 my $int = eval
"\$Geo::GDAL::Const::CXT_$string";
47 $S2I{node_type}{$string} = $int;
48 $I2S{node_type}{$int} = $string;
52 $HAVE_PDL = 1 unless $@;
55 #** @method CPLBinaryToHex()
60 #** @method CPLHexToBinary()
65 #** @method ContourGenerateEx()
67 sub ContourGenerateEx {
70 #** @method CreatePansharpenedVRT()
72 sub CreatePansharpenedVRT {
75 #** @method scalar DataTypeIsComplex($DataType)
77 # @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
78 # @return true if the data type is a complex number.
80 sub DataTypeIsComplex {
81 return _DataTypeIsComplex(s2i(data_type => shift));
84 #** @method list DataTypeValueRange($DataType)
86 # @param DataType Data type (one of those listed by Geo::GDAL::DataTypes).
87 # @note Some returned values are inaccurate.
89 # @return the minimum, maximum range of the data type.
91 sub DataTypeValueRange {
94 # these values are from gdalrasterband.cpp
95 return (0,255)
if $t =~ /Byte/;
96 return (0,65535)
if $t =~/UInt16/;
97 return (-32768,32767)
if $t =~/Int16/;
98 return (0,4294967295)
if $t =~/UInt32/;
99 return (-2147483648,2147483647)
if $t =~/Int32/;
100 return (-4294967295.0,4294967295.0)
if $t =~/Float32/;
101 return (-4294967295.0,4294967295.0)
if $t =~/Float64/;
104 #** @method list DataTypes()
105 # Package subroutine.
106 # @return a list of GDAL raster cell data types. These are currently:
107 # Byte, CFloat32, CFloat64, CInt16, CInt32, Float32, Float64, Int16, Int32, UInt16, UInt32, and Unknown.
113 #** @method scalar DecToDMS($angle, $axis, $precision=2)
114 # Package subroutine.
115 # Convert decimal degrees to degrees, minutes, and seconds string
116 # @param angle A number
117 # @param axis A string specifying latitude or longitude ('Long').
119 # @return a string nndnn'nn.nn'"L where n is a number and L is either
125 #** @method scalar DecToPackedDMS($dec)
126 # Package subroutine.
127 # @param dec Decimal degrees
128 # @return packed DMS, i.e., a number DDDMMMSSS.SS
133 #** @method DontUseExceptions()
134 # Package subroutine.
135 # Do not use the Perl exception mechanism for GDAL messages. Instead
136 # the messages are printed to standard error.
138 sub DontUseExceptions {
141 #** @method Geo::GDAL::Driver Driver($Name)
142 # Package subroutine.
143 # Access a format driver.
144 # @param Name The short name of the driver. One of
145 # Geo::GDAL::DriverNames or Geo::OGR::DriverNames.
146 # @note This subroutine is imported into the main namespace if Geo::GDAL
147 # is used with qw/:all/.
148 # @return a Geo::GDAL::Driver object.
151 return 'Geo::GDAL::Driver' unless @_;
153 my $driver = GetDriver($name);
154 error(
"Driver \"$name\" not found. Is it built in? Check with Geo::GDAL::Drivers or Geo::OGR::Drivers.")
159 #** @method list DriverNames()
160 # Package subroutine.
161 # Available raster format drivers.
163 # perl -MGeo::GDAL -e '@d=Geo::GDAL::DriverNames;print "@d\n"'
165 # @note Use Geo::OGR::DriverNames for vector drivers.
166 # @return a list of the short names of all available GDAL raster drivers.
171 #** @method list Drivers()
172 # Package subroutine.
173 # @note Use Geo::OGR::Drivers for vector drivers.
174 # @return a list of all available GDAL raster drivers.
178 for my $i (0..GetDriverCount()-1) {
179 my $driver = GetDriver($i);
180 push @drivers, $driver
if $driver->TestCapability(
'RASTER');
185 #** @method EscapeString()
190 #** @method scalar FindFile($basename)
191 # Package subroutine.
192 # Search for GDAL support files.
197 # $a = Geo::GDAL::FindFile('pcs.csv');
198 # print STDERR "$a\n";
200 # Prints (for example):
202 # c:\msys\1.0\local\share\gdal\pcs.csv
205 # @param basename The name of the file to search for. For example
207 # @return the path to the searched file or undef.
217 #** @method FinderClean()
218 # Package subroutine.
219 # Clear the set of support file search paths.
224 #** @method GDALMultiDimInfo()
226 sub GDALMultiDimInfo {
229 #** @method GEDTC_COMPOUND()
234 #** @method GEDTC_NUMERIC()
239 #** @method GEDTC_STRING()
244 #** @method GOA2GetAccessToken()
246 sub GOA2GetAccessToken {
249 #** @method GOA2GetAuthorizationURL()
251 sub GOA2GetAuthorizationURL {
254 #** @method GOA2GetRefreshToken()
256 sub GOA2GetRefreshToken {
259 #** @method GVM_Diagonal()
264 #** @method GVM_Edge()
269 #** @method GVM_Max()
274 #** @method GVM_Min()
279 #** @method GVOT_MIN_TARGET_HEIGHT_FROM_DEM()
281 sub GVOT_MIN_TARGET_HEIGHT_FROM_DEM {
284 #** @method GVOT_MIN_TARGET_HEIGHT_FROM_GROUND()
286 sub GVOT_MIN_TARGET_HEIGHT_FROM_GROUND {
287 # keeper maintains child -> parent relationships
288 # child is kept as a key, i.e., string not the real object
289 # parent is kept as the value, i.e., a real object
290 # a child may have only one parent!
291 # call these as Geo::GDAL::*
296 #** @method GVOT_NORMAL()
301 #** @method GetActualURL()
306 #** @method scalar GetCacheMax()
307 # Package subroutine.
308 # @return maximum amount of memory (as bytes) for caching within GDAL.
313 #** @method scalar GetCacheUsed()
314 # Package subroutine.
315 # @return the amount of memory currently used for caching within GDAL.
320 #** @method scalar GetConfigOption($key)
321 # Package subroutine.
322 # @param key A GDAL config option. Consult <a
323 # href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL
324 # documentation</a> for available options and their use.
325 # @return the value of the GDAL config option.
327 sub GetConfigOption {
330 #** @method scalar GetDataTypeSize($DataType)
331 # Package subroutine.
332 # @param DataType A GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
333 # @return the size as the number of bits.
335 sub GetDataTypeSize {
336 return _GetDataTypeSize(s2i(data_type => shift, 1));
339 #** @method GetErrorCounter()
341 sub GetErrorCounter {
344 #** @method GetFileMetadata()
346 sub GetFileMetadata {
349 #** @method GetFileSystemOptions()
351 sub GetFileSystemOptions {
354 #** @method GetFileSystemsPrefixes()
356 sub GetFileSystemsPrefixes {
359 #** @method GetJPEG2000StructureAsString()
361 sub GetJPEG2000StructureAsString {
364 #** @method GetSignedURL()
369 #** @method Geo::GDAL::Driver IdentifyDriver($path, $siblings)
370 # Package subroutine.
371 # @param path a dataset path.
372 # @param siblings [optional] A list of names of files that belong to the data format.
373 # @return a Geo::GDAL::Driver.
378 #** @method IdentifyDriverEx()
380 sub IdentifyDriverEx {
383 #** @method MkdirRecursive()
388 #** @method Geo::GDAL::Dataset Open(%params)
389 # Package subroutine.
391 # An example, which opens an existing raster dataset for editing:
393 # use Geo::GDAL qw/:all/;
394 # $ds = Open(Name => 'existing.tiff', Access => 'Update');
396 # @param params Named parameters:
397 # - \a Name Dataset string (typically a filename). Default is '.'.
398 # - \a Access Access type, either 'ReadOnly' or 'Update'. Default is 'ReadOnly'.
399 # - \a Type Dataset type, either 'Raster', 'Vector', or 'Any'. Default is 'Any'.
400 # - \a Options A hash of GDAL open options passed to candidate drivers. Default is {}.
401 # - \a Files A list of names of files that are auxiliary to the main file. Default is [].
403 # @note This subroutine is imported into the main namespace if Geo::GDAL
404 # is use'd with qw/:all/.
406 # @note Some datasets / dataset strings do not explicitly imply the
407 # dataset type (for example a PostGIS database). If the type is not
408 # specified in such a case the returned dataset may be of either type.
410 # @return a new Geo::GDAL::Dataset object if success.
413 my $p = named_parameters(\@_, Name =>
'.', Access =>
'ReadOnly', Type =>
'Any', Options => {}, Files => []);
415 my %o = (READONLY => 1, UPDATE => 1);
416 error(1, $p->{access}, \%o) unless $o{uc($p->{access})};
417 push @flags, uc($p->{access});
418 %o = (RASTER => 1, VECTOR => 1, ANY => 1);
419 error(1, $p->{type}, \%o) unless $o{uc($p->{type})};
420 push @flags, uc($p->{type}) unless uc($p->{type}) eq
'ANY';
421 my $dataset = OpenEx(Name => $p->{name}, Flags => \@flags, Options => $p->{options}, Files => $p->{files});
423 my $t =
"Failed to open $p->{name}.";
424 $t .=
" Is it a ".lc($p->{type}).
" dataset?" unless uc($p->{type}) eq
'ANY';
430 #** @method Geo::GDAL::Dataset OpenEx(%params)
431 # Package subroutine.
432 # The generic dataset open method, used internally by all Open and OpenShared methods.
433 # @param params Named parameters:
434 # - \a Name The name of the data set or source to open. (Default is '.')
435 # - \a Flags A list of access mode flags. Available flags are listed by Geo::GDAL::OpenFlags(). (Default is [])
436 # - \a Drivers A list of short names of drivers that may be used. Empty list means all. (Default is [])
437 # - \a Options A hash of GDAL open options passed to candidate drivers. (Default is {})
438 # - \a Files A list of names of files that are auxiliary to the main file. (Default is [])
442 # $ds = Geo::GDAL::OpenEx(Name => 'existing.tiff', Flags => [qw/RASTER UPDATE/]);
444 # @return a new Geo::GDAL::Dataset object.
447 my $p = named_parameters(\@_, Name =>
'.', Flags => [], Drivers => [], Options => {}, Files => []);
451 $p = {name => $name, flags => \@flags, drivers => [], options => {}, files => []};
455 for my $flag (@{$p->{flags}}) {
456 $f |= s2i(open_flag => $flag);
460 return _OpenEx($p->{name}, $p->{flags}, $p->{drivers}, $p->{options}, $p->{files});
463 #** @method list OpenFlags()
464 # Package subroutine.
465 # @return a list of GDAL data set open modes. These are currently:
466 # ALL, GNM, MULTIDIM_RASTER, RASTER, READONLY, SHARED, UPDATE, VECTOR, and VERBOSE_ERROR.
472 #** @method scalar PackCharacter($DataType)
473 # Package subroutine.
474 # Get the character that is needed for Perl's pack and unpack when
475 # they are used with Geo::GDAL::Band::ReadRaster and
476 # Geo::GDAL::Band::WriteRaster. Note that Geo::GDAL::Band::ReadTile
477 # and Geo::GDAL::Band::WriteTile have simpler interfaces that do not
478 # require pack and unpack.
479 # @param DataType A GDAL raster cell data type, typically from $band->DataType.
480 # @return a character which can be used in Perl's pack and unpack.
484 $t = i2s(data_type => $t);
485 s2i(data_type => $t); # test
486 my $is_big_endian = unpack(
"h*", pack(
"s", 1)) =~ /01/; # from Programming Perl
487 return 'C' if $t =~ /^Byte$/;
488 return ($is_big_endian ?
'n':
'v')
if $t =~ /^UInt16$/;
489 return 's' if $t =~ /^Int16$/;
490 return ($is_big_endian ?
'N' :
'V')
if $t =~ /^UInt32$/;
491 return 'l' if $t =~ /^Int32$/;
492 return 'f' if $t =~ /^Float32$/;
493 return 'd' if $t =~ /^Float64$/;
496 #** @method scalar PackedDMSToDec($packed)
497 # Package subroutine.
498 # @param packed DMS as a number DDDMMMSSS.SS
499 # @return decimal degrees
504 #** @method PopFinderLocation()
505 # Package subroutine.
506 # Remove the latest addition from the set of support file search
507 # paths. Note that calling this subroutine may remove paths GDAL put
510 sub PopFinderLocation {
513 #** @method PushFinderLocation($path)
514 # Package subroutine.
515 # Add a path to the set of paths from where GDAL support files are
516 # sought. Note that GDAL puts initially into the finder the current
517 # directory and value of GDAL_DATA environment variable (if it
518 # exists), installation directory (prepended with '/share/gdal' or
519 # '/Resources/gdal'), or '/usr/local/share/gdal'. It is usually only
520 # needed to add paths to the finder if using an alternate set of data
521 # files or a non-installed GDAL is used (as in testing).
523 sub PushFinderLocation {
526 #** @method list RIOResamplingTypes()
527 # Package subroutine.
528 # @return a list of GDAL raster IO resampling methods. These are currently:
529 # Average, Bilinear, Cubic, CubicSpline, Gauss, Lanczos, Mode, and NearestNeighbour.
531 sub RIOResamplingTypes {
532 return @RIO_RESAMPLING_TYPES;
535 #** @method list ResamplingTypes()
536 # Package subroutine.
537 # @return a list of GDAL resampling methods. These are currently:
538 # Average, Bilinear, Cubic, CubicSpline, Lanczos, Max, Med, Min, Mode, NearestNeighbour, Q1, and Q3.
540 sub ResamplingTypes {
541 return @RESAMPLING_TYPES;
544 #** @method RmdirRecursive()
549 #** @method SetCacheMax($Bytes)
550 # Package subroutine.
551 # @param Bytes New maximum amount of memory for caching within GDAL.
556 #** @method SetConfigOption($key, $value)
557 # Package subroutine.
558 # @param key A GDAL config option. Consult <a
559 # href="https://trac.osgeo.org/gdal/wiki/ConfigOptions">the GDAL
560 # documentation</a> for available options and their use.
561 # @param value A value for the option, typically 'YES', 'NO',
562 # undef, path, numeric value, or a filename.
564 sub SetConfigOption {
567 #** @method SetFileMetadata()
569 sub SetFileMetadata {
572 #** @method UnlinkBatch()
577 #** @method UseExceptions()
578 # Package subroutine.
579 # Use the Perl exception mechanism for GDAL messages (failures are
580 # confessed and warnings are warned) and collect the messages
581 # into \@Geo::GDAL::error. This is the default.
586 #** @method VSICurlClearCache()
588 sub VSICurlClearCache {
591 #** @method VSICurlPartialClearCache()
593 sub VSICurlPartialClearCache {
596 #** @method VSIErrorReset()
601 #** @method VSIFEofL()
606 #** @method VSIFFlushL()
611 #** @method VSIFOpenExL()
616 #** @method VSIGetLastErrorMsg()
618 sub VSIGetLastErrorMsg {
621 #** @method VSIGetLastErrorNo()
623 sub VSIGetLastErrorNo {
626 #** @method scalar VersionInfo($request = 'VERSION_NUM')
627 # Package subroutine.
628 # @param request A string specifying the request. Currently either
629 # "VERSION_NUM", "RELEASE_DATE", "RELEASE_NAME", or
630 # "--version". Default is "VERSION_NUM".
631 # @return Requested information.
636 #** @method ViewshedGenerate()
638 sub ViewshedGenerate {
641 #** @method scalar errstr()
642 # Package subroutine.
643 # Clear the error stack and return all generated GDAL error messages in one (possibly multiline) string.
644 # @return the chomped error stack joined with newlines.
650 return join(
"\n", @stack);
652 # usage: named_parameters(\@_, key value list of default parameters);
653 # returns parameters in a hash with low-case-without-_ keys
656 #** @method wrapper_GDALMultiDimTranslateDestName()
658 sub wrapper_GDALMultiDimTranslateDestName {
661 #** @class Geo::GDAL::AsyncReader
662 # @brief Enable asynchronous requests.
663 # @details This class is not yet documented nor tested in the GDAL Perl wrappers
664 # @todo Test and document.
666 package Geo::GDAL::AsyncReader;
670 #** @method GetNextUpdatedRegion()
672 sub GetNextUpdatedRegion {
675 #** @method LockBuffer()
680 #** @method UnlockBuffer()
685 #** @class Geo::GDAL::Attribute
687 package Geo::GDAL::Attribute;
691 #** @method GetDataType()
696 #** @method GetDimensionCount()
698 sub GetDimensionCount {
701 #** @method GetFullName()
706 #** @method GetName()
711 #** @method GetTotalElementsCount()
713 sub GetTotalElementsCount {
716 #** @method ReadAsDouble()
721 #** @method ReadAsInt()
726 #** @method ReadAsString()
731 #** @method ReadAsStringArray()
733 sub ReadAsStringArray {
736 #** @method WriteDouble()
741 #** @method WriteInt()
746 #** @method WriteString()
751 #** @method WriteStringArray()
753 sub WriteStringArray {
756 #** @class Geo::GDAL::Band
757 # @brief A raster band.
760 package Geo::GDAL::Band;
766 # scalar (access as $band->{XSize})
771 # scalar (access as $band->{YSize})
774 #** @method AdviseRead()
779 #** @method AsMDArray()
784 #** @method Geo::GDAL::RasterAttributeTable AttributeTable($AttributeTable)
786 # @param AttributeTable [optional] A Geo::GDAL::RasterAttributeTable object.
787 # @return a new Geo::GDAL::RasterAttributeTable object, whose data is
788 # contained within the band.
792 SetDefaultRAT($self, $_[0])
if @_ and defined $_[0];
793 return unless defined wantarray;
794 my $r = GetDefaultRAT($self);
795 keep($r, $self)
if $r;
798 #** @method list BlockSize()
801 # @return The size of a preferred i/o raster block size as a list
807 #** @method list CategoryNames(@names)
809 # @param names [optional]
814 SetRasterCategoryNames($self, \@_)
if @_;
815 return unless defined wantarray;
816 my $n = GetRasterCategoryNames($self);
820 #** @method scalar Checksum($xoff = 0, $yoff = 0, $xsize = undef, $ysize = undef)
822 # Computes a checksum from the raster or a part of it.
827 # @return the checksum.
832 #** @method hashref ClassCounts($classifier, $progress = undef, $progress_data = undef)
834 # Compute the counts of cell values or number of cell values in ranges.
835 # @note Classifier is required only for float bands.
836 # @note NoData values are counted similar to other values when
837 # classifier is not defined for integer rasters.
839 # @param classifier Anonymous array of format [ $comparison,
840 # $classifier ], where $comparison is a string '<', '<=', '>', or '>='
841 # and $classifier is an anonymous array of format [ $value,
842 # $value|$classifier, $value|$classifier ], where $value is a numeric
843 # value against which the reclassified value is compared to. If the
844 # comparison returns true, then the second $value or $classifier is
845 # applied, and if not then the third $value or $classifier.
847 # In the example below, the line is divided into ranges
848 # [-inf..3), [3..5), and [5..inf], i.e., three ranges with class
849 # indexes 0, 1, and 2. Note that the indexes are used as keys for
850 # class counts and not the class values (here 1.0, 2.0, and 3.0),
851 # which are used in Geo::GDAL::Band::Reclassify.
853 # $classifier = [ '<', [5.0, [3.0, 1.0, 2.0], 3.0] ];
854 # # Howto create this $classifier from @class_boundaries:
855 # my $classifier = ['<='];
856 # my $tree = [$class_boundaries[0], 0, 1];
857 # for my $i (1 .. $#class_boundaries) {
858 # $tree = [$class_boundaries[$i], [@$tree], $i+1];
860 # push @$classifier, $tree;
862 # @return a reference to an anonymous hash, which contains the class
863 # values (indexes) as keys and the number of cells with that value or
864 # in that range as values. If the subroutine is user terminated an
870 #** @method scalar ColorInterpretation($color_interpretation)
872 # @note a.k.a. GetRasterColorInterpretation and GetColorInterpretation
873 # (get only and returns an integer), SetRasterColorInterpretation and
874 # SetColorInterpretation (set only and requires an integer)
875 # @param color_interpretation [optional] new color interpretation, one
876 # of Geo::GDAL::Band::ColorInterpretations.
877 # @return The color interpretation of this band. One of Geo::GDAL::Band::ColorInterpretations.
879 sub ColorInterpretation {
882 $ci = s2i(color_interpretation => $ci);
883 SetRasterColorInterpretation($self, $ci);
885 return unless defined wantarray;
886 i2s(color_interpretation => GetRasterColorInterpretation($self));
889 #** @method ColorInterpretations()
890 # Package subroutine.
891 # @return a list of types of color interpretation for raster
892 # bands. These are currently:
893 # AlphaBand, BlackBand, BlueBand, CyanBand, GrayIndex, GreenBand, HueBand, LightnessBand, MagentaBand, PaletteIndex, RedBand, SaturationBand, Undefined, YCbCr_CbBand, YCbCr_CrBand, YCbCr_YBand, and YellowBand.
895 sub ColorInterpretations {
896 return @COLOR_INTERPRETATIONS;
899 #** @method Geo::GDAL::ColorTable ColorTable($ColorTable)
901 # Get or set the color table of this band.
902 # @param ColorTable [optional] a Geo::GDAL::ColorTable object
903 # @return A new Geo::GDAL::ColorTable object which represents the
904 # internal color table associated with this band. Returns undef this
905 # band does not have an associated color table.
909 SetRasterColorTable($self, $_[0])
if @_ and defined $_[0];
910 return unless defined wantarray;
911 GetRasterColorTable($self);
914 #** @method ComputeBandStats($samplestep = 1)
916 # @param samplestep the row increment in computing the statistics.
917 # @note Returns uncorrected sample standard deviation.
919 # See also Geo::GDAL::Band::ComputeStatistics.
920 # @return a list (mean, stddev).
922 sub ComputeBandStats {
925 #** @method ComputeRasterMinMax($approx_ok = 0)
927 # @return arrayref MinMax = [min, max]
929 sub ComputeRasterMinMax {
932 #** @method list ComputeStatistics($approx_ok, $progress = undef, $progress_data = undef)
934 # @param approx_ok Whether it is allowed to compute the statistics
935 # based on overviews or similar.
936 # @note Returns uncorrected sample standard deviation.
938 # See also Geo::GDAL::Band::ComputeBandStats.
939 # @return a list ($min, $max, $mean, $stddev).
941 sub ComputeStatistics {
944 #** @method Geo::OGR::Layer Contours($DataSource, hashref LayerConstructor, $ContourInterval, $ContourBase, arrayref FixedLevels, $NoDataValue, $IDField, $ElevField, coderef Progress, $ProgressData)
946 # Generate contours for this raster band. This method can also be used with named parameters.
947 # @note This method is a wrapper for ContourGenerate.
952 # $dem = Geo::GDAL::Open('dem.gtiff');
953 # $contours = $dem->Band->Contours(ContourInterval => 10, ElevField => 'z');
954 # $n = $contours->GetFeatureCount;
957 # @param DataSource a Geo::OGR::DataSource object, default is a Memory data source
958 # @param LayerConstructor data for Geo::OGR::DataSource::CreateLayer, default is {Name => 'contours'}
959 # @param ContourInterval default is 100
960 # @param ContourBase default is 0
961 # @param FixedLevels a reference to a list of fixed contour levels, default is []
962 # @param NoDataValue default is undef
963 # @param IDField default is '', i.e., no field (the field is created if this is given)
964 # @param ElevField default is '', i.e., no field (the field is created if this is given)
965 # @param progress [optional] a reference to a subroutine, which will
966 # be called with parameters (number progress, string msg, progress_data)
967 # @param progress_data [optional]
972 my $p = named_parameters(\@_,
974 LayerConstructor => {Name =>
'contours'},
975 ContourInterval => 100,
978 NoDataValue => undef,
982 ProgressData => undef);
984 $p->{layerconstructor}->{Schema}
985 $p->{layerconstructor}->{Schema}{Fields}
987 unless ($p->{idfield} =~ /^[+-]?\d+$/ or $fields{$p->{idfield}}) {
988 push @{$p->{layerconstructor}->{Schema}{Fields}}, {Name => $p->{idfield}, Type =>
'Integer'};
990 unless ($p->{elevfield} =~ /^[+-]?\d+$/ or $fields{$p->{elevfield}}) {
991 my $type = $self->DataType() =~ /Float/ ?
'Real' :
'Integer';
992 push @{$p->{layerconstructor}->{Schema}{Fields}}, {Name => $p->{elevfield}, Type => $type};
994 my $layer = $p->{datasource}->CreateLayer($p->{layerconstructor});
995 my $schema = $layer->GetLayerDefn;
996 for (
'idfield',
'elevfield') {
997 $p->{$_} = $schema->GetFieldIndex($p->{$_}) unless $p->{$_} =~ /^[+-]?\d+$/;
999 $p->{progressdata} = 1
if $p->{progress} and not defined $p->{progressdata};
1000 ContourGenerate($self, $p->{contourinterval}, $p->{contourbase}, $p->{fixedlevels},
1001 $p->{nodatavalue}, $layer, $p->{idfield}, $p->{elevfield},
1002 $p->{progress}, $p->{progressdata});
1006 #** @method CreateMaskBand(@flags)
1008 # @note May invalidate any previous mask band obtained with Geo::GDAL::Band::GetMaskBand.
1010 # @param flags one or more mask flags. The flags are Geo::GDAL::Band::MaskFlags.
1012 sub CreateMaskBand {
1015 if (@_ and $_[0] =~ /^\d$/) {
1019 carp
"Unknown mask flag: '$flag'." unless $MASK_FLAGS{$flag};
1020 $f |= $MASK_FLAGS{$flag};
1023 $self->_CreateMaskBand($f);
1026 #** @method scalar DataType()
1028 # @return The data type of this band. One of Geo::GDAL::DataTypes.
1032 return i2s(data_type => $self->{DataType});
1035 #** @method Geo::GDAL::Dataset Dataset()
1037 # @return The dataset which this band belongs to.
1044 #** @method scalar DeleteNoDataValue()
1047 sub DeleteNoDataValue {
1050 #** @method Geo::GDAL::Band Distance(%params)
1052 # Compute distances to specific cells of this raster.
1053 # @param params Named parameters:
1054 # - \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.
1055 # - \a Options Hash of options. Options are:
1056 # - \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.
1057 # - \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.
1058 # - \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.
1059 # - \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).
1060 # - \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.
1061 # - \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.
1062 # - \a DataType The data type for the result if it is not given.
1063 # - \a Progress Progress function.
1064 # - \a ProgressData Additional parameter for the progress function.
1066 # @note This GDAL function behind this API is called GDALComputeProximity.
1068 # @return The distance raster.
1072 my $p = named_parameters(\@_, Distance => undef, Options => undef, Progress => undef, ProgressData => undef);
1073 for my $key (keys %{$p->{options}}) {
1074 $p->{options}{uc($key)} = $p->{options}{$key};
1077 unless ($p->{distance}) {
1078 my ($w, $h) = $self->Size;
1079 $p->{distance} =
Geo::GDAL::Driver(
'MEM')->
Create(Name =>
'distance', Width => $w, Height => $h, Type => $p->{options}{TYPE})->Band;
1081 Geo::GDAL::ComputeProximity($self, $p->{distance}, $p->{options}, $p->{progress}, $p->{progressdata});
1082 return $p->{distance};
1085 #** @method Domains()
1091 #** @method Fill($real_part, $imag_part = 0.0)
1093 # Fill the band with a constant value.
1094 # @param real_part Real component of fill value.
1095 # @param imag_part Imaginary component of fill value.
1101 #** @method FillNoData($mask, $max_search_dist, $smoothing_iterations, $options, coderef progress, $progress_data)
1103 # Interpolate values for cells in this raster. The cells to fill
1104 # should be marked in the mask band with zero.
1106 # @param mask [optional] a mask band indicating cells to be interpolated (zero valued) (default is to get it with Geo::GDAL::Band::GetMaskBand).
1107 # @param max_search_dist [optional] the maximum number of cells to
1108 # search in all directions to find values to interpolate from (default is 10).
1109 # @param smoothing_iterations [optional] the number of 3x3 smoothing filter passes to run (0 or more) (default is 0).
1110 # @param options [optional] A reference to a hash. No options have been defined so far for this algorithm (default is {}).
1111 # @param progress [optional] a reference to a subroutine, which will
1112 # be called with parameters (number progress, string msg, progress_data) (default is undef).
1113 # @param progress_data [optional] (default is undef).
1115 # <a href="http://www.gdal.org/gdal__alg_8h.html">Documentation for GDAL algorithms</a>
1120 #** @method FlushCache()
1122 # Write cached data to disk. There is usually no need to call this
1128 #** @method scalar GetBandNumber()
1130 # @return The index of this band in the parent dataset list of bands.
1135 #** @method GetBlockSize()
1140 #** @method list GetDefaultHistogram($force = 1, coderef progress = undef, $progress_data = undef)
1142 # @param force true to force the computation
1143 # @param progress [optional] a reference to a subroutine, which will
1144 # be called with parameters (number progress, string msg, progress_data)
1145 # @param progress_data [optional]
1146 # @note See Note in Geo::GDAL::Band::GetHistogram.
1147 # @return a list: ($min, $max, arrayref histogram).
1149 sub GetDefaultHistogram {
1152 #** @method list GetHistogram(%parameters)
1154 # Compute histogram from the raster.
1155 # @param parameters Named parameters:
1156 # - \a Min the lower bound, default is -0.5
1157 # - \a Max the upper bound, default is 255.5
1158 # - \a Buckets the number of buckets in the histogram, default is 256
1159 # - \a IncludeOutOfRange whether to use the first and last values in the returned list
1160 # for out of range values, default is false;
1161 # the bucket size is (Max-Min) / Buckets if this is false and
1162 # (Max-Min) / (Buckets-2) if this is true
1163 # - \a ApproxOK if histogram can be computed from overviews, default is false
1164 # - \a Progress an optional progress function, the default is undef
1165 # - \a ProgressData data for the progress function, the default is undef
1166 # @note Histogram counts are treated as strings in the bindings to be
1167 # able to use large integers (if GUIntBig is larger than Perl IV). In
1168 # practice this is only important if you have a 32 bit machine and
1169 # very large bucket counts. In those cases it may also be necessary to
1171 # @return a list which contains the count of values in each bucket
1175 my $p = named_parameters(\@_,
1179 IncludeOutOfRange => 0,
1182 ProgressData => undef);
1183 $p->{progressdata} = 1
if $p->{progress} and not defined $p->{progressdata};
1184 _GetHistogram($self, $p->{min}, $p->{max}, $p->{buckets},
1185 $p->{includeoutofrange}, $p->{approxok},
1186 $p->{progress}, $p->{progressdata});
1189 #** @method Geo::GDAL::Band GetMaskBand()
1191 # @return the mask band associated with this
1196 my $band = _GetMaskBand($self);
1200 #** @method list GetMaskFlags()
1202 # @return the mask flags of the mask band associated with this
1203 # band. The flags are one or more of Geo::GDAL::Band::MaskFlags.
1207 my $f = $self->_GetMaskFlags;
1209 for my $flag (keys %MASK_FLAGS) {
1210 push @f, $flag
if $f & $MASK_FLAGS{$flag};
1212 return wantarray ? @f : $f;
1215 #** @method scalar GetMaximum()
1217 # @note Call Geo::GDAL::Band::ComputeStatistics before calling
1218 # GetMaximum to make sure the value is computed.
1220 # @return statistical minimum of the band or undef if statistics are
1221 # not kept or computed in scalar context. In list context returns the
1222 # maximum value or a (kind of) maximum value supported by the data
1223 # type and a boolean value, which indicates which is the case (true is
1224 # first, false is second).
1229 #** @method scalar GetMinimum()
1231 # @note Call Geo::GDAL::Band::ComputeStatistics before calling
1232 # GetMinimum to make sure the value is computed.
1234 # @return statistical minimum of the band or undef if statistics are
1235 # not kept or computed in scalar context. In list context returns the
1236 # minimum value or a (kind of) minimum value supported by the data
1237 # type and a boolean value, which indicates which is the case (true is
1238 # first, false is second).
1243 #** @method Geo::GDAL::Band GetOverview($index)
1245 # @param index 0..GetOverviewCount-1
1246 # @return a Geo::GDAL::Band object, which represents the internal
1247 # overview band, or undef. if the index is out of bounds.
1250 my ($self, $index) = @_;
1251 my $band = _GetOverview($self, $index);
1255 #** @method scalar GetOverviewCount()
1257 # @return the number of overviews available of the band.
1259 sub GetOverviewCount {
1262 #** @method list GetStatistics($approx_ok, $force)
1264 # @param approx_ok Whether it is allowed to compute the statistics
1265 # based on overviews or similar.
1266 # @param force Whether to force scanning of the whole raster.
1267 # @note Uses Geo::GDAL::Band::ComputeStatistics internally.
1269 # @return a list ($min, $max, $mean, $stddev).
1274 #** @method HasArbitraryOverviews()
1276 # @return true or false.
1278 sub HasArbitraryOverviews {
1281 #** @method list MaskFlags()
1282 # Package subroutine.
1283 # @return the list of mask flags. These are
1284 # - \a AllValid: There are no invalid cell, all mask values will be 255.
1285 # When used this will normally be the only flag set.
1286 # - \a PerDataset: The mask band is shared between all bands on the dataset.
1287 # - \a Alpha: The mask band is actually an alpha band and may have values
1288 # other than 0 and 255.
1289 # - \a NoData: Indicates the mask is actually being generated from NoData values.
1290 # (mutually exclusive of Alpha).
1293 my @f = sort {$MASK_FLAGS{$a} <=> $MASK_FLAGS{$b}} keys %MASK_FLAGS;
1297 #** @method scalar NoDataValue($NoDataValue)
1299 # Get or set the "no data" value.
1300 # @param NoDataValue [optional]
1301 # @note $band->NoDataValue(undef) sets the NoData value to the
1302 # Posix floating point maximum. Use Geo::GDAL::Band::DeleteNoDataValue
1303 # to stop this band using a NoData value.
1304 # @return The NoData value or undef in scalar context. An undef
1305 # value indicates that there is no NoData value associated with this
1311 if (defined $_[0]) {
1312 SetNoDataValue($self, $_[0]);
1314 SetNoDataValue($self, POSIX::FLT_MAX); # hopefully an
"out of range" value
1317 GetNoDataValue($self);
1320 #** @method scalar PackCharacter()
1322 # @return The character to use in Perl pack and unpack for the data of this band.
1329 #** @method Piddle($piddle, $xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>, $xdim, $ydim)
1331 # Read or write band data from/into a piddle.
1333 # \note The PDL module must be available for this method to work. Also, you
1334 # should 'use PDL' in the code that you use this method.
1336 # @param piddle [only when writing] The piddle from which to read the data to be written into the band.
1337 # @param xoff, yoff The offset for data in the band, default is top left (0, 0).
1338 # @param xsize, ysize [optional] The size of the window in the band.
1339 # @param xdim, ydim [optional, only when reading from a band] The size of the piddle to create.
1340 # @return A new piddle when reading from a band (no not use when writing into a band).
1343 # TODO: add Piddle sub to dataset too to make Width x Height x Bands piddles
1344 error(
"PDL is not available.") unless $Geo::GDAL::HAVE_PDL;
1346 my $t = $self->{DataType};
1347 unless (defined wantarray) {
1349 error(
"The datatype of the Piddle and the band do not match.")
1350 unless $PDL2DATATYPE{$pdl->get_datatype} == $t;
1351 my ($xoff, $yoff, $xsize, $ysize) = @_;
1354 my $data = $pdl->get_dataref();
1355 my ($xdim, $ydim) = $pdl->dims();
1356 if ($xdim > $self->{XSize} - $xoff) {
1357 warn
"Piddle XSize too large ($xdim) for this raster band (width = $self->{XSize}, offset = $xoff).";
1358 $xdim = $self->{XSize} - $xoff;
1360 if ($ydim > $self->{YSize} - $yoff) {
1361 $ydim = $self->{YSize} - $yoff;
1362 warn
"Piddle YSize too large ($ydim) for this raster band (height = $self->{YSize}, offset = $yoff).";
1366 $self->_WriteRaster($xoff, $yoff, $xsize, $ysize, $data, $xdim, $ydim, $t, 0, 0);
1369 my ($xoff, $yoff, $xsize, $ysize, $xdim, $ydim, $alg) = @_;
1377 $alg = s2i(rio_resampling => $alg);
1378 my $buf = $self->_ReadRaster($xoff, $yoff, $xsize, $ysize, $xdim, $ydim, $t, 0, 0, $alg);
1380 my $datatype = $DATATYPE2PDL{$t};
1381 error(
"The band datatype is not supported by PDL.") if $datatype < 0;
1382 $pdl->set_datatype($datatype);
1383 $pdl->setdims([$xdim, $ydim]);
1384 my $data = $pdl->get_dataref();
1387 # FIXME: we want approximate equality since no data value can be very large floating point value
1388 my $bad = GetNoDataValue($self);
1389 return $pdl->setbadif($pdl == $bad)
if defined $bad;
1393 #** @method Geo::OGR::Layer Polygonize(%params)
1395 # Polygonize this raster band.
1397 # @param params Named parameters:
1398 # - \a Mask A raster band, which is used as a mask to select polygonized areas. Default is undef.
1399 # - \a OutLayer A vector layer into which the polygons are written. If not given, an in-memory layer 'polygonized' is created and returned.
1400 # - \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'.
1401 # - \a Options Hash or list of options. Connectedness can be set to 8
1402 # to use 8-connectedness, otherwise 4-connectedness is
1403 # used. ForceIntPixel can be set to 1 to force using a 32 bit int buffer
1404 # for cell values in the process. If this is not set and the data type
1405 # of this raster does not fit into a 32 bit int buffer, a 32 bit float
1407 # - \a Progress Progress function.
1408 # - \a ProgressData Additional parameter for the progress function.
1410 # @return Output vector layer.
1414 my $p = named_parameters(\@_, Mask => undef, OutLayer => undef, PixValField =>
'val', Options => undef, Progress => undef, ProgressData => undef);
1415 my %known_options = (Connectedness => 1, ForceIntPixel => 1, DATASET_FOR_GEOREF => 1,
'8CONNECTED' => 1);
1416 for my $option (keys %{$p->{options}}) {
1417 error(1, $option, \%known_options) unless exists $known_options{$option};
1419 my $dt = $self->DataType;
1420 my %leInt32 = (Byte => 1, Int16 => 1, Int32 => 1, UInt16 => 1);
1421 my $leInt32 = $leInt32{$dt};
1422 $dt = $dt =~ /Float/ ?
'Real' :
'Integer';
1424 CreateLayer(Name =>
'polygonized',
1425 Fields => [{Name =>
'val', Type => $dt},
1426 {Name =>
'geom', Type =>
'Polygon'}]);
1427 $p->{pixvalfield} = $p->{outlayer}->GetLayerDefn->GetFieldIndex($p->{pixvalfield});
1428 $p->{options}{
'8CONNECTED'} = 1
if $p->{options}{Connectedness} && $p->{options}{Connectedness} == 8;
1429 if ($leInt32 || $p->{options}{ForceIntPixel}) {
1430 Geo::GDAL::_Polygonize($self, $p->{mask}, $p->{outlayer}, $p->{pixvalfield}, $p->{options}, $p->{progress}, $p->{progressdata});
1432 Geo::GDAL::FPolygonize($self, $p->{mask}, $p->{outlayer}, $p->{pixvalfield}, $p->{options}, $p->{progress}, $p->{progressdata});
1434 set the srs of the outlayer
if it was created here
1435 return $p->{outlayer};
1438 #** @method RasterAttributeTable()
1440 sub RasterAttributeTable {
1443 #** @method scalar ReadRaster(%params)
1445 # Read data from the band.
1447 # @param params Named parameters:
1448 # - \a XOff x offset (cell coordinates) (default is 0)
1449 # - \a YOff y offset (cell coordinates) (default is 0)
1450 # - \a XSize width of the area to read (default is the width of the band)
1451 # - \a YSize height of the area to read (default is the height of the band)
1452 # - \a BufXSize (default is undef, i.e., the same as XSize)
1453 # - \a BufYSize (default is undef, i.e., the same as YSize)
1454 # - \a BufType data type of the buffer (default is the data type of the band)
1455 # - \a BufPixelSpace (default is 0)
1456 # - \a BufLineSpace (default is 0)
1457 # - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'),
1458 # - \a Progress reference to a progress function (default is undef)
1459 # - \a ProgressData (default is undef)
1461 # <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
1462 # @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter.
1466 my ($width, $height) = $self->Size;
1467 my ($type) = $self->DataType;
1468 my $p = named_parameters(\@_,
1478 ResampleAlg =>
'NearestNeighbour',
1480 ProgressData => undef
1482 $p->{resamplealg} = s2i(rio_resampling => $p->{resamplealg});
1483 $p->{buftype} = s2i(data_type => $p->{buftype}, 1);
1484 $self->_ReadRaster($p->{xoff},$p->{yoff},$p->{xsize},$p->{ysize},$p->{bufxsize},$p->{bufysize},$p->{buftype},$p->{bufpixelspace},$p->{buflinespace},$p->{resamplealg},$p->{progress},$p->{progressdata});
1487 #** @method array reference ReadTile($xoff = 0, $yoff = 0, $xsize = <width>, $ysize = <height>)
1489 # Read band data into a Perl array.
1491 # \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle.
1493 # Usage example (print the data from a band):
1495 # print "@$_\n" for ( @{ $band->ReadTile() } );
1497 # Another usage example (process the data of a large dataset that has one band):
1499 # my($W,$H) = $dataset->Band()->Size();
1500 # my($xoff,$yoff,$w,$h) = (0,0,200,200);
1502 # if ($xoff >= $W) {
1505 # last if $yoff >= $H;
1507 # my $data = $dataset->Band(1)->ReadTile($xoff,$yoff,min($W-$xoff,$w),min($H-$yoff,$h));
1508 # # add your data processing code here
1509 # $dataset->Band(1)->WriteTile($data,$xoff,$yoff);
1514 # return $_[0] < $_[1] ? $_[0] : $_[1];
1517 # @param xoff Number of cell to skip before starting to read from a row. Pixels are read from left to right.
1518 # @param yoff Number of cells to skip before starting to read from a column. Pixels are read from top to bottom.
1519 # @param xsize Number of cells to read from each row.
1520 # @param ysize Number of cells to read from each column.
1521 # @return a two-dimensional Perl array, organizes as data->[y][x], y =
1522 # 0..height-1, x = 0..width-1. I.e., y is row and x is column.
1525 my($self, $xoff, $yoff, $xsize, $ysize, $w_tile, $h_tile, $alg) = @_;
1533 $alg = s2i(rio_resampling => $alg);
1534 my $t = $self->{DataType};
1535 my $buf = $self->_ReadRaster($xoff, $yoff, $xsize, $ysize, $w_tile, $h_tile, $t, 0, 0, $alg);
1540 for my $y (0..$h_tile-1) {
1541 my @d = unpack($pc.
"[$w_tile]", substr($buf, $offset, $w));
1548 #** @method Reclassify($classifier, $progress = undef, $progress_data = undef)
1550 # Reclassify the cells in the band.
1551 # @note NoData values in integer rasters are reclassified if
1552 # explicitly specified in the hash classifier. However, they are not
1553 # reclassified to the default value, if one is specified. In real
1554 # valued rasters nodata cells are not reclassified.
1555 # @note If the subroutine is user terminated or the classifier is
1556 # incorrect, already reclassified cells will stay reclassified but an
1558 # @param classifier For integer rasters an anonymous hash, which
1559 # contains old class values as keys and new class values as values, or
1560 # an array classifier as in Geo::GDAL::Band::ClassCounts. In a hash
1561 # classifier a special key '*' (star) can be used as default, to act
1562 # as a fallback new class value. For real valued rasters the
1563 # classifier is as in Geo::GDAL::Band::ClassCounts.
1568 #** @method RegenerateOverview(Geo::GDAL::Band overview, $resampling, coderef progress, $progress_data)
1570 # @param overview a Geo::GDAL::Band object for the overview.
1571 # @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average).
1572 # @param progress [optional] a reference to a subroutine, which will
1573 # be called with parameters (number progress, string msg, progress_data)
1574 # @param progress_data [optional]
1576 sub RegenerateOverview {
1578 #Geo::GDAL::Band overview, scalar resampling, subref callback, scalar callback_data
1580 Geo::GDAL::RegenerateOverview($self, @p);
1583 #** @method RegenerateOverviews(arrayref overviews, $resampling, coderef progress, $progress_data)
1585 # @todo This is not yet available
1587 # @param overviews a list of Geo::GDAL::Band objects for the overviews.
1588 # @param resampling [optional] the resampling method (one of Geo::GDAL::RIOResamplingTypes) (default is Average).
1589 # @param progress [optional] a reference to a subroutine, which will
1590 # be called with parameters (number progress, string msg, progress_data)
1591 # @param progress_data [optional]
1593 sub RegenerateOverviews {
1595 #arrayref overviews, scalar resampling, subref callback, scalar callback_data
1597 Geo::GDAL::RegenerateOverviews($self, @p);
1600 #** @method ScaleAndOffset($scale, $offset)
1602 # Scale and offset are used to transform raw cell values into the
1603 # units returned by GetUnits(). The conversion function is:
1605 # Units value = (raw value * scale) + offset
1607 # @return a list ($scale, $offset), the values are undefined if they
1609 # @since version 1.9 of the bindings.
1611 sub ScaleAndOffset {
1613 SetScale($self, $_[0])
if @_ > 0 and defined $_[0];
1614 SetOffset($self, $_[1])
if @_ > 1 and defined $_[1];
1615 return unless defined wantarray;
1616 my $scale = GetScale($self);
1617 my $offset = GetOffset($self);
1618 return ($scale, $offset);
1621 #** @method list SetDefaultHistogram($min, $max, $histogram)
1625 # @note See Note in Geo::GDAL::Band::GetHistogram.
1626 # @param histogram reference to an array containing the histogram
1628 sub SetDefaultHistogram {
1631 #** @method SetStatistics($min, $max, $mean, $stddev)
1633 # Save the statistics of the band if possible (the format can save
1634 # arbitrary metadata).
1643 #** @method Geo::GDAL::Band Sieve(%params)
1645 # Remove small areas by merging them into the largest neighbour area.
1646 # @param params Named parameters:
1647 # - \a Mask A raster band, which is used as a mask to select sieved areas. Default is undef.
1648 # - \a Dest A raster band into which the result is written. If not given, an new in-memory raster band is created and returned.
1649 # - \a Threshold The smallest area size (in number of cells) which are not sieved away.
1650 # - \a Options Hash or list of options. {Connectedness => 4} can be specified to use 4-connectedness, otherwise 8-connectedness is used.
1651 # - \a Progress Progress function.
1652 # - \a ProgressData Additional parameter for the progress function.
1654 # @return The filtered raster band.
1658 my $p = named_parameters(\@_, Mask => undef, Dest => undef, Threshold => 10, Options => undef, Progress => undef, ProgressData => undef);
1659 unless ($p->{dest}) {
1660 my ($w, $h) = $self->Size;
1664 if ($p->{options}{Connectedness}) {
1665 $c = $p->{options}{Connectedness};
1666 delete $p->{options}{Connectedness};
1668 Geo::GDAL::SieveFilter($self, $p->{mask}, $p->{dest}, $p->{threshold}, $c, $p->{options}, $p->{progress}, $p->{progressdata});
1672 #** @method list Size()
1674 # @return The size of the band as a list (width, height).
1678 return ($self->{XSize}, $self->{YSize});
1681 #** @method Unit($type)
1683 # @param type [optional] the unit (a string).
1684 # @note $band->Unit(undef) sets the unit value to an empty string.
1685 # @return the unit (a string).
1686 # @since version 1.9 of the bindings.
1693 SetUnitType($self, $unit);
1695 return unless defined wantarray;
1699 #** @method WriteRaster(%params)
1701 # Write data into the band.
1703 # @param params Named parameters:
1704 # - \a XOff x offset (cell coordinates) (default is 0)
1705 # - \a YOff y offset (cell coordinates) (default is 0)
1706 # - \a XSize width of the area to write (default is the width of the band)
1707 # - \a YSize height of the area to write (default is the height of the band)
1708 # - \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.
1709 # - \a BufXSize (default is undef, i.e., the same as XSize)
1710 # - \a BufYSize (default is undef, i.e., the same as YSize)
1711 # - \a BufType data type of the buffer (default is the data type of the band)
1712 # - \a BufPixelSpace (default is 0)
1713 # - \a BufLineSpace (default is 0)
1715 # <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
1719 my ($width, $height) = $self->Size;
1720 my ($type) = $self->DataType;
1721 my $p = named_parameters(\@_,
1733 confess
"Usage: \$band->WriteRaster( Buf => \$data, ... )" unless defined $p->{buf};
1734 $p->{buftype} = s2i(data_type => $p->{buftype}, 1);
1735 $self->_WriteRaster($p->{xoff},$p->{yoff},$p->{xsize},$p->{ysize},$p->{buf},$p->{bufxsize},$p->{bufysize},$p->{buftype},$p->{bufpixelspace},$p->{buflinespace});
1738 #** @method WriteTile($data, $xoff = 0, $yoff = 0)
1740 # Write band data from a Perl array.
1742 # \note Accessing band data in this way is slow. Consider using PDL and Geo::GDAL::Band::Piddle.
1744 # @param data A two-dimensional Perl array, organizes as data->[y][x], y =
1745 # 0..height-1, x = 0..width-1.
1751 my($self, $data, $xoff, $yoff) = @_;
1754 error(
'The data must be in a two-dimensional array') unless ref $data eq
'ARRAY' && ref $data->[0] eq
'ARRAY';
1755 my $xsize = @{$data->[0]};
1756 if ($xsize > $self->{XSize} - $xoff) {
1757 warn
"Buffer XSize too large ($xsize) for this raster band (width = $self->{XSize}, offset = $xoff).";
1758 $xsize = $self->{XSize} - $xoff;
1760 my $ysize = @{$data};
1761 if ($ysize > $self->{YSize} - $yoff) {
1762 $ysize = $self->{YSize} - $yoff;
1763 warn
"Buffer YSize too large ($ysize) for this raster band (height = $self->{YSize}, offset = $yoff).";
1766 for my $i (0..$ysize-1) {
1767 my $scanline = pack($pc.
"[$xsize]", @{$data->[$i]});
1768 $self->WriteRaster( $xoff, $yoff+$i, $xsize, 1, $scanline );
1772 #** @class Geo::GDAL::ColorTable
1773 # @brief A color table from a raster band or a color table, which can be used for a band.
1776 package Geo::GDAL::ColorTable;
1780 #** @method Geo::GDAL::ColorTable Clone()
1782 # Clone an existing color table.
1783 # @return a new Geo::GDAL::ColorTable object
1788 #** @method list Color($index, @color)
1790 # Get or set a color in this color table.
1791 # @param index The index of the color in the table. Note that the
1792 # color table may expand if the index is larger than the current max
1793 # index of this table and a color is given. An attempt to retrieve a
1794 # color out of the current size of the table causes an error.
1795 # @param color [optional] The color, either a list or a reference to a
1796 # list. If the list is too short or has undef values, the undef values
1797 # are taken as 0 except for alpha, which is taken as 255.
1798 # @note A color is an array of four integers having a value between 0
1799 # and 255: (gray, red, cyan or hue; green, magenta, or lightness;
1800 # blue, yellow, or saturation; alpha or blackband)
1801 # @return A color, in list context a list and in scalar context a reference to an anonymous array.
1806 #** @method list Colors(@colors)
1808 # Get or set the colors in this color table.
1809 # @note The color table will expand to the size of the input list but
1810 # it will not shrink.
1811 # @param colors [optional] A list of all colors (a list of lists) for this color table.
1812 # @return A list of colors (a list of lists).
1817 #** @method CreateColorRamp($start_index, arrayref start_color, $end_index, arrayref end_color)
1819 # @param start_index
1820 # @param start_color
1824 sub CreateColorRamp {
1827 #** @method scalar GetCount()
1829 # @return The number of colors in this color table.
1834 #** @method scalar GetPaletteInterpretation()
1836 # @return palette interpretation (string)
1838 sub GetPaletteInterpretation {
1840 return i2s(palette_interpretation => GetPaletteInterpretation($self));
1843 #** @method Geo::GDAL::ColorTable new($GDALPaletteInterp = 'RGB')
1845 # Create a new empty color table.
1846 # @return a new Geo::GDAL::ColorTable object
1851 $pi = s2i(palette_interpretation => $pi);
1852 my $self = Geo::GDALc::new_ColorTable($pi);
1853 bless $self, $pkg
if defined($self);
1856 #** @class Geo::GDAL::Dataset
1857 # @brief A set of associated raster bands or vector layer source.
1860 package Geo::GDAL::Dataset;
1864 #** @attr $RasterCount
1865 # scalar (access as $dataset->{RasterCount})
1868 #** @attr $RasterXSize
1869 # scalar (access as $dataset->{RasterXSize})
1872 #** @attr $RasterYSize
1873 # scalar (access as $dataset->{RasterYSize})
1876 #** @method AddBand($datatype = 'Byte', hashref options = {})
1878 # Add a new band to the dataset. The driver must support the action.
1879 # @param datatype GDAL raster cell data type (one of those listed by Geo::GDAL::DataTypes).
1880 # @param options reference to a hash of format specific options.
1881 # @return The added band.
1884 my ($self, $type, $options) = @_;
1886 $type = s2i(data_type => $type);
1887 $self->_AddBand($type, $options);
1888 return unless defined wantarray;
1889 return $self->GetRasterBand($self->{RasterCount});
1892 #** @method AdviseRead()
1897 #** @method Geo::GDAL::Band Band($index)
1899 # Create a band object for the band within the dataset.
1900 # @note a.k.a. GetRasterBand
1901 # @param index 1...RasterCount, default is 1.
1902 # @return a new Geo::GDAL::Band object
1907 #** @method list Bands()
1909 # @return a list of new Geo::GDAL::Band objects
1914 for my $i (1..$self->{RasterCount}) {
1915 push @bands, GetRasterBand($self, $i);
1920 #** @method BuildOverviews($resampling, arrayref overviews, coderef progress, $progress_data)
1922 # @param resampling the resampling method, one of Geo::GDAL::RIOResamplingTypes.
1923 # @param overviews The list of overview decimation factors to
1924 # build. For example [2,4,8].
1925 # @param progress [optional] a reference to a subroutine, which will
1926 # be called with parameters (number progress, string msg, progress_data)
1927 # @param progress_data [optional]
1929 sub BuildOverviews {
1932 $p[0] = uc($p[0])
if $p[0];
1934 $self->_BuildOverviews(@p);
1936 confess(last_error()) if $@;
1939 #** @method Geo::GDAL::Dataset BuildVRT($Dest, arrayref Sources, hashref Options, coderef progress, $progress_data)
1941 # Build a virtual dataset from a set of datasets.
1942 # @param Dest Destination raster dataset definition string (typically
1943 # filename), or an object, which implements write and close.
1944 # @param Sources A list of filenames of input datasets or a list of
1946 # @param Options See section \ref index_processing_options.
1947 # @return Dataset object
1949 # @note This subroutine is imported into the main namespace if Geo::GDAL
1950 # is use'd with qw/:all/.
1953 my ($dest, $sources, $options, $progress, $progress_data) = @_;
1954 $options = Geo::GDAL::GDALBuildVRTOptions->new(make_processing_options($options));
1955 error(
"Usage: Geo::GDAL::DataSet::BuildVRT(\$vrt_file_name, \\\@sources)")
1956 unless ref $sources eq 'ARRAY' && defined $sources->[0];
1957 unless (blessed($dest)) {
1958 if (blessed($sources->[0])) {
1959 return Geo::GDAL::wrapper_GDALBuildVRT_objects($dest, $sources, $options, $progress, $progress_data);
1961 return Geo::GDAL::wrapper_GDALBuildVRT_names($dest, $sources, $options, $progress, $progress_data);
1964 if (blessed($sources->[0])) {
1965 return stdout_redirection_wrapper(
1967 \&Geo::GDAL::wrapper_GDALBuildVRT_objects,
1968 $options, $progress, $progress_data);
1970 return stdout_redirection_wrapper(
1972 \&Geo::GDAL::wrapper_GDALBuildVRT_names,
1973 $options, $progress, $progress_data);
1978 #** @method CommitTransaction()
1980 sub CommitTransaction {
1983 #** @method Geo::GDAL::ColorTable ComputeColorTable(%params)
1985 # Compute a color table from an RGB image
1986 # @param params Named parameters:
1987 # - \a Red The red band, the default is to use the red band of this dataset.
1988 # - \a Green The green band, the default is to use the green band of this dataset.
1989 # - \a Blue The blue band, the default is to use the blue band of this dataset.
1990 # - \a NumColors The number of colors in the computed color table. Default is 256.
1991 # - \a Progress reference to a progress function (default is undef)
1992 # - \a ProgressData (default is undef)
1993 # - \a Method The computation method. The default and currently only option is the median cut algorithm.
1995 # @return a new color table object.
1997 sub ComputeColorTable {
1999 my $p = named_parameters(\@_,
2005 ProgressData => undef,
2006 Method =>
'MedianCut');
2007 for my $b ($self->Bands) {
2008 for my $cion ($b->ColorInterpretation) {
2009 if ($cion eq
'RedBand') { $p->{red}
2010 if ($cion eq
'GreenBand') { $p->{green}
2011 if ($cion eq
'BlueBand') { $p->{blue}
2015 Geo::GDAL::ComputeMedianCutPCT($p->{red},
2019 $ct, $p->{progress},
2020 $p->{progressdata});
2024 #** @method Geo::OGR::Layer CopyLayer($layer, $name, hashref options = undef)
2026 # @param layer A Geo::OGR::Layer object to be copied.
2027 # @param name A name for the new layer.
2028 # @param options A ref to a hash of format specific options.
2029 # @return a new Geo::OGR::Layer object.
2034 #** @method Geo::OGR::Layer CreateLayer(%params)
2036 # @brief Create a new vector layer into this dataset.
2038 # @param %params Named parameters:
2039 # - \a Name (scalar) name for the new layer.
2040 # - \a Fields (array reference) a list of (scalar and geometry) field definitions as in
2041 # Geo::OGR::Layer::CreateField.
2042 # - \a ApproxOK (boolean value, default is true) a flag, which is forwarded to Geo::OGR::Layer::CreateField.
2043 # - \a Options (hash reference) driver specific hash of layer creation options.
2044 # - \a Schema (hash reference, deprecated, use \a Fields and \a Name) may contain keys Name, Fields, GeomFields, GeometryType.
2045 # - \a SRS (scalar) the spatial reference for the default geometry field.
2046 # - \a GeometryType (scalar) the type of the default geometry field
2047 # (if only one geometry field). Default is 'Unknown'.
2049 # @note If Fields or Schema|Fields is not given, a default geometry
2050 # field (Name => '', GeometryType => 'Unknown') is created. If it is
2051 # given and it contains spatial fields, both GeometryType and SRS are
2052 # ignored. The type can be also set with the named parameter.
2056 # my $roads = Geo::OGR::Driver('Memory')->Create('road')->
2058 # Fields => [ { Name => 'class',
2059 # Type => 'Integer' },
2061 # Type => 'LineString25D' } ] );
2064 # @note Many formats allow only one spatial field, which currently
2065 # requires the use of GeometryType.
2067 # @return a new Geo::OGR::Layer object.
2071 my $p = named_parameters(\@_,
2074 GeometryType =>
'Unknown',
2079 error(
"The 'Fields' argument must be an array reference.")
if $p->{fields} && ref($p->{fields}) ne
'ARRAY';
2080 if (defined $p->{schema}) {
2081 my $s = $p->{schema};
2082 $p->{geometrytype} = $s->{GeometryType}
if exists $s->{GeometryType};
2083 $p->{fields} = $s->{Fields}
if exists $s->{Fields};
2084 $p->{name} = $s->{Name}
if exists $s->{Name};
2086 $p->{fields} = [] unless ref($p->{fields}) eq
'ARRAY';
2087 # if fields contains spatial fields, then do not create default one
2088 for my $f (@{$p->{fields}}) {
2089 error(
"Field definitions must be hash references.") unless ref $f eq 'HASH';
2090 if ($f->{GeometryType} || ($f->{Type} && s_exists(geometry_type => $f->{Type}))) {
2091 $p->{geometrytype} =
'None';
2095 my $gt = s2i(geometry_type => $p->{geometrytype});
2096 my $layer = _CreateLayer($self, $p->{name}, $p->{srs}, $gt, $p->{options});
2097 for my $f (@{$p->{fields}}) {
2098 $layer->CreateField($f);
2100 keep($layer, $self);
2103 #** @method CreateMaskBand()
2105 # Add a mask band to the dataset.
2107 sub CreateMaskBand {
2108 return _CreateMaskBand(@_);
2111 #** @method Geo::GDAL::Dataset DEMProcessing($Dest, $Processing, $ColorFilename, hashref Options, coderef progress, $progress_data)
2113 # Apply a DEM processing to this dataset.
2114 # @param Dest Destination raster dataset definition string (typically filename) or an object, which implements write and close.
2115 # @param Processing Processing to apply, one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", or "Roughness".
2116 # @param ColorFilename The color palette for color-relief.
2117 # @param Options See section \ref index_processing_options.
2118 # @param progress [optional] A reference to a subroutine, which will
2119 # be called with parameters (number progress, string msg, progress_data).
2120 # @param progress_data [optional]
2124 my ($self, $dest, $Processing, $ColorFilename, $options, $progress, $progress_data) = @_;
2125 $options = Geo::GDAL::GDALDEMProcessingOptions->new(make_processing_options($options));
2126 return $self->stdout_redirection_wrapper(
2128 \&Geo::GDAL::wrapper_GDALDEMProcessing,
2129 $Processing, $ColorFilename, $options, $progress, $progress_data
2133 #** @method Dataset()
2140 #** @method DeleteLayer($name)
2142 # Deletes a layer from the data source. Note that if there is a layer
2143 # object for the deleted layer, it becomes unusable.
2144 # @param name name of the layer to delete.
2147 my ($self, $name) = @_;
2149 for my $i (0..$self->GetLayerCount-1) {
2150 my $layer = GetLayerByIndex($self, $i);
2151 $index = $i, last
if $layer->GetName eq $name;
2153 error(2, $name,
'Layer') unless defined $index;
2154 _DeleteLayer($self, $index);
2157 #** @method Geo::GDAL::Band Dither(%params)
2159 # Compute one band with color table image from an RGB image
2160 # @params params Named parameters:
2161 # - \a Red The red band, the default is to use the red band of this dataset.
2162 # - \a Green The green band, the default is to use the green band of this dataset.
2163 # - \a Blue The blue band, the default is to use the blue band of this dataset.
2164 # - \a Dest The destination band. If this is not defined, a new in-memory band (and a dataset) will be created.
2165 # - \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.
2166 # - \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.
2167 # - \a ProgressData (default is undef)
2169 # @return the destination band.
2171 # Usage example. This code converts an RGB JPEG image into a one band PNG image with a color table.
2173 # my $d = Geo::GDAL::Open('pic.jpg');
2174 # Geo::GDAL::Driver('PNG')->Copy(Name => 'test.png', Src => $d->Dither->Dataset);
2179 my $p = named_parameters(\@_,
2186 ProgressData => undef);
2187 for my $b ($self->Bands) {
2188 for my $cion ($b->ColorInterpretation) {
2189 if ($cion eq
'RedBand') { $p->{red}
2190 if ($cion eq
'GreenBand') { $p->{green}
2191 if ($cion eq
'BlueBand') { $p->{blue}
2194 my ($w, $h) = $self->Size;
2198 Type =>
'Byte')->Band;
2202 Green => $p->{green},
2204 Progress => $p->{progress},
2205 ProgressData => $p->{progressdata});
2206 Geo::GDAL::DitherRGB2PCT($p->{red},
2212 $p->{progressdata});
2213 $p->{dest}->ColorTable($p->{colortable});
2217 #** @method Domains()
2223 #** @method Geo::GDAL::Driver Driver()
2225 # @note a.k.a. GetDriver
2226 # @return a Geo::GDAL::Driver object that was used to open or create this dataset.
2231 #** @method Geo::OGR::Layer ExecuteSQL($statement, $geom = undef, $dialect = "")
2233 # @param statement A SQL statement.
2234 # @param geom A Geo::OGR::Geometry object.
2236 # @return a new Geo::OGR::Layer object. The data source object will
2237 # exist as long as the layer object exists.
2241 my $layer = $self->_ExecuteSQL(@_);
2242 note($layer,
"is result set");
2243 keep($layer, $self);
2246 #** @method Geo::GDAL::Extent Extent(@params)
2248 # @param params nothing, or a list ($xoff, $yoff, $w, $h)
2249 # @return A new Geo::GDAL::Extent object that represents the area that
2250 # this raster or the specified tile covers.
2254 my $t = $self->GeoTransform;
2255 my $extent = $t->Extent($self->Size);
2257 my ($xoff, $yoff, $w, $h) = @_;
2258 my ($x, $y) = $t->Apply([$xoff, $xoff+$w, $xoff+$w, $xoff], [$yoff, $yoff, $yoff+$h, $yoff+$h]);
2259 my $xmin = shift @$x;
2262 $xmin = $x
if $x < $xmin;
2263 $xmax = $x
if $x > $xmax;
2265 my $ymin = shift @$y;
2268 $ymin = $y
if $y < $ymin;
2269 $ymax = $y
if $y > $ymax;
2276 #** @method list GCPs(@GCPs, Geo::OSR::SpatialReference sr)
2278 # Get or set the GCPs and their projection.
2279 # @param GCPs [optional] a list of Geo::GDAL::GCP objects
2280 # @param sr [optional] the projection of the GCPs.
2281 # @return a list of Geo::GDAL::GCP objects followed by a Geo::OSR::SpatialReference object.
2287 $proj = $proj->Export(
'WKT')
if $proj and ref($proj);
2288 SetGCPs($self, \@_, $proj);
2290 return unless defined wantarray;
2292 my $GCPs = GetGCPs($self);
2293 return (@$GCPs, $proj);
2296 #** @method Geo::GDAL::GeoTransform GeoTransform(Geo::GDAL::GeoTransform $geo_transform)
2298 # Transformation from cell coordinates (column,row) to projection
2301 # x = geo_transform[0] + column*geo_transform[1] + row*geo_transform[2]
2302 # y = geo_transform[3] + column*geo_transform[4] + row*geo_transform[5]
2304 # @param geo_transform [optional]
2305 # @return the geo transform in a non-void context.
2311 SetGeoTransform($self, $_[0]);
2313 SetGeoTransform($self, \@_);
2316 confess(last_error())
if $@;
2317 return unless defined wantarray;
2318 my $t = GetGeoTransform($self);
2326 #** @method GetDriver()
2331 #** @method list GetFileList()
2333 # @return list of files GDAL believes to be part of this dataset.
2338 #** @method scalar GetGCPProjection()
2340 # @return projection string.
2342 sub GetGCPProjection {
2345 #** @method GetGCPSpatialRef()
2347 sub GetGCPSpatialRef {
2350 #** @method Geo::OGR::Layer GetLayer($name)
2352 # @param name the name of the requested layer. If not given, then
2353 # returns the first layer in the data source.
2354 # @return a new Geo::OGR::Layer object that represents the layer
2355 # in the data source.
2358 my($self, $name) = @_;
2359 my $layer = defined $name ? GetLayerByName($self,
"$name") : GetLayerByIndex($self, 0);
2361 error(2, $name,
'Layer') unless $layer;
2362 keep($layer, $self);
2365 #** @method list GetLayerNames()
2367 # @note Delivers the functionality of undocumented method GetLayerCount.
2368 # @return a list of the names of the layers this data source provides.
2373 for my $i (0..$self->GetLayerCount-1) {
2374 my $layer = GetLayerByIndex($self, $i);
2375 push @names, $layer->GetName;
2380 #** @method GetNextFeature()
2382 sub GetNextFeature {
2385 #** @method GetRootGroup()
2390 #** @method GetSpatialRef()
2395 #** @method GetStyleTable()
2400 #** @method Geo::GDAL::Dataset Grid($Dest, hashref Options)
2402 # Creates a regular raster grid from this data source.
2403 # This is equivalent to the gdal_grid utility.
2404 # @param Dest Destination raster dataset definition string (typically
2405 # filename) or an object, which implements write and close.
2406 # @param Options See section \ref index_processing_options.
2409 my ($self, $dest, $options, $progress, $progress_data) = @_;
2410 $options = Geo::GDAL::GDALGridOptions->new(make_processing_options($options));
2411 return $self->stdout_redirection_wrapper(
2413 \&Geo::GDAL::wrapper_GDALGrid,
2414 $options, $progress, $progress_data
2418 #** @method scalar Info(hashref Options)
2420 # Information about this dataset.
2421 # @param Options See section \ref index_processing_options.
2424 my ($self, $o) = @_;
2425 $o = Geo::GDAL::GDALInfoOptions->new(make_processing_options($o));
2426 return GDALInfo($self, $o);
2429 #** @method Geo::GDAL::Dataset Nearblack($Dest, hashref Options, coderef progress, $progress_data)
2431 # Convert nearly black/white pixels to black/white.
2432 # @param Dest Destination raster dataset definition string (typically
2433 # filename), destination dataset to which to add an alpha or mask
2434 # band, or an object, which implements write and close.
2435 # @param Options See section \ref index_processing_options.
2436 # @return Dataset if destination dataset definition string was given,
2437 # otherwise a boolean for success/fail but the method croaks if there
2441 my ($self, $dest, $options, $progress, $progress_data) = @_;
2442 $options = Geo::GDAL::GDALNearblackOptions->new(make_processing_options($options));
2443 my $b = blessed($dest);
2444 if ($b && $b eq
'Geo::GDAL::Dataset') {
2445 Geo::GDAL::wrapper_GDALNearblackDestDS($dest, $self, $options, $progress, $progress_data);
2447 return $self->stdout_redirection_wrapper(
2449 \&Geo::GDAL::wrapper_GDALNearblackDestName,
2450 $options, $progress, $progress_data
2455 #** @method Geo::GDAL::Dataset Open()
2456 # Package subroutine.
2457 # The same as Geo::GDAL::Open
2462 #** @method Geo::GDAL::Dataset OpenShared()
2463 # Package subroutine.
2464 # The same as Geo::GDAL::OpenShared
2469 #** @method Geo::GDAL::Dataset Rasterize($Dest, hashref Options, coderef progress, $progress_data)
2471 # Render data from this data source into a raster.
2472 # @param Dest Destination raster dataset definition string (typically
2473 # filename), destination dataset, or an object, which implements write and close.
2474 # @param Options See section \ref index_processing_options.
2475 # @return Dataset if destination dataset definition string was given,
2476 # otherwise a boolean for success/fail but the method croaks if there
2481 my ($self, $dest, $options, $progress, $progress_data) = @_;
2482 $options = Geo::GDAL::GDALRasterizeOptions->new(make_processing_options($options));
2483 my $b = blessed($dest);
2484 if ($b && $b eq
'Geo::GDAL::Dataset') {
2485 Geo::GDAL::wrapper_GDALRasterizeDestDS($dest, $self, $options, $progress, $progress_data);
2487 # TODO: options need to force a new raster be made, otherwise segfault
2488 return $self->stdout_redirection_wrapper(
2490 \&Geo::GDAL::wrapper_GDALRasterizeDestName,
2491 $options, $progress, $progress_data
2496 #** @method scalar ReadRaster(%params)
2498 # Read data from the dataset.
2500 # @param params Named parameters:
2501 # - \a XOff x offset (cell coordinates) (default is 0)
2502 # - \a YOff y offset (cell coordinates) (default is 0)
2503 # - \a XSize width of the area to read (default is the width of the dataset)
2504 # - \a YSize height of the area to read (default is the height of the dataset)
2505 # - \a BufXSize (default is undef, i.e., the same as XSize)
2506 # - \a BufYSize (default is undef, i.e., the same as YSize)
2507 # - \a BufType data type of the buffer (default is the data type of the first band)
2508 # - \a BandList a reference to an array of band indices (default is [1])
2509 # - \a BufPixelSpace (default is 0)
2510 # - \a BufLineSpace (default is 0)
2511 # - \a BufBandSpace (default is 0)
2512 # - \a ResampleAlg one of Geo::GDAL::RIOResamplingTypes (default is 'NearestNeighbour'),
2513 # - \a Progress reference to a progress function (default is undef)
2514 # - \a ProgressData (default is undef)
2516 # <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
2517 # @return a buffer, open the buffer with \a unpack function of Perl. See Geo::GDAL::Band::PackCharacter.
2521 my ($width, $height) = $self->Size;
2522 my ($type) = $self->Band->DataType;
2523 my $p = named_parameters(\@_,
2535 ResampleAlg =>
'NearestNeighbour',
2537 ProgressData => undef
2539 $p->{resamplealg} = s2i(rio_resampling => $p->{resamplealg});
2540 $p->{buftype} = s2i(data_type => $p->{buftype}, 1);
2541 $self->_ReadRaster($p->{xoff},$p->{yoff},$p->{xsize},$p->{ysize},$p->{bufxsize},$p->{bufysize},$p->{buftype},$p->{bandlist},$p->{bufpixelspace},$p->{buflinespace},$p->{bufbandspace},$p->{resamplealg},$p->{progress},$p->{progressdata});
2544 #** @method ReadTile()
2547 my ($self, $xoff, $yoff, $xsize, $ysize, $w_tile, $h_tile, $alg) = @_;
2549 for my $i (0..$self->Bands-1) {
2550 $data[$i] = $self->Band($i+1)->ReadTile($xoff, $yoff, $xsize, $ysize, $w_tile, $h_tile, $alg);
2555 #** @method ReleaseResultSet($layer)
2557 # @param layer A layer the has been created with ExecuteSQL.
2558 # @note There is no need to call this method. The result set layer is
2559 # released in the destructor of the layer that was created with SQL.
2561 sub ReleaseResultSet {
2562 # a no-op, _ReleaseResultSet is called from Layer::DESTROY
2565 #** @method ResetReading()
2570 #** @method RollbackTransaction()
2572 sub RollbackTransaction {
2575 #** @method SetGCPs2()
2580 #** @method SetSpatialRef()
2585 #** @method SetStyleTable()
2590 #** @method list Size()
2592 # @return (width, height)
2596 return ($self->{RasterXSize}, $self->{RasterYSize});
2599 #** @method Geo::OSR::SpatialReference SpatialReference(Geo::OSR::SpatialReference sr)
2601 # Get or set the projection of this dataset.
2602 # @param sr [optional] a Geo::OSR::SpatialReference object,
2603 # which replaces the existing projection definition of this dataset.
2604 # @return a Geo::OSR::SpatialReference object, which represents the
2605 # projection of this dataset.
2606 # @note Methods GetProjection, SetProjection, and Projection return WKT strings.
2608 sub SpatialReference {
2609 my($self, $sr) = @_;
2610 SetProjection($self, $sr->As(
'WKT')) if defined $sr;
2611 if (defined wantarray) {
2612 my $p = GetProjection($self);
2618 #** @method StartTransaction()
2620 sub StartTransaction {
2623 #** @method TestCapability()
2625 sub TestCapability {
2626 return _TestCapability(@_);
2629 #** @method Tile(Geo::GDAL::Extent e)
2631 # Compute the top left cell coordinates and width and height of the
2632 # tile that covers the given extent.
2633 # @param e The extent whose tile is needed.
2634 # @note Requires that the raster is a strictly north up one.
2635 # @return A list ($xoff, $yoff, $xsize, $ysize).
2638 my ($self, $e) = @_;
2639 my ($w, $h) = $self->Size;
2640 my $t = $self->GeoTransform;
2641 confess
"GeoTransform is not \"north up\"." unless $t->NorthUp;
2642 my $xoff = floor(($e->[0] - $t->[0])/$t->[1]);
2643 $xoff = 0
if $xoff < 0;
2644 my $yoff = floor(($e->[1] - $t->[3])/$t->[5]);
2645 $yoff = 0
if $yoff < 0;
2646 my $xsize = ceil(($e->[2] - $t->[0])/$t->[1]) - $xoff;
2647 $xsize = $w - $xoff
if $xsize > $w - $xoff;
2648 my $ysize = ceil(($e->[3] - $t->[3])/$t->[5]) - $yoff;
2649 $ysize = $h - $yoff
if $ysize > $h - $yoff;
2650 return ($xoff, $yoff, $xsize, $ysize);
2653 #** @method Geo::GDAL::Dataset Translate($Dest, hashref Options, coderef progress, $progress_data)
2655 # Convert this dataset into another format.
2656 # @param Dest Destination dataset definition string (typically
2657 # filename) or an object, which implements write and close.
2658 # @param Options See section \ref index_processing_options.
2659 # @return New dataset object if destination dataset definition
2660 # string was given, otherwise a boolean for success/fail but the
2661 # method croaks if there was an error.
2664 my ($self, $dest, $options, $progress, $progress_data) = @_;
2665 return $self->stdout_redirection_wrapper(
2669 #** @method Geo::GDAL::Dataset Warp($Dest, hashref Options, coderef progress, $progress_data)
2671 # Reproject this dataset.
2672 # @param Dest Destination raster dataset definition string (typically
2673 # filename) or an object, which implements write and close.
2674 # @param Options See section \ref index_processing_options.
2675 # @note This method can be run as a package subroutine with a list of
2676 # datasets as the first argument to mosaic several datasets.
2679 my ($self, $dest, $options, $progress, $progress_data) = @_;
2680 # can be run as object method (one dataset) and as package sub (a list of datasets)
2681 $options = Geo::GDAL::GDALWarpAppOptions->new(make_processing_options($options));
2682 my $b = blessed($dest);
2683 $self = [$self] unless ref $self eq
'ARRAY';
2684 if ($b && $b eq
'Geo::GDAL::Dataset') {
2685 Geo::GDAL::wrapper_GDALWarpDestDS($dest, $self, $options, $progress, $progress_data);
2687 return stdout_redirection_wrapper(
2690 \&Geo::GDAL::wrapper_GDALWarpDestName,
2691 $options, $progress, $progress_data
2696 #** @method Geo::GDAL::Dataset Warped(%params)
2698 # Create a virtual warped dataset from this dataset.
2700 # @param params Named parameters:
2701 # - \a SrcSRS Override the spatial reference system of this dataset if there is one (default is undef).
2702 # - \a DstSRS The target spatial reference system of the result (default is undef).
2703 # - \a ResampleAlg The resampling algorithm (default is 'NearestNeighbour').
2704 # - \a MaxError Maximum error measured in input cellsize that is allowed in approximating the transformation (default is 0 for exact calculations).
2706 # # <a href="http://www.gdal.org/gdalwarper_8h.html">Documentation for GDAL warper.</a>
2708 # @return a new Geo::GDAL::Dataset object
2712 my $p = named_parameters(\@_, SrcSRS => undef, DstSRS => undef, ResampleAlg =>
'NearestNeighbour', MaxError => 0);
2713 for my $srs (qw/srcsrs dstsrs/) {
2714 $p->{$srs} = $p->{$srs}->ExportToWkt
if $p->{$srs} && blessed $p->{$srs};
2716 $p->{resamplealg} = s2i(resampling => $p->{resamplealg});
2717 my $warped = Geo::GDAL::_AutoCreateWarpedVRT($self, $p->{srcsrs}, $p->{dstsrs}, $p->{resamplealg}, $p->{maxerror});
2718 keep($warped, $self)
if $warped; #
self must live as
long as warped
2721 #** @method WriteRaster(%params)
2723 # Write data into the dataset.
2725 # @param params Named parameters:
2726 # - \a XOff x offset (cell coordinates) (default is 0)
2727 # - \a YOff y offset (cell coordinates) (default is 0)
2728 # - \a XSize width of the area to write (default is the width of the dataset)
2729 # - \a YSize height of the area to write (default is the height of the dataset)
2730 # - \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.
2731 # - \a BufXSize (default is undef, i.e., the same as XSize)
2732 # - \a BufYSize (default is undef, i.e., the same as YSize)
2733 # - \a BufType data type of the buffer (default is the data type of the first band)
2734 # - \a BandList a reference to an array of band indices (default is [1])
2735 # - \a BufPixelSpace (default is 0)
2736 # - \a BufLineSpace (default is 0)
2737 # - \a BufBandSpace (default is 0)
2739 # <a href="http://www.gdal.org/classGDALDataset.html">Entry in GDAL docs (method RasterIO)</a>
2743 my ($width, $height) = $self->Size;
2744 my ($type) = $self->Band->DataType;
2745 my $p = named_parameters(\@_,
2759 $p->{buftype} = s2i(data_type => $p->{buftype}, 1);
2760 $self->_WriteRaster($p->{xoff},$p->{yoff},$p->{xsize},$p->{ysize},$p->{buf},$p->{bufxsize},$p->{bufysize},$p->{buftype},$p->{bandlist},$p->{bufpixelspace},$p->{buflinespace},$p->{bufbandspace});
2763 #** @method WriteTile()
2766 my ($self, $data, $xoff, $yoff) = @_;
2769 for my $i (0..$self->Bands-1) {
2770 $self->Band($i+1)->WriteTile($data->[$i], $xoff, $yoff);
2774 #** @class Geo::GDAL::Dimension
2776 package Geo::GDAL::Dimension;
2780 #** @method GetDirection()
2785 #** @method GetFullName()
2790 #** @method GetIndexingVariable()
2792 sub GetIndexingVariable {
2795 #** @method GetName()
2800 #** @method GetSize()
2805 #** @method GetType()
2810 #** @method SetIndexingVariable()
2812 sub SetIndexingVariable {
2815 #** @class Geo::GDAL::Driver
2816 # @brief A driver for a specific dataset format.
2819 package Geo::GDAL::Driver;
2823 #** @attr $HelpTopic
2824 # $driver->{HelpTopic}
2828 # $driver->{LongName}
2831 #** @attr $ShortName
2832 # $driver->{ShortName}
2835 #** @method list Capabilities()
2837 # @return A list of capabilities. When executed as a package subroutine
2838 # returns a list of all potential capabilities a driver may have. When
2839 # executed as an object method returns a list of all capabilities the
2842 # Currently capabilities are:
2843 # CREATE, CREATECOPY, DEFAULT_FIELDS, NOTNULL_FIELDS, NOTNULL_GEOMFIELDS, OPEN, RASTER, VECTOR, and VIRTUALIO.
2847 # @all_capabilities = Geo::GDAL::Driver::Capabilities;
2848 # @capabilities_of_the_geotiff_driver = Geo::GDAL::Driver('GTiff')->Capabilities;
2853 return @CAPABILITIES unless $self;
2854 my $h = $self->GetMetadata;
2856 for my $cap (@CAPABILITIES) {
2857 my $test = $h->{
'DCAP_'.uc($cap)};
2858 push @cap, $cap
if defined($test) and $test eq
'YES';
2863 #** @method Geo::GDAL::Dataset Copy(%params)
2865 # Create a new raster Geo::GDAL::Dataset as a copy of an existing dataset.
2866 # @note a.k.a. CreateCopy
2868 # @param params Named parameters:
2869 # - \a Name name for the new raster dataset.
2870 # - \a Src the source Geo::GDAL::Dataset object.
2871 # - \a Strict 1 (default) if the copy must be strictly equivalent, or 0 if the copy may adapt.
2872 # - \a Options an anonymous hash of driver specific options.
2873 # - \a Progress [optional] a reference to a subroutine, which will
2874 # be called with parameters (number progress, string msg, progress_data).
2875 # - \a ProgressData [optional]
2876 # @return a new Geo::GDAL::Dataset object.
2880 my $p = named_parameters(\@_, Name =>
'unnamed', Src => undef, Strict => 1, Options => {}, Progress => undef, ProgressData => undef);
2881 return $self->stdout_redirection_wrapper(
2883 $self->can(
'_CreateCopy'),
2884 $p->{src}, $p->{strict}, $p->{options}, $p->{progress}, $p->{progressdata});
2887 #** @method CopyFiles($NewName, $OldName)
2889 # Copy the files of a dataset.
2890 # @param NewName String.
2891 # @param OldName String.
2896 #** @method Geo::GDAL::Dataset Create(%params)
2898 # Create a raster dataset using this driver.
2899 # @note a.k.a. CreateDataset
2901 # @param params Named parameters:
2902 # - \a Name The name for the dataset (default is 'unnamed') or an object, which implements write and close.
2903 # - \a Width The width for the raster dataset (default is 256).
2904 # - \a Height The height for the raster dataset (default is 256).
2905 # - \a Bands The number of bands to create into the raster dataset (default is 1).
2906 # - \a Type The data type for the raster cells (default is 'Byte'). One of Geo::GDAL::Driver::CreationDataTypes.
2907 # - \a Options Driver creation options as a reference to a hash (default is {}).
2909 # @return A new Geo::GDAL::Dataset object.
2913 my $p = named_parameters(\@_, Name =>
'unnamed', Width => 256, Height => 256, Bands => 1, Type =>
'Byte', Options => {});
2914 my $type = s2i(data_type => $p->{type});
2915 return $self->stdout_redirection_wrapper(
2917 $self->can(
'_Create'),
2918 $p->{width}, $p->{height}, $p->{bands}, $type, $p->{options}
2922 #** @method CreateMultiDimensional()
2924 sub CreateMultiDimensional {
2927 #** @method list CreationDataTypes()
2929 # @return a list of data types that can be used for new datasets of this format. A subset of Geo::GDAL::DataTypes
2931 sub CreationDataTypes {
2933 my $h = $self->GetMetadata;
2934 return split /\s+/, $h->{DMD_CREATIONDATATYPES}
if $h->{DMD_CREATIONDATATYPES};
2937 #** @method list CreationOptionList()
2939 # @return a list of options, each option is a hashref, the keys are
2940 # name, type and description or Value. Value is a listref.
2942 sub CreationOptionList {
2945 my $h = $self->GetMetadata->{DMD_CREATIONOPTIONLIST};
2947 $h = ParseXMLString($h);
2948 my($type, $value) = NodeData($h);
2949 if ($value eq
'CreationOptionList') {
2950 for my $o (Children($h)) {
2952 for my $a (Children($o)) {
2953 my(undef, $key) = NodeData($a);
2954 my(undef, $value) = NodeData(Child($a, 0));
2955 if ($key eq
'Value') {
2956 push @{$option{$key}}, $value;
2958 $option{$key} = $value;
2961 push @options, \%option;
2968 #** @method Delete($name)
2975 #** @method Domains()
2981 #** @method scalar Extension()
2983 # @note The returned extension does not contain a '.' prefix.
2984 # @return a suggested single extension or a list of extensions (in
2985 # list context) for datasets.
2989 my $h = $self->GetMetadata;
2991 my $e = $h->{DMD_EXTENSIONS};
2992 my @e = split / /, $e;
2994 for my $i (0..$#e) {
2999 my $e = $h->{DMD_EXTENSION};
3000 return '' if $e =~ /\
3006 #** @method scalar MIMEType()
3008 # @return a suggested MIME type for datasets.
3012 my $h = $self->GetMetadata;
3013 return $h->{DMD_MIMETYPE};
3016 #** @method scalar Name()
3018 # @return The short name of the driver.
3022 return $self->{ShortName};
3027 # The same as Geo::GDAL::Open except that only this driver is allowed.
3031 my @p = @_; # name, update
3032 my @flags = qw/RASTER/;
3033 push @flags, qw/READONLY/
if $p[1] eq
'ReadOnly';
3034 push @flags, qw/UPDATE/
if $p[1] eq
'Update';
3035 my $dataset = OpenEx($p[0], \@flags, [$self->Name()]);
3036 error(
"Failed to open $p[0]. Is it a raster dataset?") unless $dataset;
3040 #** @method Rename($NewName, $OldName)
3042 # Rename (move) a GDAL dataset.
3043 # @param NewName String.
3044 # @param OldName String.
3049 #** @method scalar TestCapability($cap)
3051 # Test whether the driver has the specified capability.
3052 # @param cap A capability string (one of those returned by Capabilities).
3053 # @return a boolean value.
3055 sub TestCapability {
3056 my($self, $cap) = @_;
3057 my $h = $self->GetMetadata->{
'DCAP_'.uc($cap)};
3058 return (defined($h) and $h eq
'YES') ? 1 : undef;
3061 #** @method stdout_redirection_wrapper()
3063 sub stdout_redirection_wrapper {
3064 my ($self, $name, $sub, @params) = @_;
3066 if ($name && blessed $name) {
3068 my $ref = $object->can(
'write');
3069 VSIStdoutSetRedirection($ref);
3070 $name =
'/vsistdout/';
3074 $ds = $sub->($self, $name, @params);
3078 $Geo::GDAL::stdout_redirection{tied(%$ds)} = $object;
3080 VSIStdoutUnsetRedirection();
3084 confess(last_error()) if $@;
3085 confess("Failed. Use Geo::OGR::Driver for vector drivers.") unless $ds;
3089 #** @class Geo::GDAL::EDTComponent
3091 package Geo::GDAL::EDTComponent;
3095 #** @method GetName()
3100 #** @method GetOffset()
3105 #** @method GetType()
3110 #** @class Geo::GDAL::ExtendedDataType
3112 package Geo::GDAL::ExtendedDataType;
3116 #** @method CanConvertTo()
3121 #** @method CreateString()
3126 #** @method Equals()
3131 #** @method GetClass()
3136 #** @method GetMaxStringLength()
3138 sub GetMaxStringLength {
3141 #** @method GetName()
3146 #** @method GetNumericDataType()
3148 sub GetNumericDataType {
3151 #** @method GetSize()
3156 #** @class Geo::GDAL::Extent
3157 # @brief A rectangular area in projection coordinates: xmin, ymin, xmax, ymax.
3159 package Geo::GDAL::Extent;
3161 #** @method ExpandToInclude($extent)
3162 # Package subroutine.
3163 # Extends this extent to include the other extent.
3164 # @param extent Another Geo::GDAL::Extent object.
3166 sub ExpandToInclude {
3167 my ($self, $e) = @_;
3168 return if $e->IsEmpty;
3169 if ($self->IsEmpty) {
3172 $self->[0] = $e->[0]
if $e->[0] < $self->[0];
3173 $self->[1] = $e->[1]
if $e->[1] < $self->[1];
3174 $self->[2] = $e->[2]
if $e->[2] > $self->[2];
3175 $self->[3] = $e->[3]
if $e->[3] > $self->[3];
3179 #** @method IsEmpty()
3183 return $self->[2] < $self->[0];
3186 #** @method scalar Overlap($extent)
3187 # Package subroutine.
3188 # @param extent Another Geo::GDAL::Extent object.
3189 # @return A new, possibly empty, Geo::GDAL::Extent object, which
3190 # represents the joint area of the two extents.
3193 my ($self, $e) = @_;
3196 $ret->[0] = $e->[0]
if $self->[0] < $e->[0];
3197 $ret->[1] = $e->[1]
if $self->[1] < $e->[1];
3198 $ret->[2] = $e->[2]
if $self->[2] > $e->[2];
3199 $ret->[3] = $e->[3]
if $self->[3] > $e->[3];
3203 #** @method scalar Overlaps($extent)
3204 # Package subroutine.
3205 # @param extent Another Geo::GDAL::Extent object.
3206 # @return True if this extent overlaps the other extent, false otherwise.
3209 my ($self, $e) = @_;
3210 return $self->[0] < $e->[2] && $self->[2] > $e->[0] && $self->[1] < $e->[3] && $self->[3] > $e->[1];
3213 #** @method list Size()
3214 # Package subroutine.
3215 # @return A list ($width, $height).
3219 return (0,0)
if $self->
IsEmpty;
3220 return ($self->[2] - $self->[0], $self->[3] - $self->[1]);
3223 #** @method Geo::GDAL::Extent new(@params)
3224 # Package subroutine.
3225 # @param params nothing, a list ($xmin, $ymin, $xmax, $ymax), or an Extent object
3226 # @return A new Extent object (empty if no parameters, a copy of the parameter if it is an Extent object).
3233 } elsif (ref $_[0]) {
3238 bless $self, $class;
3242 #** @class Geo::GDAL::GCP
3243 # @brief A ground control point for georeferencing rasters.
3246 package Geo::GDAL::GCP;
3251 # cell x coordinate (access as $gcp->{Column})
3255 # unique identifier (string) (access as $gcp->{Id})
3259 # informational message (access as $gcp->{Info})
3263 # cell y coordinate (access as $gcp->{Row})
3267 # projection coordinate (access as $gcp->{X})
3271 # projection coordinate (access as $gcp->{Y})
3275 # projection coordinate (access as $gcp->{Z})
3278 #** @method scalar new($x = 0.0, $y = 0.0, $z = 0.0, $column = 0.0, $row = 0.0, $info = "", $id = "")
3280 # @param x projection coordinate
3281 # @param y projection coordinate
3282 # @param z projection coordinate
3283 # @param column cell x coordinate
3284 # @param row cell y coordinate
3285 # @param info informational message
3286 # @param id unique identifier (string)
3287 # @return a new Geo::GDAL::GCP object
3291 my $self = Geo::GDALc::new_GCP(@_);
3292 bless $self, $pkg
if defined($self);
3295 #** @class Geo::GDAL::GDALMultiDimInfoOptions
3297 package Geo::GDAL::GDALMultiDimInfoOptions;
3305 my $self = Geo::GDALc::new_GDALMultiDimInfoOptions(@_);
3306 bless $self, $pkg
if defined($self);
3309 #** @class Geo::GDAL::GDALMultiDimTranslateOptions
3311 package Geo::GDAL::GDALMultiDimTranslateOptions;
3319 my $self = Geo::GDALc::new_GDALMultiDimTranslateOptions(@_);
3320 bless $self, $pkg
if defined($self);
3323 #** @class Geo::GDAL::GeoTransform
3324 # @brief An array of affine transformation coefficients.
3325 # @details The geo transformation has the form
3327 # x = a + column * b + row * c
3328 # y = d + column * e + row * f
3331 # (column,row) is the location in cell coordinates, and
3332 # (x,y) is the location in projection coordinates, or vice versa.
3333 # A Geo::GDAL::GeoTransform object is a reference to an anonymous array [a,b,c,d,e,f].
3335 package Geo::GDAL::GeoTransform;
3337 #** @method Apply($x, $y)
3339 # @param x Column or x, or a reference to an array of columns or x's
3340 # @param y Row or y, or a reference to an array of rows or y's
3341 # @return a list (x, y), where x and y are the transformed coordinates
3342 # or references to arrays of transformed coordinates.
3345 my ($self, $columns, $rows) = @_;
3346 return Geo::GDAL::ApplyGeoTransform($self, $columns, $rows) unless ref($columns) eq
'ARRAY';
3348 for my $i (0..$#$columns) {
3350 Geo::GDAL::ApplyGeoTransform($self, $columns->[$i], $rows->[$i]);
3357 # @return a new Geo::GDAL::GeoTransform object, which is the inverse
3358 # of this one (in void context changes this object).
3362 my @inv = Geo::GDAL::InvGeoTransform($self);
3367 #** @method NorthUp()
3371 return $self->[2] == 0 && $self->[4] == 0;
3374 #** @method new(@params)
3376 # @param params nothing, a reference to an array [a,b,c,d,e,f], a list
3377 # (a,b,c,d,e,f), or named parameters
3378 # - \a GCPs A reference to an array of Geo::GDAL::GCP objects.
3379 # - \a ApproxOK Minimize the error in the coefficients (integer, default is 1 (true), used with GCPs).
3380 # - \a Extent A Geo::GDAL::Extent object used to obtain the coordinates of the up left corner position.
3381 # - \a CellSize The cell size (width and height) (default is 1, used with Extent).
3383 # @note When Extent is specifid, the created geo transform will be
3384 # north up, have square cells, and coefficient f will be -1 times the
3385 # cell size (image y - row - will increase downwards and projection y
3386 # will increase upwards).
3387 # @return a new Geo::GDAL::GeoTransform object.
3393 $self = [0,1,0,0,0,1];
3394 } elsif (ref $_[0]) {
3396 } elsif ($_[0] =~ /^[a-zA-Z]/i) {
3397 my $p = named_parameters(\@_, GCPs => undef, ApproxOK => 1, Extent => undef, CellSize => 1);
3399 $self = Geo::GDAL::GCPsToGeoTransform($p->{gcps}, $p->{approxok});
3400 } elsif ($p->{extent}) {
3403 error(
"Missing GCPs or Extent");
3409 bless $self, $class;
3412 #** @class Geo::GDAL::Group
3414 package Geo::GDAL::Group;
3418 #** @method CreateAttribute()
3420 sub CreateAttribute {
3423 #** @method CreateDimension()
3425 sub CreateDimension {
3428 #** @method CreateGroup()
3433 #** @method GetAttribute()
3438 #** @method GetFullName()
3443 #** @method GetGroupNames()
3448 #** @method GetMDArrayNames()
3450 sub GetMDArrayNames {
3453 #** @method GetName()
3458 #** @method GetStructuralInfo()
3460 sub GetStructuralInfo {
3463 #** @method OpenGroup()
3468 #** @method OpenMDArray()
3473 #** @class Geo::GDAL::MDArray
3475 package Geo::GDAL::MDArray;
3479 #** @method AsClassicDataset()
3481 sub AsClassicDataset {
3484 #** @method CreateAttribute()
3486 sub CreateAttribute {
3489 #** @method DeleteNoDataValue()
3491 sub DeleteNoDataValue {
3494 #** @method GetAttribute()
3499 #** @method GetDataType()
3504 #** @method GetDimensionCount()
3506 sub GetDimensionCount {
3509 #** @method GetFullName()
3514 #** @method GetMask()
3519 #** @method GetName()
3524 #** @method GetNoDataValueAsDouble()
3526 sub GetNoDataValueAsDouble {
3529 #** @method GetOffset()
3534 #** @method GetScale()
3539 #** @method GetSpatialRef()
3544 #** @method GetStructuralInfo()
3546 sub GetStructuralInfo {
3549 #** @method GetTotalElementsCount()
3551 sub GetTotalElementsCount {
3554 #** @method GetUnit()
3559 #** @method GetUnscaled()
3564 #** @method GetView()
3569 #** @method SetNoDataValueDouble()
3571 sub SetNoDataValueDouble {
3574 #** @method SetOffset()
3579 #** @method SetScale()
3584 #** @method SetSpatialRef()
3589 #** @method SetUnit()
3594 #** @method Transpose()
3599 #** @class Geo::GDAL::MajorObject
3600 # @brief An object, which holds meta data.
3603 package Geo::GDAL::MajorObject;
3607 #** @method scalar Description($description)
3609 # @param description [optional]
3610 # @return the description in a non-void context.
3613 my($self, $desc) = @_;
3614 SetDescription($self, $desc)
if defined $desc;
3615 GetDescription($self)
if defined wantarray;
3618 #** @method Domains()
3619 # Package subroutine.
3620 # @return the class specific DOMAINS list
3626 #** @method scalar GetDescription()
3630 sub GetDescription {
3633 #** @method hash reference GetMetadata($domain = "")
3635 # @note see Metadata
3642 #** @method GetMetadataDomainList()
3644 sub GetMetadataDomainList {
3647 #** @method hash reference Metadata(hashref metadata = undef, $domain = '')
3651 # @return the metadata in a non-void context.
3655 my $metadata = ref $_[0] ? shift : undef;
3657 SetMetadata($self, $metadata, $domain)
if defined $metadata;
3658 GetMetadata($self, $domain)
if defined wantarray;
3661 #** @method SetDescription($NewDesc)
3666 sub SetDescription {
3669 #** @method SetMetadata(hashref metadata, $domain = "")
3671 # @note see Metadata
3679 #** @class Geo::GDAL::RasterAttributeTable
3680 # @brief An attribute table in a raster band.
3683 package Geo::GDAL::RasterAttributeTable;
3694 #** @method ChangesAreWrittenToFile()
3696 sub ChangesAreWrittenToFile {
3699 #** @method Geo::GDAL::RasterAttributeTable Clone()
3701 # @return a new Geo::GDAL::RasterAttributeTable object
3706 #** @method hash Columns(%columns)
3708 # A get/set method for the columns of the RAT
3709 # @param columns optional, a the keys are column names and the values are anonymous
3710 # hashes with keys Type and Usage
3711 # @return a hash similar to the optional input parameter
3716 if (@_) { # create columns
3718 for my $name (keys %columns) {
3719 $self->CreateColumn($name, $columns{$name}{Type}, $columns{$name}{Usage});
3723 for my $c (0..$self->GetColumnCount-1) {
3724 my $name = $self->GetNameOfCol($c);
3725 $columns{$name}{Type} = $self->GetTypeOfCol($c);
3726 $columns{$name}{Usage} = $self->GetUsageOfCol($c);
3731 #** @method CreateColumn($name, $type, $usage)
3734 # @param type one of FieldTypes
3735 # @param usage one of FieldUsages
3738 my($self, $name, $type, $usage) = @_;
3739 for my $color (qw/Red Green Blue Alpha/) {
3740 carp
"RAT column type will be 'Integer' for usage '$color'." if $usage eq $color and $type ne
'Integer';
3742 $type = s2i(rat_field_type => $type);
3743 $usage = s2i(rat_field_usage => $usage);
3744 _CreateColumn($self, $name, $type, $usage);
3747 #** @method DumpReadable()
3752 #** @method list FieldTypes()
3753 # Package subroutine.
3757 return @FIELD_TYPES;
3760 #** @method list FieldUsages()
3761 # Package subroutine.
3765 return @FIELD_USAGES;
3768 #** @method scalar GetColOfUsage($usage)
3774 my($self, $usage) = @_;
3775 _GetColOfUsage($self, s2i(rat_field_usage => $usage));
3778 #** @method scalar GetColumnCount()
3782 sub GetColumnCount {
3785 #** @method scalar GetNameOfCol($column)
3793 #** @method scalar GetRowCount()
3799 #** @method scalar GetRowOfValue($value)
3801 # @param value a cell value
3802 # @return row index or -1
3807 #** @method GetTableType()
3812 #** @method scalar GetTypeOfCol($column)
3818 my($self, $col) = @_;
3819 i2s(rat_field_type => _GetTypeOfCol($self, $col));
3822 #** @method scalar GetUsageOfCol($column)
3828 my($self, $col) = @_;
3829 i2s(rat_field_usage => _GetUsageOfCol($self, $col));
3832 #** @method scalar GetValueAsDouble($row, $column)
3838 sub GetValueAsDouble {
3841 #** @method scalar GetValueAsInt($row, $column)
3850 #** @method scalar GetValueAsString($row, $column)
3856 sub GetValueAsString {
3859 #** @method LinearBinning($Row0MinIn, $BinSizeIn)
3861 # @param Row0MinIn [optional] the lower bound (cell value) of the first category.
3862 # @param BinSizeIn [optional] the width of each category (in cell value units).
3863 # @return ($Row0MinIn, $BinSizeIn) or an empty list if LinearBinning is not set.
3867 SetLinearBinning($self, @_)
if @_ > 0;
3868 return unless defined wantarray;
3869 my @a = GetLinearBinning($self);
3870 return $a[0] ? ($a[1], $a[2]) : ();
3873 #** @method SetRowCount($count)
3881 #** @method SetTableType()
3886 #** @method SetValueAsDouble($row, $column, $value)
3893 sub SetValueAsDouble {
3896 #** @method SetValueAsInt($row, $column, $value)
3906 #** @method SetValueAsString($row, $column, $value)
3913 sub SetValueAsString {
3916 #** @method scalar Value($row, $column, $value)
3920 # @param value [optional]
3924 my($self, $row, $column) = @_;
3925 SetValueAsString($self, $row, $column, $_[3])
if defined $_[3];
3926 return unless defined wantarray;
3927 GetValueAsString($self, $row, $column);
3930 #** @method Geo::GDAL::RasterAttributeTable new()
3932 # @return a new Geo::GDAL::RasterAttributeTable object
3936 my $self = Geo::GDALc::new_RasterAttributeTable(@_);
3937 bless $self, $pkg
if defined($self);
3940 #** @class Geo::GDAL::Transformer
3942 # @details This class is not yet documented for the GDAL Perl bindings.
3943 # @todo Test and document.
3945 package Geo::GDAL::Transformer;
3949 #** @method TransformGeolocations()
3951 sub TransformGeolocations {
3954 #** @method TransformPoint()
3956 sub TransformPoint {
3963 my $self = Geo::GDALc::new_Transformer(@_);
3964 bless $self, $pkg
if defined($self);
3967 #** @class Geo::GDAL::VSIF
3968 # @brief A GDAL virtual file system.
3971 package Geo::GDAL::VSIF;
3973 use base qw(Exporter)
3980 Geo::GDAL::VSIFCloseL($self);
3990 #** @method MkDir($path)
3991 # Package subroutine.
3993 # @param path The directory to make.
3994 # @note The name of this method is VSIMkdir in GDAL.
3998 # mode unused in CPL
3999 Geo::GDAL::Mkdir($path, 0);
4002 #** @method Geo::GDAL::VSIF Open($filename, $mode)
4003 # Package subroutine.
4004 # @param filename Name of the file to open. For example "/vsimem/x".
4005 # @param mode Access mode. 'r', 'r+', 'w', etc.
4006 # @return A file handle on success.
4009 my ($path, $mode) = @_;
4010 my $self = Geo::GDAL::VSIFOpenL($path, $mode);
4011 bless $self,
'Geo::GDAL::VSIF';
4014 #** @method scalar Read($count)
4016 # @param count The number of bytes to read from the file.
4017 # @return A byte string.
4020 my ($self, $count) = @_;
4021 Geo::GDAL::VSIFReadL($count, $self);
4024 #** @method list ReadDir($dir)
4025 # Package subroutine.
4026 # @return Contents of a directory in an anonymous array or as a list.
4030 Geo::GDAL::ReadDir($path);
4033 #** @method scalar ReadDirRecursive($dir)
4034 # Package subroutine.
4035 # @note Give the directory in the form '/vsimem', i.e., without trailing '/'.
4036 # @return Contents of a directory tree in an anonymous array.
4038 sub ReadDirRecursive {
4040 Geo::GDAL::ReadDirRecursive($path);
4043 #** @method Rename($old, $new)
4044 # Package subroutine.
4046 # @note The name of this method is VSIRename in GDAL.
4049 my ($old, $new) = @_;
4050 Geo::GDAL::Rename($old, $new);
4053 #** @method RmDir($path)
4054 # Package subroutine.
4055 # Remove a directory.
4056 # @note The name of this method is VSIRmdir in GDAL.
4059 my ($dirname, $recursive) = @_;
4062 Geo::GDAL::Rmdir($dirname);
4064 for my $f (ReadDir($dirname)) {
4065 next
if $f eq
'..' or $f eq
'.';
4066 my @s = Stat($dirname.
'/'.$f);
4068 Unlink($dirname.
'/'.$f);
4069 } elsif ($s[0] eq
'd') {
4070 Rmdir($dirname.
'/'.$f, 1);
4071 Rmdir($dirname.
'/'.$f);
4078 my $r = $recursive ?
' recursively' :
'';
4079 error(
"Cannot remove directory \"$dirname\"$r.");
4083 #** @method Seek($offset, $whence)
4087 my ($self, $offset, $whence) = @_;
4088 Geo::GDAL::VSIFSeekL($self, $offset, $whence);
4091 #** @method list Stat($filename)
4092 # Package subroutine.
4093 # @return ($filemode, $filesize). filemode is f for a plain file, d
4094 # for a directory, l for a symbolic link, p for a named pipe (FIFO), S
4095 # for a socket, b for a block special file, and c for a character
4100 Geo::GDAL::Stat($path);
4103 #** @method scalar Tell()
4108 Geo::GDAL::VSIFTellL($self);
4111 #** @method Truncate($new_size)
4115 my ($self, $new_size) = @_;
4116 Geo::GDAL::VSIFTruncateL($self, $new_size);
4119 #** @method Unlink($filename)
4120 # Package subroutine.
4121 # @param filename The file to delete.
4122 # @return 0 on success and -1 on an error.
4125 my ($filename) = @_;
4126 Geo::GDAL::Unlink($filename);
4129 #** @method Write($scalar)
4131 # @param scalar The byte string to write to the file.
4132 # @return Number of bytes written into the file.
4135 my ($self, $data) = @_;
4136 Geo::GDAL::VSIFWriteL($data, $self);
4139 #** @class Geo::GDAL::VSILFILE
4141 package Geo::GDAL::VSILFILE;
4145 #** @class Geo::GDAL::XML
4146 # @brief A simple XML parser
4149 package Geo::GDAL::XML;
4151 #** @method new($string)
4153 # @param string String containing XML.
4154 # @return A new Geo::GDAL::XML object, which is a reference to an anonymous array.
4159 my $self = ParseXMLString($xml);
4160 bless $self, $class;
4161 $self->traverse(sub {my $node = shift; bless $node, $class});
4165 #** @method serialize()
4167 # @return The XML serialized into a string.
4171 return SerializeXMLTree($self);
4174 # This file was automatically generated by SWIG (http://www.swig.org).
4177 # Do not make changes to this file unless you know what you are doing--modify
4178 # the SWIG interface file instead.
4181 #** @method traverse(coderef subroutine)
4183 # @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.
4186 my ($self, $sub) = @_;
4187 my $type = $self->[0];
4188 my $data = $self->[1];
4189 $type = NodeType($type);
4190 $sub->($self, $type, $data);
4191 for my $child (@{$self}[2..$#$self]) {
4192 traverse($child, $sub);
4197 # @brief Base class for geographical networks in GDAL.
4202 #** @method CastToGenericNetwork()
4204 sub CastToGenericNetwork {
4207 #** @method CastToNetwork()
4212 #** @method GATConnectedComponents()
4214 sub GATConnectedComponents {
4217 #** @method GATDijkstraShortestPath()
4219 sub GATDijkstraShortestPath {
4222 #** @method GATKShortestPath()
4224 sub GATKShortestPath {
4227 #** @method GNM_EDGE_DIR_BOTH()
4229 sub GNM_EDGE_DIR_BOTH {
4232 #** @method GNM_EDGE_DIR_SRCTOTGT()
4234 sub GNM_EDGE_DIR_SRCTOTGT {
4237 #** @method GNM_EDGE_DIR_TGTTOSRC()
4239 sub GNM_EDGE_DIR_TGTTOSRC {
4243 #** @class Geo::GNM::GenericNetwork
4246 package Geo::GNM::GenericNetwork;
4250 #** @method ChangeAllBlockState()
4252 sub ChangeAllBlockState {
4255 #** @method ChangeBlockState()
4257 sub ChangeBlockState {
4260 #** @method ConnectFeatures()
4262 sub ConnectFeatures {
4265 #** @method ConnectPointsByLines()
4267 sub ConnectPointsByLines {
4270 #** @method CreateRule()
4275 #** @method DeleteAllRules()
4277 sub DeleteAllRules {
4280 #** @method DeleteRule()
4285 #** @method DisconnectFeatures()
4287 sub DisconnectFeatures {
4290 #** @method DisconnectFeaturesWithId()
4292 sub DisconnectFeaturesWithId {
4295 #** @method GetRules()
4300 #** @method ReconnectFeatures()
4302 sub ReconnectFeatures {
4305 #** @class Geo::GNM::MajorObject
4308 package Geo::GNM::MajorObject;
4310 #** @class Geo::GNM::Network
4313 package Geo::GNM::Network;
4317 #** @method CommitTransaction()
4319 sub CommitTransaction {
4322 #** @method CopyLayer()
4327 #** @method DisconnectAll()
4332 #** @method GetFeatureByGlobalFID()
4334 sub GetFeatureByGlobalFID {
4337 #** @method GetFileList()
4342 #** @method GetLayerByIndex()
4344 sub GetLayerByIndex {
4347 #** @method GetLayerByName()
4349 sub GetLayerByName {
4352 #** @method GetLayerCount()
4357 #** @method GetName()
4362 #** @method GetPath()
4367 #** @method GetProjection()
4372 #** @method GetProjectionRef()
4374 sub GetProjectionRef {
4377 #** @method GetVersion()
4382 #** @method RollbackTransaction()
4384 sub RollbackTransaction {
4387 #** @method StartTransaction()
4389 sub StartTransaction {
4393 # @brief OGR utility functions.
4394 # @details A wrapper for many OGR utility functions and a root class for all
4399 #** @method list ByteOrders()
4400 # Package subroutine.
4401 # @return a list of byte order types, XDR and NDR. XDR denotes
4402 # big-endian and NDR denotes little-endian.
4407 #** @method CreateGeometryFromEsriJson()
4409 sub CreateGeometryFromEsriJson {
4412 #** @method Geo::GDAL::Driver Driver($name)
4413 # Package subroutine.
4415 # @param name the short name of the driver.
4416 # @note No check is made that the driver is actually a vector driver.
4417 # @return a Geo::GDAL::Driver object.
4420 return 'Geo::GDAL::Driver' unless @_;
4424 #** @method list DriverNames()
4425 # Package subroutine.
4426 # A.k.a GetDriverNames
4428 # perl -MGeo::GDAL -e '@d=Geo::OGR::DriverNames;print "@d\n"'
4430 # @note Use Geo::GDAL::DriverNames for raster drivers.
4431 # @return a list of the short names of all available GDAL vector drivers.
4436 #** @method list Drivers()
4437 # Package subroutine.
4438 # @note Use Geo::GDAL::Drivers for raster drivers.
4439 # @return a list of all available GDAL vector drivers.
4443 for my $i (0..GetDriverCount()-1) {
4444 my $driver = Geo::GDAL::GetDriver($i);
4445 push @drivers, $driver
if $driver->TestCapability(
'VECTOR');
4450 #** @method Flatten()
4455 #** @method scalar GeometryTypeModify($type, $modifier)
4457 # @param type a geometry type (one of Geo::OGR::GeometryTypes).
4458 # @param modifier one of 'flatten', 'set_Z', 'make_collection', 'make_curve', or 'make_linear'.
4459 # @return modified geometry type.
4461 sub GeometryTypeModify {
4462 my($type, $modifier) = @_;
4463 $type = s2i(geometry_type => $type);
4464 return i2s(geometry_type => GT_Flatten($type))
if $modifier =~ /flat/i;
4465 return i2s(geometry_type => GT_SetZ($type))
if $modifier =~ /z/i;
4466 return i2s(geometry_type => GT_GetCollection($type))
if $modifier =~ /collection/i;
4467 return i2s(geometry_type => GT_GetCurve($type))
if $modifier =~ /curve/i;
4468 return i2s(geometry_type => GT_GetLinear($type))
if $modifier =~ /linear/i;
4469 error(1, $modifier, {Flatten => 1, SetZ => 1, GetCollection => 1, GetCurve => 1, GetLinear => 1});
4472 #** @method scalar GeometryTypeTest($type, $test, $type2)
4474 # @param type a geometry type (one of Geo::OGR::GeometryTypes).
4475 # @param test one of 'has_z', 'is_subclass_of', 'is_curve', 'is_surface', or 'is_non_linear'.
4476 # @param type2 a geometry type (one of Geo::OGR::GeometryTypes). Required for 'is_subclass_of' test.
4477 # @return result of the test.
4479 sub GeometryTypeTest {
4480 my($type, $test, $type2) = @_;
4481 $type = s2i(geometry_type => $type);
4482 if (defined $type2) {
4483 $type = s2i(geometry_type => $type);
4485 error(
"Usage: GeometryTypeTest(type1, 'is_subclass_of', type2).") if $test =~ /subclass/i;
4487 return GT_HasZ($type) if $test =~ /z/i;
4488 return GT_IsSubClassOf($type, $type2) if $test =~ /subclass/i;
4489 return GT_IsCurve($type) if $test =~ /curve/i;
4490 return GT_IsSurface($type) if $test =~ /surface/i;
4491 return GT_IsNonLinear($type) if $test =~ /linear/i;
4492 error(1, $test, {HasZ => 1, IsSubClassOf => 1, IsCurve => 1, IsSurface => 1, IsNonLinear => 1});
4495 #** @method list GeometryTypes()
4496 # Package subroutine.
4497 # @return a list of all geometry types, currently:
4498 # CircularString, CircularStringM, CircularStringZ, CircularStringZM, CompoundCurve, CompoundCurveM, CompoundCurveZ, CompoundCurveZM, Curve, CurveM, CurvePolygon, CurvePolygonM, CurvePolygonZ, CurvePolygonZM, CurveZ, CurveZM, GeometryCollection, GeometryCollection25D, GeometryCollectionM, GeometryCollectionZM, LineString, LineString25D, LineStringM, LineStringZM, LinearRing, MultiCurve, MultiCurveM, MultiCurveZ, MultiCurveZM, MultiLineString, MultiLineString25D, MultiLineStringM, MultiLineStringZM, MultiPoint, MultiPoint25D, MultiPointM, MultiPointZM, MultiPolygon, MultiPolygon25D, MultiPolygonM, MultiPolygonZM, MultiSurface, MultiSurfaceM, MultiSurfaceZ, MultiSurfaceZM, None, Point, Point25D, PointM, PointZM, Polygon, Polygon25D, PolygonM, PolygonZM, PolyhedralSurface, PolyhedralSurfaceM, PolyhedralSurfaceZ, PolyhedralSurfaceZM, Surface, SurfaceM, SurfaceZ, SurfaceZM, TIN, TINM, TINZ, TINZM, Triangle, TriangleM, TriangleZ, TriangleZM, and Unknown.
4502 # This file was automatically generated by SWIG (http://www.swig.org).
4505 # Do not make changes to this file unless you know what you are doing--modify
4506 # the SWIG interface file instead.
4509 #** @method GetNonLinearGeometriesEnabledFlag()
4511 sub GetNonLinearGeometriesEnabledFlag {
4514 #** @method GetOpenDSCount()
4516 sub GetOpenDSCount {
4529 #** @method Geo::GDAL::Dataset Open($name, $update = 0)
4531 # Open a vector data source.
4532 # @param name The data source string (directory, filename, etc.).
4533 # @param update Whether to open the data source in update mode (default is not).
4534 # @return a new Geo::GDAL::Dataset object.
4537 my @p = @_; # name, update
4538 my @flags = qw/VECTOR/;
4539 push @flags, qw/UPDATE/
if $p[1];
4541 error(
"Failed to open $p[0]. Is it a vector dataset?") unless $dataset;
4545 #** @method Geo::GDAL::Dataset OpenShared($name, $update = 0)
4547 # Open a vector data source in shared mode.
4548 # @param name The data source string (directory, filename, etc.).
4549 # @param update Whether to open the data source in update mode.
4550 # @return a new Geo::GDAL::Dataset object.
4553 my @p = @_; # name, update
4554 my @flags = qw/VECTOR SHARED/;
4555 push @flags, qw/UPDATE/
if $p[1];
4557 error(
"Failed to open $p[0]. Is it a vector dataset?") unless $dataset;
4561 #** @method SetGenerate_DB2_V72_BYTE_ORDER($Generate_DB2_V72_BYTE_ORDER)
4563 # Needed only on IBM DB2.
4565 sub SetGenerate_DB2_V72_BYTE_ORDER {
4568 #** @method SetNonLinearGeometriesEnabledFlag()
4570 sub SetNonLinearGeometriesEnabledFlag {
4573 #** @class Geo::OGR::DataSource
4574 # @brief A vector dataset.
4575 # @details This is a legacy class which should not be
4576 # used in new code. Use Geo::GDAL::Dataset.
4578 package Geo::OGR::DataSource;
4580 #** @method Geo::GDAL::Dataset Open()
4581 # Package subroutine.
4582 # The same as Geo::OGR::Open
4587 #** @method Geo::GDAL::Dataset OpenShared()
4588 # Package subroutine.
4589 # The same as Geo::OGR::OpenShared
4594 #** @class Geo::OGR::Driver
4595 # @brief A vector format driver.
4596 # @details This is a legacy class which
4597 # should not be used in new code. Use Geo::GDAL::Driver.
4599 package Geo::OGR::Driver;
4603 #** @method Geo::GDAL::Dataset Copy(Geo::GDAL::Dataset source, $name, arrayref options = undef)
4605 # Copy a vector data source into a new data source with this driver.
4606 # @param source The Geo::GDAL::Dataset object to be copied.
4607 # @param name The name for the new data source.
4608 # @param options Driver specific options. In addition to options
4609 # specified in GDAL documentation the option STRICT can be set to 'NO'
4610 # for a more relaxed copy. Otherwise the STRICT is 'YES'.
4611 # @note The order of the first two parameters is different from that in Geo::GDAL::Driver::Copy.
4612 # @return a new Geo::GDAL::Dataset object.
4615 my ($self, @p) = @_; # src, name, options
4616 my $strict = 1; # the
default in bindings
4617 $strict = 0
if $p[2] && $p[2]->{STRICT} eq
'NO';
4618 $self->SUPER::Copy($p[1], $p[0], $strict, @{$p[2..4]}); # path, src, strict, options, cb, cb_data
4621 #** @method Geo::GDAL::Dataset Create($name, hashref options = undef )
4623 # Create a new vector data source using this driver.
4624 # @param name The data source name.
4625 # @param options Driver specific dataset creation options.
4628 my ($self, $name, $options) = @_; # name, options
4630 $self->SUPER::Create(Name => $name, Width => 0, Height => 0, Bands => 0, Type =>
'Byte', Options => $options);
4635 # The same as Geo::OGR::Open except that only this driver is allowed.
4639 my @p = @_; # name, update
4640 my @flags = qw/VECTOR/;
4641 push @flags, qw/UPDATE/
if $p[1];
4643 error(
"Failed to open $p[0]. Is it a vector dataset?") unless $dataset;
4647 #** @class Geo::OGR::Feature
4648 # @brief A collection of non-spatial and spatial attributes.
4649 # @details A feature is a collection of non-spatial and spatial attributes and
4650 # an id, which is a special attribute, and data records according to
4651 # this data model. Attributes are called fields and some fields are
4652 # spatial, i.e., their value is a geometry. Fields have at least a
4653 # name and a type. Features may exist within a layer or
4654 # separetely. The data model of a feature is a definition object.
4656 package Geo::OGR::Feature;
4660 #** @method Geo::OGR::Feature Clone()
4662 # @return a new Geo::OGR::Feature object
4667 #** @method DumpReadable()
4669 # Write the contents of this feature to stdout.
4674 #** @method scalar Equal($feature)
4676 # @param feature a Geo::OGR::Feature object for comparison
4682 #** @method scalar FID($id)
4684 # @brief Get or set the id of this feature.
4685 # @param id [optional] the id to set for this feature.
4686 # @return integer the id of this feature.
4690 $self->SetFID($_[0])
if @_;
4691 return unless defined wantarray;
4695 #** @method Field($name, $value, ...)
4697 # @brief Get, set, or unset the field value.
4698 # @param name the name (or the index) of the field.
4699 # @param value a scalar, a list of scalars or a reference to a
4700 # list. If undef, the field is unset. If a scalar or a list of
4701 # scalars, the field is set from them.
4702 # @note Non-scalar fields (for example Date) can be set either from a
4703 # scalar, which is then assumed to be a string and parsed, or from a
4704 # list of values (for example year, month, day for Date).
4705 # @note Setting and getting Integer64 fields requires 'use bigint' if
4706 # \$Config{ivsize} is smaller than 8, i.e., in a 32 bit machine.
4707 # @return in non-void context the value of the field, which may be a
4708 # scalar or a list, depending on the field type. For unset fields the
4709 # undef value is returned.
4713 my $field = $self->GetFieldIndex(shift
4714 $self->SetField($field, @_)
if @_;
4715 $self->GetField($field)
if defined wantarray;
4718 #** @method FillUnsetWithDefault()
4720 sub FillUnsetWithDefault {
4723 #** @method Geometry($name, $geometry)
4725 # @brief Get or set the value of a geometry field.
4726 # @note This method delivers the functionality of undocumented methods
4727 # SetGeometry($geometry), SetGeometryDirectly, SetGeomField,
4728 # SetGeomFieldDirectly, GetGeometry, GetGeometryRef.
4730 # Set or get the geometry in the feature. When setting, does a check
4731 # against the schema (GeometryType) of the feature. If the parameter
4732 # is a geometry object, it is cloned.
4733 # @param name [optional] the name of the spatial field,
4734 # whose geometry is to be set. If not given, sets or gets the geometry
4735 # of the first (or the single) spatial field.
4736 # @param geometry [optional] a Geo::OGR::Geometry object or a
4737 # reference to a hash from which such can be created (using
4738 # Geo::OGR::Geometry::new).
4739 # @return in a non-void context the indicated geometry in the feature
4740 # as a Geo::OGR::Geometry object. The returned object contains a
4741 # reference to the actual geometry data in the feature (the geometry
4742 # is not cloned) and to the feature object, thus keeping the feature
4743 # object from being destroyed while the geometry object exists.
4747 my $field = ((@_ > 0 and ref($_[0]) eq
'') or (@_ > 2 and @_ % 2 == 1)) ? shift : 0;
4748 $field = $self->GetGeomFieldIndex($field);
4750 if (@_ and @_ % 2 == 0) {
4756 my $type = $self->GetDefn->GetGeomFieldDefn($field)->Type;
4757 if (blessed($geometry) and $geometry->isa(
'Geo::OGR::Geometry')) {
4758 my $gtype = $geometry->GeometryType;
4759 error(
"The type of the inserted geometry ('$gtype') is not the same as the type of the field ('$type').")
4760 if $type ne
'Unknown' and $type ne $gtype;
4762 $self->SetGeomFieldDirectly($field, $geometry->Clone);
4764 confess last_error()
if $@;
4765 } elsif (ref($geometry) eq
'HASH') {
4766 $geometry->{GeometryType}
4770 confess last_error() if $@;
4771 my $gtype = $geometry->GeometryType;
4772 error("The type of the inserted geometry ('$gtype') is not the same as the type of the field ('$type').")
4773 if $type ne 'Unknown' and $type ne $gtype;
4775 $self->SetGeomFieldDirectly($field, $geometry);
4777 confess last_error() if $@;
4779 error(
"Usage: \$feature->Geometry([field],[geometry])");
4782 return unless defined wantarray;
4783 $geometry = $self->GetGeomFieldRef($field);
4784 return unless $geometry;
4785 keep($geometry, $self);
4788 #** @method Geo::OGR::FeatureDefn GetDefn()
4790 # @note A.k.a GetDefnRef.
4791 # @return a Geo::OGR::FeatureDefn object, which represents the definition of this feature.
4795 my $defn = $self->GetDefnRef;
4799 #** @method scalar GetFID()
4801 # @return the feature id (an integer).
4806 #** @method list GetField($name)
4811 my ($self, $field) = @_;
4812 $field = $self->GetFieldIndex($field);
4813 return unless IsFieldSet($self, $field);
4814 my $type = GetFieldType($self, $field);
4815 return GetFieldAsInteger($self, $field)
if $type == $Geo::OGR::OFTInteger;
4816 return GetFieldAsInteger64($self, $field)
if $type == $Geo::OGR::OFTInteger64;
4817 return GetFieldAsDouble($self, $field)
if $type == $Geo::OGR::OFTReal;
4818 return GetFieldAsString($self, $field)
if $type == $Geo::OGR::OFTString;
4819 if ($type == $Geo::OGR::OFTIntegerList) {
4820 my $ret = GetFieldAsIntegerList($self, $field);
4821 return wantarray ? @$ret : $ret;
4823 if ($type == $Geo::OGR::OFTInteger64List) {
4824 my $ret = GetFieldAsInteger64List($self, $field);
4825 return wantarray ? @$ret : $ret;
4827 if ($type == $Geo::OGR::OFTRealList) {
4828 my $ret = GetFieldAsDoubleList($self, $field);
4829 return wantarray ? @$ret : $ret;
4831 if ($type == $Geo::OGR::OFTStringList) {
4832 my $ret = GetFieldAsStringList($self, $field);
4833 return wantarray ? @$ret : $ret;
4835 if ($type == $Geo::OGR::OFTBinary) {
4836 return GetFieldAsBinary($self, $field);
4838 if ($type == $Geo::OGR::OFTDate) {
4839 my @ret = GetFieldAsDateTime($self, $field);
4840 # year, month, day, hour, minute, second, timezone
4841 return wantarray ? @ret[0..2] : [@ret[0..2]];
4843 if ($type == $Geo::OGR::OFTTime) {
4844 my @ret = GetFieldAsDateTime($self, $field);
4845 return wantarray ? @ret[3..6] : [@ret[3..6]];
4847 if ($type == $Geo::OGR::OFTDateTime) {
4848 my @ret = GetFieldAsDateTime($self, $field);
4849 return wantarray ? @ret : [@ret];
4851 error(
"Perl bindings do not support the field type '".i2s(field_type => $type).
"'.");
4854 #** @method scalar GetFieldDefn($name)
4856 # Get the definition of a field.
4857 # @param name the name of the field.
4858 # @return a Geo::OGR::FieldDefn object.
4862 my $field = $self->GetFieldIndex(shift);
4863 return $self->GetFieldDefnRef($field);
4866 #** @method list GetFieldNames()
4868 # Get the names of the fields in this feature.
4873 #** @method scalar GetGeomFieldDefn($name)
4875 # Get the definition of a spatial field.
4876 # @param name the name of the spatial field.
4877 # @return a Geo::OGR::GeomFieldDefn object.
4879 sub GetGeomFieldDefn {
4881 my $field = $self->GetGeomFieldIndex(shift);
4882 return $self->GetGeomFieldDefnRef($field);
4885 #** @method GetNativeData()
4890 #** @method GetNativeMediaType()
4892 sub GetNativeMediaType {
4895 #** @method hash reference GetSchema()
4897 # @brief Get the schema of this feature.
4899 # @return the schema as a hash whose keywords are Name, StyleIgnored
4900 # and Fields. Fields is an anonymous array of first non-spatial and
4901 # then spatial field schemas as in Geo::OGR::FieldDefn::Schema() and
4902 # Geo::OGR::GeomFieldDefn::Schema().
4906 error(
"Schema of a feature cannot be set directly.") if @_;
4907 return $self->GetDefnRef->Schema;
4910 #** @method scalar GetStyleString()
4914 sub GetStyleString {
4917 #** @method IsFieldNull()
4922 #** @method IsFieldSetAndNotNull()
4924 sub IsFieldSetAndNotNull {
4927 #** @method Geo::OGR::Layer Layer()
4929 # @return the layer to which this feature belongs to or undef.
4936 #** @method hash reference Row(%row)
4938 # @note This method discards the data the destination feature (or
4939 # layer) does not support. Changes in data due to differences between
4940 # field types may also occur.
4942 # Get and/or set the data of the feature. The key of the (key,value)
4943 # pairs of the row is the field name. Special field names FID and
4944 # Geometry are used for feature id and (single) geometry
4945 # respectively. The geometry/ies is/are set and get using the
4946 # Geo::OGR::Feature::Geometry method. Field values are set using the
4947 # Geo::OGR::Feature::Field method.
4948 # @param row [optional] feature data in a hash.
4949 # @return a reference to feature data in a hash. Spatial fields are
4950 # returned as Geo::OGR::Geometry objects.
4954 my $nf = $self->GetFieldCount;
4955 my $ngf = $self->GetGeomFieldCount;
4958 if (@_ == 1 and ref($_[0]) eq
'HASH') {
4960 } elsif (@_ and @_ % 2 == 0) {
4963 error(
'Usage: $feature->Row(%FeatureData).');
4965 $self->SetFID($row{FID})
if defined $row{FID};
4966 #$self->Geometry($schema, $row{Geometry}) if $row{Geometry};
4967 for my $name (keys %row) {
4968 next
if $name eq
'FID';
4969 if ($name eq
'Geometry') {
4970 $self->Geometry(0, $row{$name});
4974 for my $i (0..$nf-1) {
4975 if ($self->GetFieldDefnRef($i)->Name eq $name) {
4976 $self->SetField($i, $row{$name});
4982 for my $i (0..$ngf-1) {
4983 if ($self->GetGeomFieldDefnRef($i)->Name eq $name) {
4984 $self->Geometry($i, $row{$name});
4990 carp
"Unknown field: '$name'.";
4993 return unless defined wantarray;
4995 for my $i (0..$nf-1) {
4996 my $name = $self->GetFieldDefnRef($i)->Name;
4997 $row{$name} = $self->GetField($i);
4999 for my $i (0..$ngf-1) {
5000 my $name = $self->GetGeomFieldDefnRef($i)->Name ||
'Geometry';
5001 $row{$name} = $self->GetGeometry($i);
5003 $row{FID} = $self->GetFID;
5007 #** @method SetFID($id)
5009 # @param id the feature id.
5014 #** @method SetField($name, @Value)
5020 my $field = $self->GetFieldIndex(shift);
5022 if (@_ == 0 or !defined($arg)) {
5023 _UnsetField($self, $field);
5026 $arg = [@_]
if @_ > 1;
5027 my $type = $self->GetFieldType($field);
5029 if ($type == $Geo::OGR::OFTIntegerList) {
5030 SetFieldIntegerList($self, $field, $arg);
5032 elsif ($type == $Geo::OGR::OFTInteger64List) {
5033 SetFieldInteger64List($self, $field, $arg);
5035 elsif ($type == $Geo::OGR::OFTRealList) {
5036 SetFieldDoubleList($self, $field, $arg);
5038 elsif ($type == $Geo::OGR::OFTStringList) {
5039 SetFieldStringList($self, $field, $arg);
5041 elsif ($type == $Geo::OGR::OFTDate) {
5042 _SetField($self, $field, @$arg[0..2], 0, 0, 0, 0);
5044 elsif ($type == $Geo::OGR::OFTTime) {
5046 _SetField($self, $field, 0, 0, 0, @$arg[0..3]);
5048 elsif ($type == $Geo::OGR::OFTDateTime) {
5050 _SetField($self, $field, @$arg[0..6]);
5052 elsif ($type == $Geo::OGR::OFTInteger64)
5054 SetFieldInteger64($self, $field, $arg);
5057 $type = i2s(field_type => $type);
5058 my $name = $self->GetFieldDefnRef($field)->Name;
5059 error(
"'$arg' is not a suitable value for field $name($type).");
5062 if ($type == $Geo::OGR::OFTBinary) {
5063 #$arg = unpack('H*', $arg); # remove when SetFieldBinary is available
5064 $self->SetFieldBinary($field, $arg);
5066 elsif ($type == $Geo::OGR::OFTInteger64)
5068 SetFieldInteger64($self, $field, $arg);
5070 elsif ($type == $Geo::OGR::OFTInteger or $type == $Geo::OGR::OFTReal or $type == $Geo::OGR::OFTString)
5072 _SetField($self, $field, $arg);
5075 $type = i2s(field_type => $type);
5076 my $name = $self->GetFieldDefnRef($field)->Name;
5077 error(
"'$arg' is not a suitable value for field $name($type).");
5082 #** @method SetFieldNull()
5087 #** @method SetFrom($other, $forgiving = 1, hashref map)
5089 # @param other a Geo::OGR::Feature object
5090 # @param forgiving [optional] set to false if the operation should not
5091 # continue if output fields do not match some of the source fields
5092 # @param map [optional] a mapping from output field indexes to source
5093 # fields, include into the hash all field indexes of this feature
5094 # which should be set
5097 my($self, $other) = @_;
5098 _SetFrom($self, $other),
return if @_ <= 2;
5099 my $forgiving = $_[2];
5100 _SetFrom($self, $other, $forgiving),
return if @_ <= 3;
5103 for my $i (1..GetFieldCount($self)) {
5104 push @list, ($map->{$i} || -1);
5106 SetFromWithMap($self, $other, 1, \@list);
5109 #** @method SetNativeData()
5114 #** @method SetNativeMediaType()
5116 sub SetNativeMediaType {
5119 #** @method SetStyleString($string)
5123 sub SetStyleString {
5126 #** @method list Tuple(@tuple)
5128 # @note This method discards the data the destination feature (or
5129 # layer) does not support. Changes in data due to differences between
5130 # field types may also occur.
5132 # @note The schema of the tuple needs to be the same as that of the
5135 # Get and/set the data of the feature. The expected data in the tuple
5136 # is ([feature_id,] non-spatial fields, spatial fields). The fields in
5137 # the tuple are in the order they are in the schema. Field values are
5138 # set using the Geo::OGR::Feature::Field method. Geometries are set
5139 # and get using the Geo::OGR::Feature::Geometry method.
5140 # @param tuple [optional] feature data in an array
5141 # @return feature data in an array
5145 my $nf = $self->GetFieldCount;
5146 my $ngf = $self->GetGeomFieldCount;
5148 my $values = ref $_[0] ? $_[0] : \@_;
5150 $FID = shift @$values
if @$values == $nf + $ngf + 1;
5151 $self->SetFID($FID)
if defined $FID;
5152 if (@$values != $nf + $ngf) {
5154 error(
"Too many or too few attribute values for a feature (need $n).");
5156 my $index = 0; # index to non-geometry and geometry fields
5157 for my $i (0..$nf-1) {
5158 $self->SetField($i, $values->[$i]);
5160 for my $i (0..$ngf-1) {
5161 $self->Geometry($i, $values->[$nf+$i]);
5164 return unless defined wantarray;
5165 my @ret = ($self->GetFID);
5166 for my $i (0..$nf-1) {
5167 my $v = $self->GetField($i);
5170 for my $i (0..$ngf-1) {
5171 my $v = $self->GetGeometry($i);
5177 #** @method scalar Validate(list flags)
5179 # @param flags one of more of null, geom_type, width,
5180 # allow_null_when_default, or all.
5181 # @exception croaks with an error message if the feature is not valid.
5182 # @return integer denoting the validity of the feature object.
5188 my $f = eval
'$Geo::OGR::'.uc($flag);
5191 _Validate($self, $flags);
5194 #** @method Geo::OGR::Feature new(%schema)
5196 # @brief Create a new feature.
5197 # @param Named parameters:
5198 # - \a Schema a reference to a schema hash, or a Geo::OGR::Layer,
5199 # Geo::OGR::Feature, or Geo::OGR::FeatureDefn object.
5200 # - \a Values values for the feature attributes.
5201 # - \a StyleIgnored whether the style can be omitted when fetching
5202 # features. (default is false)
5204 # Schema is a hash with the following keys:
5205 # - \a Name name of the schema (not used).
5206 # - \a Fields a list of Geo::OGR::FieldDefn or Geo::OGR::GeomFieldDefn
5207 # objects or references to hashes from which fields can be created.
5208 # - \a GeometryType the geometry type if the feature has only one spatial field.
5210 # @note Do not mix GeometryType and geometry fields in Fields list.
5211 # @note Old syntax where the argument is a Geo::OGR::FeatureDefn
5212 # object or Schema hash is supported.
5214 # @return a new Geo::OGR::Feature object.
5220 if (ref $_[0] eq
'HASH' && $_[0]->{Schema}) {
5223 $arg = {Schema => $_[0]};
5225 } elsif (@_ and @_ % 2 == 0) {
5227 unless ($arg->{Schema}) {
5229 $arg->{Schema} = \%tmp;
5232 error(
"The argument must be either a schema or a hash.");
5234 error(
"Missing schema.") unless $arg->{Schema};
5236 for (ref $arg->{Schema}) {
5238 $defn = $arg->{Schema}->GetDefn;
5242 $defn = $arg->{Schema};
5247 my $self = Geo::OGRc::new_Feature($defn);
5248 error(
"Feature creation failed.") unless $self;
5250 for (ref $arg->{Values}) {
5252 $self->Tuple($arg->{Values});
5256 $self->Row($arg->{Values});
5260 $self->
Tuple($arg->{Values}->Tuple);
5266 error(
"Value parameter must be an array, hash, or another feature. Not $_.");
5271 #** @class Geo::OGR::FeatureDefn
5272 # @brief The schema of a feature or a layer.
5273 # @details A FeatureDefn object is a collection of field definition objects. A
5274 # read-only FeatureDefn object can be obtained from a layer
5275 # (Geo::OGR::Layer::GetDefn()) or a feature
5276 # (Geo::OGR::Feature::GetDefn()).
5278 package Geo::OGR::FeatureDefn;
5282 #** @method AddField(%params)
5284 # @param params Named parameters to create a new Geo::OGR::FieldDefn
5285 # or Geo::OGR::GeomFieldDefn object.
5289 error(
"Read-only definition.")
if parent($self);
5292 } elsif (ref($_[0]) eq
'HASH') {
5294 } elsif (@_ % 2 == 0) {
5298 if (s_exists(field_type => $params{Type})) {
5300 $self->AddFieldDefn($fd);
5303 $self->AddGeomFieldDefn($fd);
5307 #** @method DeleteField($name)
5309 # @note Currently only geometry fields can be deleted.
5310 # @param index the index of the geometry field to be deleted.
5313 my ($self, $name) = @_;
5314 error(
"Read-only definition.")
if parent($self);
5315 for my $i (0..$self->GetFieldCount-1) {
5316 error(
"Non-spatial fields cannot be deleted.")
if $self->_GetFieldDefn($i)->Name eq $name;
5318 for my $i (0..$self->GetGeomFieldCount-1) {
5319 $self->DeleteGeomFieldDefn($i)
if $self->_GetGeomFieldDefn($i)->Name eq $name;
5321 error(2, $name,
'Field');
5324 #** @method Feature()
5328 return parent($self);
5331 #** @method scalar GetFieldDefn($name)
5333 # Get the definition of a field.
5334 # @param name the name of the field.
5335 # @return a Geo::OGR::FieldDefn object.
5339 my $field = $self->GetFieldIndex(shift);
5340 return $self->_GetFieldDefn($field);
5343 #** @method list GetFieldNames()
5345 # The names of the fields in this layer or feature definition.
5346 # @return the list of field names.
5351 for my $i (0..$self->GetFieldCount-1) {
5352 push @names, $self->_GetFieldDefn($i)->Name;
5354 for my $i (0..$self->GetGeomFieldCount-1) {
5355 push @names, $self->_GetGeomFieldDefn($i)->Name;
5360 #** @method scalar GetGeomFieldDefn($name)
5362 # Get the definition of a spatial field.
5363 # @param name the name of the spatial field.
5364 # @return a Geo::OGR::GeomFieldDefn object.
5366 sub GetGeomFieldDefn {
5368 my $field = $self->GetGeomFieldIndex(shift);
5369 return $self->_GetGeomFieldDefn($field);
5372 #** @method scalar GetName()
5374 # @return the name of this layer or feature definition.
5379 #** @method hash reference GetSchema()
5381 # @brief Get the schema of this feature or layer definition.
5383 # @return the schema as a hash whose keywords are Name, StyleIgnored
5384 # and Fields. Fields is an anonymous array of first non-spatial and
5385 # then spatial field schemas as in Geo::OGR::FieldDefn::Schema() and
5386 # Geo::OGR::GeomFieldDefn::Schema().
5390 carp
"Schema of a feature definition should not be set directly." if @_;
5391 if (@_ and @_ % 2 == 0) {
5393 if ($schema{Fields}) {
5394 for my $field (@{$schema{Fields}}) {
5395 $self->AddField($field);
5400 $schema{Name} = $self->Name();
5401 $schema{StyleIgnored} = $self->StyleIgnored();
5402 $schema{Fields} = [];
5403 for my $i (0..$self->GetFieldCount-1) {
5404 my $s = $self->_GetFieldDefn($i)->Schema;
5405 push @{$schema{Fields}}, $s;
5407 for my $i (0..$self->GetGeomFieldCount-1) {
5408 my $s = $self->_GetGeomFieldDefn($i)->Schema;
5409 push @{$schema{Fields}}, $s;
5411 return wantarray ? %schema : \%schema;
5414 #** @method IsSame(Geo::OGR::FeatureDefn defn)
5416 # @return true if this definition is similar to the other definition,
5422 #** @method scalar IsStyleIgnored()
5424 # Get the ignore status of style information when fetching features.
5425 # @return the ignore status of style information
5428 sub IsStyleIgnored {
5431 #** @method SetStyleIgnored($IgnoreState)
5433 # Set the ignore status of style information when fetching features.
5436 sub SetStyleIgnored {
5439 #** @method Geo::OGR::FeatureDefn new(%schema)
5441 # Creates a new layer or feature definition. The new definition is
5442 # either initialized to the given schema or it will contain no
5443 # non-spatial fields and one spatial field, whose Name is '' and
5444 # GeometryType is 'Unknown' or the value of the named parameter
5446 # @param schema [optional] The schema for the new feature definition,
5447 # as in Geo::OGR::FeatureDefn::Schema().
5448 # @return a Geo::OGR::FeatureDefn object
5452 # $fd = Geo::OGR::FeatureDefn->new(
5454 # Fields => [{ Name => 'field1', Type => 'String' },
5455 # { Name => 'geom', GeometryType => 'Point' }] );
5461 if (@_ == 1 and ref($_[0]) eq
'HASH') {
5463 } elsif (@_ and @_ % 2 == 0) {
5466 my $fields = $schema{Fields};
5467 error(
"The 'Fields' argument must be an array reference.") if $fields and ref($fields) ne 'ARRAY';
5469 my $self = Geo::OGRc::new_FeatureDefn($schema{Name});
5471 my $gt = $schema{GeometryType};
5473 $self->GeometryType($gt);
5475 $self->DeleteGeomFieldDefn(0);
5477 $self->StyleIgnored($schema{StyleIgnored})
if exists $schema{StyleIgnored};
5478 for my $fd (@{$fields}) {
5480 if (ref($fd) eq
'HASH') {
5481 # if Name and Type are missing, assume Name => Type
5482 if (!(exists $fd->{Name} && exists $fd->{Type})) {
5483 for my $key (sort keys %$fd) {
5484 if (s_exists(field_type => $fd->{$key}) ||
5485 s_exists(geometry_type => $fd->{$key}))
5488 $fd->{Type} = $fd->{$key};
5494 if ($fd->{GeometryType} or ($fd->{Type} && s_exists(geometry_type => $fd->{Type}))) {
5500 if (blessed($d) and $d->isa(
'Geo::OGR::FieldDefn')) {
5501 AddFieldDefn($self, $d);
5502 } elsif (blessed($d) and $d->isa(
'Geo::OGR::GeomFieldDefn')) {
5503 error(
"Do not mix GeometryType and geometry fields in Fields.") if $gt;
5504 AddGeomFieldDefn($self, $d);
5506 error(
"Item in field list does not define a field.");
5512 #** @class Geo::OGR::FieldDefn
5513 # @brief A definition of a non-spatial attribute.
5516 package Geo::OGR::FieldDefn;
5520 #** @method scalar Default($value)
5522 # Get or set the default value for this field.
5523 # @note a.k.a. GetDefault and SetDefault
5524 # @param value [optional]
5525 # @return the default value of this field in non-void context.
5529 SetDefault($self, $_[0])
if @_;
5530 GetDefault($self)
if defined wantarray;
5533 #** @method GetSchema()
5538 #** @method scalar Ignored($ignore)
5540 # Get and/or set the ignore status (whether this field should be
5541 # omitted when fetching features) of this field.
5542 # @note a.k.a. IsIgnored, SetIgnored
5543 # @param ignore [optional]
5544 # @return the ignore status of this field in non-void context.
5549 SetIgnored($self, $_[0])
if @_;
5550 IsIgnored($self)
if defined wantarray;
5553 #** @method IsDefaultDriverSpecific()
5555 sub IsDefaultDriverSpecific {
5558 #** @method scalar Justify($justify)
5560 # Get and/or set the justification of this field.
5561 # @note a.k.a. GetJustify, SetJustify
5562 # @param justify [optional] One of field justify types (Geo::OGR::FieldDefn::JustifyValues).
5563 # @return the justify value of this field in non-void context.
5566 my($self, $justify) = @_;
5567 if (defined $justify) {
5568 $justify = s2i(justify => $justify);
5569 SetJustify($self, $justify);
5571 return i2s(justify => GetJustify($self))
if defined wantarray;
5574 #** @method list JustifyValues()
5575 # Package subroutine.
5576 # Justify values supported by GDAL. Current list is
5577 # Left, Right, and Undefined.
5583 #** @method scalar Name($name)
5585 # Get and/or set the name of the field.
5586 # @note a.k.a. GetName, GetNameRef, SetName
5587 # @param name [optional]
5588 # @return the name in non-void context
5592 SetName($self, $_[0])
if @_;
5593 GetName($self)
if defined wantarray;
5596 #** @method scalar Nullable($nullable)
5598 # Get or set the nullable constraint for this field.
5599 # @note a.k.a. IsNullable and SetNullable
5600 # @param nullable [optional]
5601 # @return the nullable value of this field in non-void context.
5605 SetNullable($self, $_[0])
if @_;
5606 IsNullable($self)
if defined wantarray;
5609 #** @method scalar Precision($precision)
5611 # Get and/or set the precision of this field.
5612 # @note a.k.a. GetPrecision, SetPrecision
5613 # @param precision [optional]
5614 # @return the precision of this field in non-void context.
5618 SetPrecision($self, $_[0])
if @_;
5619 GetPrecision($self)
if defined wantarray;
5622 #** @method hash reference Schema(%params)
5624 # Get the schema or set parts of the schema
5625 # @param params [optional] as those in Geo::OGR::FieldDefn::new.
5626 # @return a reference to a hash whose keys are as those in Geo::OGR::FieldDefn::new.
5631 my $params = @_ % 2 == 0 ? {@_} : shift;
5632 for my $key (keys %SCHEMA_KEYS) {
5633 next unless exists $params->{$key};
5634 eval
"\$self->$key(\$params->{$key})";
5635 confess(last_error()) if $@;
5638 return unless defined wantarray;
5640 for my $key (keys %SCHEMA_KEYS) {
5641 $schema{$key} = eval
'$self->'.$key;
5643 return wantarray ? %schema : \%schema;
5646 #** @method SetSchema()
5651 #** @method scalar SubType($SubType)
5653 # @note a.k.a. GetSubType, SetSubType
5654 # @param SubType [optional] One of field sub types (Geo::OGR::FieldDefn::SubTypes).
5655 # @return the sub type of this field in non-void context.
5658 my($self, $subtype) = @_;
5659 if (defined $subtype) {
5660 $subtype = s2i(field_subtype => $subtype);
5661 SetSubType($self, $subtype);
5663 return i2s(field_subtype => GetSubType($self))
if defined wantarray;
5666 #** @method SubTypes()
5672 #** @method scalar Type($type)
5674 # Get and/or set the type of the field.
5675 # @note a.k.a. GetFieldTypeName, GetTypeName, GetType, SetType
5676 # @param type [optional] One of field types (Geo::OGR::FieldDefn::Types).
5677 # @return one of field types in non-void context.
5680 my($self, $type) = @_;
5681 if (defined $type) {
5682 $type = s2i(field_type => $type);
5683 SetType($self, $type);
5685 return i2s(field_type => GetType($self))
if defined wantarray;
5688 #** @method list Types()
5689 # Package subroutine.
5690 # Field types supported by GDAL. Current list is
5691 # Binary, Date, DateTime, Integer, Integer64, Integer64List, IntegerList, Real, RealList, String, StringList, Time, WideString, and WideStringList.
5692 # (However, WideString is not supported.)
5698 #** @method scalar Width($width)
5700 # Get and/or set the field width.
5701 # @note a.k.a. GetWidth, SetWidth
5702 # @param width [optional]
5703 # @return the width of this field in non-void context.
5707 SetWidth($self, $_[0])
if @_;
5708 GetWidth($self)
if defined wantarray;
5711 #** @method Geo::OGR::FieldDefn new(%params)
5713 # @brief Create a new field definition.
5715 # @param Named parameters:
5716 # - \a Name Field name (default is 'unnamed').
5717 # - \a Type Field type, one of Geo::OGR::FieldDefn::Types (default is 'String').
5718 # - \a SubType Field sub type, one of Geo::OGR::FieldDefn::SubTypes.
5719 # - \a Justify Justify value, one of Geo::OGR::FieldDefn::JustifyValues
5722 # - \a Nullable (default is true)
5724 # - \a Ignored (default is false)
5726 # @note Simplified parameters Name => 'Type' are also supported.
5728 # @return a new Geo::OGR::FieldDefn object
5732 my $params = {Name =>
'unnamed', Type =>
'String'};
5734 } elsif (@_ == 1 and not ref $_[0]) {
5735 $params->{Name} = shift;
5736 } elsif (@_ == 2 and not $Geo::OGR::FieldDefn::SCHEMA_KEYS{$_[0]}) {
5737 $params->{Name} = shift;
5738 $params->{Type} = shift;
5740 my $tmp = @_ % 2 == 0 ? {@_} : shift;
5741 for my $key (keys %$tmp) {
5742 if ($Geo::OGR::FieldDefn::SCHEMA_KEYS{$key}) {
5743 $params->{$key} = $tmp->{$key};
5745 carp
"Unknown parameter: '$key'." if $key ne
'Index';
5749 $params->{Type} = s2i(field_type => $params->{Type});
5750 my $self = Geo::OGRc::new_FieldDefn($params->{Name}, $params->{Type});
5752 delete $params->{Name};
5753 delete $params->{Type};
5754 $self->Schema($params);
5758 #** @class Geo::OGR::GeomFieldDefn
5759 # @brief A definition of a spatial attribute.
5762 package Geo::OGR::GeomFieldDefn;
5766 #** @method scalar GeometryType($type)
5768 # @note a.k.a. GetType, SetType
5769 # @return the geometry type of the field.
5774 #** @method GetSchema()
5779 #** @method scalar Ignored($ignore)
5781 # @note a.k.a. IsIgnored, SetIgnored
5782 # @return the ignore status of the field.
5786 SetIgnored($self, $_[0])
if @_;
5787 IsIgnored($self)
if defined wantarray;
5790 #** @method scalar Name($name)
5792 # @note a.k.a. GetName, GetNameRef, SetName
5793 # @return the name of the field.
5797 SetName($self, $_[0])
if @_;
5798 GetName($self)
if defined wantarray;
5801 #** @method scalar Nullable($nullable)
5803 # @note a.k.a. IsNullable, SetNullable
5804 # @return the nullable status of the field.
5808 SetNullable($self, $_[0])
if @_;
5809 IsNullable($self)
if defined wantarray;
5812 #** @method hash reference Schema(%params)
5814 # Get the schema or set parts of the schema.
5815 # @param params [optional] as those in Geo::OGR::GeomFieldDefn::new.
5816 # @return a reference to a hash whose keys are as those in Geo::OGR::GeomFieldDefn::new.
5821 my $params = @_ % 2 == 0 ? {@_} : shift;
5822 for my $key (keys %SCHEMA_KEYS) {
5823 next unless exists $params->{$key};
5824 eval
"\$self->$key(\$params->{$key})";
5825 confess last_error()
if $@;
5828 return unless defined wantarray;
5830 for my $key (keys %SCHEMA_KEYS) {
5831 $schema{$key} = eval
'$self->'.$key;
5833 return wantarray ? %schema : \%schema;
5836 #** @method SetSchema()
5841 #** @method scalar SpatialReference($sr)
5843 # @note a.k.a. GetSpatialRef, SetSpatialRef
5844 # @return the spatial reference of the field as a Geo::OSR::SpatialReference object.
5846 sub SpatialReference {
5848 SetSpatialRef($self, $_[0])
if @_;
5849 GetSpatialRef($self)
if defined wantarray;
5854 # @return the type of this geometry field. One of Geo::OGR::GeomFieldDefn::Types
5857 my($self, $type) = @_;
5858 if (defined $type) {
5859 $type = s2i(geometry_type => $type);
5860 SetType($self, $type);
5862 i2s(geometry_type => GetType($self))
if defined wantarray;
5866 # Package subroutine.
5867 # @return a list of all geometry types, currently:
5868 # CircularString, CircularStringM, CircularStringZ, CircularStringZM, CompoundCurve, CompoundCurveM, CompoundCurveZ, CompoundCurveZM, Curve, CurveM, CurvePolygon, CurvePolygonM, CurvePolygonZ, CurvePolygonZM, CurveZ, CurveZM, GeometryCollection, GeometryCollection25D, GeometryCollectionM, GeometryCollectionZM, LineString, LineString25D, LineStringM, LineStringZM, LinearRing, MultiCurve, MultiCurveM, MultiCurveZ, MultiCurveZM, MultiLineString, MultiLineString25D, MultiLineStringM, MultiLineStringZM, MultiPoint, MultiPoint25D, MultiPointM, MultiPointZM, MultiPolygon, MultiPolygon25D, MultiPolygonM, MultiPolygonZM, MultiSurface, MultiSurfaceM, MultiSurfaceZ, MultiSurfaceZM, None, Point, Point25D, PointM, PointZM, Polygon, Polygon25D, PolygonM, PolygonZM, PolyhedralSurface, PolyhedralSurfaceM, PolyhedralSurfaceZ, PolyhedralSurfaceZM, Surface, SurfaceM, SurfaceZ, SurfaceZM, TIN, TINM, TINZ, TINZM, Triangle, TriangleM, TriangleZ, TriangleZM, and Unknown.
5874 #** @method Geo::OGR::GeomFieldDefn new(%params)
5876 # @brief Create a new spatial field definition.
5878 # @param params one or more of:
5879 # - \a Name name for the field (default is 'geom').
5880 # - \a GeometryType type for the field type, one of Geo::OGR::GeomFieldDefn::Types (default is 'Unknown').
5881 # - \a SpatialReference a Geo::OSR::SpatialReference object.
5882 # - \a Nullable (default is true)
5883 # - \a Ignored (default is false)
5885 # @note Simplified parameters <name> => <type> is also supported.
5887 # @return a new Geo::OGR::GeomFieldDefn object
5891 my $params = {Name =>
'geom', Type =>
'Unknown'};
5894 $params->{Name} = shift;
5895 } elsif (@_ == 2 and not $Geo::OGR::GeomFieldDefn::SCHEMA_KEYS{$_[0]}) {
5896 $params->{Name} = shift;
5897 $params->{Type} = shift;
5899 my $tmp = @_ % 2 == 0 ? {@_} : shift;
5900 for my $key (keys %$tmp) {
5901 if ($Geo::OGR::GeomFieldDefn::SCHEMA_KEYS{$key}) {
5902 $params->{$key} = $tmp->{$key};
5904 carp
"Unknown parameter: '$key'." if $key ne
'Index' && $key ne
'GeometryType';
5909 $params->{Type} = s2i(geometry_type => $params->{Type});
5910 my $self = Geo::OGRc::new_GeomFieldDefn($params->{Name}, $params->{Type});
5912 delete $params->{Name};
5913 delete $params->{Type};
5914 $self->Schema($params);
5918 #** @class Geo::OGR::GeomTransformer
5920 package Geo::OGR::GeomTransformer;
5924 #** @method Transform()
5933 my $self = Geo::OGRc::new_GeomTransformer(@_);
5934 bless $self, $pkg
if defined($self);
5937 #** @class Geo::OGR::Geometry
5938 # @brief Spatial data.
5939 # @details A geometry is spatial data (coordinate values, and a reference to a
5940 # spatial reference system) organized into one of the geometry
5941 # types. Geometries can be created from several type of data including
5942 # a Perl data structure. There are several methods, which modify,
5943 # compare, test, or compute values from geometries.
5944 # @note Most spatial analysis methods require <a
5945 # href="http://geos.osgeo.org/doxygen/">GEOS</a> to work rigorously.
5947 package Geo::OGR::Geometry;
5951 #** @method AddGeometry($other)
5953 # Add a copy of another geometry to a geometry collection
5954 # @param other a Geo::OGR::Geometry object
5959 #** @method AddGeometryDirectly($other)
5961 # @param other a Geo::OGR::Geometry object
5963 sub AddGeometryDirectly {
5966 #** @method AddPoint($x, $y, $z)
5968 # Set the data of a point or add a point to a line string. Consider
5969 # using Geo::OGR::Geometry::Points. Note that the coordinate
5970 # dimension is automatically upgraded to 25D (3) if z is given.
5973 # @param z [optional]
5974 # Calls internally the 2D or 3D version depending on the number of parameters.
5978 my $t = $self->GetGeometryType;
5979 my $has_z = HasZ($t);
5980 my $has_m = HasM($t);
5981 if (!$has_z && !$has_m) {
5982 $self->AddPoint_2D(@_[0..1]);
5983 } elsif ($has_z && !$has_m) {
5984 $self->AddPoint_3D(@_[0..2]);
5985 } elsif (!$has_z && $has_m) {
5986 $self->AddPointM(@_[0..2]);
5988 $self->AddPointZM(@_[0..3]);
5992 #** @method AddPointM()
5997 #** @method AddPointZM()
6002 #** @method AddPoint_2D($x, $y)
6004 # Set the data of a point or add a point to a line string. Consider
6005 # using Geo::OGR::Geometry::Points.
6012 #** @method AddPoint_3D($x, $y, $z)
6014 # Set the data of a point or add a point to a line string. Note that
6015 # the coordinate dimension is automatically upgraded to 25D (3). Consider
6016 # using Geo::OGR::Geometry::Points.
6024 #** @method Geo::OGR::Geometry ApproximateArcAngles(%params)
6025 # Package subroutine.
6026 # Create a line string, which approximates an arc.
6027 # @note All angles are in degrees.
6029 # @param %params Named parameters:
6030 # - \a Center center point (default is [0, 0, 0])
6031 # - \a PrimaryRadius default is 1.
6032 # - \a SecondaryAxis default is 1.
6033 # - \a Rotation default is 0.
6034 # - \a StartAngle default is 0.
6035 # - \a EndAngle default is 360.
6036 # - \a MaxAngleStepSizeDegrees default is 4.
6037 # @return a new Geo::OGR::Geometry object.
6039 sub ApproximateArcAngles {
6041 my %
default = ( Center => [0,0,0],
6047 MaxAngleStepSizeDegrees => 4
6049 for my $p (keys %p) {
6050 if (exists $default{$p}) {
6053 carp
"Unknown parameter: '$p'.";
6056 for my $p (keys %
default) {
6059 error(
"Usage: Center => [x,y,z].") unless ref($p{Center}) eq
'ARRAY';
6063 return Geo::OGR::ApproximateArcAngles($p{Center}->[0], $p{Center}->[1], $p{Center}->[2], $p{PrimaryRadius}, $p{SecondaryAxis}, $p{Rotation}, $p{StartAngle}, $p{EndAngle}, $p{MaxAngleStepSizeDegrees});
6066 #** @method scalar Area()
6068 # @note a.k.a. GetArea
6069 # @return the area of the polygon or multipolygon
6074 #** @method scalar As(%params)
6076 # Export the geometry into a known format.
6078 # @param params Named parameters:
6079 # - \a Format One of
6080 # - \a WKT Well Known Text.
6081 # - <em>ISO WKT</em>
6082 # - \a Text Same as WKT.
6083 # - \a WKB Well Known Binary.
6084 # - <em>ISO WKB</em>
6085 # - \a Binary Same as WKB.
6090 # - \a ByteOrder Byte order for binary formats. Default is 'XDR'.
6091 # - \a SRID Spatial reference id for HEXEWKB.
6092 # - \a Options GML generation options.
6093 # - \a AltitudeMode For KML.
6095 # @return the geometry in a given format.
6099 my $p = named_parameters(\@_, Format => undef, ByteOrder =>
'XDR', SRID => undef, Options => undef, AltitudeMode => undef);
6100 my $f = $p->{format};
6101 if ($f =~ /text/i) {
6102 return $self->AsText;
6103 } elsif ($f =~ /wkt/i) {
6105 return $self->ExportToIsoWkt;
6107 return $self->AsText;
6109 } elsif ($f =~ /binary/i) {
6110 return $self->ExportToWkb($p->{byteorder});
6111 } elsif ($f =~ /wkb/i) {
6113 $p->{byteorder} = s2i(byte_order => $p->{byteorder});
6114 return $self->ExportToIsoWkb($p->{byteorder});
6115 } elsif ($f =~ /ewkb/i) {
6116 return $self->AsHEXEWKB($p->{srid});
6117 } elsif ($f =~ /hex/i) {
6118 return $self->AsHEXWKB;
6120 return $self->ExportToWkb($p->{byteorder});
6122 } elsif ($f =~ /gml/i) {
6123 return $self->ExportToGML($p->{options});
6124 } elsif ($f =~ /kml/i) {
6125 return $self->ExportToKML($p->{altitudemode});
6126 } elsif ($f =~ /json/i) {
6127 return $self->AsJSON;
6129 error(1, $f, map {$_=>1} qw/Text WKT ISO_WKT ISO_WKB HEX_WKB HEX_EWKB Binary GML KML JSON/);
6133 #** @method scalar AsBinary()
6135 # Export the geometry into WKB.
6136 # @sa Geo::OGR::Geometry::As
6137 # @return the geometry as WKB.
6142 #** @method scalar AsText()
6144 # Export the geometry into WKT.
6145 # @sa Geo::OGR::Geometry::As
6146 # @return the geometry as WKT.
6151 #** @method AssignSpatialReference($srs)
6153 # @param srs a Geo::OSR::SpatialReference object
6155 sub AssignSpatialReference {
6158 #** @method Geo::OGR::Geometry Boundary()
6160 # @note a.k.a. GetBoundary
6161 # @return the boundary of this geometry as a geometry
6167 #** @method Geo::OGR::Geometry Buffer($distance, $quadsecs = 30)
6171 # @return a new Geo::OGR::Geometry object
6176 #** @method Geo::OGR::Geometry BuildPolygonFromEdges($BestEffort = 0, $AutoClose = 0, $Tolerance = 0)
6178 # Attempt to create a polygon from a collection of lines or from a multilinestring.
6179 # @param BestEffort For future
6180 # @param AutoClose Assure the first and last points of rings are same.
6181 # @param Tolerance Snap distance.
6182 # @exception Several possibilities, some are reported, some are general errors.
6183 # @return a new Geo::OGR::Geometry object (Polygon)
6185 sub BuildPolygonFromEdges {
6188 #** @method list ByteOrders()
6189 # Package subroutine.
6190 # Same as Geo::OGR::ByteOrders
6193 return @BYTE_ORDER_TYPES;
6196 #** @method Geo::OGR::Geometry Centroid()
6198 # @return a new Geo::OGR::Geometry object
6204 #** @method Geo::OGR::Geometry Clone()
6206 # @return a new Geo::OGR::Geometry object
6211 #** @method CloseRings()
6217 #** @method Geo::OGR::Geometry Collect(@geometries)
6219 # Create a geometrycollection from this and possibly other geometries.
6220 # @param geometries [optional] More geometries to add to the collection.
6221 # @return a new Geo::OGR::Geometry object of type geometrycollection.
6226 #** @method scalar Contains($other)
6228 # @param other a Geo::OGR::Geometry object
6229 # @return true if this geometry contains the other geometry, false otherwise
6234 #** @method Geo::OGR::Geometry ConvexHull()
6236 # @return a new Geo::OGR::Geometry object
6241 #** @method scalar CoordinateDimension($dimension)
6243 # @param dimension [optional]
6246 sub CoordinateDimension {
6248 SetCoordinateDimension($self, $_[0])
if @_;
6249 GetCoordinateDimension($self)
if defined wantarray;
6252 #** @method scalar Crosses($other)
6254 # @param other a Geo::OGR::Geometry object
6255 # @return true if this geometry crosses the other geometry, false otherwise
6260 #** @method DelaunayTriangulation()
6262 sub DelaunayTriangulation {
6265 #** @method Geo::OGR::Geometry Difference($other)
6267 # @param other a Geo::OGR::Geometry object
6268 # @return a new Geo::OGR::Geometry object
6273 #** @method scalar Disjoint($other)
6275 # @param other a Geo::OGR::Geometry object
6276 # @return true if this geometry is disjoint from the other geometry, false otherwise
6281 #** @method list Dissolve()
6283 # Dissolve a geometrycollection into separate geometries.
6284 # @return a list of new Geo::OGR::Geometry objects cloned from the collection.
6289 my $n = $self->GetGeometryCount;
6291 for my $i (0..$n-1) {
6292 push @c, $self->GetGeometryRef($i)->Clone;
6300 #** @method scalar Distance($other)
6302 # @param other a Geo::OGR::Geometry object
6303 # @return the distance to the other geometry
6308 #** @method Distance3D()
6315 # Clear geometry data, i.e., remove all points, or, for a point, set
6316 # the coordinate dimension as zero.
6321 #** @method scalar Equals($other)
6323 # @note a.k.a. Equal (deprecated)
6324 # @param other a Geo::OGR::Geometry object
6325 # @return true if this geometry is equivalent to the other geometry, false otherwise
6330 #** @method Extent()
6337 #** @method Feature()
6344 #** @method FlattenTo2D()
6350 #** @method Geo::OGR::Geometry ForceTo($type, ref options)
6352 # Attempt to make a geometry of type 'type' out of this geometry.
6353 # @param type target geometry type. One of Geo::OGR::GeometryTypes.
6354 # @param options not used currently.
6355 # @return a new Geo::OGR::Geometry object.
6360 $type = s2i(geometry_type => $type);
6362 $self = Geo::OGR::ForceTo($self, $type, @_);
6364 confess last_error() if $@;
6368 #** @method Geo::OGR::Geometry ForceToCollection(@geometries)
6370 # Create a geometrycollection from the geometry.
6371 # @param geometries [optional] More geometries to add to the collection.
6372 # @return a new Geo::OGR::Geometry object of type geometrycollection.
6374 sub ForceToCollection {
6382 #** @method Geo::OGR::Geometry ForceToLineString()
6384 # Attempt to create a line string from this geometry.
6385 # @return a new Geo::OGR::Geometry object.
6387 sub ForceToLineString {
6389 return Geo::OGR::ForceToLineString($self);
6392 #** @method Geo::OGR::Geometry ForceToMultiLineString(@linestrings)
6394 # Attempt to create a multilinestring from the geometry, which must be a linestring.
6395 # @param linestrings [optional] More linestrings to add to the collection.
6396 # @return a new Geo::OGR::Geometry object of type multilinestring.
6398 sub ForceToMultiLineString {
6400 $self = Geo::OGR::ForceToMultiLineString($self);
6402 $self->AddGeometry($g);
6407 #** @method Geo::OGR::Geometry ForceToMultiPoint(@points)
6409 # Attempt to create a multipoint from the geometry, which must be a point.
6410 # @param points [optional] More points to add to the collection.
6411 # @return a new Geo::OGR::Geometry object of type multipoint.
6413 sub ForceToMultiPoint {
6415 $self = Geo::OGR::ForceToMultiPoint($self);
6417 $self->AddGeometry($g);
6422 #** @method Geo::OGR::Geometry ForceToMultiPolygon(@polygons)
6424 # Attempt to create a multipolygon from the geometry, which must be a polygon.
6425 # @param polygons [optional] More polygons to add to the collection.
6426 # @return a new Geo::OGR::Geometry object of type multipolygon.
6428 sub ForceToMultiPolygon {
6430 $self = Geo::OGR::ForceToMultiPolygon($self);
6432 $self->AddGeometry($g);
6437 #** @method Geo::OGR::Geometry ForceToPolygon()
6439 # Attempt to create a polygon from this geometry.
6440 # @exception None reported. If this method fails, just a copy is returned.
6441 # @return a new Geo::OGR::Geometry object.
6443 sub ForceToPolygon {
6446 #** @method scalar Geometry($n)
6448 # Return the n:th (note zero-based index) element in this geometry or
6449 # geometry in this collection.
6450 # @note a.k.a. GetGeometryRef
6451 # @param n index to the geometry, which is a part of this geometry
6452 # @return a new Geo::OGR::Geometry object whose data is a part of the
6453 # parent geometry (this geometry is kept alive while the returned
6459 #** @method scalar GeometryCount()
6461 # Return the number of elements in this geometry or geometries in this collection.
6462 # @note a.k.a. GetGeometryCount
6463 # @return an integer
6468 #** @method scalar GeometryType()
6471 # @note The deprecated method GetGeometryType returns the
6472 # type as an integer
6474 # @return the geometry type of this geometry (one of Geo::OGR::GeometryTypes).
6478 return i2s(geometry_type => $self->GetGeometryType);
6481 #** @method list GeometryTypes()
6482 # Package subroutine.
6483 # Same as Geo::OGR::GeometryTypes
6486 return @GEOMETRY_TYPES;
6489 #** @method scalar GetCoordinateDimension()
6491 # @return an integer
6493 sub GetCoordinateDimension {
6496 #** @method GetCurveGeometry()
6498 sub GetCurveGeometry {
6501 #** @method scalar GetDimension()
6503 # @return 0, 1, or 2
6508 #** @method list GetEnvelope()
6510 # @note In scalar context returns a reference to an anonymous array
6511 # containing the envelope.
6512 # @return the envelope ($minx, $maxx, $miny, $maxy)
6517 #** @method list GetEnvelope3D()
6519 # @note In scalar context returns a reference to an anonymous array
6520 # containing the envelope.
6521 # @return the 3-D envelope ($minx, $maxx, $miny, $maxy, $minz, $maxz)
6527 #** @method scalar GetGeometryRef($index)
6529 # @deprecated Use Geo::OGR::Geometry
6531 sub GetGeometryRef {
6532 my ($self, $i) = @_;
6533 my $ref = $self->_GetGeometryRef($i);
6538 #** @method GetLinearGeometry()
6540 sub GetLinearGeometry {
6548 #** @method list GetPoint($index = 0)
6551 # @return (x,y) or a list with more coordinates
6556 my $t = $self->GetGeometryType;
6557 my $has_z = HasZ($t);
6558 my $has_m = HasM($t);
6560 if (!$has_z && !$has_m) {
6561 $point = $self->GetPoint_2D($i);
6562 } elsif ($has_z && !$has_m) {
6563 $point = $self->GetPoint_3D($i);
6564 } elsif (!$has_z && $has_m) {
6565 $point = $self->GetPointZM($i);
6566 @$point = ($point->[0], $point->[1], $point->[3]);
6568 $point = $self->GetPointZM($i);
6570 return wantarray ? @$point : $point;
6573 #** @method scalar GetPointCount()
6575 # @return an integer
6580 #** @method GetPointZM()
6585 #** @method scalar GetPoint_2D($index = 0)
6588 # @return (x,y) or a list with more coordinates
6593 #** @method scalar GetPoint_3D($index = 0)
6596 # @return (x,y) or a list with more coordinates
6601 #** @method Geo::OSR::SpatialReference GetSpatialReference()
6603 # @return a new Geo::OSR::SpatialReference object
6605 sub GetSpatialReference {
6608 #** @method scalar GetX($index = 0)
6616 #** @method scalar GetY($index = 0)
6624 #** @method scalar GetZ($index = 0)
6632 #** @method HasCurveGeometry()
6634 sub HasCurveGeometry {
6637 #** @method Geo::OGR::Geometry Intersection($other)
6639 # @param other a Geo::OGR::Geometry object
6640 # @return a new Geo::OGR::Geometry object
6645 #** @method scalar Intersects($other)
6647 # @note a.k.a. Intersect (deprecated)
6648 # @param other a Geo::OGR::Geometry object
6649 # @return true if this geometry intersects with the other geometry, false otherwise
6659 #** @method scalar IsEmpty()
6661 # Test whether the geometry is empty (has no points, or, for a point,
6662 # has coordinate dimension of zero).
6668 #** @method IsMeasured()
6673 #** @method scalar IsRing()
6675 # Test if the geometry is a ring. Requires GEOS in GDAL.
6681 #** @method scalar IsSimple()
6683 # Test the simplicity of the geometry (OGC sense). Requires GEOS in GDAL.
6689 #** @method scalar IsValid()
6691 # Test the validity of the geometry (OGC sense). Requires GEOS in GDAL.
6697 #** @method scalar Length()
6699 # @return the length of the linestring
6704 #** @method MakeValid()
6709 #** @method Move($dx, $dy, $dz)
6711 # Move every point of the object as defined by the parameters.
6714 # @param dz [optional]
6719 #** @method scalar Overlaps($other)
6721 # @param other a Geo::OGR::Geometry object
6722 # @return true if this geometry overlaps the other geometry, false otherwise
6727 #** @method list Point($index, $x, $y, $z)
6729 # Get or set the point
6730 # @param index The index of the point. Optional (ignored if given) for
6731 # Point and Point25D geometries.
6732 # @param x [optional]
6733 # @param y [optional]
6734 # @param z [optional]
6741 my $t = $self->GetGeometryType;
6743 if (Flatten($t) == $Geo::OGR::wkbPoint) {
6744 my $has_z = HasZ($t);
6745 my $has_m = HasM($t);
6746 if (!$has_z && !$has_m) {
6749 } elsif ($has_z || $has_m) {
6757 $i = shift unless defined $i;
6758 $self->SetPoint($i, @_);
6760 return unless defined wantarray;
6761 my $point = $self->GetPoint;
6762 return wantarray ? @$point : $point;
6765 #** @method PointOnSurface()
6767 sub PointOnSurface {
6770 #** @method array reference Points(arrayref points)
6772 # Get or set the points of the geometry. The points (vertices) are
6773 # stored in obvious lists of lists. When setting, the geometry is
6774 # first emptied. The method uses internally either AddPoint_2D or
6775 # AddPoint_3D depending on the coordinate dimension of the input data.
6777 # @note The same structure may represent different geometries
6778 # depending on the actual geometry type of the object.
6780 # @param points [optional] A reference to an array. A point is a reference to an
6781 # array of numbers, a linestring or a ring is a reference to an array of points,
6782 # a polygon is a reference to an array of rings, etc.
6784 # @return A reference to an array.
6788 my $t = $self->GetGeometryType;
6789 my $has_z = HasZ($t);
6790 my $has_m = HasM($t);
6792 $postfix .=
'Z' if HasZ($t);
6793 $postfix .=
'M' if HasM($t);
6794 $t = i2s(geometry_type => Flatten($t));
6798 if ($t eq
'Unknown' or $t eq
'None' or $t eq
'GeometryCollection') {
6799 error(
"Can't set points of a geometry of type '$t'.");
6800 } elsif ($t eq
'Point') {
6801 # support both "Point" as a list of one point and one point
6802 if (ref($points->[0])) {
6803 $self->AddPoint(@{$points->[0]});
6805 $self->AddPoint(@$points);
6807 } elsif ($t eq
'LineString' or $t eq
'LinearRing' or $t eq
'CircularString') {
6808 for my $p (@$points) {
6809 $self->AddPoint(@$p);
6811 } elsif ($t eq
'Polygon') {
6812 for my $r (@$points) {
6814 $ring->
Set3D(1)
if $has_z;
6815 $ring->SetMeasured(1)
if $has_m;
6817 $self->AddGeometryDirectly($ring);
6819 } elsif ($t eq
'MultiPoint') {
6820 for my $p (@$points) {
6823 $self->AddGeometryDirectly($point);
6825 } elsif ($t eq
'MultiLineString') {
6826 for my $l (@$points) {
6829 $self->AddGeometryDirectly($linestring);
6831 } elsif ($t eq
'MultiPolygon') {
6832 for my $p (@$points) {
6835 $self->AddGeometryDirectly($polygon);
6839 return unless defined wantarray;
6840 $self->_GetPoints();
6843 #** @method Polygonize()
6848 #** @method RemoveGeometry()
6850 sub RemoveGeometry {
6853 #** @method RemoveLowerDimensionSubGeoms()
6855 sub RemoveLowerDimensionSubGeoms {
6858 #** @method Segmentize($MaxLength)
6860 # Modify the geometry such it has no segment longer than the given length.
6861 # @param MaxLength the given length
6871 #** @method SetCoordinateDimension($dimension)
6875 sub SetCoordinateDimension {
6878 #** @method SetMeasured()
6883 #** @method SetPoint($index, $x, $y, $z)
6885 # Set the data of a point or a line string. Note that the coordinate
6886 # dimension is automatically upgraded to 25D (3) if z is given.
6890 # @param z [optional]
6894 my $t = $self->GetGeometryType;
6895 my $has_z = HasZ($t);
6896 my $has_m = HasM($t);
6897 if (!$has_z && !$has_m) {
6898 $self->SetPoint_2D(@_[0..2]);
6899 } elsif ($has_z && !$has_m) {
6900 $self->SetPoint_3D(@_[0..3]);
6901 } elsif (!$has_z && $has_m) {
6902 $self->SetPointM(@_[0..3]);
6904 $self->SetPointZM(@_[0..4]);
6908 #** @method SetPointM()
6913 #** @method SetPointZM()
6918 #** @method SetPoint_2D($index, $x, $y)
6927 #** @method SetPoint_3D($index, $x, $y, $z)
6929 # Set the data of a point or a line string. Note that the coordinate
6930 # dimension is automatically upgraded to 25D (3).
6939 #** @method Geo::OGR::Geometry Simplify($Tolerance)
6941 # Simplify the geometry.
6942 # @param Tolerance the length tolerance for the simplification
6944 # @return a new Geo::OSR::Geometry object
6949 #** @method SimplifyPreserveTopology()
6951 sub SimplifyPreserveTopology {
6954 #** @method SwapXY()
6959 #** @method Geo::OGR::Geometry SymDifference($other)
6961 # Compute symmetric difference.
6962 # @note a.k.a. SymmetricDifference
6963 # @param other a Geo::OGR::Geometry object
6964 # @return a new Geo::OGR::Geometry object
6970 #** @method scalar Touches($other)
6972 # @param other a Geo::OGR::Geometry object
6973 # @return true if this geometry touches the other geometry, false otherwise
6978 #** @method Transform($trans)
6980 # @param trans a Geo::OSR::CoordinateTransformation object
6985 #** @method TransformTo($srs)
6987 # @param srs a Geo::OSR::SpatialReference object
6992 #** @method Geo::OGR::Geometry Union($other)
6994 # @param other a Geo::OGR::Geometry object
6995 # @return a new Geo::OGR::Geometry object
7000 #** @method Geo::OGR::Geometry UnionCascaded()
7002 # @return a new Geo::OGR::Geometry object
7013 #** @method scalar Within($other)
7015 # @param other a Geo::OGR::Geometry object
7016 # @return true if this geometry is within the other geometry, false otherwise
7021 #** @method scalar WkbSize()
7023 # @return an integer
7028 #** @method Geo::OGR::Geometry new(%params)
7030 # @param %params A named parameter, one of:
7031 # - \a GeometryType one the supported geometry types, see Geo::OGR::GeometryTypes.
7032 # - \a WKT a well known text string, which defines a geometry.
7033 # - \a WKB a well known binary string, which defines a geometry.
7034 # - \a HEXWKB WKB in hexadecimal.
7035 # - \a HEXEWKB PostGIS extended WKB.
7036 # - \a GML geometry written in Geographic Markup Language.
7037 # - \a GeoJSON geometry written in GeoJSON (JavaScript Object Notation for Geographic data).
7038 # - \a arc a reference to a list of values defining an arc: [CenterX,
7039 # CenterY, CenterZ, PrimaryRadius, SecondaryRadius, Rotation,
7040 # StartAngle, EndAngle, MaxAngleStepSizeDegrees] (see also Geo::OGR::Geometry::ApproximateArcAngles)
7041 # - \a Points An anonymous array as in method
7042 # Geo::OGR::Geometry::Points; Note: requires also GeometryType
7045 # @return a new Geo::OGR::Geometry object.
7050 if (@_ == 1 and ref($_[0]) eq
'HASH') {
7052 } elsif (@_ % 2 == 0) {
7055 ($param{GeometryType}) = @_;
7057 my $type = $param{GeometryType}
7058 my $srs = $param{SRS}
7059 my $wkt = $param{WKT}
7060 my $wkb = $param{WKB}
7061 my $hex = $param{HEXEWKB}
7064 # EWKB contains SRID
7065 $srid = substr($hex, 10, 8);
7066 substr($hex, 10, 8) =
'';
7068 $hex = $param{HEXWKB}
7072 for (my $i = 0; $i < length($hex); $i+=2) {
7073 $wkb .= chr(hex(substr($hex,$i,2)));
7076 my $gml = $param{GML}
7077 my $json = $param{GeoJSON}
7078 my $points = $param{Points}
7079 my $arc = $param{Arc}
7082 $self = Geo::OGRc::CreateGeometryFromWkt($wkt, $srs);
7083 } elsif (defined $wkb) {
7084 $self = Geo::OGRc::CreateGeometryFromWkb($wkb, $srs);
7085 } elsif (defined $gml) {
7086 $self = Geo::OGRc::CreateGeometryFromGML($gml);
7087 } elsif (defined $json) {
7088 $self = Geo::OGRc::CreateGeometryFromJson($json);
7089 } elsif (defined $type) {
7090 $type = s2i(geometry_type => $type);
7091 $self = Geo::OGRc::new_Geometry($type); # flattens the type
7092 $self->Set3D(1)
if HasZ($type);
7093 $self->SetMeasured(1)
if HasM($type);
7094 } elsif (defined $arc) {
7095 $self = Geo::OGRc::ApproximateArcAngles(@$arc);
7097 error(1, undef, map {$_=>1} qw/GeometryType WKT WKB HEXEWKB HEXWKB GML GeoJSON Arc/);
7099 bless $self, $pkg
if defined $self;
7100 $self->Points($points)
if $points;
7104 #** @class Geo::OGR::Layer
7105 # @brief A collection of similar features.
7106 # @details A layer object is typically obtained with a data source object. A
7107 # layer has a data model (a schema), which is maintained in a
7108 # definition object, and a set of features, which contain data
7109 # according to the data model. The schema is typically set when the
7110 # layer is created or opened, but it may be altered somewhat with
7111 # methods Geo::OGR::Layer::CreateField,
7112 # Geo::OGR::Layer::AlterFieldDefn, and
7113 # Geo::OGR::Layer::DeleteField. Features and/or their data can be
7114 # read, inserted and deleted. Reading can be filtered. Layers can be
7115 # compared to each other with methods Clip, Erase, Identity,
7116 # Intersection, SymDifference, Union, and Update.
7117 # A layer may have metadata OLMD_FID64 => 'YES' if it holds features
7118 # with 64 bit FIDs. The metadata of a layer can be obtained with
7119 # GetMetadata method.
7121 package Geo::OGR::Layer;
7125 #** @method AlterFieldDefn($name, %params)
7127 # @param field the name of the field to be altered.
7128 # @param params as in Geo::OGR::FieldDefn::new. Width and
7129 # Precision should be both or neither.
7130 # @note Only non-spatial fields can be altered.
7131 # @note Also the deprecated form AlterFieldDefn($field,
7132 # Geo::OGR::FieldDefn $Defn, $Flags) works.
7134 sub AlterFieldDefn {
7136 my $index = $self->GetLayerDefn->GetFieldIndex(shift
7137 my $param = @_ % 2 == 0 ? {@_} : shift;
7138 if (blessed($param) and $param->isa(
'Geo::OGR::FieldDefn')) {
7139 _AlterFieldDefn($self, $index, @_);
7141 my $definition = Geo::OGR::FieldDefn->new($param);
7143 $flags |= 1 if exists $param->{Name};
7144 $flags |= 2
if exists $param->{Type};
7145 $flags |= 4
if exists $param->{Width} or exists $param->{Precision};
7146 $flags |= 8
if exists $param->{Nullable};
7147 $flags |= 16
if exists $param->{Default};
7148 _AlterFieldDefn($self, $index, $definition, $flags);
7152 #** @method list Capabilities()
7154 # Both a package subroutine and an object method.
7155 # @return a list of capabilities. The object method returns a list of
7156 # the capabilities the layer has. The package subroutine returns a list of
7157 # all potential capabilities a layer may have. These are currently:
7158 # AlterFieldDefn, CreateField, CreateGeomField, CurveGeometries, DeleteFeature, DeleteField, FastFeatureCount, FastGetExtent, FastSetNextByIndex, FastSpatialFilter, IgnoreFields, MeasuredGeometries, RandomRead, RandomWrite, ReorderFields, SequentialWrite, StringsAsUTF8, and Transactions.
7162 # @cap = Geo::OGR::Layer::Capabilities(); # the package subroutine
7163 # @cap = $layer->Capabilities(); # the object method
7167 return @CAPABILITIES
if @_ == 0;
7170 for my $cap (@CAPABILITIES) {
7171 push @cap, $cap
if _TestCapability($self, $CAPABILITIES{$cap});
7176 #** @method Clip(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7178 # Clip off areas that are not covered by the method layer. The schema
7179 # of the result layer can be set before calling this method, or is
7180 # initialized to to contain all fields from
7181 # this and method layer.
7182 # @param method method layer.
7183 # @param result result layer.
7184 # @param options a reference to an options hash.
7185 # @param callback [optional] a reference to a subroutine, which will
7186 # be called with parameters (number progress, string msg, callback_data)
7187 # @param callback_data [optional]
7192 #** @method CommitTransaction()
7195 sub CommitTransaction {
7198 #** @method CreateFeature()
7203 #** @method CreateField(%params)
7206 # @param params as in Geo::OGR::FieldDefn::new or
7207 # Geo::OGR::GeomFieldDefn::new, plus ApproxOK (whose default is true).
7211 my %defaults = ( ApproxOK => 1,
7215 } elsif (ref($_[0]) eq
'HASH') {
7217 } elsif (@_ % 2 == 0) {
7220 ($params{Defn}) = @_;
7222 for my $k (keys %defaults) {
7225 if (blessed($params{Defn}) and $params{Defn}->isa(
'Geo::OGR::FieldDefn')) {
7226 $self->_CreateField($params{Defn}, $params{ApproxOK});
7227 } elsif (blessed($_[0]) and $params{Defn}->isa(
'Geo::OGR::GeomFieldDefn')) {
7228 $self->CreateGeomField($params{Defn}, $params{ApproxOK});
7230 # if Name and Type are missing, assume Name => Type
7231 if (!(exists $params{Name} && exists $params{Type})) {
7232 for my $key (sort keys %params) {
7233 if (s_exists(field_type => $params{$key}) ||
7234 s_exists(geometry_type => $params{$key}))
7236 $params{Name} = $key;
7237 $params{Type} = $params{$key};
7238 delete $params{$key};
7243 my $a = $params{ApproxOK};
7244 delete $params{ApproxOK};
7245 if (exists $params{GeometryType}) {
7246 $params{Type} = $params{GeometryType};
7247 delete $params{GeometryType};
7249 if (s_exists(field_type => $params{Type})) {
7251 _CreateField($self, $fd, $a);
7252 } elsif (s_exists(geometry_type => $params{Type})) {
7254 CreateGeomField($self, $fd, $a);
7255 } elsif ($params{Type} ) {
7256 error(
"Invalid field type: $params{Type}.")
7257 } elsif ($params{Name} ) {
7258 error(
"Missing type for field: $params{Name}.")
7260 error(
"Missing name and type for a field.")
7265 #** @method DataSource()
7270 #** @method Dataset()
7277 #** @method DeleteFeature($fid)
7279 # @param fid feature id
7284 #** @method DeleteField($field)
7286 # Delete an existing field from a layer.
7287 # @param field name (or index) of the field which is deleted
7288 # @note Only non-spatial fields can be deleted.
7291 my ($self, $field) = @_;
7292 my $index = $self->GetLayerDefn->GetFieldIndex($field
7293 _DeleteField($self, $index);
7296 #** @method Erase(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7298 # The result layer contains features whose geometries represent areas
7299 # that are in the input layer but not in the method layer. The
7300 # features in the result layer have attributes from the input
7301 # layer. The schema of the result layer can be set by the user or, if
7302 # it is empty, is initialized to contain all fields in the input
7304 # @param method method layer.
7305 # @param result result layer.
7306 # @param options a reference to an options hash.
7307 # @param callback [optional] a reference to a subroutine, which will
7308 # be called with parameters (number progress, string msg, callback_data)
7309 # @param callback_data [optional]
7314 #** @method Geo::OGR::Feature Feature($f)
7317 # @param f [optional] feature id, a feature, a row, or a tuple
7319 # @note If the argument feature has a null FID (FID not set) the
7320 # feature is inserted into the layer as a new feature. If the FID is
7321 # non null, then the feature replaces the feature in the layer with
7324 # @return a new Geo::OGR::Feature object that represents the feature
7330 return $self->GetFeature($x) unless $x && ref $x;
7331 # Insert or Set depending on the FID
7333 if (ref $x eq
'ARRAY') {
7334 # FID is the first item in the array
7336 } elsif (ref $x eq
'HASH') {
7343 if (!defined $fid || $fid < 0) {
7344 $self->InsertFeature($x);
7346 $self->SetFeature($x);
7350 #** @method scalar FeatureCount($force = 1)
7352 # A.k.a GetFeatureCount
7359 #** @method Features()
7363 $self->ResetReading;
7365 return $self->GetNextFeature;
7369 #** @method ForFeatures($code, $in_place)
7371 # @note experimental, the syntax may change
7373 # Call code for all features. This is a simple wrapper for
7374 # ResetReading and while(GetNextFeature).
7378 # $layer->ForFeatures(sub {my $f = shift; $self->DeleteFeature($f->FID)}); # empties the layer
7381 # @param code a reference to a subroutine, which is called with each
7382 # feature as an argument
7383 # @param in_place if set to true, the feature is stored back to the
7389 my $in_place = shift;
7390 $self->ResetReading;
7391 while (my $f = $self->GetNextFeature) {
7394 $self->SetFeature($f)
if $in_place;
7398 #** @method ForGeometries($code, $in_place)
7400 # @note experimental, the syntax may change
7402 # Call code for all geometries. This is a simple wrapper for
7403 # ResetReading and while(GetNextFeature).
7408 # $layer->ForGeometries(sub {my $g = shift; $area += $g->Area}); # computes the total area
7411 # @param code a reference to a subroutine, which is called with each
7412 # geometry as an argument
7413 # @param in_place if set to true, the geometry is stored back to the
7419 my $in_place = shift;
7420 $self->ResetReading;
7421 while (my $f = $self->GetNextFeature) {
7422 my $g = $f->Geometry();
7426 $self->SetFeature($f);
7431 #** @method Geometries()
7435 $self->ResetReading;
7437 my $f = $self->GetNextFeature;
7439 return $f->Geometry;
7443 #** @method scalar GeometryType($field)
7445 # @param field the name or index of the spatial field.
7446 # @return the geometry type of the spatial field.
7450 my $d = $self->GetDefn;
7451 my $field = $d->GetGeomFieldIndex(shift
7452 my $fd = $d->_GetGeomFieldDefn($field);
7453 return $fd->Type
if $fd;
7456 #** @method Geo::OGR::DataSource GetDataSource()
7458 # @return the data source object to which this layer object belongs to.
7465 #** @method Geo::OGR::FeatureDefn GetDefn()
7467 # A.k.a GetLayerDefn.
7468 # @return a Geo::OGR::FeatureDefn object.
7472 my $defn = $self->GetLayerDefn;
7476 #** @method list GetExtent($force = 1)
7478 # @param force compute the extent even if it is expensive
7479 # @note In scalar context returns a reference to an anonymous array
7480 # containing the extent.
7481 # @return the extent ($minx, $maxx, $miny, $maxy)
7483 # @return the extent = ($minx, $maxx, $miny, $maxy) as a listref
7488 #** @method scalar GetFIDColumn()
7490 # @return the name of the underlying database column being used as the
7491 # FID column, or "" if not supported.
7496 #** @method Geo::OGR::Feature GetFeature($fid)
7498 # @param fid feature id
7499 # @return a new Geo::OGR::Feature object that represents the feature in the layer.
7502 my ($self, $fid) = @_;
7504 my $f = $self->_GetFeature($fid);
7505 error(2,
"FID=$fid",
'"Feature') unless ref $f eq
'Geo::OGR::Feature';
7509 #** @method GetFeatureCount()
7511 sub GetFeatureCount {
7514 #** @method scalar GetFeaturesRead()
7518 sub GetFeaturesRead {
7521 #** @method scalar GetFieldDefn($name)
7523 # Get the definition of a field.
7524 # @param name the name of the field.
7525 # @return a Geo::OGR::FieldDefn object.
7529 my $d = $self->GetDefn;
7530 my $field = $d->GetFieldIndex(shift
7531 return $d->_GetFieldDefn($field);
7534 #** @method list GetFieldNames()
7536 # @return a list of the names of the fields in this layer. The
7537 # non-geometry field names are first in the list and then the geometry
7542 my $d = $self->GetDefn;
7544 for (my $i = 0; $i < $d->GetFieldCount; $i++) {
7545 push @ret, $d->GetFieldDefn($i)->Name();
7547 for (my $i = 0; $i < $d->GetGeomFieldCount; $i++) {
7548 push @ret, $d->GetGeomFieldDefn($i)->Name();
7553 #** @method scalar GetGeomFieldDefn($name)
7555 # Get the definition of a spatial field.
7556 # @param name the name of the spatial field.
7557 # @return a Geo::OGR::GeomFieldDefn object.
7559 sub GetGeomFieldDefn {
7561 my $d = $self->GetDefn;
7562 my $field = $d->GetGeomFieldIndex(shift
7563 return $d->_GetGeomFieldDefn($field);
7566 #** @method scalar GetName()
7568 # @return the name of the layer.
7573 #** @method Geo::OGR::Feature GetNextFeature()
7575 # @return iteratively Geo::OGR::Feature objects from the layer. The
7576 # iteration obeys the spatial and the attribute filter.
7578 sub GetNextFeature {
7581 #** @method hash reference GetSchema()
7583 # @brief Get the schema of this layer.
7584 # @note The schema of a layer cannot be set with this method. If you
7585 # have a Geo::OGR::FeatureDefn object before creating the layer, use
7586 # its schema in the Geo::OGR::CreateLayer method.
7587 # @return the schema of this layer, as in Geo::OGR::FeatureDefn::Schema.
7591 carp
"Schema of a layer should not be set directly." if @_;
7592 if (@_ and @_ % 2 == 0) {
7594 if ($schema{Fields}) {
7595 for my $field (@{$schema{Fields}}) {
7596 $self->CreateField($field);
7600 return $self->GetDefn->Schema;
7603 #** @method Geo::OGR::Geometry GetSpatialFilter()
7605 # @return a new Geo::OGR::Geometry object
7607 sub GetSpatialFilter {
7610 #** @method GetStyleTable()
7615 #** @method Identity(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7617 # The result layer contains features whose geometries represent areas
7618 # that are in the input layer. The features in the result layer have
7619 # attributes from both input and method layers. The schema of the
7620 # result layer can be set by the user or, if it is empty, is
7621 # initialized to contain all fields in input and method layers.
7622 # @param method method layer.
7623 # @param result result layer.
7624 # @param options a reference to an options hash.
7625 # @param callback [optional] a reference to a subroutine, which will
7626 # be called with parameters (number progress, string msg, callback_data)
7627 # @param callback_data [optional]
7632 #** @method InsertFeature($feature)
7634 # Creates a new feature which has the schema of the layer and
7635 # initializes it with data from the argument. Then inserts the feature
7636 # into the layer (using CreateFeature). Uses Geo::OGR::Feature::Row or
7637 # Geo::OGR::Feature::Tuple.
7638 # @param feature a Geo::OGR::Feature object or reference to feature
7639 # data in a hash (as in Geo::OGR::Feature::Row) or in an array (as in
7640 # Geo::OGR::Feature::Tuple)
7641 # @return the new feature.
7645 my $feature = shift;
7646 error(
"Usage: \$feature->InsertFeature(reference to a hash or array).") unless ref($feature);
7648 $self->CreateFeature($new);
7649 return unless defined wantarray;
7653 #** @method Intersection(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7655 # The result layer contains features whose geometries represent areas
7656 # that are common between features in the input layer and in the
7657 # method layer. The schema of the result layer can be set before
7658 # calling this method, or is initialized to contain all fields from
7659 # this and method layer.
7660 # @param method method layer.
7661 # @param result result layer.
7662 # @param options a reference to an options hash.
7663 # @param callback [optional] a reference to a subroutine, which will
7664 # be called with parameters (number progress, string msg, callback_data)
7665 # @param callback_data [optional]
7670 #** @method ReorderField()
7675 #** @method ReorderFields()
7680 #** @method ResetReading()
7682 # Initialize the layer object for iterative reading.
7687 #** @method RollbackTransaction()
7690 sub RollbackTransaction {
7693 #** @method hash reference Row(%row)
7695 # Get and/or set the data of a feature that has the supplied feature
7696 # id (the next feature obtained with GetNextFeature is used if feature
7697 # id is not given). Calls Geo::OGR::Feature::Row.
7698 # @param row [optional] feature data
7699 # @return a reference to feature data in a hash
7703 my $update = @_ > 0;
7705 my $feature = defined $row{FID} ? $self->GetFeature($row{FID}) : $self->GetNextFeature;
7706 return unless $feature;
7708 if (defined wantarray) {
7709 $ret = $feature->Row(@_);
7713 $self->SetFeature($feature)
if $update;
7714 return unless defined wantarray;
7718 #** @method SetAttributeFilter($filter_string)
7720 # Set or clear the attribute filter.
7721 # @param filter_string a SQL WHERE clause or undef to clear the
7724 sub SetAttributeFilter {
7727 #** @method SetFeature($feature)
7729 # @note The feature should have the same schema as the layer.
7731 # Replaces a feature in the layer based on the given feature's
7732 # id. Requires RandomWrite capability.
7733 # @param feature a Geo::OGR::Feature object
7738 #** @method SetIgnoredFields(@fields)
7740 # @param fields a list of field names
7742 sub SetIgnoredFields {
7745 #** @method SetNextByIndex($new_index)
7747 # @param new_index the index to which set the read cursor in the
7750 sub SetNextByIndex {
7753 #** @method SetSpatialFilter($filter)
7755 # @param filter [optional] a Geo::OGR::Geometry object. If not given,
7756 # removes the filter if there is one.
7758 sub SetSpatialFilter {
7761 #** @method SetSpatialFilterRect($minx, $miny, $maxx, $maxy)
7768 sub SetSpatialFilterRect {
7771 #** @method SetStyleTable()
7776 #** @method Geo::OGR::Geometry SpatialFilter(@filter)
7778 # @param filter [optional] a Geo::OGR::Geometry object or a string. An
7779 # undefined value removes the filter if there is one.
7780 # @return a new Geo::OGR::Geometry object
7781 # @param filter [optional] a rectangle ($minx, $miny, $maxx, $maxy).
7782 # @return a new Geo::OGR::Geometry object
7786 $self->SetSpatialFilter($_[0])
if @_ == 1;
7787 $self->SetSpatialFilterRect(@_)
if @_ == 4;
7788 return unless defined wantarray;
7789 $self->GetSpatialFilter;
7792 #** @method Geo::OSR::SpatialReference SpatialReference($name, Geo::OSR::SpatialReference sr)
7794 # @note A.k.a GetSpatialRef.
7795 # Get or set the projection of a spatial field of this layer. Gets or
7796 # sets the projection of the first field if no field name is given.
7797 # @param name [optional] a name of a spatial field in this layer.
7798 # @param sr [optional] a Geo::OSR::SpatialReference object,
7799 # which replaces the existing projection.
7800 # @return a Geo::OSR::SpatialReference object, which represents the
7801 # projection in the given spatial field.
7803 sub SpatialReference {
7805 my $d = $self->GetDefn;
7806 my $field = @_ == 2 ? $d->GetGeomFieldIndex(shift
7808 my $d2 = $d->_GetGeomFieldDefn($field);
7809 $d2->SpatialReference($sr)
if defined $sr;
7810 return $d2->SpatialReference()
if defined wantarray;
7813 #** @method StartTransaction()
7816 sub StartTransaction {
7819 #** @method SymDifference(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7821 # The result layer contains features whose geometries represent areas
7822 # that are in either in the input layer or in the method layer but not
7823 # in both. The features in the result layer have attributes from both
7824 # input and method layers. For features which represent areas that are
7825 # only in the input or in the method layer the respective attributes
7826 # have undefined values. The schema of the result layer can be set by
7827 # the user or, if it is empty, is initialized to contain all fields in
7828 # the input and method layers.
7829 # @param method method layer.
7830 # @param result result layer.
7831 # @param options a reference to an options hash.
7832 # @param callback [optional] a reference to a subroutine, which will
7833 # be called with parameters (number progress, string msg, callback_data)
7834 # @param callback_data [optional]
7839 #** @method SyncToDisk()
7845 #** @method scalar TestCapability($cap)
7847 # @param cap A capability string.
7848 # @return a boolean value indicating whether the layer has the
7849 # specified capability.
7851 sub TestCapability {
7852 my($self, $cap) = @_;
7853 return _TestCapability($self, $CAPABILITIES{$cap});
7856 #** @method list Tuple(@tuple)
7858 # Get and/set the data of a feature that has the supplied feature id
7859 # (the next feature obtained with GetNextFeature is used if feature id
7860 # is not given). The expected data in the tuple is: ([feature id,]
7861 # non-spatial fields, spatial fields). Calls Geo::OGR::Feature::Tuple.
7862 # @param tuple [optional] feature data
7863 # @note The schema of the tuple needs to be the same as that of the
7865 # @return a reference to feature data in an array
7870 my $feature = defined $FID ? $self->GetFeature($FID) : $self->GetNextFeature;
7871 return unless $feature;
7873 unshift @_, $feature->GetFID
if $set;
7875 if (defined wantarray) {
7876 @ret = $feature->Tuple(@_);
7878 $feature->Tuple(@_);
7880 $self->SetFeature($feature)
if $set;
7881 return unless defined wantarray;
7885 #** @method Union(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7887 # The result layer contains features whose geometries represent areas
7888 # that are in either in the input layer or in the method layer. The
7889 # schema of the result layer can be set before calling this method, or
7890 # is initialized to contain all fields from this and method layer.
7891 # @param method method layer.
7892 # @param result result layer.
7893 # @param options a reference to an options hash.
7894 # @param callback [optional] a reference to a subroutine, which will
7895 # be called with parameters (number progress, string msg, callback_data)
7896 # @param callback_data [optional]
7901 #** @method Update(Geo::OGR::Layer method, Geo::OGR::Layer result, hashref options, coderef callback, $callback_data)
7903 # The result layer contains features whose geometries represent areas
7904 # that are either in the input layer or in the method layer. The
7905 # features in the result layer have areas of the features of the
7906 # method layer or those ares of the features of the input layer that
7907 # are not covered by the method layer. The features of the result
7908 # layer get their attributes from the input layer. The schema of the
7909 # result layer can be set by the user or, if it is empty, is
7910 # initialized to contain all fields in the input layer.
7911 # @param method method layer.
7912 # @param result result layer.
7913 # @param options a reference to an options hash.
7914 # @param callback [optional] a reference to a subroutine, which will
7915 # be called with parameters (number progress, string msg, callback_data)
7916 # @param callback_data [optional]
7921 #** @class Geo::OGR::StyleTable
7923 package Geo::OGR::StyleTable;
7927 #** @method AddStyle()
7937 #** @method GetLastStyleName()
7939 sub GetLastStyleName {
7942 #** @method GetNextStyle()
7947 #** @method LoadStyleTable()
7949 sub LoadStyleTable {
7952 #** @method ResetStyleStringReading()
7954 sub ResetStyleStringReading {
7957 #** @method SaveStyleTable()
7959 sub SaveStyleTable {
7966 my $self = Geo::OGRc::new_StyleTable(@_);
7967 bless $self, $pkg
if defined($self);
7971 # @brief Base class for projection related classes.
7976 #** @method list AngularUnits()
7977 # Package subroutine.
7978 # @return list of known angular units.
7981 return keys %ANGULAR_UNITS;
7984 #** @method CreateCoordinateTransformation()
7986 sub CreateCoordinateTransformation {
7989 #** @method list Datums()
7990 # Package subroutine.
7991 # @return list of known datums.
7994 return keys %DATUMS;
7997 #** @method GetPROJSearchPaths()
7999 sub GetPROJSearchPaths {
8002 #** @method GetPROJVersionMajor()
8004 sub GetPROJVersionMajor {
8007 #** @method GetPROJVersionMicro()
8009 sub GetPROJVersionMicro {
8012 #** @method GetPROJVersionMinor()
8014 sub GetPROJVersionMinor {
8017 #** @method scalar GetUserInputAsWKT($name)
8018 # Package subroutine.
8019 # @param name the user input
8020 # @return a WKT string.
8022 sub GetUserInputAsWKT {
8025 #** @method scalar GetWellKnownGeogCSAsWKT($name)
8026 # Package subroutine.
8027 # @brief Get well known geographic coordinate system as WKT
8028 # @param name a well known name
8029 # @return a WKT string.
8031 sub GetWellKnownGeogCSAsWKT {
8034 #** @method list LinearUnits()
8035 # Package subroutine.
8036 # @return list of known linear units.
8039 return keys %LINEAR_UNITS;
8042 #** @method OAMS_AUTHORITY_COMPLIANT()
8044 sub OAMS_AUTHORITY_COMPLIANT {
8047 #** @method OAMS_CUSTOM()
8052 #** @method OAMS_TRADITIONAL_GIS_ORDER()
8054 sub OAMS_TRADITIONAL_GIS_ORDER {
8057 #** @method OAO_Down()
8062 #** @method OAO_East()
8067 #** @method OAO_North()
8072 #** @method OAO_Other()
8077 #** @method OAO_South()
8082 #** @method OAO_Up()
8087 #** @method OAO_West()
8092 #** @method OSRAreaOfUse_east_lon_degree_get()
8094 sub OSRAreaOfUse_east_lon_degree_get {
8097 #** @method OSRAreaOfUse_name_get()
8099 sub OSRAreaOfUse_name_get {
8102 #** @method OSRAreaOfUse_north_lat_degree_get()
8104 sub OSRAreaOfUse_north_lat_degree_get {
8107 #** @method OSRAreaOfUse_south_lat_degree_get()
8109 sub OSRAreaOfUse_south_lat_degree_get {
8112 #** @method OSRAreaOfUse_west_lon_degree_get()
8114 sub OSRAreaOfUse_west_lon_degree_get {
8117 #** @method list Parameters()
8118 # Package subroutine.
8119 # @return list of known projection parameters.
8122 return keys %PARAMETERS;
8125 #** @method list Projections()
8126 # Package subroutine.
8127 # @return list of known projections.
8130 return keys %PROJECTIONS;
8133 #** @method SRS_PM_GREENWICH()
8135 sub SRS_PM_GREENWICH {
8138 #** @method SRS_WGS84_INVFLATTENING()
8140 sub SRS_WGS84_INVFLATTENING {
8143 #** @method SRS_WGS84_SEMIMAJOR()
8145 sub SRS_WGS84_SEMIMAJOR {
8148 #** @method SRS_WKT_WGS84_LAT_LONG()
8150 sub SRS_WKT_WGS84_LAT_LONG {
8153 #** @method SetPROJSearchPath()
8155 sub SetPROJSearchPath {
8158 #** @method SetPROJSearchPaths()
8160 sub SetPROJSearchPaths {
8163 #** @class Geo::OSR::AreaOfUse
8165 package Geo::OSR::AreaOfUse;
8173 my $self = Geo::OSRc::new_AreaOfUse(@_);
8174 bless $self, $pkg
if defined($self);
8177 #** @class Geo::OSR::CoordinateTransformation
8178 # @brief An object for transforming from one projection to another.
8181 package Geo::OSR::CoordinateTransformation;
8185 #** @method array reference TransformPoint($x, $y, $z)
8189 # @param z [optional]
8190 # @return arrayref = [$x, $y, $z]
8192 sub TransformPoint {
8195 #** @method TransformPoints(arrayref points)
8197 # @param points [in/out] a reference to a list of points (line string
8198 # or ring) that is modified in-place. A list of points is: ([x, y, z],
8199 # [x, y, z], ...), where z is optional. Supports also lists of line
8200 # strings and polygons.
8202 sub TransformPoints {
8203 my($self, $points) = @_;
8204 _TransformPoints($self, $points),
return unless ref($points->[0]->[0]);
8205 for my $p (@$points) {
8206 TransformPoints($self, $p);
8210 # This file was automatically generated by SWIG (http://www.swig.org).
8213 # Do not make changes to this file unless you know what you are doing--modify
8214 # the SWIG interface file instead.
8217 #** @method Geo::OSR::CoordinateTransformation new($src, $dst)
8219 # @param src a Geo::OSR::SpatialReference object
8220 # @param dst a Geo::OSR::SpatialReference object
8221 # @return a new Geo::OSR::CoordinateTransformation object
8225 my $self = Geo::OSRc::new_CoordinateTransformation(@_);
8226 bless $self, $pkg
if defined($self);
8229 #** @class Geo::OSR::CoordinateTransformationOptions
8231 package Geo::OSR::CoordinateTransformationOptions;
8235 #** @method SetAreaOfInterest()
8237 sub SetAreaOfInterest {
8240 #** @method SetOperation()
8249 my $self = Geo::OSRc::new_CoordinateTransformationOptions(@_);
8250 bless $self, $pkg
if defined($self);
8253 #** @class Geo::OSR::SpatialReference
8254 # @brief A spatial reference system.
8255 # @details <a href="http://www.gdal.org/classOGRSpatialReference.html">Documentation
8256 # of the underlying C++ class at www.gdal.org</a>
8258 package Geo::OSR::SpatialReference;
8262 #** @method AddGuessedTOWGS84()
8264 sub AddGuessedTOWGS84 {
8272 #** @method AutoIdentifyEPSG()
8274 # Set EPSG authority info if possible.
8276 sub AutoIdentifyEPSG {
8279 #** @method Geo::OSR::SpatialReference Clone()
8281 # Make a duplicate of this SpatialReference object.
8282 # @return a new Geo::OSR::SpatialReference object
8287 #** @method Geo::OSR::SpatialReference CloneGeogCS()
8289 # Make a duplicate of the GEOGCS node of this SpatialReference object.
8290 # @return a new Geo::OSR::SpatialReference object
8295 #** @method ConvertToOtherProjection()
8297 sub ConvertToOtherProjection {
8300 #** @method CopyGeogCSFrom($rhs)
8302 # @param rhs Geo::OSR::SpatialReference
8304 sub CopyGeogCSFrom {
8307 #** @method EPSGTreatsAsLatLong()
8309 # Returns TRUE if EPSG feels this geographic coordinate system should be treated as having lat/long coordinate ordering.
8311 sub EPSGTreatsAsLatLong {
8314 #** @method EPSGTreatsAsNorthingEasting()
8316 sub EPSGTreatsAsNorthingEasting {
8319 #** @method Export($format)
8321 # Export the spatial reference to a selected format.
8324 # @param format One of the following. The return value is explained
8325 # after the format. Other arguments are explained in parenthesis.
8326 # - WKT (Text): Well Known Text string
8327 # - PrettyWKT: Well Known Text string nicely formatted (simplify)
8328 # - Proj4: PROJ.4 string
8329 # - PCI: a list: ($proj_string, $units, [$parms1, ...])
8330 # - USGS: a list: ($code, $zone, [$parms1, ...], $datum)
8331 # - GML (XML): GML based string (dialect)
8332 # - MapInfoCS (MICoordSys): MapInfo style co-ordinate system definition
8334 # @note The named parameter syntax also works and is needed is those
8335 # cases when other arguments need or may be given. The format should
8336 # be given using key as, 'to' or 'format'.
8338 # @note ExportTo* and AsText methods also exist but are not documented here.
8340 # @return a scalar or a list depending on the export format
8345 $format = pop
if @_ == 1;
8348 my $simplify = $params{simplify}
8349 my $dialect = $params{dialect}
8351 WKT => sub {
return ExportToWkt($self) },
8352 Text => sub {
return ExportToWkt($self) },
8353 PrettyWKT => sub {
return ExportToPrettyWkt($self, $simplify) },
8354 Proj4 => sub {
return ExportToProj4($self) },
8355 PCI => sub {
return ExportToPCI($self) },
8356 USGS => sub {
return ExportToUSGS($self) },
8357 GML => sub {
return ExportToXML($self, $dialect) },
8358 XML => sub {
return ExportToXML($self, $dialect) },
8359 MICoordSys => sub {
return ExportToMICoordSys() },
8360 MapInfoCS => sub {
return ExportToMICoordSys() },
8362 error(1, $format, \%converters) unless $converters{$format};
8363 return $converters{$format}->();
8366 #** @method ExportToPROJJSON()
8368 sub ExportToPROJJSON {
8371 #** @method scalar GetAngularUnits()
8375 sub GetAngularUnits {
8378 #** @method GetAngularUnitsName()
8380 sub GetAngularUnitsName {
8383 #** @method GetAreaOfUse()
8388 #** @method scalar GetAttrValue($name, $child = 0)
8397 #** @method scalar GetAuthorityCode($target_key)
8402 sub GetAuthorityCode {
8405 #** @method scalar GetAuthorityName($target_key)
8410 sub GetAuthorityName {
8413 #** @method GetAxesCount()
8418 #** @method GetAxisMappingStrategy()
8420 sub GetAxisMappingStrategy {
8423 #** @method GetAxisName()
8428 #** @method GetAxisOrientation()
8430 sub GetAxisOrientation {
8433 #** @method GetDataAxisToSRSAxisMapping()
8435 sub GetDataAxisToSRSAxisMapping {
8438 #** @method GetInvFlattening()
8441 sub GetInvFlattening {
8444 #** @method scalar GetLinearUnits()
8448 sub GetLinearUnits {
8451 #** @method scalar GetLinearUnitsName()
8455 sub GetLinearUnitsName {
8458 #** @method GetName()
8463 #** @method scalar GetNormProjParm($name, $default_val = 0.0)
8466 # @param default_val
8469 sub GetNormProjParm {
8472 #** @method scalar GetProjParm($name, $default_val = 0.0)
8475 # @param default_val
8481 #** @method GetSemiMajor()
8487 #** @method GetSemiMinor()
8493 #** @method GetTOWGS84()
8495 # @return array = ($p1, $p2, $p3, $p4, $p5, $p6, $p7)
8500 #** @method GetTargetLinearUnits()
8502 sub GetTargetLinearUnits {
8505 #** @method GetUTMZone()
8507 # Get UTM zone information.
8508 # @return The UTM zone (integer). In scalar context the returned value
8509 # is negative for southern hemisphere zones. In list context returns
8510 # two values ($zone, $north), where $zone is always non-negative and
8511 # $north is true or false.
8515 my $zone = _GetUTMZone($self);
8522 return ($zone, $north);
8528 #** @method HasTOWGS84()
8533 #** @method ImportFromOzi()
8538 #** @method scalar IsCompound()
8545 #** @method IsDerivedGeographic()
8547 sub IsDerivedGeographic {
8550 #** @method scalar IsGeocentric()
8557 #** @method scalar IsGeographic()
8564 #** @method scalar IsLocal()
8571 #** @method scalar IsProjected()
8578 #** @method scalar IsSame($rs)
8580 # @param rs a Geo::OSR::SpatialReference object
8586 #** @method scalar IsSameGeogCS($rs)
8588 # @param rs a Geo::OSR::SpatialReference object
8594 #** @method scalar IsSameVertCS($rs)
8596 # @param rs a Geo::OSR::SpatialReference object
8602 #** @method scalar IsVertical()
8609 #** @method MorphFromESRI()
8615 #** @method MorphToESRI()
8621 #** @method PromoteTo3D()
8626 #** @method Set(%params)
8628 # Set a parameter or parameters in the spatial reference object.
8629 # @param params Named parameters. Recognized keys and respective
8630 # values are the following.
8631 # - Authority: authority name (give also TargetKey, Node and Code)
8633 # - Node: partial or complete path to the target node (Node and Value together sets an attribute value)
8634 # - Code: code for value with an authority
8635 # - Value: value to be assigned to a node, a projection parameter or an object
8636 # - AngularUnits: angular units for the geographic coordinate system (give also Value) (one of Geo::OSR::LinearUnits)
8637 # - LinearUnits: linear units for the target node or the object (give also Value and optionally Node) (one of Geo::OSR::LinearUnits)
8638 # - Parameter: projection parameter to set (give also Value and Normalized) (one of Geo::OSR::Parameters)
8639 # - Normalized: set to true to indicate that the Value argument is in "normalized" form
8640 # - Name: a well known name of a geographic coordinate system (e.g. WGS84)
8641 # - GuessFrom: arbitrary text that specifies a projection ("user input")
8642 # - LOCAL_CS: name of a local coordinate system
8643 # - GeocentricCS: name of a geocentric coordinate system
8644 # - VerticalCS: name of a vertical coordinate system (give also Datum and optionally VertDatumType [default is 2005])
8645 # - Datum: a known (OGC or EPSG) name (or(?) one of Geo::OSR::Datums)
8646 # - CoordinateSystem: 'WGS', 'UTM', 'State Plane', or a user visible name (give optionally also Parameters, Zone, North, NAD83, UnitName, UnitConversionFactor, Datum, Spheroid, HorizontalCS, and/or VerticalCS
8647 # - Parameters: a reference to a list containing the coordinate system or projection parameters
8648 # - Zone: zone for setting up UTM or State Plane coordinate systems (State Plane zone in USGS numbering scheme)
8649 # - North: set false for southern hemisphere
8650 # - NAD83: set false if the NAD27 zone definition should be used instead of NAD83
8651 # - UnitName: to override the legal definition for a zone
8652 # - UnitConversionFactor: to override the legal definition for a zone
8653 # - Spheroid: user visible name
8654 # - HorizontalCS: Horizontal coordinate system name
8655 # - Projection: name of a projection, one of Geo::OSR::Projections (give also optionally Parameters and Variant)
8657 # @note Numerous Set* methods also exist but are not documented here.
8660 my($self, %params) = @_;
8661 if (exists $params{Authority} and exists $params{TargetKey} and exists $params{Node} and exists $params{Code}) {
8662 SetAuthority($self, $params{TargetKey}, $params{Authority}, $params{Code});
8663 } elsif (exists $params{Node} and exists $params{Value}) {
8664 SetAttrValue($self, $params{Node}, $params{Value});
8665 } elsif (exists $params{AngularUnits} and exists $params{Value}) {
8666 SetAngularUnits($self, $params{AngularUnits}, $params{Value});
8667 } elsif (exists $params{LinearUnits} and exists $params{Node} and exists $params{Value}) {
8668 SetTargetLinearUnits($self, $params{Node}, $params{LinearUnits}, $params{Value});
8669 } elsif (exists $params{LinearUnits} and exists $params{Value}) {
8670 SetLinearUnitsAndUpdateParameters($self, $params{LinearUnits}, $params{Value});
8671 } elsif ($params{Parameter} and exists $params{Value}) {
8672 error(1, $params{Parameter}, \%Geo::OSR::PARAMETERS) unless exists $Geo::OSR::PARAMETERS{$params{Parameter}};
8673 $params{Normalized} ?
8674 SetNormProjParm($self, $params{Parameter}, $params{Value}) :
8675 SetProjParm($self, $params{Parameter}, $params{Value});
8676 } elsif (exists $params{Name}) {
8677 SetWellKnownGeogCS($self, $params{Name});
8678 } elsif (exists $params{GuessFrom}) {
8679 SetFromUserInput($self, $params{GuessFrom});
8680 } elsif (exists $params{LOCAL_CS}) {
8681 SetLocalCS($self, $params{LOCAL_CS});
8682 } elsif (exists $params{GeocentricCS}) {
8683 SetGeocCS($self, $params{GeocentricCS});
8684 } elsif (exists $params{VerticalCS} and $params{Datum}) {
8685 my $type = $params{VertDatumType} || 2005;
8686 SetVertCS($self, $params{VerticalCS}, $params{Datum}, $type);
8687 } elsif (exists $params{CoordinateSystem}) {
8688 my @parameters = ();
8689 @parameters = @{$params{Parameters}}
if ref($params{Parameters});
8690 if ($params{CoordinateSystem} eq
'State Plane' and exists $params{Zone}) {
8691 my $NAD83 = exists $params{NAD83} ? $params{NAD83} : 1;
8692 my $name = exists $params{UnitName} ? $params{UnitName} : undef;
8693 my $c = exists $params{UnitConversionFactor} ? $params{UnitConversionFactor} : 0.0;
8694 SetStatePlane($self, $params{Zone}, $NAD83, $name, $c);
8695 } elsif ($params{CoordinateSystem} eq
'UTM' and exists $params{Zone} and exists $params{North}) {
8696 my $north = exists $params{North} ? $params{North} : 1;
8697 SetUTM($self, $params{Zone}, $north);
8698 } elsif ($params{CoordinateSystem} eq
'WGS') {
8699 SetTOWGS84($self, @parameters);
8700 } elsif ($params{CoordinateSystem} and $params{Datum} and $params{Spheroid}) {
8701 SetGeogCS($self, $params{CoordinateSystem}, $params{Datum}, $params{Spheroid}, @parameters);
8702 } elsif ($params{CoordinateSystem} and $params{HorizontalCS} and $params{VerticalCS}) {
8703 SetCompoundCS($self, $params{CoordinateSystem}, $params{HorizontalCS}, $params{VerticalCS});
8705 SetProjCS($self, $params{CoordinateSystem});
8707 } elsif (exists $params{Projection}) {
8708 error(1, $params{Projection}, \%Geo::OSR::PROJECTIONS) unless exists $Geo::OSR::PROJECTIONS{$params{Projection}};
8709 my @parameters = ();
8710 @parameters = @{$params{Parameters}}
if ref($params{Parameters});
8711 if ($params{Projection} eq
'Albers_Conic_Equal_Area') {
8712 SetACEA($self, @parameters);
8713 } elsif ($params{Projection} eq
'Azimuthal_Equidistant') {
8714 SetAE($self, @parameters);
8715 } elsif ($params{Projection} eq
'Bonne') {
8716 SetBonne($self, @parameters);
8717 } elsif ($params{Projection} eq
'Cylindrical_Equal_Area') {
8718 SetCEA($self, @parameters);
8719 } elsif ($params{Projection} eq
'Cassini_Soldner') {
8720 SetCS($self, @parameters);
8721 } elsif ($params{Projection} eq
'Equidistant_Conic') {
8722 SetEC($self, @parameters);
8723 # Eckert_I, Eckert_II, Eckert_III, Eckert_V ?
8724 } elsif ($params{Projection} eq
'Eckert_IV') {
8725 SetEckertIV($self, @parameters);
8726 } elsif ($params{Projection} eq
'Eckert_VI') {
8727 SetEckertVI($self, @parameters);
8728 } elsif ($params{Projection} eq
'Equirectangular') {
8730 SetEquirectangular($self, @parameters) :
8731 SetEquirectangular2($self, @parameters);
8732 } elsif ($params{Projection} eq
'Gauss_Schreiber_Transverse_Mercator') {
8733 SetGaussSchreiberTMercator($self, @parameters);
8734 } elsif ($params{Projection} eq
'Gall_Stereographic') {
8735 SetGS($self, @parameters);
8736 } elsif ($params{Projection} eq
'Goode_Homolosine') {
8737 SetGH($self, @parameters);
8738 } elsif ($params{Projection} eq
'Interrupted_Goode_Homolosine') {
8740 } elsif ($params{Projection} eq
'Geostationary_Satellite') {
8741 SetGEOS($self, @parameters);
8742 } elsif ($params{Projection} eq
'Gnomonic') {
8743 SetGnomonic($self, @parameters);
8744 } elsif ($params{Projection} eq
'Hotine_Oblique_Mercator') {
8745 # Hotine_Oblique_Mercator_Azimuth_Center ?
8746 SetHOM($self, @parameters);
8747 } elsif ($params{Projection} eq
'Hotine_Oblique_Mercator_Two_Point_Natural_Origin') {
8748 SetHOM2PNO($self, @parameters);
8749 } elsif ($params{Projection} eq
'Krovak') {
8750 SetKrovak($self, @parameters);
8751 } elsif ($params{Projection} eq
'Lambert_Azimuthal_Equal_Area') {
8752 SetLAEA($self, @parameters);
8753 } elsif ($params{Projection} eq
'Lambert_Conformal_Conic_2SP') {
8754 SetLCC($self, @parameters);
8755 } elsif ($params{Projection} eq
'Lambert_Conformal_Conic_1SP') {
8756 SetLCC1SP($self, @parameters);
8757 } elsif ($params{Projection} eq
'Lambert_Conformal_Conic_2SP_Belgium') {
8758 SetLCCB($self, @parameters);
8759 } elsif ($params{Projection} eq
'miller_cylindrical') {
8760 SetMC($self, @parameters);
8761 } elsif ($params{Projection} =~ /^Mercator/) {
8762 # Mercator_1SP, Mercator_2SP, Mercator_Auxiliary_Sphere ?
8763 # variant is in Variant (or Name)
8764 SetMercator($self, @parameters);
8765 } elsif ($params{Projection} eq
'Mollweide') {
8766 SetMollweide($self, @parameters);
8767 } elsif ($params{Projection} eq
'New_Zealand_Map_Grid') {
8768 SetNZMG($self, @parameters);
8769 } elsif ($params{Projection} eq
'Oblique_Stereographic') {
8770 SetOS($self, @parameters);
8771 } elsif ($params{Projection} eq
'Orthographic') {
8772 SetOrthographic($self, @parameters);
8773 } elsif ($params{Projection} eq
'Polyconic') {
8774 SetPolyconic($self, @parameters);
8775 } elsif ($params{Projection} eq
'Polar_Stereographic') {
8776 SetPS($self, @parameters);
8777 } elsif ($params{Projection} eq
'Robinson') {
8778 SetRobinson($self, @parameters);
8779 } elsif ($params{Projection} eq
'Sinusoidal') {
8780 SetSinusoidal($self, @parameters);
8781 } elsif ($params{Projection} eq
'Stereographic') {
8782 SetStereographic($self, @parameters);
8783 } elsif ($params{Projection} eq
'Swiss_Oblique_Cylindrical') {
8784 SetSOC($self, @parameters);
8785 } elsif ($params{Projection} eq
'Transverse_Mercator_South_Orientated') {
8786 SetTMSO($self, @parameters);
8787 } elsif ($params{Projection} =~ /^Transverse_Mercator/) {
8788 my($variant) = $params{Projection} =~ /^Transverse_Mercator_(\w+)/;
8791 SetTMVariant($self, $variant, @parameters) :
8792 SetTM($self, @parameters);
8793 } elsif ($params{Projection} eq
'Tunisia_Mining_Grid') {
8794 SetTMG($self, @parameters);
8795 } elsif ($params{Projection} eq
'VanDerGrinten') {
8796 SetVDG($self, @parameters);
8798 # Aitoff, Craster_Parabolic, International_Map_of_the_World_Polyconic, Laborde_Oblique_Mercator
8799 # Loximuthal, Miller_Cylindrical, Quadrilateralized_Spherical_Cube, Quartic_Authalic, Two_Point_Equidistant
8800 # Wagner_I, Wagner_II, Wagner_III, Wagner_IV, Wagner_V, Wagner_VI, Wagner_VII
8801 # Winkel_I, Winkel_II, Winkel_Tripel
8803 SetProjection($self, $params{Projection});
8806 error(
"Not enough information to create a spatial reference object.");
8810 #** @method SetAxisMappingStrategy()
8812 sub SetAxisMappingStrategy {
8815 #** @method SetDataAxisToSRSAxisMapping()
8817 sub SetDataAxisToSRSAxisMapping {
8820 #** @method SetMercator2SP()
8822 sub SetMercator2SP {
8825 #** @method SetVerticalPerspective()
8827 sub SetVerticalPerspective {
8830 #** @method Validate()
8836 #** @method Geo::OSR::SpatialReference new(%params)
8838 # Create a new spatial reference object using a named parameter. This
8839 # constructor recognizes the following key words (alternative in
8840 # parenthesis): WKT (Text), Proj4, ESRI, EPSG, EPSGA, PCI, USGS, GML
8841 # (XML), URL, ERMapper (ERM), MapInfoCS (MICoordSys). The value
8842 # depends on the key.
8843 # - WKT: Well Known Text string
8844 # - Proj4: PROJ.4 string
8845 # - ESRI: reference to a list of strings (contents of ESRI .prj file)
8846 # - EPSG: EPSG code number
8847 # - EPSGA: EPSG code number (the resulting CS will have EPSG preferred axis ordering)
8848 # - PCI: listref: [PCI_projection_string, Grid_units_code, [17 cs parameters]]
8849 # - USGS: listref: [Projection_system_code, Zone, [15 cs parameters], Datum_code, Format_flag]
8851 # - URL: URL for downloading the spatial reference from
8852 # - ERMapper: listref: [Projection, Datum, Units]
8853 # - MapInfoCS: MapInfo style co-ordinate system definition
8855 # For more information, consult the import methods in <a href="http://www.gdal.org/classOGRSpatialReference.html">OGR documentation</a>.
8857 # @note ImportFrom* methods also exist but are not documented here.
8861 # $sr = Geo::OSR::SpatialReference->new( key => value );
8863 # @return a new Geo::OSR::SpatialReference object
8868 my $self = Geo::OSRc::new_SpatialReference();
8869 if (exists $param{WKT}) {
8870 ImportFromWkt($self, $param{WKT});
8871 } elsif (exists $param{Text}) {
8872 ImportFromWkt($self, $param{Text});
8873 } elsif (exists $param{Proj4}) {
8874 ImportFromProj4($self, $param{Proj4});
8875 } elsif (exists $param{ESRI}) {
8876 ImportFromESRI($self, @{$param{ESRI}});
8877 } elsif (exists $param{EPSG}) {
8878 ImportFromEPSG($self, $param{EPSG});
8879 } elsif (exists $param{EPSGA}) {
8880 ImportFromEPSGA($self, $param{EPSGA});
8881 } elsif (exists $param{PCI}) {
8882 ImportFromPCI($self, @{$param{PCI}});
8883 } elsif (exists $param{USGS}) {
8884 ImportFromUSGS($self, @{$param{USGS}});
8885 } elsif (exists $param{XML}) {
8886 ImportFromXML($self, $param{XML});
8887 } elsif (exists $param{GML}) {
8888 ImportFromGML($self, $param{GML});
8889 } elsif (exists $param{URL}) {
8890 ImportFromUrl($self, $param{URL});
8891 } elsif (exists $param{ERMapper}) {
8892 ImportFromERM($self, @{$param{ERMapper}});
8893 } elsif (exists $param{ERM}) {
8894 ImportFromERM($self, @{$param{ERM}});
8895 } elsif (exists $param{MICoordSys}) {
8896 ImportFromMICoordSys($self, $param{MICoordSys});
8897 } elsif (exists $param{MapInfoCS}) {
8898 ImportFromMICoordSys($self, $param{MapInfoCS});
8899 } elsif (exists $param{WGS}) {
8901 SetWellKnownGeogCS($self,
'WGS'.$param{WGS});
8903 confess last_error() if $@;
8905 error(
"Unrecognized/missing parameters: @_.");
8907 bless $self, $pkg
if defined $self;