view release on metacpan or  search on metacpan

lib/PDL/Graphics/Prima/Simple.pm  view on Meta::CPAN

=back

And with that, let's look at how to I<use> these to view data!

=head1 TUTORIAL

To begin, let's assume you have some x/y data that you want to plot with lines
connecting them. My canonical example is a sine wave. Here's a complete script
to get us started:

 use PDL;
 use PDL::Graphics::Prima::Simple;
 my $x = sequence(100)/10;
 line_plot($x, $x->sin);
 print "All done!\n";

The C<use PDL> line L<pulls in all the machinery for the Perl Data Language|PDL>
and, more importantly, imports the L<C<sequence>|PDL::Basic/sequence> function
(among many others) into the current package. On the third line we use that
function to generate a bunch of x-data with a spacing of 1/10. In the last
line we plot the sine of that sequence of points.

When you run the above example script, it will block at the C<line_plot>
command and display a L<Prima window|Prima::Window> with your plot. (On the
other hand, if you are in the L<pdl shell|perldl>, the plot will be displayed
but it will not block your shell if you have a recent version of
L<Term::ReadLine>.) We will return to the blocking behavior, and how to call
this in a non-blocking fashion, in a little bit.

=head2 Interactive Features

For now, turn your attention to the plot. This is a highly interactive
plot, as are all plots made with
L<PDL::Graphics::Prima>. In particular,
your plot responds to the following user interactions:

=over

=item right-click zooming

Clicking and dragging your right mouse button will zoom into a specific region.
You will see a zoom rectangle on the plot until you release the mouse, at which
point the plot will be zoomed-in to the region that you selected.

=item scroll-wheel zooming

You can zoom-in and zoom-out using your scroll wheel. The zooming is designed to
keep the data under the mouse at the same location as you zoom in and out.
(This is not a 100% guarantee, but for most uses it works about right.)

=item dragging/panning

Once you have zoomed into a region, you can examine nearby data by clicking and
dragging with your left mouse button, much like an interactive map.

=item context menu

Right-clicking on the plot will bring up a L<context menu|Prima::Menu> with
options including restoring auto-scaling, L<copying the current plot image to
your clipboard|PDL::Graphics::Prima/copy_to_clipboard>* (to paste directly
into, say, Microsoft's PowerPoint or LibreOffice's Impress),
and saving the current plot image to a
L<postscript|PDL::Graphics::Prima/save_to_postscript> or
L<raster|PDL::Graphics::Prima/save_to_file> file. Postscript
output is L<always|Prima::PS::Drawable> L<supported|Prima::PS::Printer>, but
the supported raster output file formats depend on the L<image libraries and
codecs that Prima was able to build against|Prima::image-load>, so are system-
and machine-dependent. For additional information on raster images, see
L<Prima::Image>.

* For reasons not clear to me, copying the plot to the clipboard does not
seem to work on Mac and appear to be due to limitations with the X-window
bindings.

=item resizable

When packed into a resizable window (as is the case in this example), the plot
can be resized and it will be updated and redrawn smoothly.

=back

The library lets you
L<specify the|PDL::Graphics::Prima::Axis/min, max>
L<x- and y-bounds of the plot|PDL::Graphics::Prima::Axis/minmax>, but if you do
not specify bounds, the axis bounds will be calculated to tightly fit the data.
In fact, the library is designed to automatically choose axis boundaries that fit your
data and symbols exactly. (And if you wanted a bit of padding included in that
auto-fitting... well... it's on my todo list. :-)

=head2 Soapbox

Having played around with the plot widget, you probably want to know how to
modify it programatically, by adding a L<title|PDL::Graphics::Prima/title> or
L<axis labels|PDL::Graphics::Prima::Axis/label>, perhaps. "What sort of
options," you ask, "does L</line_plot> accept for me to specify
these things?" Well, you can't specify those in your call to
L</line_plot>. You either add them to the object after
L</line_plot> builds something for you, or you use the more
powerful but verbose L<plot function|/"PLOT FUNCTION">.

"But WHY?" you ask. "WHY can't I just specify a plot title in
L</line_plot> and be done with it?" The reason is simple. The
underlying library is built on a very clean and well-thought-out object and
I would rather not waste my time creating or your time learning some
intermediate API. A means for specifying the plot title in
L</line_plot> is the first step down the road of confused mental
models. So, it's really in your best interest. Honest. :-)

"But WHY?" you ask again. OK, OK, I'll tell you how to essentially get what
you want.

=head2 Adding axis labels and titles via methods

First, you can use the C<line_plot> command to build a
L<plot object|PDL::Graphics::Prima/> and return them to you I<without
blocking your script.> This will allow you to modify the properties of the 
L<plot object|PDL::Graphics::Prima/> before it gets displayed. For example, I
can L<add a plot title|PDL::Graphics::Prima/title> and
L<specifically choose when to view the plot|Prima::Window/execute> like so:

 use PDL;
 use PDL::Graphics::Prima::Simple;

 # Non-blocking
 auto_twiddle(0);

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

 # Add a title