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 ($numeric_type)
53 Returns true if the major type of this data file is the same as the
54 type passed to type_is().
55 get_dbf_record ($record_index)
57 Returns the data from the dbf file associated with the specified
58 record index (shapefile indexes start at 1). If called in a list
59 context, returns a hash, if called in a scalar context, returns a
60 hashref.
61 x_min() x_max() y_min() y_max()
63 m_min() m_max() z_min() z_max()
64 Returns the minimum and maximum values for x, y, z, and m fields as
65 indicated in the shp file header.
66 upper_left_corner() upper_right_corner()
68 lower_left_corner() lower_right_corner()
69 Returns a Geo::ShapeFile::Point object indicating the respective
70 corners.
71 height() width()
73 Returns the height and width of the area contained in the shp file.
74 Note that this likely does not return miles, kilometers, or any
75 other useful measure, it simply returns x_max - x_min, or y_max -
76 y_min. Whether this data is a useful measure or not depends on
77 your data.
78 corners()
80 Returns a four element array consisting of the corners of the area
81 contained in the shp file. The corners are listed clockwise
82 starting with the upper left. (upper_left_corner,
83 upper_right_corner, lower_right_corner, lower_left_corner)
84 area_contains_point ($point, $x_min, $y_min, $x_max, $y_max)
86 Utility function that returns true if the Geo::ShapeFile::Point
87 object in point falls within the bounds of the rectangle defined by
88 the area indicated. See bounds_contains_point() if you want to
89 check if a point falls within the bounds of the current shp file.
90 bounds_contains_point ($point)
92 Returns true if the specified point falls within the bounds of the
93 current shp file.
94 file_version()
96 Returns the ShapeFile version number of the current shp/shx file.
97 shape_type()
99 Returns the shape type contained in the current shp/shx file. The
100 ESRI spec currently allows for a file to contain only a single type
101 of shape (null shapes are the exception, they may appear in any
102 data file). This returns the numeric value for the type, use
103 type() to find the text name of this value.
104 shapes()
106 Returns the number of shapes contained in the current shp/shx file.
107 This is the value that allows you to iterate through all the shapes
108 using "for(1 .. $obj->shapes()) {".
109 records()
111 Returns the number of records contained in the current data. This
112 is similar to shapes(), but can be used even if you don't have
113 shp/shx files, so you can access data that is stored as dbf, but
114 does not have shapes associated with it.
115 shape_type_text()
117 Returns the shape type of the current shp/shx file (see
118 shape_type()), but as the human-readable string type, rather than
119 an integer.
120 get_shx_record ($record_index)
122 get_shx_record_header ($record_index)
123 Get the contents of an shx record or record header (for
124 compatibility with the other get_* functions, both are provided,
125 but in the case of shx data, they return the same information).
126 The return value is a two element array consisting of the offset in
127 the shp file where the indicated record begins, and the content
128 length of that record.
129 get_shp_record_header ($record_index)
131 Retrieve an shp record header for the specified index. Returns a
132 two element array consisting of the record number and the content
133 length of the record.
134 get_shp_record ($record_index)
136 Retrieve an shp record for the specified index. Returns a
137 Geo::ShapeFile::Shape object.
138 shapes_in_area ($x_min, $y_min, $x_max, $y_max)
140 Returns an array of integers listing which shape IDs have bounding
141 boxes that overlap with the area specified.
142 check_in_area ($x1_min, $y1_min, $x1_max, $y1_max, $x2_min, $x2_max,
144 $y2_min, $y2_max)
145 Returns true if the two specified areas overlap.
146 bounds()
148 Returns the bounds for the current shp file. (x_min, y_min, x_max,
149 y_max)
150 shx_handle() shp_handle() dbf_handle()
152 Returns the file handles associated with the respective data files.
153 type ($shape_type_number)
155 Returns the name of the type associated with the given type id
156 number.
157 find_bounds (@shapes)
159 Takes an array of Geo::ShapeFile::Shape objects, and returns a
160 hash, with keys of x_min, y_min, x_max, y_max, with the values for
161 each of those bounds.
162 get_dbf_field_names()
164 Returns an array of the field names in the dbf file, in file order.
165 Returns an array reference if used in scalar context.
166 get_all_shapes()
168 Returns an array (or arrayref in scalar context) with all shape
169 objects in the shapefile.
170 get_shapes_sorted()
172 get_shapes_sorted (\@shapes, \&sort_sub)
173 Returns an array (or arrayref in scalar context) of shape objects
174 sorted by ID. Defaults to all shapes, but will also take an array
175 of Geo::ShapeFile::Shape objects. Sorts by record number by
176 default, but you can pass your own sub for more fancy work.
177 get_shapes_sorted_spatially()
179 get_shapes_sorted_spatially (\@shapes, \&sort_sub)
180 Convenience wrapper around get_shapes_sorted to sort spatially
181 (south-west to north-east) then by record number. You can pass
182 your own shapes and sort sub. The sort sub does not need to be
183 spatial since it will sort by whatever you say, but it is your code
184 so do what you like.
185 build_spatial_index()
187 Builds a spatial index (a Tree::R object) and returns it. This
188 will be used internally for many of the routines, but you can use
189 it directly if useful.
190 get_spatial_index()
192 Returns the spatial index object, or "undef" if one has not been
193 built.
194 get_dbf_field_info()
196 Returns an array of hashes containing information about the fields.
197 Useful if you are modifying the shapes and then writing them out to
198 a new shapefile using Geo::Shapefile::Writer.
199
201 Please send any bugs, suggestions, or feature requests to
202 <https://github.com/shawnlaffan/Geo-ShapeFile/issues>.
203
205 Geo::ShapeFile::Shape, Geo::ShapeFile::Point, Geo::Shapefile::Writer,
206 Geo::GDAL::FFI
207
209 Jason Kohles, <email@jasonkohles.com>
210 Shawn Laffan, <shawnlaffan@gmail.com>
212
214 Copyright 2002-2013 by Jason Kohles (versions up to and including 2.52)
215 Copyright 2014 by Shawn Laffan (versions 2.53 -)
217 This library is free software; you can redistribute it and/or modify it
219 under the same terms as Perl itself.
220perl v5.32.0 2020-07-28 Geo::ShapeFile(3)