view release on metacpan or  search on metacpan

lib/PDL/Graphics/Gnuplot.pm  view on Meta::CPAN

If you want to plot multiple curves of the same type without setting
any curve options explicitly, you must include an empty hash ref
between the tuples for subsequent lines, as in:

 gplot( $x, $a, {}, $x, $b, {}, $x, $c );

=head2 Data arguments

Following the curve options in the C<plot()> argument list is the
actual data being plotted. Each output data point is a "tuple" whose
size varies depending on what is being plotted. For example if we're
making a simple 2D x-y plot, each tuple has 2 values; if we're making
a 3d plot with each point having variable size and color, each tuple
has 5 values (x,y,z,size,color). Each tuple element must be passed
separately.  For ordinary 2-D plots, the 0 dim of the tuple elements
runs across plotted point.  PDL threading is active, so you can plot
multiple curves with similar curve options on a normal 2-D plot, just
by stacking data inside the passed-in PDLs.  (An exception is that
threading is disabled if one or more of the data elements is a list
ref).

=head3 PDLs vs array refs

The usual way to pass in data is as a PDL -- one PDL per column of data
in the tuple.  But strings, in particular, cannot easily be hammered into
PDLs.  Therefore any column in each tuple can be an array ref containing
values (either numeric or string).  The column is interpreted using the
usual polymorphous cast-behind-your-back behavior of Perl.  For the sake
of sanity, if even one array ref is present in a tuple, then threading is
disabled in that tuple: everything has to have a nice 1-D shape.


=head3 Implicit domains

When making a simple 2D plot, if exactly 1 dimension is missing,
PDL::Graphics::Gnuplot will use C<sequence(N)> as the domain. This is
why code like C<plot(pdl(1,5,3,4,4) )> works. Only one PDL is given
here, but the plot type ("lines" by default) requires 2 elements per
tuple. We are thus exactly 1 ndarray short; C<sequence(5)> is used as
the missing domain PDL.  This is thus equivalent to
C<plot(sequence(5), pdl(1,5,3,4,4) )>.

If plotting in 3d or displaying an image, an implicit domain will be
used if we are exactly 2 ndarrays short. In this case,
PDL::Graphics::Gnuplot will use a 2D grid as a domain. Example:

 my $xy = zeros(21,21)->ndcoords - pdl(10,10);
 gplot({'3d' => 1},
        with => 'points', inner($xy, $xy));
 gplot( with => 'image',  sin(rvals(51,51)) );

Here the only given ndarray has dimensions (21,21). This is a 3D plot, so we are
exactly 2 ndarrays short. Thus, PDL::Graphics::Gnuplot generates an implicit
domain, corresponding to a 21-by-21 grid.

C<PDL::Graphics::Gnuplot> requires explicit separators between tuples
for different plots, so it is always clear from the arguments you pass
in just how many columns you are supplying. For example,
C<plot($a,$b)> will plot C<$b> vs. C<$a>.  If you actually want to
plot an overlay of both C<$a> and C<$b> against array index, you want
C<plot($a,{},$b)> instead.  The C<{}> is a hash ref containing a
collection of all the curve options that you are changing between
the two curves -- in this case, zero of them.

=head2 Images

PDL::Graphics::Gnuplot supports four styles of image plot, via the "with" curve option.

The "image" style accepts a single image plane and displays it using
the palette (pseudocolor map) that is specified in the plot options
for that plot.  As a special case, if you supply as data a (3xWxH) or
(WxHx3) PDL it is treated as an RGB image and displayed with the
"rgbimage" style (below), provided there are at least 5 pixels in each of the
other two dimensions (just to be sure).  For quick image display there
is also an "image" method:

 use PDL::Graphics::Gnuplot qw/image gplot/;
 $im = sin(rvals(51,51)/2);
 image( $im );                # display the image
 gplot( with=>'image', $im );  # display the image (longer form)

The colors are autoscaled in both cases.  To set a particular color range, use
the 'cbrange' plot option:

 image( {cbrange=>[0,1]}, $im );

You can plot rgb images directly with the image style, just by including a
3rd dimension of size 3 on your image:

 $rgbim = pdl( xvals($im), yvals($im),rvals($im)/sqrt(2));
 image( $rgbim );                # display an RGB image
 gplot( with=>'image', $rgbim ); # display an RGB image (longer form)

Some additional plot styles exist to specify RGB and RGB transparent forms
directly.  These are the "with" styles "rgbimage" and "rgbalpha".  For each
of them you must specify the channels as separate PDLs:

 gplot( with=>'rgbimage', $rgbim->dog );               # RGB  the long way
 gplot( with=>'rgbalpha', $rgbim->dog, 255*($im>0) );  # RGBA the long way

According to the gnuplot specification you can also give X and Y
values for each pixel, as in

 gplot( with=>'image', xvals($im), yvals($im), $im )

but this appears not to work properly for anything more complicated
than a trivial matrix of X and Y values.

PDL::Graphics::Gnuplot provides a "fits" plot style that interprets
World Coordinate System (WCS) information supplied in the header of
the scientific image format FITS. The image is displayed in rectified
scientific coordinates, rather than in pixel coordinates.  You can plot
FITS images in scientific coordinates with

 gplot( with=>'fits', $fitsdata );

The fits plot style accepts a curve option "resample" (which may be
abbreviated), that allows you to downsample and/or rectify the image
before it is passed to the Gnuplot back-end.  This is useful either to
cut down on the burden of transferring large blocks of image data or