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

cpanm Geo::Shapelib

perl -MCPAN -e shell
install Geo::Shapelib