NAME

Geo::Shapelib - Perl extension for reading and writing shapefiles as defined by ESRI(r)

SYNOPSIS

use Geo::Shapelib;

or

    use Geo::Shapelib qw/:all/;

    my $shape = new Geo::Shapelib;
    foreach my $i (0..10) {
        push @{$shape->{Shapes}},{SHPType=>POINT,
				  ShapeID=>$i++,
				  Vertices=>[[$i,$i,0,0]]
				 };
      }

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. Get it from http://gdal.velocet.ca/projects/shapelib/index.html

Currently no methods exist for populating an empty Shape. You need to do it in your own code. This is the HOWTO:

First you create the shapefile object:

$shape = new Geo::Shapelib;

the set its attributes:

$shape->{Name} to be the name (path) of the shapefile, it may contain
an extension. You may also use the argument in the save method.

$shape->{Shapetype} to be the (integer) denoting the shapetype. Look
into this file or some other doc for the numbers.

don't care about these attributes:

$shape->{NShapes} the number of shapes in your object. Shapefile
is a collection of shapes. This is automatically deduced from the
Shapes array.

$shape->{MinBounds} 

$shape->{MaxBounds}

then create shapes and put them into the shape

for many times {
    make $s, a new shape
    push @{$shape->{Shapes}}, $s;
}

how to create $s? It is a hash.

set

$s->{SHPType} to be the type of the shape (this needs to be the
same as the type of the shape, i.e., of the object?)

$s->{ShapeId} may be left undefined. The save method sets it to
the index in the Shapes array.

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

$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->{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 are actually in the Parts or Vertices arrays.

Then you need to have at least some data assigned to each shape.

$self->{FieldNames} is a reference to the names of the data items,
i.e., an array.

$self->{FieldTypes} is a reference to the types of the data items,
i.e., and array. Type is either 'Integer', 'Double', or 'String'.

The Types may have optional 'width' and 'decimals' fields defined,
like: 
    'Integer[:width]'            defaults: width = 10
    'Double[:width[:decimals]]'  defaults: width = 10, decimals = 4
    'String[:width]'             defaults: width = 255

populate the data table:

for my $i (0..$self->{NShapes}-1) {
    $self->{ShapeRecords}->[$i] = [item1,item2,item3,...];
}

That's all. Then save it and start your shapefile viewer to look at the result.

An example:

    $shape = new Geo::Shapelib;

    $shape->{Shapetype} = 1;

    $shape->{FieldNames} = ['StationName'];
    $shape->{FieldTypes} = ['String:60'];

    while (<DATA>) {
        chomp;
        ($station,$x,$y) = split /\|/;
        push @{$shape->{Shapes}}, {
                SHPType=>1,
                Vertices=>[[$x,$y]]
	};
        push @{$shape->{ShapeRecords}}, [$station];
    }

    $shape->save('stations');

    __DATA__
    Helsinki-Vantaan Lentoasema|3387419|6692222
    Helsinki Kaisaniemi        |3385926|6675529
    Hyvinkää Mutila            |3379813|6722622
    Nurmijärvi Rajamäki        |3376486|6715764
    Vihti Maasoja              |3356766|6703481
    Porvoo Järnböle            |3426574|6703254
    Porvoon Mlk Bengtsby       |3424354|6684723
    Orimattila Käkelä          |3432847|6743998
    Tuusula Ruotsinkylä        |3388723|6696784

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:

$shape = new Geo::Shapelib "myshapefile", {<options>};

This one creates a new, blank Perl shapefile object:

$shape = new Geo::Shapelib {<options>};

{<options>} is optional in both cases

<options>:

CombineVertices:

Default 1, CombineVertices makes each part an array of two elements

UnhashFields:

Default 1, Makes $self's attributes FieldNames, FieldTypes, and ShapeRecords refs to arrays

LoadAll:

Default 1, Reads shapes into $self automatically using the get_shape($shape_index) method

ForceStrings:

Default 0, If 1, sets all FieldTypes to string, may be useful if values are very large ints

METHODS

Saving the shapefile

$shape->save($shapefile);

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

Extension is removed from $shapefile.

Dump

$shape->dump($to);

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

AUTHOR

Ari Jolma, ari.jolma@hut.fi

LIMITATIONS

SEE ALSO

perl(1).

cpanm Geo::Shapelib

perl -MCPAN -e shell
install Geo::Shapelib