NAME

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

SYNOPSIS

use Geo::ShapeFile::Shape;

my $shape = Geo::ShapeFile::Shape->new;
$shape->parse_shp($shape_data);

ABSTRACT

This is a utility class for Geo::ShapeFile that represents shapes.

DESCRIPTION

This is the Geo::ShapeFile utility class that actually contains shape data for an individual shape from the shp file.

EXPORT

None by default.

METHODS

new()

Creates a new Geo::ShapeFile::Shape object, takes no arguments and returns the created object. Normally Geo::ShapeFile does this for you when you call its get_shp_record() method, so you shouldn't need to create a new object. (Eventually this module will have support for _creating_ shapefiles rather than just reading them, then this method will become important.

num_parts()

Returns the number of parts that make up this shape.

num_points()

Returns the number of points that make up this shape.

points()

Returns an array of Geo::ShapeFile::Point objects that contains all the points in this shape. Note that because a shape can contain multiple segments, which may not be directly connected, you probably don't want to use this to retrieve points which you are going to plot. If you are going to draw the shape, you probably want to use get_part() to retrieve the individual parts instead.

get_part($part_index);

Returns the specified part of the shape. This is the information you want if you intend to draw the shape. You can iterate through all the parts that make up a shape like this:

for(1 .. $obj->num_parts) {
  my $part = $obj->get_part($_);
  # ... do something here, draw a map maybe
}

shape_type()

Returns the numeric type of this shape, use Geo::ShapeFile::type() to determine the human-readable name from this type.

shape_id()

Returns the id number for this shape, as contained in the shp file.

x_min() x_max() y_min() y_max()

z_min() z_max() m_min() m_max()

Returns the minimum/maximum ranges of the X, Y, Z, or M values for this shape, as contained in it's header information.

has_point($point)

Returns true if the point object provided matches one of the points in the shape. Note that this does a simple comparison with the points that make up the shape, it will not find a point that falls along a vertex between two points in the shape. See the Geo::ShapeFile::Point documentation for a note about how to exclude Z and/or M data from being considered when matching points.

contains_point($point); =item contains_point($point, $use_index);

Returns true if the specified point falls in the interior of this shape and false if the point is outside the shape. Return value is unspecified if the point is one of the vertices or lies on some segment of the bounding polygon.

Passing $use_index uses a spatial index if defined (building it if needed). See build_spatial_index for more details. This will be the default behaviour in a future release.

Note that the algorithm uses a sidedness algorithm ignoring Z and M fields and so will likely not work if the point is contained within a shape winding the wrong way. Polygon shapes should be anticlockwise for outer boundaries, and clockwise for inner void polygons.

build_spatial_index ($index_res)

Builds a spatial index for use in contains_point(). $index_res is a positive integer which sets the nnumber of along the y-axis. A value of 0 lets the system determine the number.

get_spatial_index()

Gets the spatial index. This is a hash indexed by part number. Returns a hash reference in scalar context.

bounds

Returns the object's bounds as an array (x_min, y_min, x_max, y_max). Returns an array ref in scalar context.

get_segments($part)

Returns an array consisting of array hashes, which contain the points for each segment of a multi-segment part.

vertex_centroid( $part );

Returns a Geo::ShapeFile::Point that represents the calculated centroid of the shapes vertices. If given a part index, calculates just for that part, otherwise calculates it for the entire shape. See "centroid" for more on vertex_centroid vs area_centroid.

area_centroid( $part );

Returns a Geo::ShapeFile::Point that represents the calculated area centroid of the shape. If given a part index, calculates just for that part, otherwise calculates it for the entire shape. See "centroid" for more on vertex_centroid vs area_centroid.

centroid($part)

For backwards-compatibility reasons, centroid() is currently an alias to vertex_centroid(), although it would probably make more sense for it to point to area_centroid(). To avoid confusion (and possible future deprecation), you should avoid this and use either vertex_centroid or area_centroid.

dump()

Returns a text dump of the object, showing the shape type, id number, number of parts, number of total points, the bounds for the X, Y, Z, and M ranges, and the coordinates of the points in each part of the shape.

REPORTING BUGS

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

SEE ALSO

Geo::ShapeFile

AUTHOR

Jason Kohles, <email@jasonkohles.com>

Shawn Laffan, <shawnlaffan@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2002-2013 by Jason Kohles

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.