NAME

Image::GeoTIFF::Tiled::Shape

SYNOPSIS

use Image::GeoTIFF::Tiled;

# Initiate an instance via a class factory method, importing a pre-existing shape object:
use Geo::ShapeFile;
my $shp_shape = ... # A Geo::ShapeFile::Shape retrieved from Geo::ShapeFile methods
my $shape = Image::GeoTIFF::Tiled::Shape->load_shape( $tiff, $proj, $shp_shape );

# OR Create your own:
my $shape = Image::GeoTIFF::Tiled::Shape->new({
    x_min => ...,
    y_min => ...,
    x_max => ...,
    y_max => ...
});
$shape->add_point($x,$y) for ...;

# Initiate the TIFF image object
my $t = Image::GeoTIFF::Tiled->new( $tiff );

# Get in iterator for the pixels in the shape
my $iter = $t->get_iterator( $shape );

DESCRIPTION

This class is meant to be used in conjuction with Image::GeoTIFF::Tiled in order to easily iterate over image pixels contained in an arbitrary shape. It does so by linking Image::GeoTIFF::Tiled::ShapePart's, which are essentially lines between two points, with all intermediate points along integer y-values interpolated.

Objects should be instantiated via the load_shape method for pre-defined shape-like objects (Geo::ShapeFile::Shape being an example). Otherwise they must be instantiated with a boundary, and points should be added sequentially.

Other than constructing a useful data structure for getting an iterator, there isn't any other stated purpose for this class.

All coordinates must be in pixels.

METHODS

CONSTRUCTOR

new( \%boundary )

new( \@boundary )

where %boundary has the x_min, y_min, x_max, and y_max keys filled or @boundary has them in that order. Pixel coordinates required. Without defining a boundary the constructor throws an exception.

FACTORY METHOD

load_shape( $tiff, $proj, $shape )

Loads a pre-defined shape object defined by an external class. Currently only loads Geo::ShapeFile::Shape objects.

Geo::Proj4 and Image::GeoTIFF::Tiled objects must be pre-loaded into the class before calling this method, unless the shape is already projected, in which case pass undef as the $proj parameter.

METHODS

x_min x_max y_min y_max

Retrieves the boundary values.

boundary

Equivalent to ($shape-x_min>, $shape-y_min>, $shape-x_max>, $shape-y_max>).

corners

Returns a list of four two-element arrayref's containing the upper left, lower left, upper right, and lower right corner coordinates, in that order.

num_parts

Returns the number of Image::GeoTIFF::Tiled::ShapePart's in this shape.

get_part($i)

Returns the ith Image::GeoTIFF::Tiled::ShapePart in this shape.

as_array

Returns a 2D array reference of [ start, end ] points corresponding to each part of the shape.

add_point($x,$y)

Adds the ($x,$y) point to this shape. Only used for making custom shapes.

reset_points

Resets internal points metadata. Only used for making custom shapes, after a series of connecting points are made concentric ("parts" in ShapeFile parlance).

project_boundary($proj,$b)

Class method. Returns the projected boundary using projection (Geo::Proj4) $proj and boundary $b, a 4-element array ref with x_min, y_min, x_max, y_max as values.

get_x($y)

Returns a reference to a sorted array containing all x-pixel values along the integer y latitude. This method is used to determine if a given pixel lies inside the shape by implementing a ray-casting algorithm using a state machine (either outside or inside).

Repeated values indicate a local horizontal vertex.

SEE ALSO

Geo::Proj4, Image::GeoTIFF::Tiled, Image::GeoTIFF::Tiled::Iterator, Image::GeoTIFF::Tiled::ShapePart, Geo::ShapeFile

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.