Provided by: libgeo-shapelib-perl_0.22-3build1_amd64 bug

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>