Geo::ShapeFile(3)

📦
version 3.03 · 2 versions
, in fedora 43

💖 Geo::ShapeFile 💖

okay bestie, welcome to the Geo::ShapeFile era — it's a User Contributed Perl Documentation moment, and we are reading ESRI GIS Shapefiles like it's nothing. no cap. ✨

🌸 NAME 🌸

Geo::ShapeFile — a Perl extension for handling ESRI GIS Shapefiles. it's giving cartography, it's giving data, it's giving slay. 🗺️

✨ 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});

like. look at her. she's so clean. 💅

🦋 ABSTRACT 🦋

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

💜 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. yes bestie, this is the same energy as the ABSTRACT, and honestly? the module said it twice because it meant it. 🫶

🎀 METHODS 🎀

💖 new ($filename_base)

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

Creates a new shapefile object. the first argument is the basename for your data — and there is no need to include the extension, because the module will automatically find the extensions it supports. so if you've got data files called roads.shp, roads.shx, and roads.dbf, you just do Geo::ShapeFile->new("roads"); and boom, new object, and the module loads the data it needs from the files as it needs it. 🪄

The second argument is optional and it's a hashref. rn only no_cache is supported. if you specify it, then data will not be cached in memory and the system will read from disk each time you access a shape. it'll save memory for large files, though. tradeoffs, bestie. ⚖️

🔥 type_is ($type)

Returns true if the major type of this data file is the same as the type passed to type_is(). vibe check passed, basically. ✅

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 (and shapefile indexes start at 1, don't forget). if called in a list context, returns a hash; if called in a scalar context, returns a hashref. she adapts. 💅

🌈 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. all the min/max girlies in one place. 📐

🧚 upper_left_corner() upper_right_corner()

🧚 lower_left_corner() lower_right_corner()

Returns a Geo::ShapeFile::Point object indicating the respective corners. four corners, four icons. ✨

⭐ height() width()

Returns the height and width of the area contained in the shp file. and like — heads up — 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. so don't come for her, she's just doing math. 😭

🎀 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). periodt. 🔄

💜 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. she's a helper, she's humble. 🫶

🦋 bounds_contains_point ($point)

Returns true if the specified point falls within the bounds of the current shp file. yes ma'am. ✅

🌸 file_version()

Returns the ShapeFile version number of the current shp/shx file. what's her version? iconic. 💅

👑 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 (and null shapes are the exception — they may appear in any data file). this returns the numeric value for the type, so 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 lets you iterate through all the shapes using for(1 .. $obj->shapes()) {. the loop girlies know. 🔁

🍓 records()

Returns the number of records contained in the current data. this is similar to shapes(), but you can use it 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. flexible queen. 🎀

🌈 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. same info, cuter packaging. ✨

🧚 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. two values, no drama. 🫶

💖 get_shp_record ($record_index)

Retrieve an shp record for the specified index. returns a Geo::ShapeFile::Shape object. this is the main character of the whole operation ngl. 👑

🎀 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. overlapping is her love language. 💜

💜 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. (and yes bestie, the argument order is exactly what it is — we don't question the original, we just vibe with it.) 🌸

🦋 bounds()

Returns the bounds for the current shp file. (x_min, y_min, x_max, y_max). that's the whole rectangle, in order, no notes. 📦

🌸 shx_handle() shp_handle() dbf_handle()

Returns the file handles associated with the respective data files. handles for days. 🫶

🔥 type ($shape_type_number)

Returns the name of the type associated with the given type id number. number in, name out. 🔢➡️🔤

🍓 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. she did the math for you, say thank you. 😌

🌈 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. context-aware icon. ✨

🧚 get_all_shapes()

Returns an array (or arrayref in scalar context) with all shape objects in the shapefile. all of them. every single one. 💖

⭐ 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. custom sort sub? oh she's fancy fancy. 💅

💖 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. live your truth, bestie. 🗺️

🎀 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. sharing is caring. 🫶

💜 get_spatial_index()

Returns the spatial index object, or undef if one has not been built. no index? undef. it's giving honest. 😭

🦋 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. (yes, spelled exactly like that, keep it cute.) ✍️

🌸 REPORTING BUGS 🌸

Please send any bugs, suggestions, or feature requests to

<https://github.com/shawnlaffan/Geo-ShapeFile/issues>.

we love feedback in this house. constructive only, be nice. 💖

✨ SEE ALSO ✨

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

the friend group. go say hi. 🫶

👑 AUTHOR 👑

Jason Kohles, <email@jasonkohles.com>

Shawn Laffan, <shawnlaffan@gmail.com>

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. free software, as a treat. 🎀

okay that's the whole page bestie, and just so you have the receipts: this was perl v5.42.0, dated 2025-07-25, from the Geo::ShapeFile(3) page. go read your shapefiles, you're gonna eat. 💖✨🦋🌸💅👑

📦 where this page comes from