diff --git a/README.pod b/README.pod index a2c6953..48cba05 100644 --- a/README.pod +++ b/README.pod @@ -43,7 +43,7 @@ PDL::Graphics::Gnuplot - Gnuplot-based plotting for PDL This module allows PDL data to be plotted using Gnuplot as a backend for 2D and 3D plotting and image display. Gnuplot (not affiliated -with the Gnu project) is a venerable, open-source program that +with the GNU project) is a venerable, open-source program that produces both interactive and publication-quality plots on many different output devices. It is available through most Linux repositories, on MacOS, and from its website @@ -54,6 +54,12 @@ basic, or even complex, plots - though the full syntax is available for advanced users who want the full flexibility of the Gnuplot backend. +For a very quick demonstration of the power of this module, see +L, +and others on visualisation of +L and +L. + Gnuplot recognizes both hard-copy and interactive plotting devices, and on interactive devices (like X11) it is possible to pan, scale, and rotate both 2-D and 3-D plots interactively. You can also enter @@ -120,8 +126,8 @@ is called a "tuple". These plots have two columns in their tuples: Normal threading rules apply across the arguments to a given plot. -All data are required to be supplied as either PDLs or list refs. -If you use a list ref as a data column, then normal +All data are required to be supplied as either PDLs or array refs. +If you use an array ref as a data column, then normal threading is disabled. For example: $x = xvals(5); @@ -394,14 +400,14 @@ 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 list refs +=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 a list ref containing +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 list ref is present in a tuple, then threading is +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. @@ -608,7 +614,7 @@ specifies the printf format used by contour labels in contour plots.) C controls where the plot key (that relates line/symbol style to label) is placed on the plot. It takes a scalar boolean indicating whether to turn the -key on (with default values) or off, or a list ref containing any of the following +key on (with default values) or off, or an array ref containing any of the following arguments (all are optional) in the order listed: =over 3 @@ -709,21 +715,21 @@ These are Gnuplot's usual three options for line control. =back The C option indicates whether gridlines should be drawn on -each axis. It takes a list ref of arguments, each of which is either "no" or "m" or "", +each axis. It takes an array ref of arguments, each of which is either "no" or "m" or "", followed by an axis name and "tics" -- e.g. C<< grid=>["noxtics","ymtics"] >> draws no X gridlines and draws (horizontal) Y gridlines on Y axis major and minor tics, while C<< grid=>["xtics","ytics"] >> or C<< grid=>["xtics ytics"] >> will draw both vertical (X) and horizontal (Y) grid lines on major tics. -vTo draw a coordinate grid with default values, set C<< grid=>1 >>. For more -control, feed in a list ref with zero or more of the following parameters, in order: +To draw a coordinate grid with default values, set C<< grid=>1 >>. For more +control, feed in an array ref with zero or more of the following parameters, in order: The C keyword indicates whether to actually draw each axis line at the corresponding zero along its indicated dimension. For example, to draw the X axis (y=0), use C<< xzeroaxis=>1 >>. If you just want the axis turned on with default values, you can feed in a Boolean -scalar; if you want to set its parameters, you can feed in a list ref +scalar; if you want to set its parameters, you can feed in an array ref containing linewidth, linestyle, and linetype (with appropriate parameters for each), e.g. C<< xzeroaxis=>[linewidth=>2] >>. @@ -760,7 +766,7 @@ The options described here are =back Gnuplot accepts explicit ranges as plot options for all axes. Each option -accepts a list ref with (min, max). If either min or max is missing, then +accepts an array ref with (min, max). If either min or max is missing, then the opposite limit is autoscaled. The x and y ranges refer to the usual ordinate and abscissa of the plot; x2 and y2 refer to alternate ordinate and abscissa; z if for 3-D plots; r is for polar plots; t, u, and v are for parametric @@ -788,7 +794,7 @@ once by setting the keyword name to ' '. Examples: autoscale=>{x=>'max',y=>'fix'}; -There is an older list ref syntax which is deprecated but still accepted. +There is an older array ref syntax which is deprecated but still accepted. To not autoscale an axis at all, specify a range for it. The fix style of autoscaling forces the autoscaler to use the actual min/max of the data as @@ -797,7 +803,7 @@ to the next minor tic (as set by the autoticker or by a tic specification, see below). C allows you to turn on logarithmic scaling for any or all -axes, and to set the base of the logarithm. It takes a list ref, the +axes, and to set the base of the logarithm. It takes an array ref, the first element of which is a string mushing together the names of all the axes to scale logarithmically, and the second of which is the base of the logarithm: C<< logscale=>[xy=>10] >>. You can also leave off the @@ -886,7 +892,7 @@ If you pass in undef, tics get the default length. If you pass in a scalar, maj =item * labels - sets tic locations explicitly, with text labels for each. If you specify both C and C, you get both sets of tics on the same axis. -The labels should be a nested list ref that is a collection of duals +The labels should be a nested array ref that is a collection of duals or triplets. Each dual or triplet should contain [label, position, minorflag], as in C<< labels=>[["one",1,0],["three-halves",1.5,1],["two",2,0]] >>. @@ -1076,7 +1082,7 @@ an alternative to the C and C options below. The C option allows you to put an empty boundary around the data, inside the plot borders, in an autosacaled graph. The offsets only affect the x1 and y1 axes, and only in 2D plot commands. -C accepts a list ref with four values for the offsets, which +C accepts an array ref with four values for the offsets, which are given in scientific (plotted) axis units. The C option lets you specify the origin (lower left corner) @@ -1107,7 +1113,7 @@ grayscale can have a "color box" that shows the photometric meaning of the color The colorbox generally appears when necessary but can be controlled manually with the C option. C accepts a scalar boolean value indicating -whether or no to draw a color box, or a list ref containing additional options. +whether or no to draw a color box, or an array ref containing additional options. The options are all, well, optional but must appear in the order given: =over 3 @@ -1142,7 +1148,7 @@ of color tables, and have better support for scientific images. C (synonym C) gives access to the color tables built in to the C package, if that package is -available. It takes either a color table name or a list ref which +available. It takes either a color table name or an array ref which is a collection of arguments that get sent to the C transform definition method. Sending the empty string or undef will generate a list of allowable color @@ -1185,7 +1191,7 @@ version of the module but are explained in the gnuplot manual. C accepts a list of parameters to control how hidden surfaces are plotted (or not) in 3D. It accepts a boolean argument indicating whether to hide -"hidden" surfaces and lines; or a list ref containing parameters that control how +"hidden" surfaces and lines; or an array ref containing parameters that control how hidden surfaces and lines are handled. For details see the gnuplot manual. C sets the location of that plane (which is drawn) relative @@ -1211,7 +1217,7 @@ C enables contour drawing on surfaces in 3D. It takes a single string, which should be "base", "surface", or "both". C manages how contours are generated and smoothed. It -accepts a list ref with a collection of Gnuplot parameters that are +accepts an array ref with a collection of Gnuplot parameters that are issued one per line; refer to the Gnuplot manual for how to operate it. @@ -1233,7 +1239,7 @@ You specify plot markup in advance of the plot command, with plot options (or add it later with the C method). The options give you access to a collection of (separately) numbered descriptions that are accumulated into the plot object. To add a markup object to the -next plot, supply the appropriate options as a list ref or as a single +next plot, supply the appropriate options as an array ref or as a single string. To specify all markup objects at once, supply the appropriate options for all of them as a nested list-of-lists. @@ -1266,7 +1272,7 @@ you care about. The C