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, $shp_shape, $proj );
    
    # 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 ...;
    $shape->finish_loading;
    
    # 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, $shape, $proj )

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 omit last argument.

METHODS

x_min y_min x_max y_max

Boundary values.

boundary

Returns the list of (x_min, y_min, x_max, y_max).

corners

Returns a list of four two-element arrayref's containing the upper left, upper right, lower right, and lower left 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).

sort_parts

Sorts the internal parts array on the upper point latitude (called by finish_loading).

finish_loading

Call when done making a custom shape.

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