NAME

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

SYNOPSIS

use Geo::ShapeFile;

my $shapefile = Geo::ShapeFile->new('roads');

#  note that IDs are 1-based
foreach my $id (1 .. $shapefile->shapes()) {
  my $shape = $shapefile->get_shp_record($id);
  # see Geo::ShapeFile::Shape docs for what to do with $shape

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

#  As before, but do not cache any data.
#  Useful if you have large files and only need to access
#  each shape once or a small nmber of times.
my $shapefile = Geo::ShapeFile->new('roads', {no_cache => 1});

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)

new ($filename_base, {no_cache => 1})

Creates a new shapefile object. The first argument is the basename for your data (there is no need to 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 Geo::ShapeFile->new("roads"); to create a new object, and the module will load the data it needs from the files as it needs it.

The second (optional) argument is a hashref. Currently only no_cache is supported. If specified then data will not be cached in memory and the system will read from disk each time you access a shape. It will save memory for large files, though.

type_is ($type)

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

The $type argument can be either the numeric code (see "shape_type"), or the string code (see "shape_type_text").

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)

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 listing which shape IDs have bounding boxes that overlap with the area specified.

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

get_dbf_field_names()

Returns an array of the field names in the dbf file, in file order. Returns an array reference if used in scalar context.

get_all_shapes()

Returns an array (or arrayref in scalar context) with all shape objects in the shapefile.

get_shapes_sorted()

get_shapes_sorted (\@shapes, \&sort_sub)

Returns an array (or arrayref in scalar context) of shape objects sorted by ID. Defaults to all shapes, but will also take an array of Geo::ShapeFile::Shape objects. Sorts by record number by default, but you can pass your own sub for more fancy work.

get_shapes_sorted_spatially()

get_shapes_sorted_spatially (\@shapes, \&sort_sub)

Convenience wrapper around get_shapes_sorted to sort spatially (south-west to north-east) then by record number. You can pass your own shapes and sort sub. The sort sub does not need to be spatial since it will sort by whatever you say, but it is your code so do what you like.

build_spatial_index()

Builds a spatial index (a Tree::R object) and returns it. This will be used internally for many of the routines, but you can use it directly if useful.

get_spatial_index()

Returns the spatial index object, or undef if one has not been built.

get_dbf_field_info()

Returns an array of hashes containing information about the fields. Useful if you are modifying the shapes and then writing them out to a new shapefile using Geo::Shapefile::Writer.

REPORTING BUGS

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

SEE ALSO

Geo::ShapeFile::Shape, Geo::ShapeFile::Point, Geo::Shapefile::Writer, Geo::GDAL::FFI

AUTHOR

Jason Kohles, <email@jasonkohles.com>

Shawn Laffan, <shawnlaffan@gmail.com>

COPYRIGHT AND LICENSE

Copyright 2002-2013 by Jason Kohles (versions up to and including 2.52)

Copyright 2014-2023 by Shawn Laffan (versions 2.53 -)

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