=head1 NAME

gdal - A part of the Perl interface to the GDAL library.

=head1 SYNOPSIS

  use gdalconst;
  use gdal;

=head1 ABSTRACT

This module is a part of the Perl bindings to the GDAL library. The
GDAL modules allows you to access and manipulate from Perl all
geospatial data that the installed GDAL library is configured to
read/write.

=head1 STATUS

This module is beta quality. As most of the names and calling
conventions come directly from the underlying GDAL library they are
quite stable and will continue to work like they do now. However, many
things could, should, and will be made more perlish.

Generally, those methods which are documented, have been tested. If
the method or constructor you are looking for is not documented,
perhaps there is another way of doing what you want to do.

=head1 DESCRIPTION

The gdal module allows a geospatial programmer to use the GDAL library
with the ease and comfort of Perl. Find out more about GDAL at
http://www.gdal.org.

To discuss gdal, ask questions and flame/praise the authors, join
gdal-dev@lists.maptools.org at
http://lists.maptools.org/mailman/listinfo/gdal-dev/.

=head1 PACKAGE METHODS

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

SomeMethod(arg1, arg2 = 4);

arg1 is a required argument and an example or a variable with illustrative
name is given

arg2 is optional and if left off, will get the value 4 (in this case)

=over

=item UseExceptions

  Turned on by default.

=item DontUseExceptions

=item Debug

=item Error

=item PushErrorHandler

=item PopErrorHandler

=item ErrorReset

=item GetLastErrorNo

=item GetLastErrorType

=item GetLastErrorMsg

=item PushFinderLocation

=item PopFinderLocation

=item FinderClean

=item FindFile

=item SetConfigOption

=item GetConfigOption

=item GCPsToGeoTransform

=item AllRegister

  Done by default.

=item GetCacheMax

=item SetCacheMax

=item GetCacheUsed

=item GetDataTypeSize

=item DataTypeIsComplex

=item GetDataTypeName

=item GetDataTypeByName

=item GetColorInterpretationName

=item GetPaletteInterpretationName

=item DecToDMS

=item PackedDMSToDec

=item DecToPackedDMS

=item ParseXMLString

=item SerializeXMLTree

=item GetDriverCount

  $n = gdal::GetDriverCount();

=item GetDriverByName

  $driver = gdal::GetDriverByName('driver name');

The driver name is the $driver->{ShortName}, but that is a chicken and
an egg problem!

=item GetDriver

  $driver = gdal::GetDriver($i);

=item Open

  $dataset = gdal::Open('filename', 
    $access = $gdalconst::GA_ReadOnly);

  $access = $gdalconst::GA_ReadOnly | $gdalconst::GA_Update

=item OpenShared

=item AutoCreateWarpedVRT

=back

=head1 CLASSES

=head2 gdal::MajorObject

Superclass of gdal::Driver, gdal::Dataset, and gdal::Band

=over

=item GetDescription

=item SetDescription

=item GetMetadata

  $metadata = $object->GetMetadata();

=item SetMetadata

=back

=head2 gdal::Driver

=over

=item ShortName

  $driver->{ShortName}

=item LongName

  $driver->{LongName}

=item HelpTopic

  $driver->{HelpTopic}

=item Create

  $dataset = $driver->Create('filename', $width, $height, 
    $bands = 1, $type = $gdalconst::GDT_Byte, $options = []);

=item CreateCopy

  $dataset = $driver->CreateCopy('filename', $src_dataset, 
    $strict =1, $options = []);

=item Delete

=back

=head2 gdal::Dataset

=over

=item RasterXSize

  $dataset->{RasterXSize}

=item RasterYSize

  $dataset->{RasterYSize}

=item RasterCount

  $dataset->{RasterCount}

=item GetDriver

=item GetRasterBand

  for $i (1..$dataset->RasterCount) {
    $band = $dataset->GetRasterBand($i);
  }

=item GetProjection

  $projection = $dataset->GetProjection;

=item GetProjectionRef

=item SetProjection

  $dataset->SetProjection($projection);

=item GetGeoTransform

  $transform = $dataset->GetGeoTransform();

=item SetGeoTransform

  @transform = ($minX, $dx, 0, $maxY, 0, $dy);
  $dataset->SetGeoTransform(\@transform);

=item BuildOverviews

=item GetGCPCount

  $gcp_count = $dataset->GetGCPCount();

=item GetGCPProjection

  $gcp_projection = $dataset->GetGCPProjection();

=item GetGCPs

An example:

  my $gcps = $dataset->GetGCPs();
  for (0..$#$gcps) {
    $x[$_] = $gcps->[$_]->{GCPX};
    $y[$_] = $gcps->[$_]->{GCPY};
  }

=item SetGCPs

An example:

  my @gcps = ();
  push @gcps,new gdal::GCP($x1, $y1);
  push @gcps,new gdal::GCP($x2, $y2);
  $dataset->SetGCPs(\@gcps, "some projection");

=item FlushCache

=item AddBand

=item WriteRaster

=back

=head2 gdal::Band

=over

=item XSize

  $band->{XSize}

=item YSize

  $band->{YSize}

=item DataType

  $band->{DataType}

=item GetRasterColorInterpretation

=item SetRasterColorInterpretation

=item GetNoDataValue

  $value = $band->GetNoDataValue;

=item SetNoDataValue

  $band->SetNoDataValue($value);

=item GetMinimum

=item GetMaximum

=item GetOffset

=item GetScale

=item GetOverviewCount

=item GetOverview

=item Checksum

=item ComputeRasterMinMax

=item Fill

=item ReadRaster

  $scanline = $band->ReadRaster( 0, 0, $width, 1 );
  @data = unpack("i[$width]", $scanline);

See also the example below.

=item WriteRaster

  SWITCH: for ($band->{DataType}) {
    if ($_ == $gdalconst::$GDT_Byte) { $type = 'C'; last SWITCH; }
    if ($_ == $gdalconst::$GDT_Int16) { $type = 's'; last SWITCH; }
    if ($_ == $gdalconst::$GDT_Int32) { $type = 'i'; last SWITCH; }
    $nothing = 1;
  }

  unless ($nothing) {

    $buf = pack($type.'['.$width*$height.']',@data);

    $band->WriteRaster( $xoff, $yoff, $width, $height, $buf );

  }

  The $type chars are listed in the documentation for "pack" in man perlfunc.

=item FlushCache

=item GetRasterColorTable

  $colortable = $band->GetRasterColorTable;

=item SetRasterColorTable

  $band->SetRasterColorTable($colortable);

=back

=head2 gdal::ColorTable

  $colortable = new gdal::ColorTable(
    $palette_interpretation = $gdalconst::GPI_RGB);

=over

=item Clone

=item GetPaletteInterpretation

=item GetCount

=item GetColorEntry

  @color = $colortable->GetColorEntryAsRGB($i);

=item GetColorEntryAsRGB

  @color = $colortable->GetColorEntryAsRGB($i);

=item SetColorEntry

  @color = (255,0,0,255); # an example, opaque red, 
                          # and RGBA color interpretation
  $colortable->SetColorEntry($i, \@color);

=back

=head2 gdal::GCP

=over

=item GCPX

  $gcp->{GCPX}

=item GCPY

  $gcp->{GCPY}

=item GCPZ

  $gcp->{GCPZ}

=item GCPPixel

  $gcp->{GCPPixel}

=item GCPLine

  $gcp->{GCPLine}

=item Info

  $gcp->{Info}

=item Id

  $gcp->{Id}

=back

=head1 KNOWN BUGS

The reference counting scheme is not yet implemented. Make sure that
parents are not deleted before their children! Use "my" a lot.  Do not
give undefined/uninitialized variables to methods.

=head1 SEE ALSO

L<perl>(1), L<perlfunc>(1), L<gdalconst>(3pm), L<osr>(3pm), L<ogr>(3pm).

http://www.gdal.org

=head1 AUTHORS

The GDAL bindings team (in alphabetical order):

ari.jolma at tkk.fi
cfis at interserv.com
hobu at iastate.edu
kruland at ku.edu
warmerdam at pobox.com

=head1 COPYRIGHT AND LICENSE

Copyright 2005-2006 by the GDAL bindings team.

This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Library General Public License for more details.

You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the 
Free Software Foundation, Inc., 59 Temple Place - Suite 330, 
Boston, MA  02111-1307  USA.