PGPLOT::Simple - Simple Interface to PGPLOT
use strict; use PGPLOT::Simple qw(:essential); die "Must provide a filename.\n" unless @ARGV; my $filename = shift; chomp $filename; unless ( $filename =~ /\.ps$/ ) { $filename .= ".ps"; } set_begin({ file => "$filename/CPS", }); set_environment({ x_min => 0, x_max => 50, y_min => 0, y_max => 10, }); write_label({ title => 'A Simple Graph Using PGPLOT::Simple', color => 'Blue', font => 'Italic', }); draw_points({ x => [1, 3, 12, 32, 40], y => [1, 5, 5, 3, 9], color => 'Blue', width => 20, }); draw_error_bars({ x => [20], y1 => [4], y2 => [6], terminal => 10, width => 10, color => 'Orange', }); set_end;
PGPLOT::Simple is a simple interface to the PGPLOT library ala Perl, making simple things easy and difficult things possible.
Why simple? Because it has a simple and intiutive interface to the most common things you will need from PGPLOT, but also allowing you low-level access to the PGPLOT library.
Opens a graphical device or file and prepares it for subsequent plotting.
set_begin({ file => "$filename/$type", num_x_sub => 2, num_y_sub => 1, });
All the fields are optional. As default file would be used the Standard Output and a type of Color PostScript (CPS).
The number of X and Y subdivision of the view surface is set to 1 for each.
References:
Close and release any open graphics devices. This is the same as calling pgend directly.
This function starts a new picture and defines the range of variables and the scale of the plot. It also draws and labels the enclosing box and the axes if requested.
"set_environment" establishes the scaling for subsequent calls to "draw_points", "draw_polyline", etc. The plotter is advanced to a new page or panel, clearing the screen if necessary.
set_environment({ x_min => $x1, # Required. Bottom left coordinate y_min => $y1, # Required x_max => $x2, # Required. Top right coordinate y_max => $y2, # Required justify => 0, # Default axis => 'BoxCoordAxes', # Default });
Supported axis codes:
Clean Box BoxCoord BoxCoordAxes BoxCoordAxesGrid BoxXLog BoxYLog BoxXYLog
Also accept the axis number code from the PGPLOT library.
Set justify to something other than 0, to set the scales of the x and y axes (in world coordinates per inch) equal.
Change the size and position of the viewport, specifying the viewport in normalized device coordinates. Normalized device coordinates run from 0 to 1 in each dimension. The viewport is the rectangle on the view surface "through" which one views the graph.
set_viewport({ x_left => $x1, # Required. Left coordinate x_right => $x2, # Required. Right coordinate y_bot => $y1, # Required. Bottom coordinate y_top => $y2, # Required. Top coordinate });
Change the window in the world coordinate space that is to be mapped on the viewport.
set_window({ x_min => $x1, # Required. Bottom left coordinate y_min => $y1, # Required x_max => $x2, # Required. Top right coordinate y_max => $y2, # Required });
Draw a box and optionally label one of both axes with (DD) HH MM SS style nummeric labels (useful for time or RA - DEC plots).
You define a style or options for each label. See documentation for a larger discussion about what's available.
set_box({ x_style => 'ABCGZHON', # Default y_style => 'ABCGN', # Default x_tick => 0.0, # Default y_tick => 0.0, # Default n_x_sub => 0, # Default n_y_sub => 0, # Default });
All parameters are optional, in which case the default values will be used.
Start plotting in a different panel. If the view surface has been divided into panels by "set_begin" or using the PGPLOT functions pgbeg or pgsubp, this routine can be used to move to a different panel.
set_active_panel({ x_index => 2, # Required y_index => 1, # Required });
Choose plotting limits x_low and x_high which encompass the data range x1 to x2.
set_range({ x_low => $min - 1, # Required x_high => $max + 1, # Required x1 => $min, # Required x2 => $max, # Required });
Set the graphs title and labels.
write_label({ x => 'X', # Default y => 'Y', # Default title => 'Untitled', # Default font => 'Normal', # Default color => 'Blue', });
Primitive routine for drawing text. The text may be drawn at any angle with the horizontal, and may be centered or left- or right- justified at a specified position.
write_text({ x => 800, # Required y => 1.5, # Required string => "PGPLOT Is Great!", # Required angle => 0, # Default align => 'Left', # Default background => 'BlueMagenta', color => 'Yellow', height => 2.5, font => 'Script', });
Write text at a position specified relative to the viewport (outside or inside). This routine is useful for annotating graphs. It is used by routine "write_label".
write_text_viewport({ string => "Potatoes", # Required displace => "BR", # Default coord => 1, # Default justify => 'Left', # Default color => 'Cyan', });
Displace must include one of the characters 'B', 'L', 'T', or 'R' signifying the Bottom, Left, Top, or Right margin of the viewport. If it includes 'LV' or 'RV', the string is written perpendicular to the frame rather than parallel to it.
Justify can be one of 'Left', 'Right' and 'Center'. It also accept the nummeric values defined for the pgmtxt function.
Add graph markers points to an existing graph. Must provide X and Y data and Symbol.
draw_points({ x => \@x_data, # Required y => \@y_data, # Required symbol => $symbol, color => 'Red', });
It really draw graph markers, but by default the symbol used to graph is a point. If you want something other, you need to provide a valid symbol code. See PGPLOT documentation to get the list of symbols.
Note: It's called draw_points because mainly you will use it for drawing points, and because it's easier to remember than draw_graph_markers.
Move pen to the point with world coordinates X,Y. No line is drawn.
move_pen({ x => 200, y => 400, });
Return the current pen position. Can also be called without X and Y position, in this case only the pen position is returned.
Note: return a list with 2 values, first value correspond to the X value, and second correpond to the Y value.
Draw a line from the current pen position to the point with world coordinates X,Y. The new pen position is X,Y in world coordinates.
draw_line({ x => 743, # Required y => 324, # Required });
Add a line to an existing graph. Must provide X and Y data.
draw_polyline({ x => \@x_data, # Required y => \@y_data, # Required color => 'Green', width => 5, style => 'Dotted', });
Add a polygon to an existing graph. Must provide X and Y data.
draw_polygon({ x => \@x_data, # Required y => \@y_data, # Required color => 'Green', width => 2, style => 'Dashed', fill => 'Outline', });
Add a rectangle to an existing graph. Must provide X and Y data.
draw_rectangle({ x1 => $x1, # Required x2 => $x2, # Required y1 => $y1, # Required y2 => $y2, # Required color => 'Orange', width => 7, style => 'FullLine', fill => 'Hatched', });
Add a circle to an existing graph. Must provide X, Y and Radius data.
draw_circle({ x => $x, # Required y => $y, # Required radius => $rad, # Required color => 'Orange', width => 7, style => 'DotDashDotDash', fill => 'CrossHatched', });
Add a arrow to an existing graph. Must provide X and Y data.
draw_arrow({ x1 => 1320, # Required x2 => 1650, # Required y1 => 20, # Required y2 => 140, # Required color => 'GreenYellow', width => 10, arrow_style => { fill => 'Outline', angle => 50, }, });
Plot horizontal or vertical error bars. Must provide X and Y data.
draw_error_bars({ x1 => [400, 1000, 2600], # Required Horizontal x2 => [500, 1000, 3000], # Required y => [1.2, 1.5, 1.4], # Required terminal => 2, # Required width => 2, color => $f, }); draw_error_bars({ y1 => \@c, # Required Vertical y2 => \@b, # Required x => \@a, # Required terminal => 0.0, # Required });
You also need to provide a 'terminal' key which corresponds to the length of terminals to be drawn at the ends of the error bar, as a multiple of the default length; if 'terminal' = 0.0, no terminals will be drawn.
Draw functions. Must provide function type:
'x' - Function defined by Y = F(X) 'y' - Function defined by X = F(Y) 'xy' - Function defined by X = F(T), Y = G(T) draw_function('x', { fy => sub{ sqrt($_[0]) }, # Required num => 500, # Required. Num. of points required to # define the curve. min => 0, # Required max => 50, # Required flag => 1, # Default. color => 'Blue', width => 7, }); draw_function('xy', { fy => sub{ 3 * cos $_[0] }, # Required fx => sub{ 5 * sin $_[0] }, # Required num => 500, # Required min => 10, # Required max => 100, # Required color => 'GreenCyan', width => 7, });
Flag option define if the curve is plotted in the current window and viewport. If the value is 0 pgenv is called automatically by one of the PGPLOT functions subroutines to start a new plot with automatic scaling. Take a look at the "Notes" section to see what this would imply.
Draw a histogram of unbinned data.
draw_histogram({ data => \@a, # Required min => 0, max => 300, nbin => 25, color => 'Red', width => 2, flag => 1, # Default });
Min and max values are the minimum and maximum data value for the histogram. Min and max values defaults to the min and max value of the given array.
Nbin is the number of bins to use. Defaults to the number of elements that has the array modulo 400, which corresponds to the maximum value of bins possible.
Set next primitive color, launch exception if a wrong color supplied.
See "color" to see the valid color code names. Defaults to 'Foreground' if nothing supplied.
Support same color options as "set_color". Defaults to transparent if nothing supplied.
Set a color representation for a index value. This index value can be used later to referring to this color.
To define a color we need to pass the RGB values to the function.
set_color_representation({ code => 20, # Required red => 0.1, # Required green => 0.4, # Required blue => 0.8, # Required });
Set line height of the next primitive. Launch exception if something other than a digit is supplied.
See "width" to get the valid width range.Defaults to 2 pixel width if nothing supplied.
Set line style of the next line primitive. Launch exception if a wrong line style code is supplied.
See "style" to see the supported line style codes.
Set the Character Font for the next text plotting.
See "font" to see the supported font types. Defaults to 'Normal' if nothing supplied.
Set the Fill-Area Style attribute for subsequent area-fill by "draw_polygon", "draw_rectangle", "draw_circle" or the equivalent low level functions call pgpoly, pgrect, pgcirc.
See "fill" to see the supported styles. Defaults to 'Solid' if nothing supplied.
Set the style to be used for arrowheads drawn by "draw_arrow".
See "arrow_style" to see the accepted options.
Set the style to be used for hatching. See "fill_style".
See "hatching_style" to see the accepted options.
Supported color code names:
Background Foreground Red Green Blue Cyan Magenta Yellow Orange GreenYellow GreenCyan BlueCyan BlueMagenta RedMagenta DarkGray LightGray
Also accept the number color codes (0-255). For color numbers major than 15, you must define the color representation. See "set_color_representation" and PGPLOT docs.
See "color".
Set the line-width attribute. This attribute affects lines, graph markers, and text. The line width is specified in units of 1/200 (0.005) inch (about 0.13 mm) and must be an integer in the range 1-201.
This attribute affects line primitives only; it does not affect graph markers, text, or area fill.
Supported line style code names:
FullLine Dashed DotDashDotDash Dotted DashDotDotDot
Also accept the number line style code (1-5). See PGPLOT docs.
Font type for text.
Supported font type code names:
Normal Roman Italic Symbol
Also accept the font number code (1-4). See PGPLOT docs.
Set the Fill-Area Style attribute for polygons, rectangles or circles.
Solid Outline Hatched CrossHatched
Also accept the integer value identifiers (1-4). See PGPLOT docs.
Supported text align code names:
Left Center Right
Also accept the float value identifiers (0, 0.5, 1). See PGPLOT docs.
Set the character size attribute. The size affects all text and graph markers drawn later in the program. The default character size is 1.0, corresponding to a character height about 1/40 the height of the view surface. Changing the character size also scales the length of tick marks drawn by "set_box" and terminals drawn by "draw_error_bars".
You have 3 keys to define the different parts of an arrow head:
fill_style - Can be 'Filled' or 'Outline'. angle - The acute angle of the arrow point. barb - The fraction of the triangular arrow-head that is cut away from the back.
Example:
arrow_style => { fill => 'Filled', # Default angle => 45.0, # Default barb => 0.3, # Default },
hatching_style => { angle => 45.0, # Default spacing => 1.0, # Default phase => 0.0, # Default },
To make direct call to the PGPLOT Library you only need to call it with the package name. Example:
print PGPLOT::Simple::pgldev();
Or, if you want to import all the functions into your namespace add the pgplot into your import call. Example:
use PGPLOT::Simple qw(:pgplot);
Or combine them as you need. Example:
use PGPLOT::Simple qw( :essential set_color_representation :pgplot );
Please note that on each function where you can define attributes, this attributes are relative to the given function.
On PGPLOT you set a main style which all function inherit, so that changing the color using a function like set_color implies that each function call after the color setting will be plotted using that "active color".
To don't lose this global attributes settings mechanism, which can be useful, each function call of this module will call a function available from the PGPLOT Library that permits to save the current attributes, and another which permits to restore them.
If we set the flag option to 0, pgenv is called automatically by that function to start a new plot, but we should be aware, that each attribute we associated with the function call, for example color settings, will be applied not only to that function, but also be applied to what pgenv generates. E.g.:
draw_function('x', { fy => sub{ sqrt $_[0] }, num => 500, min => 0, max => 50, color => 'Blue', width => 7, flag => 0, # Here we set it to 0, by default is 1. });
Doing this, we will have the boxes, and labels also with a width of 7 and in blue.
PGPLOT Perl Module by Karl Glazebrook.
PGPLOT Library by Tim Pearson, http://www.astro.caltech.edu/~tjp/pgplot.
Florian Merges, <fmerges@cpan.org>
Copyright (C) 2005 by Florian Merges
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.
To install PGPLOT::Simple, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PGPLOT::Simple
CPAN shell
perl -MCPAN -e shell install PGPLOT::Simple
For more information on module installation, please visit the detailed CPAN module installation guide.