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 ($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           The $type argument can be either the numeric code (see
57           "shape_type"), or the string code (see "shape_type_text").
58
59       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
65       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
70       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
75       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
82       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
88       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
94       bounds_contains_point ($point)
95           Returns true if the specified point falls within the bounds of the
96           current shp file.
97
98       file_version()
99           Returns the ShapeFile version number of the current shp/shx file.
100
101       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
108       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
113       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
119       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
124       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
133       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
138       get_shp_record ($record_index)
139           Retrieve an shp record for the specified index.  Returns a
140           Geo::ShapeFile::Shape object.
141
142       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
146       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
150       bounds()
151           Returns the bounds for the current shp file.  (x_min, y_min, x_max,
152           y_max)
153
154       shx_handle() shp_handle() dbf_handle()
155           Returns the file handles associated with the respective data files.
156
157       type ($shape_type_number)
158           Returns the name of the type associated with the given type id
159           number.
160
161       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
166       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
170       get_all_shapes()
171           Returns an array (or arrayref in scalar context) with all shape
172           objects in the shapefile.
173
174       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
181       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
189       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
194       get_spatial_index()
195           Returns the spatial index object, or "undef" if one has not been
196           built.
197
198       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

REPORTING BUGS

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

SEE ALSO

208       Geo::ShapeFile::Shape, Geo::ShapeFile::Point, Geo::Shapefile::Writer,
209       Geo::GDAL::FFI
210

AUTHOR

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