Image::GeoTIFF::Tiled - Read data and extract shapes from tiled GeoTIFF rasters
use Image::GeoTIFF::Tiled; my $t = Image::GeoTIFF::Tiled->new( $image_file ); # Dump meta info $t->print_meta; # Dump last tile $t->dump_tile( $t->number_of_tiles - 1 ); # Get an iterator for an arbitrary shape my $iter = $t->get_iterator_shape( $shape ); # Get a histogram of pixel values my %c; $c{$v}++ while ( defined( my $v = $iter->next ) );
Image::GeoTIFF::Tiled provides an interface to libtiff and libgeotiff for reading raster data stored in tiled TIFF format conforming to the GeoTIFF specification. Several additional functions are provided for ease of access to the underlying geodata.
This library is only meant to process tiled GeoTIFF images, and in fact will fail during construction if the image isn't tiled. To create a tiled GeoTIFF from a non-tiled GeoTIFF, see the command-line utility gtifcp. Arbitrary raster data can be exported to the tiled GeoTIFF format with GIS software.
Returns a new Image::GeoTIFF::Tiled instance corresponding to the given TIFF filepath. Internally a filehandle to the image is stored along with some metadata.
Image::GeoTIFF::Tiled
As of 0.06, this supports bits per sample (bps) rasters of 8, 16, and 32 bits, and both integer and floating-point rasters. A bps value other than these will yield an exception. There's a chance of lurking bugs dealing with untested combinations of data types.
An exception will also be thrown if the filepath is invalid or if the image isn't tiled or if the samples per pixel isn't 1.
A zero-value on any attribute indicates the value could not be determined. In general this shouldn't happen.
The filepath of the image.
The length (height) of the image in pixels.
The width of the image in pixels.
Returns the 4 corners of the image as a list of [$x,$y] arrayrefs. The corners are in the following order: upper left, upper right, lower right, lower left.
Will be in projected coordinates if a Geo::Proj4 projection object isn't passed; otherwise geographic coordinates.
Returns a new (xmin,ymin,xmax,ymax) pixel boundary constrained to the image dimensions.
The length (height) of a single tile in pixels.
The width of a single tile in pixels.
The number of pixels in a tile (tile_length * tile_width).
The number of tiles in a row of the image. Computed as the tile number of the first tile in the second tile row.
The number of tiles in a row of the image. Computed as (ImageWidth + TileWidth - 1) / TileWidth.
(This should equal tile_step as a sanity check.)
tile_step
The number of tiles in a column of the image. Computed as (ImageLength + TileLength - 1) / TileLength
The number of tiles in the image. Computed as TilesAcross * TilesDown.
The number of tiles in the image (libtiff function).
(This should equal tiles_total as a sanity check.)
tiles_total
The total size (in bytes) of a tile of pixels (libtiff function).
The number of bytes of a row of data in a tile (libtiff function).
Bits per cell of data.
The following should be true:
PixelsInTile = tile_size * 8 / bits_per_sample = tile_width * tile_length
Data type of cells. Returns one of:
* 1 = unsigned integer data * 2 = two's complement signed integer data * 3 = IEEE floating point data [IEEE] * 4 = undefined data format
When unpacking with get_tile with an unknown value, uses 1 by default (as per the TIFF6 spec.).
Prints image metadata to STDOUT.
These methods transform projection and pixel coordinates.
Centers the given pixel coordinates to the middle of the pixel (mutative).
Transforms the given projection coordinate to its corresponding pixel coordinate (mutative).
Transforms the given projection coordinate, returning its corresponding pixel coordinate as a list.
Transforms the given pixel coordinate to its corresponding projection coordinate (mutative).
Transforms the given pixel coordinate, returning its corresponding projection coordinate as a list.
Returns the tile number of the given pixel coordinates.
Given a tile number and the index into the tile, sets the corresponding pixel coordinates (mutative).
Given a tile number and the index into the tile, returns the corresponding pixel coordinates as a list.
Given pixel coordinates, returns the index into its tile.
**NOTE**
The get_* methods may include padded values outside of the image boundary, which may or may not be zero (the TIFF6 spec only states that data must be present, not what values they contain).
Returns the raw tile data as a packed string encoded by libtiff into the proper native format.
Returns a reference to the tile data in an unpacked flat array.
Returns a reference to a 3D array (a 2D grid of references to the flat tile arrays) containing the rectangular tile data between the upper left ($ul) and lower right ($ur) tiles.
Transforms a flat tile arrayref into a 2D grid of data.
Passing the tile number calls get_tile first.
Transforms a 3D tile array into a 2D grid of data.
Passing the upper-left/bottom-right tile numbers calls get_tiles first.
Extracts only those values bounded by the parameters into a 2D grid.
Applies a mask on $grid to the shape object by undef-ing values in $grid not in the $shape. Returns $grid.
$grid
undef
$shape
Applies a mask on $grid to the shape object by undef-ing values in $grid not in the $shape. Returns a 2D mask of 0s and 1s corresponding to values in $grid, where 0 values at (row,col) are outside the image in (row,col) of $grid.
Pretty-prints the given tile to STDOUT (raw values).
These methods return a Image::GeoTIFF::Tiled::Iterator object that automatically handles image boundaries and shape masks.
All return undef if the given area is completely outside the image. If part of the boundary is outside, only those pixels that are inside the image will be used.
Note - these receive copies of data buffers, so start-up time and memory size may be an issue.
Convenience entry method to all of the get_iterator_* methods. The special case of no arguments returns an interator on the entire image. Otherwise this method dies if the parameters don't make sense.
Given a tile, returns an iterator constrained to the image boundary.
Given a tile rectangle (upper-left,bottom-right), returns an iterator constrained to the image boundary.
Given a rectangular pixel boundary, returns an iterator constrained to the image boundary.
Given a shape, returns an iterator constrained to the image boundary.
Applies filter_shape to a buffer (so that values outside the shape are undef'ed).
If not a Image::GeoTIFF::Tiled::Shape object, tries to load one with the optional $proj Geo::Proj4 projection object. This will die on failure.
$proj
Given a shape, returns an iterator constrained to the image boundary. Use undef for $proj if a projection isn't necessary.
Applies mask_shape to a buffer with a $buffer_size pixel extension on all sides. All buffered valeus are preserved, and instead a masking buffer of 0 and 1 values define which values are in the shape. This allows adjacent values ($iter->adjacencies) to be preserved as well, even those outside the shape.
Lightweight iterator - only pulls the data once, as needed, instead of copying into a buffer. Probably would be an anonymous sub that knows how to unpack data using a template that can apply shape masks.
Better error handling.
Geo::Proj4, Geo::ShapeFile
Copyright 2010 Blake Willmarth.
This program is free software; you can redistribute it and/or modify it under the terms of either:
the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or
the Artistic License version 2.0.
To install Image::GeoTIFF::Tiled, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Image::GeoTIFF::Tiled
CPAN shell
perl -MCPAN -e shell install Image::GeoTIFF::Tiled
For more information on module installation, please visit the detailed CPAN module installation guide.