NAME

Geo::ShapeFile - Perl extension for handling ESRI GIS Shapefiles.

SYNOPSIS

  use Geo::ShapeFile;

  my $shapefile = new Geo::ShapeFile("roads");

  for(1 .. $shapefile->shapes()) {
    my $shape = $shapefile->get_shp_record($_);
    # see Geo::ShapeFile::Shape docs for what to do with $shape

    my %db = $shapefile->get_dbf_record($_);
  }

ABSTRACT

The Geo::ShapeFile module reads ESRI ShapeFiles containing GIS mapping data, it has support for shp (shape), shx (shape index), and dbf (data base) formats.

DESCRIPTION

The Geo::ShapeFile module reads ESRI ShapeFiles containing GIS mapping data, it has support for shp (shape), shx (shape index), and dbf (data base) formats.

METHODS

new($filename_base)

Creates a new shapefile object, the only argument it takes is the basename for your data (don't include the extension, the module will automatically find the extensions it supports). For example if you have data files called roads.shp, roads.shx, and roads.dbf, use 'new Geo::ShapeFile("roads");' to create a new object, and the module will load the data it needs from the files as it needs it.

type_is($numeric_type)

Returns true if the major type of this data file is the same as the type passed to type_is().

get_dbf_record($record_index)

Returns the data from the dbf file associated with the specified record index (shapefile indexes start at 1). If called in a list context, returns a hash, if called in a scalar context, returns a hashref.

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

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

Returns the minimum and maximum values for x, y, z, and m fields as indicated in the shp file header.

upper_left_corner() upper_right_corner()

lower_left_corner() lower_right_corner()

Returns a Geo::ShapeFile::Point object indicating the respective corners.

height() width()

Returns the height and width of the area contained in the shp file. Note that this likely does not return miles, kilometers, or any other useful measure, it simply returns x_max - x_min, or y_max - y_min. Whether this data is a useful measure or not depends on your data.

corners()

Returns a four element array consisting of the corners of the area contained in the shp file. The corners are listed clockwise starting with the upper left. (upper_left_corner, upper_right_corner, lower_right_corner, lower_left_corner)

area_contains_point($point,$x_min,$y_min,$x_max,$y_max)

Utility function that returns true if the Geo::ShapeFile::Point object in point falls within the bounds of the rectangle defined by the area indicated. See bounds_contains_point() if you want to check if a point falls within the bounds of the current shp file.

bounds_contains_point($point)

Returns true if the specified point falls within the bounds of the current shp file.

file_version()

Returns the ShapeFile version number of the current shp/shx file.

shape_type()

Returns the shape type contained in the current shp/shx file. The ESRI spec currently allows for a file to contain only a single type of shape (null shapes are the exception, they may appear in any data file). This returns the numeric value for the type, use type() to find the text name of this value.

shapes()

Returns the number of shapes contained in the current shp/shx file. This is the value that allows you to iterate through all the shapes using 'for(1 .. $obj->shapes()) {'.

records()

Returns the number of records contained in the current data. This is similar to shapes(), but can be used even if you don't have shp/shx files, so you can access data that is stored as dbf, but does not have shapes associated with it.

shape_type_text()

Returns the shape type of the current shp/shx file (see shape_type()), but as the human-readable string type, rather than an integer.

get_shx_record($record_index) =item get_shx_record_header($record_index)

Get the contents of an shx record or record header (for compatibility with the other get_* functions, both are provided, but in the case of shx data, they return the same information). The return value is a two element array consisting of the offset in the shp file where the indicated record begins, and the content length of that record.

get_shp_record_header($record_index)

Retrieve an shp record header for the specified index. Returns a two element array consisting of the record number and the content length of the record.

get_shp_record($record_index)

Retrieve an shp record for the specified index. Returns a Geo::ShapeFile::Shape object.

shapes_in_area($x_min,$y_min,$x_max,$y_max)

Returns an array of integers, consisting of the indices of the shapes that overlap with the area specified. Currently this is a very oversimplified function that actually finds shapes that have any point that falls within the specified bounding box. Currently it may miss some shapes that actually do overlap with the specified area, if there are two points outside the area that cause an edge to pass through the area, but neither of the end points of that edge actually fall within the area specified. Patches to make this function more useful would be welcome.

check_in_area($x1_min,$y1_min,$x1_max,$y1_max,$x2_min,$x2_max,$y2_min,$y2_max)

Returns true if the two specified areas overlap.

bounds()

Returns the bounds for the current shp file. (x_min, y_min, x_max, y_max)

shx_handle() shp_handle() dbf_handle()

Returns the file handles associated with the respective data files.

type($shape_type_number)

Returns the name of the type associated with the given type id number.

find_bounds(@shapes)

Takes an array of Geo::ShapeFile::Shape objects, and returns a hash, with keys of x_min,y_min,x_max,y_max, with the values for each of those ranges.

REPORTING BUGS

Please send any bugs, suggestions, or feature requests to <geo-shapefile-bugs@jasonkohles.com>.

SEE ALSO

Geo::ShapeFile::Shape Geo::ShapeFile::Point

AUTHOR

Jason Kohles, <email@jasonkohles.com>

COPYRIGHT AND LICENSE

Copyright 2002,2003 by Jason Kohles

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