The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Image-GeoTIFF-Tiled-0.08
River stage zero No dependents
++
/ Image::GeoTIFF::Tiled

NAME

Image::GeoTIFF::Tiled - Read data and extract shapes from tiled GeoTIFF rasters

SYNOPSIS

    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 ) );

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.

METHODS

CONSTRUCTOR

new($image_file)

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.

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.

IMAGE METADATA

A zero-value on any attribute indicates the value could not be determined. In general this shouldn't happen.

file

The filepath of the image.

length

The length (height) of the image in pixels.

width

The width of the image in pixels.

corners($proj)

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.

constrain_boundary($xmin,$ymin,$xmax,$ymax)

Returns a new (xmin,ymin,xmax,ymax) pixel boundary constrained to the image dimensions.

tile_length

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

tile_width

The width of a single tile in pixels.

tile_area

The number of pixels in a tile (tile_length * tile_width).

tile_step

The number of tiles in a row of the image. Computed as the tile number of the first tile in the second tile row.

tiles_across

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.)

tiles_down

The number of tiles in a column of the image. Computed as (ImageLength + TileLength - 1) / TileLength

tiles_total

The number of tiles in the image. Computed as TilesAcross * TilesDown.

number_of_tiles

The number of tiles in the image (libtiff function).

(This should equal tiles_total as a sanity check.)

tile_size

The total size (in bytes) of a tile of pixels (libtiff function).

tile_row_size

The number of bytes of a row of data in a tile (libtiff function).

bits_per_sample

Bits per cell of data.

The following should be true:

    PixelsInTile
        = tile_size * 8 / bits_per_sample 
        = tile_width * tile_length
sample_format

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.

PIXEL-PROJECTION TRANSFORMATIONS

These methods transform projection and pixel coordinates.

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

pix2tile($x, $y)

Returns the tile number of the given pixel coordinates.

pix2tile_m($tile, $i_t, $x, $y)

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

tile2pix($tile, $i_t)

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

pix2tileidx($x, $y)

Given pixel coordinates, returns the index into its tile.

DATA EXTRACTION

**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).

get_raw_tile($tile)

Returns the raw tile data as a packed string encoded by libtiff into the proper native format.

get_tile($tile)

Returns a reference to the tile data in an unpacked flat array.

get_tiles($ul, $br)

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.

tile2grid($tile | $tile_data)

Transforms a flat tile arrayref into a 2D grid of data.

Passing the tile number calls get_tile first.

tiles2grid($ul, $br | $tile_data)

Transforms a 3D tile array into a 2D grid of data.

Passing the upper-left/bottom-right tile numbers calls get_tiles first.

extract_grid($xmin, $ymin, $xmax, $ymax)

Extracts only those values bounded by the parameters into a 2D grid.

filter_shape($grid, $x0, $y0, $shape)

Applies a mask on $grid to the shape object by undef-ing values in $grid not in the $shape. Returns $grid.

mask_shape($grid, $x0, $y0, $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.

dump_tile($tile)

Pretty-prints the given tile to STDOUT (raw values).

ITERATION

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.

get_iterator(...)

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.

get_iterator_tile($tile)

Given a tile, returns an iterator constrained to the image boundary.

get_iterator_tiles($ul, $br)

Given a tile rectangle (upper-left,bottom-right), returns an iterator constrained to the image boundary.

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

Given a rectangular pixel boundary, returns an iterator constrained to the image boundary.

get_iterator_shape($shape, $proj)

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.

get_iterator_mask($shape, $proj, $buffer_size)

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.

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.

TODO

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.

SEE ALSO

Geo::Proj4, Geo::ShapeFile

COPYRIGHT & LICENSE

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.