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 automatically
    deduced from the Shapes array.

    $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.

this is often not used:

    $s->{Parts} this is a reference to an array of arrays of two
    values, one for each part: the index of the first vertex in the
    vertex array, i.e. the number of vertices in all previous parts in
    this shape; and the type of the part (not the shapetype): Ring (5)
    if the shape is not Multipatch. You may leave this value
    undefined.

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

Options:

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 makes each part an array of two elements.

UnhashFields:

    Default is 1. Makes $self's attributes FieldNames, FieldTypes refs
    to lists, and ShapeRecords a list of lists.

LoadAll:

    Default is 1. Reads shapes into $self automatically in the
    constructor using the get_shape($shape_index) method

METHODS

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();

Saving the shapefile

    $shapefile->save($filename);

The argument $shapefile is optional, the internal attribute ($shapefile->{Name}) is used if $filename is not specified.

$filename may contain an extension, it is removed and .shp etc. are used instead.

Dump

$shapefile->dump($to);

$to can be undef (then dump uses STDOUT), filename, or reference to a filehandle (e.g., \*DUMP).

AUTHOR

Ari Jolma, ari.jolma at tkk.fi

LIMITATIONS

SEE ALSO

perl(1).

cpanm Geo::Shapelib

perl -MCPAN -e shell
install Geo::Shapelib