NAME

Geo::ShapeFile::Shape - Geo::ShapeFile utility class.

SYNOPSIS

use Geo::ShapeFile::Shape::Index;

my $index = Geo::ShapeFile::Shape->new;
#  $pt1 and $pt2 are point objects in this example.  
my $segment = [$pt1, $pt2];  #  example of something to pack into the index.
my @bbox = ($x_min, $y_min, $x_max, $y_max);
$index->insert($segment, @bbox);

ABSTRACT

This is a utility class for L<Geo::ShapeFile> that indexes shape objects.

DESCRIPTION

This is a 2-d block-based index class for Geo::ShapeFile::Shape objects. It probably has more generic applications, of course.

It uses a flat 2-d structure comprising a series of blocks of full width which slice the shape along the y-axis (it should really also use blocks along the x axis).

The index coordinates are simply the number of blocks across and up from the minimum coordinate specified in the new() call. These are stoed as strings jpoined by a colon, so 0:0 is the lower left. Negative block coordinates can occur if data are added which fall outside the speficied bounds. This should not affect the index, though, as it is merely a relative offset.

It is used internally by Geo::ShapeFile::Shape, so look there for examples. The method names are adapted from Tree::R to make transition easier during development, albeit the argument have morphed so it is not a drop-in replacement.

EXPORT

None by default.

METHODS

new($n_blocks_y, @bbox)

Creates a new Geo::ShapeFile::Shape::Index objectand returns it.

$n_blocks_y is the number of blocks along the y-axis. @bbox is the bounding box the index represents (x_min, y_min, x_max, y_max).

insert($item, $min_x, $min_y, $max_x, $max_y)

Adds item $item to the blocks which overlap with the specified bounds. Returns the number of blocks the item was added to.

query_point($x, $y)

Returns an array of objects on the block contains point $x,$y. Returns an arrayref in scalar context.

get_x_max() get_x_min() get_y_max() get_y_min()

Bounds of the index, as set in the call to ->new(). There is no guarantee they are the bounds of the data, as data outside the original bounds can be indexed.

get_y_res()

Block resolution along the y-axis.

snap_to_index ($x, $y)

Returns the index key associated with point $x,$y. Does not check if it is outside the bounds of the index, so negative index values are possible.

REPORTING BUGS

Please send any bugs, suggestions, or feature requests to https://github.com/shawnlaffan/Geo-ShapeFile/issues.

SEE ALSO

Geo::ShapeFile::Shape

AUTHOR

Shawn Laffan, <shawnlaffan@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2014-2023 by Shawn Laffan

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.