/ 
Image-GeoTIFF-Tiled-0.03
River stage zero No dependents
/ Image::GeoTIFF::Tiled

NAME

Image::GeoTIFF::Tiled - A Perl interface to libgeotiff for reading tiled TIFF images, with support for extracting and iterating arbitrary shapes.

SYNOPSIS

use Image::GeoTIFF::Tiled;

my $t = Image::GeoTIFF::Tiled->new( $image_file );

# Dump meta info
$t->print_meta;

# Convert to pixel coordinates
$t->proj2pix_m($lon,$lat);
# Compute tile number
my $tile = $t->get_tile_pix($lon,$lat);
# Get index into the tile
my $idx = $t->get_pix_idx($lon,$lat);

my ($px,$py);
# Get pixel coordinates of 5th pixel in the 2nd tile
$t->set_pix_tile( 2, 5, $px, $py );
# Get the projected coordinates of the pixel coordinates
$t->pix2proj_m($px,$py);

# Get an arrayref of tile data (500th tile)
my $tile = $t->get_tile(500);
# Get a 2x2 3D arrayref of tile data
my $tiles = $t->get_tiles(500,500 + $t->tile_step + 1);
# 50th pixel value in the upper right tile:    $tiles->[0][1][50]

# Get an iterator for a rectangular pixel boundary:
my $iter = $t->get_iterator_pix( 
    $t->get_pix_tile( 500, 0 ),     
        # upper left coordinate (x_min,y_min)
    $t->get_pix_tile( 500 + $t->tile_step + 1, $t->tile_length * $t->tile_width - 1 )
        # bottom right coordinate (x_max,y_max)
);
# or: Get an iterator for an arbitrary shape
my $iter = $t->get_iterator_shape( $shape );
# Count the occurance of each pixel value
my %c;
$c{$v}++ while ( defined( my $v = $iter->next ) );

DESCRIPTION

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.

A copy of the source repository is hosted on github: http://github.com/blakew/Image-GeoTIFF-Tiled.

METHODS

CONSTRUCTOR

new($tiff_filepath)

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.

An exception will be thrown if the filepath is invalid, if the image isn't tiled, if the bits per sample isn't 8, or if the samples per pixel isn't 1.

IMAGE METADATA

file

The filepath of the TIFF image.

length

The length (height) of the image in pixels.

width

The width of the image in pixels.

tile_length

The length (height) of a single tile in pixels.

tile_width

The width of a single tile in pixels.

tile_size

The total size (in bytes) of a tile of pixels (= tile_width * tile_length if bps = 1).

tile_step

The number of tiles in a row of the image.

dump_tile($tile)

Pretty-prints the given tile.

PIXEL-PROJECTION TRANSFORMATIONS

center_pixel($x,$y)

Centers the given pixel coordinates to the middle of the pixel (mutative).

proj2pix_m($x,$y)

Transforms the given projection coordinate to its corresponding pixel coordinate (mutative).

proj2pix($x,$y)

Transforms the given projection coordinate, returning its corresponding pixel coordinate as a list.

pix2proj_m($x,$y)

Transforms the given pixel coordinate to its corresponding projection coordinate (mutative).

pix2proj($x,$y)

Transforms the given pixel coordinate, returning its corresponding projection coordinate as a list.

PIXEL-TILE TRANSFORMATIONS

get_tile_pix($x,$y)

Returns the tile number of the given pixel coordinates (see TIFFComputeTile in libtiff).

set_pix_tile($tile,$idx,$x,$y)

Given a tile number and the index into the tile, sets the corresponding pixel coordinates (mutative).

get_pix_tile($tile,$idx)

Given a tile number and the index into the tile, returns the corresponding pixel coordinates as a list.

get_pix_idx($x,$y)

Given pixel coordinates, returns the index into its tile.

TILE DATA

get_tile($n)

Returns a reference to a flat array containing the data in the nth tile.

get_tiles($ul,$br)

Returns a reference to a 3D array (a 2D grid of references to the flat tile arrays) containing the tile data between the upper left ($ul) and lower right ($ur) tiles.

extract_2D_array($x_min,$y_min,$x_max,$y_max,$shape)

Returns a reference to a 2D array of data contained in the pixel boundary ($x_min,$y_min,$x_max,$y_max) and constrained within the Image::GeoTIFF::Tiled::Shape $shape. Pass undef as $shape to just get the block of data without constraining to a shape; otherwise data outside of $shape will take the value -1.

Calling this method directly is equivalent to calling the iterator methods below and retrieving the underlying data via buffer() in Image::GeoTIFF::Tiled::Iterator.

ITERATION

get_iterator_pix($x_min,$y_min,$x_max,$y_max)

Given a rectangular pixel boundary, returns a Image::GeoTIFF::Tiled::Iterator object that can iterate over the pixel values in the given boundary, or undef if the given boundary is completely outside the image. If part of the boundary is outside, only those pixels that are inside the image will be used.

get_iterator_shape($shape)

Given a Image::GeoTIFF::Tiled::Shape object, returns a Image::GeoTIFF::Tiled::Iterator that can iterate over only those pixel values inside the arbitrary shape, or undef if the given shape is completely outside the image.

SEE ALSO

Image::GeoTIFF::Tiled::Shape, Image::GeoTIFF::Tiled::Iterator, Geo::Proj4

COPYRIGHT & LICENSE

Copyright 2009 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.