1Geo::ShapeFile(3)     User Contributed Perl Documentation    Geo::ShapeFile(3)
2
3
4

NAME

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

SYNOPSIS

9         use Geo::ShapeFile;
10
11         my $shapefile = Geo::ShapeFile->new('roads');
12
13         #  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
18           my %db = $shapefile->get_dbf_record($id);
19         }
20
21         #  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

ABSTRACT

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

DESCRIPTION

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

METHODS

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
47           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
52       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
56       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
62       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
67       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
72       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
79       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
85       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
91       bounds_contains_point ($point)
92           Returns true if the specified point falls within the bounds of the
93           current shp file.
94
95       file_version()
96           Returns the ShapeFile version number of the current shp/shx file.
97
98       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
105       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
110       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
116       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
121       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
130       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
135       get_shp_record ($record_index)
136           Retrieve an shp record for the specified index.  Returns a
137           Geo::ShapeFile::Shape object.
138
139       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
143       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
147       bounds()
148           Returns the bounds for the current shp file.  (x_min, y_min, x_max,
149           y_max)
150
151       shx_handle() shp_handle() dbf_handle()
152           Returns the file handles associated with the respective data files.
153
154       type ($shape_type_number)
155           Returns the name of the type associated with the given type id
156           number.
157
158       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
163       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
167       get_all_shapes()
168           Returns an array (or arrayref in scalar context) with all shape
169           objects in the shapefile.
170
171       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
178       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
186       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
191       get_spatial_index()
192           Returns the spatial index object, or "undef" if one has not been
193           built.
194
195       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

REPORTING BUGS

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

SEE ALSO

205       Geo::ShapeFile::Shape, Geo::ShapeFile::Point, Geo::Shapefile::Writer,
206       Geo::GDAL::FFI
207

AUTHOR

209       Jason Kohles, <email@jasonkohles.com>
210
211       Shawn Laffan, <shawnlaffan@gmail.com>
212
214       Copyright 2002-2013 by Jason Kohles (versions up to and including 2.52)
215
216       Copyright 2014 by Shawn Laffan (versions 2.53 -)
217
218       This library is free software; you can redistribute it and/or modify it
219       under the same terms as Perl itself.
220
221
222
223perl v5.32.0                      2020-07-28                 Geo::ShapeFile(3)
Impressum