Geo::GDAL

Version

These pages document the version 1.8 of the GDAL Perl API, which is extended from the older versions.

The documentation for the version 1.4 API.

The documentation for the version 1.5 API.

The documentation for the version 1.6 API.

The documentation for the version 1.7 API.

Documentation for the current development version.

Introduction

The Geo::GDAL modules are the Perl bindings to the GDAL/OGR library. The modules allow you to access and manipulate from Perl all geospatial data that the installed GDAL library is configured to read/write.

This documentation covers mainly the syntax of the bindings. For more in-depth documentation see the main documentation of GDAL and OGR.

Some arguments are optional and have a default value. This is illustrated like this:

SomeMethod(arg1, arg2 = 4);

arg1 is a required argument.

arg2 may be left out and if left out, will get the value 4 (in this case).

Only the last argument or arguments can be optional.

In some cases a method can be called in a traditional way and with named arguments (i.e. with a hash):

$object->method(1, 2, 3);
$object->method(number=>1, param=>2, other=>3);
$object->method({number=>1, param=>2, other=>3});

Note especially the difference between the second and the third versions. In some cases the named arguments must be given in an anonymous hash.

In some cases a method may behave differently depending on the parameters that it gets:

$object->method($hashref); # a method called with a reference to a hash
$object->method($arrayref); # a method called with a reference to an array

In some cases a method may examine the context in which it is called, and behave differently:

$object->method();
$return = $object->method(); # method called in scalar context
@return = $object->method(); # method called in list context

Many of the methods may throw an error, which can be caught by putting the call into eval{}; and then examining the contents of $@.

Class methods vs object methods

Some methods are class methods and some methods are object methods. Object methods are always invoked for objects, i.e.

$object->method();

while class methods are invoked either as methods

Geo::GDAL::Class->method();

or as subroutines

Geo::GDAL::Class::subroutine();

The disctinction between class methods and subroutines is subtle but often important. The method invocation passes the class name as the first argument while the subroutine invocation does not. Thus constructors (new and create) must be called as class methods.

Exceptions

Geo::GDAL uses the Perl exception mechanism in such a way that exceptions that are classified in GDAL as failures or fatal errors trigger a Perl exception, and an exception that is classified as a warning triggers a Perl warning.

Perl exceptions can be caught by eval() and Perl warnings can be caught by signal '__WARN__'. Examples:

use Geo::GDAL;
eval {
    $point = Geo::OGR::Geometry->create(WKT=>"POINTXX(1 1)");
};
print STDERR "Error: $@";

Prints:

Error: RuntimeError OGR Error: Unsupported geometry type

use Geo::GDAL;
BEGIN { $SIG{'__WARN__'} = sub {  print STDERR "Warning: @_"; } }
Geo::GDAL::Driver('GTiff')->Create('x',10,10,1,'Byte',{a=>'b'});

Prints:

Warning: Driver GTiff does not support a creation option at site/lib/Geo/GDAL.pm line 771.

Note

This documentation is generated from files within the GDAL distribution (directory swig/perl) with a tweaked version of Perl Doxygen Filter with Doxygen.