Provided by: libgeo-shapelib-perl_0.22-3_amd64 
NAME
Geo::Shapelib - Perl extension for reading and writing shapefiles as defined by ESRI(r)
SYNOPSIS
use Geo::Shapelib qw/:all/;
or
use Geo::Shapelib qw/:all/;
my $shapefile = new Geo::Shapelib {
Name => 'stations',
Shapetype => POINT,
FieldNames => ['Name','Code','Founded'],
FieldTypes => ['String:50','String:10','Integer:8']
};
while (<DATA>) {
chomp;
my($station,$code,$founded,$x,$y) = split /\|/;
push @{$shapefile->{Shapes}},{ Vertices => [[$x,$y,0,0]] };
push @{$shapefile->{ShapeRecords}}, [$station,$code,$founded];
}
$shapefile->save();
DESCRIPTION
This is a library for reading, creating, and writing shapefiles as defined by ESRI(r)
using Perl. The Perl code uses Frank Warmerdam's Shapefile C Library
(http://shapelib.maptools.org/). The library is included in this distribution.
Currently no methods exist for populating an empty Shape. You need to do it in your own
code. This is how:
First you include the module into your code. If you want to define the shape type using
its name, import all:
use Geo::Shapelib qw/:all/;
Create the shapefile object and specify its name and type:
$shapefile = new Geo::Shapelib {
Name => <filename>,
Shapetype => <type from the list>,
FieldNames => <field name list>,
FieldTypes => <field type list>
}
The name (filename, may include path) of the shapefile, the extension is not used (it is
stripped in the save method).
The shape type is an integer. This module defines shape type names as constants (see
below).
The field name list is an array reference of the names of the data items assigned to each
shape.
The field type list is an array reference of the types of the data items. Field type is
either 'Integer', 'Double', or 'String'.
The types may have optional 'width' and 'decimals' fields defined, like this:
'Integer[:width]' defaults: width = 10
'Double[:width[:decimals]]' defaults: width = 10, decimals = 4
'String[:width]' defaults: width = 255
There are some other attributes which can be defined in the constructor (see below), they
are rarely needed. The shape object will need or get a couple of other attributes as well.
They should be treated as private:
$shapefile->{NShapes} is the number of shapes in your
object. Shapefile is a collection of shapes. This is usually
automatically deduced from the Shapes array when needed.
$shapefile->{MinBounds} is set by shapelib C functions.
$shapefile->{MaxBounds} is set by shapelib C functions.
Create the shapes and respective shape records and put them into the shape:
for many times {
make $s, a new shape as a reference to a hash
push @{$shapefile->{Shapes}}, $s;
make $r, a shape record as a reference to an array
push @{$shapefile->{ShapeRecords}}, $r;
}
how to create $s? It is a (reference to an) hash.
set:
$s->{Vertices} this is a reference to an array of arrays of four
values, one for each vertex: x, y, z, and m of the vertex. There
should be at least one vertex in $s. Point has only one vertex.
$s->{Parts}:
$s->{Parts} is not needed in simple cases. $s->{Parts} is a
reference to an array (a) of arrays (b). There is one (b) array
for each part. In a (b) array the first value is an index to the
Vertices array denoting the first vertex of that part. The second
value is the type of the part (NOTE: not the type of the
shape). The type is 5 (Ring) unless the shape is of type
Multipatch. The third value is set as the type of the part as a
string when reading from a file but the save method requires only
the first two values.
The index of the last vertex of any part is implicitly the index
of the next part minus one or the index of the last vertex.
forget these:
$s->{ShapeId} may be left undefined. The save method sets it to
the index in the Shapes array. Instead create and use an id field
in the record.
$s->{NParts} and $s->{NVertices} may be set but that is usually
not necessary since they are calculated in the save method. You
only need to set these if you want to save less parts or vertices
than there actually are in the Parts or Vertices arrays.
$s->{SHPType} is the type of the shape and it is automatically set
to $shape->{Shapetype} unless defined (which you should not do)
The shape record is simply an array reference, for example:
$r = [item1,item2,item3,...];
That's all. Then save it and start your shapefile viewer to look at the result.
EXPORT
None by default. The following export tags are defined.
:constants
This exports constant functions for the individual types of shapefile Types and
shapefile part types. They all return scalar (integer) values. The shapetype
functions: POINT, ARC, POLYGON, MULTIPOINT, POINTZ, ARCZ, POLYGONZ, MULTIPOINTZ,
POINTM, ARCM, POLYGONM, MULTIPOINTM, MULTIPATCH are defined. The shapefile part
types: TRISTRIP, TRIFAN, OUTERRING, INNERRING, FIRSTRING, RING are defined.
:types Exports two hashs: %ShapeTypes, %PartTypes which map the shapelib type integers to
string values.
:all All possible exports are included.
CONSTRUCTORS
This one reads in an existing shapefile:
$shapefile = new Geo::Shapelib "myshapefile", {<options>};
This one creates a new, blank Perl shapefile object:
$shapefile = new Geo::Shapelib {<options>};
{<options>} is optional in both cases, an example (note the curly braces):
$shapefile = new Geo::Shapelib {
Name => $shapefile,
Shapetype => POINT,
FieldNames => ['Name','Code','Founded'],
FieldTypes => ['String:50','String:10','Integer:8']
};
$shapefile = new Geo::Shapelib "myshapefile" {
Rtree => 1
};
Options:
Like:
A shapefile from which to copy ShapeType, FieldNames, and FieldTypes.
Name:
Default is "shapefile". The filename (if given) becomes the name
for the shapefile unless overridden by this.
Shapetype:
Default "POINT". The type of the shapes. (All non-null shapes in a
shapefile are required to be of the same shape type.)
FieldNames:
Default is [].
FieldTypes:
Default is [].
ForceStrings:
Default is 0. If 1, sets all FieldTypes to string, may be useful
if values are very large ints
Rtree:
Default is 0. If 1, creates an R-tree of the shapes into an
element Rtree. (Requires LoadAll.)
When a shapefile is read from files they end up in a bit different kind of data structure
than what is expected by the save method for example and what is described above. These
flags enable the conversion, they are not normally needed.
CombineVertices:
Default is 1. CombineVertices is experimental. The default
behavior is to put all vertices into the Vertices array and part
indexes into the Parts array. If CombineVertices is set to 0 there
is no Vertices array and all data goes into the Parts. Currently
setting CombineVertices to 0 breaks saving of shapefiles.
UnhashFields:
Default is 1. Makes $self's attributes FieldNames, FieldTypes refs
to lists, and ShapeRecords a list of lists.
The default is to load all data into Perl variables in the constructor. With these
options the data can be left into the files to be loaded on-demand.
Load:
Default is 1. If 0, has the same effect as LoadRecords=>0 and
LoadAll=>0.
LoadRecords:
Default is 1. Reads shape records into $self->{ShapeRecords}
automatically in the constructor using the
get_record($shape_index) method
LoadAll:
Default is 1. Reads shapes (the geometry data) into
$self->{Shapes} automatically in the constructor using the
get_shape($shape_index) method
METHODS
data_model
Returns data model converted into two arrays.
If in a constructor a filename is given, then the data model is read from the dbf file and
stored as a hashref in the attribute FieldTypes. This converts the hashref into two
arrays: FieldNames and respective FieldTypes. These arrayrefs are stored in attributes of
those names if UnhashFields is TRUE.
get_shape(shape_index, from_file)
Returns a shape nr. shape_index+1 (first index is 0). The shape is read from a file even
if array Shapes exists if from_file is TRUE.
Option CombineVertices is in operation here.
Use this method to get a shape unless you know what you are doing.
get_record(shape_index, from_file)
Returns the record which belongs to shape nr. shape_index+1 (first index is 0). The record
is read from a file even if array ShapeRecords exists if from_file is TRUE.
get_record_arrayref(shape_index, FieldNames, from_file)
Returns the record which belongs to shape nr. shape_index+1 (first index is 0) as an
arrayref. The parameter FieldNames may be undef but if defined, it is used as the array
according to which the record array is sorted. This in case the ShapeRecords contains
hashrefs. The record is read from the file even if array ShapeRecords exists if from_file
is TRUE.
Use this method to get a record of a shape unless you know what you are doing.
get_record_hashref(shape_index, from_file)
Returns the record which belongs to shape nr. shape_index+1 (first index is 0) as a
hashref. The record is read from the file even if array ShapeRecords exists if from_file
is TRUE. If records are in the array ShapeRecords as a list of lists, then FieldNames
_must_ contain the names of the fields.
Use this method to get a record of a shape unless you know what you are doing.
lengths(shape)
Returns the lengths of the parts of the shape. This is lengths of the parts of polyline or
the length of the boundary of polygon. 2D and 3D data is taken into account.
Using shapefile quadtree spatial indexing
Obtain a list of shape ids within the specified bound using a shapefile quadtree index:
$shapefile->query_within_rect($bounds, $maxdepth = 0);
$bounds should be an array reference of 4 elements (xmin, ymin, xmax, ymax)
This method uses the quadtree indices defined by Shapelib *not* ESRI spatial index files
(.sbn, .sbx). If a quadtree index (<basename>.qix) does not exist, one is created and
saved as a file.
To just create an index you can also use the method:
$shapefile->create_spatial_index($maxdepth = 0);
$maxdepth (optional) is the maximum depth of the index to create. Default is 0 meaning
that shapelib will calculate a reasonable default depth.
Rtree and editing the shapefile
Building a R-tree for the shapes:
$shapefile->Rtree();
This is automatically done if Rtree-option is set when a shapefile is loaded from files.
You can then use methods like (there are not yet any wrappers for these).
my @shapes;
$shapefile->{Rtree}->query_point(@xy,\@shapes); # or
$shapefile->{Rtree}->query_completely_within_rect(@rect,\@shapes); # or
$shapefile->{Rtree}->query_partly_within_rect(@rect,\@shapes);
To get a list of shapes (indexes to the shape array), which you can feed for example to
the select_vertices function.
for my $shape (@shapes) {
my $vertices = $shapefile->select_vertices($shape,@rect);
my $n = @$vertices;
print "you selected $n vertices from shape $shape\n";
}
The shapefile object remembers the selected vertices and calling the function
$shapefile->move_selected_vertices($dx,$dy);
moves the vertices. The bboxes of the affected shapes, and the R-tree, if one exists, are
updated automatically. To clear all selections from all shapes, call:
$selected->clear_selections();
Setting the bounds of the shapefile
$shapefile->set_bounds;
Sets the MinBounds and MaxBounds of all shapes and of the shapefile.
Saving the shapefile
$shapefile->save($filename);
The argument $shapefile is optional, the internal attribute $shapefile->{Name} is used if
$filename is not specified. If $filename is specified it also becomes the new name.
$filename may contain an extension, it is removed and .shp etc. are used instead.
If you are not sure that the bounds of the shapefile are ok, then call
$shapefile->set_bounds; before saving.
create, add, close
$shapefile->create($filename);
many times:
$shapefile->add($shape, $record);
$shapefile->close();
These methods make it easy to create large shapefiles. $filename is optional. These
methods create some temporary variables (prefix: _) in internal data and thus calling of
close method is required.
Dump
$shapefile->dump($to);
$to can be undef (then dump uses STDOUT), filename, or reference to a filehandle (e.g.,
\*DUMP).
This method just dumps all data. If you have yourself created the shapefile then the
reported bounds may be incorrect.
AUTHOR
Ari Jolma, https://github.com/ajolma
REPOSITORY
<https://github.com/ajolma/Geo-Shapelib>