NAME Geo::GDAL - read/write raster-based GIS data with the GDAL library SYNOPSIS use Geo::GDAL; my $data = Geo::GDAL::Open("sample.tif", GA_Update) ; my $transform = $data->GetGeoTransform; my $inv = Geo::GDAL::InvGeoTransform($transform); my ($pixel_x, $pixel_y) = Geo::GDAL::ApplyGeoTransform($inv, $geo_x, $geo_y); my $band = $data->GetRasterBand(1); my $data = $band->Read($pixel_x, $pixel_y, 10, 10); my $value = $data->[$x][$y]; $band->Write($pixel_x, $pixel_y, $data); my $type = $band->GetRasterDataType; # e.g. GDT_Float32 my $buf = $band->RasterIO( GF_Read, $pixel_x, $pixel_y, 8, 8, GDT_Float32); my @stream = unpack("f*", $buf); DESCRIPTION Geo::GDAL uses the powerful Geospatial Data Abstraction Library, or libgdal, to read and write geospatial raster data from Perl. Geo::GDAL provides OO-style classes for basic GDAL constructs, such as drivers, datasets, raster bands, color tables, Geo::GDAL can, for example, open a GeoTiff of elevation data, and obtain the elevation at any point. This software is ALPHA quality -- the XS bindings aren't done yet, so a lot may break. You must have the GDAL library (including development files) installed before attempting to build and install Geo::GDAL! CLASSES Geo::GDAL attempts to provide bindings for all of the basic functions in the GDAL C API, which is documented at . In general, the "GDAL" prefix has been removed, but the method names are otherwise still the same. Geo::GDAL breaks the GDAL C API down into the following packages. The matching C struct is given in parentheses. Where possible, C functions that take a particular struct as their first argument have been turned into object methods in the Perl class matching the C struct. Geo::GDAL::Driver (GDALDriverH) Geo::GDAL::Dataset (GDALDriverH) Geo::GDAL::RasterBand (GDALRasterBandH) Geo::GDAL::ColorTable (GDALColorTableH) Geo::GDAL::ColorEntry (GDALColorEntry) Geo::GDAL::OptionDefinition (GDALOptionDefinition) Geo::GDAL::GCP (GDAL_GCP) Geo::GDAL::RPCInfo (GDALRPCInfo) SUPPORTED FUNCTIONS AND METHODS The functions and methods from the following packages are more or less expected to work. Other functions and methods may work as expected, but OTOH, they may not. In particular GCP and ColorEntry support may be little broken. Support for other functions and methods will be hopefully added in future releases. Geo::GDAL functions AllRegister() Note that Geo::GDAL::AllRegister() is called when Geo::GDAL is imported, so you do not need to call it yourself. ApplyGeoTransform($xform, $pixel, $line) Applies the affine transform stored in $xform: $x = $xform->[0] + $xform->[1] * $pixel + $xform->[2] * $line; $y = $xform->[3] + $xform->[4] * $pixel + $xform->[5] * $line; Returns ($x, $y). If you pass an inverted affine transform to ApplyGeoTransform, the $pixel and $line arguments become $x and $y, and pixel and line values are returned instead. GetCacheMax() GetCacheUsed() GetColorInterpretationName() GetDataTypeName() GetDataTypeSize() GetDescription() GetDriver() Returns a Geo::GDAL::Driver object. GetDriverByName() Returns a Geo::GDAL::Driver object. GetDriverCount() GetPaletteInterpretationName() InvGeoTransform($transform) Takes a reference to a six-element list containing an affine transform. Returns a reference to a six-element list containing the inverse affine transform. Open($filename, $access) Instantiates a Geo::GDAL::Dataset object. Use the GA_ReadOnly and GA_Update constants to specify read-only versus read/write access. OpenShared($filename, $access) Returns a Geo::GDAL::Dataset object. ReadWorldFile(pszBaseFilename, pszExtension) Returns a reference to a six-element list containing the affine transform. SetCacheMax($nBytes) SetDescription() VersionInfo() WriteWorldFile($filename, $extension, $transform) Takes a filename, a file extension, and a reference to a six-element list containing the affine transform. Geo::GDAL::Driver methods DeleteDataset($filename) GetDriverHelpTopic() GetDriverLongName() GetDriverShortName() Geo::GDAL::Dataset methods Close() Called automatically when a Geo::GDAL::Dataset is destroyed. DereferenceDataset() FlushCache() GetAccess() GetDatasetDriver() Returns a Geo::GDAL::Driver object. GetGeoTransform() Returns a reference to a six-element list containing the affine transform. GetProjectionRef() GetRasterBand($n) Fetch raster band $n. Raster band numbering starts at 1. Returns a Geo::GDAL::RasterBand object. GetRasterCount() GetRasterXSize() GetRasterYSize() ReferenceDataset() SetGeoTransform($transform) $transform should be a reference to a six-element list containing the affine transform. SetProjection($proj) Geo::GDAL::RasterBand methods ComputeRasterMinMax($approxOK) Returns ($min, $max). FillRaster($realValue, $imaginaryValue) FlushRasterCache() GetBandDataset() GetBandNumber() GetBlockSize() Returns ($x_size, $y_size) in pixels. GetRasterAccess() GetRasterBandXSize() GetRasterBandYSize() GetRasterCategoryNames() Returns a reference to a list of scalars, or undef if no category names are available. GetRasterColorInterpretation() GetRasterColorTable() Returns a Geo::GDAL::ColorTable object. GetRasterDataType() GetRasterMaximum() GetRasterMetadata() Returns a reference to a list of scalars, or undef if no metadata is available. GetRasterMinimum() GetRasterNoDataValue() GetRasterSampleOverview($n) Returns an overview band of type Geo::GDAL::RasterBand containing at least $n pixels. GetRasterUnitType() HasArbitraryOverviews() RasterIO($RWFlag, $XOff, $YOff, $XSize, $YSize, $Buffer, $DataType) Reads or writes a block of data from the raster band $XSize pixels wide and $YSize pixels high, starting at ($XOff, $YOff) . The data is read from/written to $Buffer, which should be an ordinary scalar, and is of type $DataType, which should be one of the GDT_* constants. When reading, undef may be passed in place of $Buffer, in which case Geo::GDAL will allocate a scalar and return it. Otherwise, RasterIO() returns $Buffer. $Buffer is a packed scalar. Getting the data in and out of $Buffer involves using pack() /unpack() and a template matching the data type specified. Chances are good you will want to use Geo::GDAL::Dataset's Read() and Write() helper methods, instead. Read($XOff, $YOff, $XSize, $YSize) Read data from the raster band starting at pixel ($XOff, $YOff) into a table of values -- a list of lists. The band's native data type is used. Returns undef on failure. If $YSize is not provided, the area is assumed to be square; if $XSize is not provided, only one pixel is returned. ReadBlock($XBlockOff, $YBlockOff) Read a "natural" block of data. Returns a packed scalar. You will need to call GetRasterDataType() to figure out which unpack() template to unpack the data with. See the gdal.h API documentation for more details. Chances are good you will want to use Geo::GDAL::Dataset's Read() and Write() helper methods, instead. SetRasterCategoryNames($names) $names must be a reference to a list of scalars. SetRasterColorInterpretation($interp) SetRasterColorTable($table) SetRasterNoDataValue($val) Write($XOff, $YOff, $Data) Writes a table of values (list of lists) into the raster band starting at pixel ($XOff, $YOff) . The band's native data type is assumed, and floating point values are truncated as necessary. Returns undef on failure. WriteBlock($XBlockOff, $YBlockOff, $Data) Write a "natural" block of data from a packed scalar. You will need to call GetRasterDataType() to figure out which pack() template to pack the data with. See the gdal.h API documentation for more details. Chances are good you will want to use Geo::GDAL::Dataset's Read() and Write() helper methods, instead. EXPORT Geo::GDAL exports a ton of GDAL-related constants by default. Enjoy! BUGS Admittedly tons. The bindings need to be finished. Patches welcome! SEE ALSO GDAL homepage at In particular you will want to familiarize yourself with the GDAL C API, which is documented: A tutorial to the API is available at: Finally, for which this was written. THANKS Much appreciation is due to Frank Warmerdam for writing the GDAL library, as well as many other useful Open Source GIS tools. Frank's homepage is at . Appreciation is further due my collaborators Jo Walsh and Rich Gibson for providing the motivation and moral support. Rich contributed documentation as well. Also, thank you, Nick Clark, for answering my silly XS questions on #p5p. AUTHOR Schuyler D. Erle COPYRIGHT AND LICENSE Copyright (C) 2004 by Schuyler Erle This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.