Provided by: pdl_2.074-1_amd64 bug

NAME

       PDL::Demos::Prima - PDL demo for PDL::Graphics::Prima

SYNOPSIS

       You can enjoy this demo in any number of ways. First, you can invoke the demo from the
       command line by saying

        perl -MPDL::Demos::Prima

       Second, you can invoke the demo from with the pdl shell by saying

        pdl> demo prima

       Finally, all of the content is in the pod documentation, so you can simply read this,
       though it won't be quite so interactive. :-)

        perldoc PDL::Demos::Prima
        podview PDL::Demos::Prima

DESCRIPTION

       The documentation in this module is meant to give a short, hands-on introduction to
       PDL::Graphics::Prima, a plotting library written on top of the Prima GUI toolkit.

   use PDL::Graphics::Prima::Simple
       To get started, you will want to use PDL::Graphics::Prima::Simple. This module provides a
       set of friendly wrappers for simple, first-cut data visualization. PDL::Graphics::Prima,
       the underlying library, is a general-purpose 2D plotting library built as a widget in the
       Prima GUI toolkit, but we don't need the full functionality for the purposes of this demo.

        use PDL::Graphics::Prima::Simple;
        my $x = sequence(100)/10;
        line_plot($x, $x->sin);

   More than just lines!
       In addition to numerous ways to plot x/y data, you can also plot distributions and images.
       The best run-down of the simple plotting routines can be found in the Synopsis for
       PDL::Graphics::Prima::Simple.

        $distribution = grandom(100);
        hist_plot($distribution);

        $x = sequence(100)/10;
        cross_plot($x, $x->sin);

        $image = rvals(100, 100);
        matrix_plot($image);

   Mouse Interaction
       Plots allow for mouse interaction, herein referred to as twiddling. You can resize the
       window, zoom with the scroll wheel, or click and drag the canvas around. There is also a
       right-click zoom-rectangle, and a right-click context menu.

        hist_plot(grandom(100));

        # Run this, then try using your mouse

       In your Perl scripts, and in the PDL shell for some operating systems and some versions of
       Term::ReadLine, twiddling will cause your script to pause when you create a new plot. To
       resume your script or return execution to the shell, either close the window or press 'q'.

        # If your PDL shell supports simultaneous
        # input and plot interaction, running this
        # should display both plots simultaneously:

        $x = sequence(100)/10;
        cross_plot($x, $x->sin);
        line_plot($x, $x->cos);

   Multiple plots without blocking
       The blocking behavior just discussed is due to what is called autotwiddling.  To turn this
       off, simply send a boolean false value to auto_twiddle. Then, be sure to invoke twiddling
       when you're done creating your plots.

        auto_twiddle(0);
        hist_plot(grandom(100));
        matrix_plot(rvals(100, 100));
        twiddle();

       Once turned off, autotwiddling will remain off until you turn it back on.

        # autotwiddling still off
        hist_plot(grandom(100));
        matrix_plot(rvals(100, 100));
        twiddle();

   Adding a title and axis labels
       Functions like hist_plot, cross_plot, and matrix_plot actually create and return plot
       objects which you can subsequently modify. For example, adding a title and axis labels are
       pretty easy. For titles, you call the title method on the plot object. For axis labels,
       you call the label method on the axis objects.

        # Make sure autotwiddling is off in your script
        auto_twiddle(0);

        # Build the plot
        my $x = sequence(100)/10;
        my $plot = line_plot($x, $x->sin);

        # Add the title and labels
        $plot->title('Harmonic Oscillator');
        $plot->x->label('Time [s]');
        $plot->y->label('Displacement [cm]');

        # Manually twiddle once everything is finished
        twiddle();

   Saving to a file
       PDL::Graphics::Prima::Simple excels at user interaction, but you can save your plots to a
       file using save_to_file or save_to_postscript methods, or by right-clicking and selecting
       the appropriate menu option.

        auto_twiddle(0);
        $x = sequence(100)/10;
        line_plot($x, $x->sin)->save_to_postscript;

        # You can supply a filename to the method if you like.
        # Also available is save_to_file, which saves to raster
        # file formats. Expect save_to_postscript to be merged
        # into save_to_file in the future.

   Adding additional data to the plot
       Once you have created a plot, you can add additional data to it. You achieve this by
       adding a new DataSet with the data you want displayed.

        auto_twiddle(0);
        my $plot = hist_plot(grandom(100));

        # Add a Gaussian curve that "fits" the data
        use PDL::Constants qw(PI);
        my $fit_xs = zeroes(100)->xlinvals(-2, 2);
        my $fit_ys = exp(-$fit_xs**2 / 2) / sqrt(2*PI);
        $plot->dataSets->{fit_curve} = ds::Pair($fit_xs, $fit_ys);

        twiddle();

       The default plot type for pairwise data is Diamonds. You can choose a different pairwise
       plot type, or even mix and match multiple pairwise plot types.

        auto_twiddle(0);
        my $plot = hist_plot(grandom(100));

        # Add a Gaussian curve that "fits" the data
        use PDL::Constants qw(PI);
        my $fit_xs = zeroes(200)->xlinvals(-5, 5);
        my $fit_ys = exp(-$fit_xs**2 / 2) / sqrt(2*PI);
        $plot->dataSets->{fit_curve} = ds::Pair($fit_xs, $fit_ys,
            # Use lines
            plotTypes => [
                ppair::Lines(
                    # with a thickness of three pixels
                    lineWidth => 3,
                    # And the color red
                    color => cl::LightRed,
                ),
                ppair::Diamonds,
            ],
        );

        twiddle();

   The plot command
       If you want to specify everything in one command, you can use the plot function. This lets
       you put everything together that we've already discussed, including multiple DataSets in a
       single command, title specification, and x and y axis options.

        # Generate some data:
        my $xs = sequence(100)/10 + 0.1;
        my $ys = $xs->sin + $xs->grandom / 10;
        my $y_err = $ys->grandom/10;

        # Plot the data and the fit
        plot(
            -data => ds::Pair($xs, $ys,
                plotTypes => [
                    ppair::Triangles(filled => 1),
                    ppair::ErrorBars(y_err => $y_err),
                ],
            ),
            -fit  => ds::Func(\&PDL::sin,
                lineWidth => 3,
                color => cl::LightRed,
            ),
            -note => ds::Note(
                pnote::Text('Incoming Signal',
                    x => 0.2,
                    y => sin(0.2) . '-3em',
                ),
            ),
            title => 'Noisey Sine Wave',
            x => {
                label => 'Time [s]',
                scaling => sc::Log,
            },
            y => { label => 'Measurement [Amp]' },
        );

   Enjoy PDL::Graphics::Prima!
       I hope you've enjoyed the tour, and I hope you find PDL::Graphics::Prima to be a useful
       plotting tool!

        # Thanks!

AUTHOR

       David Mertens "dcmertens.perl@gmail.com"

LICENSE AND COPYRIGHT

       Copyright (c) 2013, David Mertens. All righs reserved.

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