NAME

NAME
Math::CatmullRom - Calculate Catmull-Rom splines

SYNOPSIS
use Math::CatmullRom;

# create curve passing through list of control points
my $curve = new Math::CatmullRom( $x1, $y1, $x2, $y2, ..., $xn, $yn );

# or pass reference to list of control points
my $curve = new Math::CatmullRom( [ $x1, $y1, $x2, $y2, ..., $xn, $yn ] );

# determine (x, y) at point along curve, range 0.0 -> 1.0
my ($x, $y) = $curve->point( 0.5 );

# returns list ref in scalar context
my $xy = $curve->point( 0.5 );

# return list of 20 (x, y) points along curve
my @curve = $curve->curve( 20 );

# returns list ref in scalar context
my $curve = $curve->curve( 20 );

# include start and finish points by adding false data points
$curve->plot_all;

DESCRIPTION
This module provides an algorithm to generate plots for Catmull-Rom
splines.

A Catmull-Rom spline can be considered a special type of Bezier curve
that guarantees that the curve will cross every control point starting
at the second point and terminating at the penultimate one. For this
reason the minimum number of control points is 4.

To plot a curve where you have a set of points but want the curve to be
drawn through the start and finish points you can tell the module to
plot all of the points. In this case it assumes that there are two extra
points, prior to the start point with the same values as the start point
and one prior to the finish point with the same values as the finish
point. This is really just a convenience function for certain kinds of
plot.

A new Catmull-Rom spline is created using the new() constructor, passing
a list of control points.

use Math::CatmullRom;

# create curve passing through list of control points
my @control = ( $x1, $y1, $x2, $y2, $x3, $y3, $x4, $y4 );
my $spline = new Math::CatmullRom( @control );

Alternatively, a reference to a list of control points may be passed.

# or pass reference to list of control points
my $spline = new Math::CatmullRom( \@control );

The point( $theta ) method can be called on the object, passing a value
in the range 0.0 to 1.0 which represents the distance along the spline.
When called in list context, the method returns the x and y coordinates
of that point on the curve.

my ( $x, $y ) = $curve->plot( 0.75 );
print "X : $x\nY : $y\n";

When called in a scalar context, it returns a reference to a list
containing the X and Y coordinates.

my $point = $curve->plot( 0.75 );
print "X : $point->[0]\nY : $point->[1]\n";

The curve( $n, $per_segment ) method can be used to return a set of
points sampled along the length of the curve (i.e. in the range 0.0 <=
$theta <= 1.0).

The parameter indicates the number of sample points required. The method
returns a list of ($x1, $y1, $x2, $y2, ..., $xn, $yn) points when called
in list context, or a reference to such an array when called in scalar
context.

The $per_segment parameter determines whether $n points total will be
plotted or $n points between every point, defaulting to $n points total.

my @points = $curve->curve( 10, 1 );

while( @points )
{
my ( $x, $y ) = splice( @points, 0, 2 );
print "X : $x\nY : $y\n";
}

my $points = $curve->curve( 50 );

while( @$points )
{
my ( $x, $y ) = splice( @$points, 0, 2 );
print "X : $x\nY : $y\n";
}

TODO
Test, test, test.

BUGS
None known so far. Please report any and all to Nigel Rantor
<[email protected]>

SUPPORT / WARRANTY
This module is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

LICENSE
The Math::CatmullRom module is Copyright (c) 2003 Nigel Rantor. England.
All rights reserved.

You may distribute under the terms of either the GNU General Public
License or the Artistic License, as specified in the Perl README file.

AUTHORS
Nigel Rantor <[email protected]>

SEE ALSO
Math::Bezier.