NAME

Geo::Walkabout::Chain - An open path representing the shape of a line feature.

SYNOPSIS

  require Geo::Walkabout::Chain;

  my $chain = Geo::Walkabout::Chain->new([1,1],[5,10.2],[12,13]);
  my $chain = Geo::Walkabout::Chain->new_from_pgpath('[(1,1),(5,10.2),(12,13)]');

  my $begin = $chain->begin;
  my $end   = $chain->end;
  my @shape = $chain->shape;
  my @raw_chain = $chain->chain;
  my $pg_path = $chain->as_pgpath;

  $chain->append_shape(@points);

DESCRIPTION

This is a representation of a complete chain. Typically, it should not be used directly, instead Geo::Walkabout::Line encapsulates a single Geo::Walkabout::Chain.

A single point in a chain is represented as a two element array representing a single point of latitude and longitutde. (OO dogma says these should be objects, too, but if I wanted to be that silly I'd be using Java.)

Public Methods

Constructors

new

  my $chain = Geo::Walkabout::Chain->new([$lat1, $long1], 
                                         [$lat2, $long2], 
                                         ...
                                        );

Creates a new Geo::Walkabout::Chain object from a list of points (two element array references). The first point is the start of the chain, the last is the end (or vice-versa depending on which way you look.) The rest are "shape" coordinates.

new_from_pgpath

  my $chain = Geo::Walkabout::Chain->new_from_pgpath($postgres_path);

An alternative constructor, it takes a PostgreSQL style open PATH of the form:

  [ ( lat1, long1 ), ... , (latn, longn) ]

So something like '[(1,1), (-1,2.2), (-2,3)]'. This is very helpful when reading in chains from a PostgreSQL database.

Accessors

begin

  my $beginning_point = $chain->begin;

Returns the beginning point of this chain as a two element array reference.

end

  my $end_point = $chain->end;

Returns the end point of this chain as a two element array reference.

shape

  my @shape = $chain->shape;

Returns the shaping points of this chain, ie. those points between the start and the end which determine the shape of the chain (without them, its just a line segment).

chain

  my @raw_chain = $chain->chain;

Dumps the chain this object represents as a series of points. This is equivalent to:

    my @raw_chain = ($chain->begin, $chain->shape, $chain->end);

as_pgpath

  my $pg_path = $chain->as_pgpath;

Returns a representation of the chain as a PostgreSQL open path suitable for insertion into the database.

to_pgpoint

  my $pg_point = $chain->to_pgpoint(\@point);

Translates a two element array reference into a PostgreSQL point.

Modifiers

append_shape

  $chain->append_shape(@points);

Adds new shaping points to the chain. They are appended to the end of the shape.

Private Methods

PRIVATE! I document them here because I'm forgetful. Use of these may result in DIRE CONSEQUENCES! (consequences may contain one or more of the following: pain, death, dismemberment, yellow dye #5)

_split_pg_path

  my @path = Geo::Walkabout::Chain->_split_pg_path($pg_path);

Converts a PostgreSQL open PATH into an array of points.

AUTHOR

Michael G Schwern <schwern@pobox.com>