NAME

Math::Project3D::Plot - Perl extension for plotting projections of 3D functions

SYNOPSIS

  use Math::Project3D::Plot;

  # Create new image or open an existing one
  my $img = Imager->new(...);

  # Create new projection
  my $projection = Math::Project3D->new(
    # see Math::Project3D manpage!
  );

  my $plotter = Math::Project3D::Plot->new(
    image      => $img,
    projection => $projection,

    # 1 logical unit => 10 pixels
    scale      => 10,

    # x/y coordinates of the origin in pixels
    origin_x   => $img->getwidth()  / 2,
    origin_y   => $img->getheight() / 2,
  );

  $plotter->plot_axis(
    color  => $color,    # see Imager manpage about colors
    vector => [1, 0, 0], # That's the x-axis
    length => 100,
  );

  $plotter->plot(
    params   => [@parameters],
    color    => $color, # see Imager manpage about colors
  );

  $plotter->plot_list(
    params => [
                [@parameter_set1],
                [@parameter_set2],
                # ...
              ],
    color  => $color, # see Imager manpage about colors
    type   => 'line', # connect points with lines
                      # other option: 'points'
  );

  $plotter->plot_range(
    params => [
                [$lower_boundary1, $upper_boundary1, $increment1],
                [$lower_boundary2, $upper_boundary2, $increment2],
                # ...
              ],
    color  => $color,   # see Imager manpage about colors
    type   => 'points', # draw the points only 
                        # other options: 'line' and 'multiline'
  );

  # Use Imager methods on $img to save the image to a file

DESCRIPTION

This module may be used to plot the results of a projection from a three dimensional vectorial function onto a plane into an image. What a horrible sentence.

Methods

new

new is the constructor for Math::Project3D::Plot objects. Using the specified arguments, it creates a new instance of Math::Project3D::Plot. Parameters are passed as a list of key value pairs. Valid parameters are:

  required:
  image      => Imager object to draw into
  projection => Math::Project3D object to get projected
                points from

  optional:
  scale      => how many pixels per logical unit
                (defaults to 10)
  origin_x   => graphical x coordinate of the origin
  origin_y   => graphical y coordinate of the origin
                (default to half the width/height of the
                image)  

plot

The plot method plots the projected point associated with the function parameters passed to the method. Takes its arguments as key/value pairs. The following parameters are valid (and required):

color

Imager color to use (see Imager::Color manpage)

params

Array reference containing a list of function parameters

In addition to plotting the point, the method returns the graphical coordinates of the point.

plot_list

The plot_list method plots all projected points associated with the sets of function parameters passed to the method. Takes its arguments as key/value pairs. The following parameters are valid:

color

Imager color to use (see Imager::Color manpage)

params

Array reference containing any number of array references containing sets of function parameters

type

May be either 'line' or 'points' (connect points or not) (defaults to 'points').

plot_range

The plot_range method plots all projected points associated with the function parameter ranges passed to the method. Takes its arguments as key/value pairs. The following parameters are valid:

color

Imager color to use (see Imager::Color manpage)

params

Array reference containing an array reference for every function parameter. These inner array references are to contain one or three items: one: static parameter three: lower boundary, upper boundary, increment

type

May be either 'line' or 'points' (connect points or not) (defaults to 'points').

New in v1.010: type 'multiline' that works similar to 'line', but does not connect points whenever a parameter other than the innermost one is incremented. This is usually the desired method whenever you are plotting functions of multiple parameters and are experiencing odd lines connecting different parts of the function. 'multiline' is only a valid type for 'plot_range', not for the other plotting methods.

plot_axis

The plot_axis method draws an axis into the image. "Axis" used as in "a line that goes through the origin". Required arguments:

  color  => Imager color to use (see Imager::Color manpage)
  vector => Array ref containing three vector components.
            (only the direction matters as the vector will
            be normalized by plot_axis.)
  length => Desired axis length.

AUTHOR

Steffen Mueller, <smueller@cpan.org>

COPYRIGHT AND LICENSE

Copyright (c) 2002-2006 Steffen Mueller. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Imager, Math::Project3D, Math::Project3D::Function, Math::MatrixReal