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
    <wiggly@wiggly.org>

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 <wiggly@wiggly.org>

SEE ALSO
    Math::Bezier.

