NAME

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

SYNOPSIS

  use Geo::ShapeFile::Shape;

  my $shape = new Geo::ShapeFile::Shape;
  $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 it's 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 provided is 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);

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.

Note that the return value is actually a winding-number computed ignoring Z and M fields and so will be negative if the point is contained within a shape winding the wrong way.

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 <geo-shapefile-bugs@jasonkohles.com>.

SEE ALSO

Geo::ShapeFile

AUTHOR

Jason Kohles, <email@jasonkohles.com<gt>

COPYRIGHT AND LICENSE

Copyright 2002 by Jason Kohles

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