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++,
				  NParts=>0,
				  NVertices=>1,
				  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} this is probably best to let be an integer which you
increment each time by one starting from zero

$s->{NParts} to be the number of how many parts want into this
shape, may be zero

$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 if
the shape is not Multipatch?

$s->{NVertices} to be the number of how many vertices there are in
your shape (point has only one vertex), at least one

$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

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} = ['ID','Station'];
    $shape->{FieldTypes} = ['Integer','String:60'];

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

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

SQL Database methods

OpenGIS Simple Features Specification for SQL compliant database methods to come! :) ..maybe..

AUTHOR

Ari Jolma, ari.jolma@hut.fi

LIMITATIONS

SEE ALSO

perl(1).

cpanm Geo::Shapelib

perl -MCPAN -e shell
install Geo::Shapelib