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>

SEE ALSO

Geo::Walkabout, Geo::Walkabout::Line, Geo::TigerLine