1Geo::ShapeFile(3) User Contributed Perl Documentation Geo::ShapeFile(3)
2
6 Geo::ShapeFile - Perl extension for handling ESRI GIS Shapefiles.
7
9 use Geo::ShapeFile;
10 my $shapefile = Geo::ShapeFile->new('roads');
12 # note that IDs are 1-based
14 foreach my $id (1 .. $shapefile->shapes()) {
15 my $shape = $shapefile->get_shp_record($id);
16 # see Geo::ShapeFile::Shape docs for what to do with $shape
17 my %db = $shapefile->get_dbf_record($id);
19 }
20 # As before, but do not cache any data.
22 # Useful if you have large files and only need to access
23 # each shape once or a small nmber of times.
24 my $shapefile = Geo::ShapeFile->new('roads', {no_cache => 1});
25
27 The Geo::ShapeFile module reads ESRI ShapeFiles containing GIS mapping
28 data, it has support for shp (shape), shx (shape index), and dbf (data
29 base) formats.
30
32 The Geo::ShapeFile module reads ESRI ShapeFiles containing GIS mapping
33 data, it has support for shp (shape), shx (shape index), and dbf (data
34 base) formats.
35
37 new ($filename_base)
38 new ($filename_base, {no_cache => 1})
39 Creates a new shapefile object. The first argument is the basename
40 for your data (there is no need to include the extension, the
41 module will automatically find the extensions it supports). For
42 example if you have data files called roads.shp, roads.shx, and
43 roads.dbf, use "Geo::ShapeFile->new("roads");" to create a new
44 object, and the module will load the data it needs from the files
45 as it needs it.
46 The second (optional) argument is a hashref. Currently only
48 no_cache is supported. If specified then data will not be cached
49 in memory and the system will read from disk each time you access a
50 shape. It will save memory for large files, though.
51 type_is ($type)
53 Returns true if the major type of this data file is the same as the
54 type passed to type_is().
55 The $type argument can be either the numeric code (see
57 "shape_type"), or the string code (see "shape_type_text").
58 get_dbf_record ($record_index)
60 Returns the data from the dbf file associated with the specified
61 record index (shapefile indexes start at 1). If called in a list
62 context, returns a hash, if called in a scalar context, returns a
63 hashref.
64 x_min() x_max() y_min() y_max()
66 m_min() m_max() z_min() z_max()
67 Returns the minimum and maximum values for x, y, z, and m fields as
68 indicated in the shp file header.
69 upper_left_corner() upper_right_corner()
71 lower_left_corner() lower_right_corner()
72 Returns a Geo::ShapeFile::Point object indicating the respective
73 corners.
74 height() width()
76 Returns the height and width of the area contained in the shp file.
77 Note that this likely does not return miles, kilometers, or any
78 other useful measure, it simply returns x_max - x_min, or y_max -
79 y_min. Whether this data is a useful measure or not depends on
80 your data.
81 corners()
83 Returns a four element array consisting of the corners of the area
84 contained in the shp file. The corners are listed clockwise
85 starting with the upper left. (upper_left_corner,
86 upper_right_corner, lower_right_corner, lower_left_corner)
87 area_contains_point ($point, $x_min, $y_min, $x_max, $y_max)
89 Utility function that returns true if the Geo::ShapeFile::Point
90 object in point falls within the bounds of the rectangle defined by
91 the area indicated. See bounds_contains_point() if you want to
92 check if a point falls within the bounds of the current shp file.
93 bounds_contains_point ($point)
95 Returns true if the specified point falls within the bounds of the
96 current shp file.
97 file_version()
99 Returns the ShapeFile version number of the current shp/shx file.
100 shape_type()
102 Returns the shape type contained in the current shp/shx file. The
103 ESRI spec currently allows for a file to contain only a single type
104 of shape (null shapes are the exception, they may appear in any
105 data file). This returns the numeric value for the type, use
106 type() to find the text name of this value.
107 shapes()
109 Returns the number of shapes contained in the current shp/shx file.
110 This is the value that allows you to iterate through all the shapes
111 using "for(1 .. $obj->shapes()) {".
112 records()
114 Returns the number of records contained in the current data. This
115 is similar to shapes(), but can be used even if you don't have
116 shp/shx files, so you can access data that is stored as dbf, but
117 does not have shapes associated with it.
118 shape_type_text()
120 Returns the shape type of the current shp/shx file (see
121 shape_type()), but as the human-readable string type, rather than
122 an integer.
123 get_shx_record ($record_index)
125 get_shx_record_header ($record_index)
126 Get the contents of an shx record or record header (for
127 compatibility with the other get_* functions, both are provided,
128 but in the case of shx data, they return the same information).
129 The return value is a two element array consisting of the offset in
130 the shp file where the indicated record begins, and the content
131 length of that record.
132 get_shp_record_header ($record_index)
134 Retrieve an shp record header for the specified index. Returns a
135 two element array consisting of the record number and the content
136 length of the record.
137 get_shp_record ($record_index)
139 Retrieve an shp record for the specified index. Returns a
140 Geo::ShapeFile::Shape object.
141 shapes_in_area ($x_min, $y_min, $x_max, $y_max)
143 Returns an array of integers listing which shape IDs have bounding
144 boxes that overlap with the area specified.
145 check_in_area ($x1_min, $y1_min, $x1_max, $y1_max, $x2_min, $x2_max,
147 $y2_min, $y2_max)
148 Returns true if the two specified areas overlap.
149 bounds()
151 Returns the bounds for the current shp file. (x_min, y_min, x_max,
152 y_max)
153 shx_handle() shp_handle() dbf_handle()
155 Returns the file handles associated with the respective data files.
156 type ($shape_type_number)
158 Returns the name of the type associated with the given type id
159 number.
160 find_bounds (@shapes)
162 Takes an array of Geo::ShapeFile::Shape objects, and returns a
163 hash, with keys of x_min, y_min, x_max, y_max, with the values for
164 each of those bounds.
165 get_dbf_field_names()
167 Returns an array of the field names in the dbf file, in file order.
168 Returns an array reference if used in scalar context.
169 get_all_shapes()
171 Returns an array (or arrayref in scalar context) with all shape
172 objects in the shapefile.
173 get_shapes_sorted()
175 get_shapes_sorted (\@shapes, \&sort_sub)
176 Returns an array (or arrayref in scalar context) of shape objects
177 sorted by ID. Defaults to all shapes, but will also take an array
178 of Geo::ShapeFile::Shape objects. Sorts by record number by
179 default, but you can pass your own sub for more fancy work.
180 get_shapes_sorted_spatially()
182 get_shapes_sorted_spatially (\@shapes, \&sort_sub)
183 Convenience wrapper around get_shapes_sorted to sort spatially
184 (south-west to north-east) then by record number. You can pass
185 your own shapes and sort sub. The sort sub does not need to be
186 spatial since it will sort by whatever you say, but it is your code
187 so do what you like.
188 build_spatial_index()
190 Builds a spatial index (a Tree::R object) and returns it. This
191 will be used internally for many of the routines, but you can use
192 it directly if useful.
193 get_spatial_index()
195 Returns the spatial index object, or "undef" if one has not been
196 built.
197 get_dbf_field_info()
199 Returns an array of hashes containing information about the fields.
200 Useful if you are modifying the shapes and then writing them out to
201 a new shapefile using Geo::Shapefile::Writer.
202
204 Please send any bugs, suggestions, or feature requests to
205 <https://github.com/shawnlaffan/Geo-ShapeFile/issues>.
206
208 Geo::ShapeFile::Shape, Geo::ShapeFile::Point, Geo::Shapefile::Writer,
209 Geo::GDAL::FFI
210
212 Jason Kohles, <email@jasonkohles.com>
213 Shawn Laffan, <shawnlaffan@gmail.com>
215
217 Copyright 2002-2013 by Jason Kohles (versions up to and including 2.52)
218 Copyright 2014 by Shawn Laffan (versions 2.53 -)
220 This library is free software; you can redistribute it and/or modify it
222 under the same terms as Perl itself.
223perl v5.34.0 2021-07-22 Geo::ShapeFile(3)