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.

cpanm Math::CatmullRom

perl -MCPAN -e shell
install Math::CatmullRom