NAME
PGPLOT::Simple - Simple Interface to PGPLOT
SYNOPSIS
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;DESCRIPTION
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.
FUNCTIONS : ESSENTIAL
set_begin
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:
set_end
Close and release any open graphics devices. This is the same as calling pgend directly.
References:
set_environment
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
BoxXYLogAlso 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.
References:
set_viewport
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
});References:
set_window
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
});References:
set_box
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.
References:
set_active_panel
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
});References:
set_range
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
});References:
write_label
Set the graphs title and labels.
write_label({ x => 'X', # Default
y => 'Y', # Default
title => 'Untitled', # Default
font => 'Normal', # Default
color => 'Blue',
});References:
write_text
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',
});References:
write_text_viewport
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.
References:
draw_points
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.
References:
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPT
- http://www.astro.caltech.edu/~tjp/pgplot/hershey.html
move_pen
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_line
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
});References:
draw_polyline
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',
});References:
draw_polygon
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',
});References:
draw_rectangle
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',
});References:
draw_circle
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',
});References:
draw_arrow
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,
},
});References:
draw_error_bars
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.
References:
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGERRX
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGERRY
draw_function
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.
References:
- PGPLOT to see accepted function pass methods.
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNX
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNY
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNT
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV
draw_histogram
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.
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.
References:
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGHIST
- http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV
FUNCTIONS : OPTIONAL
set_color
Set next primitive color, launch exception if a wrong color supplied.
See "color" to see the valid color code names. Defaults to 'Black' if nothing supplied.
References:
set_text_background
Set next primitive color, launch exception if a wrong color supplied.
Support same color options as "set_color". Defaults to transparent if nothing supplied.
References:
set_color_representation
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
});References:
set_line_width
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.
References:
set_line_style
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.
References:
set_font
Set the Character Font for the next text plotting.
See "font" to see the supported font types. Defaults to 'Normal' if nothing supplied.
References:
set_fill_area_style
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.
References:
set_arrow_style
Set the style to be used for arrowheads drawn by "draw_arrow".
See "arrow_style" to see the accepted options.
References:
set_hatching_style
Set the style to be used for hatching. See "fill_style".
See "hatching_style" to see the accepted options.
References:
OPTIONS
color
Supported color code names:
Black
White
Red
Green
Blue
Cyan
Magenta
Yellow
Orange
GreenYellow
GreenCyan
BlueCyan
BlueMagenta
RedMagenta
DarkGray
LightGrayAlso 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.
background
See "color".
width
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.
style
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
DashDotDotDotAlso accept the number line style code (1-5). See PGPLOT docs.
font
Font type for text.
Supported font type code names:
Normal
Roman
Italic
SymbolAlso accept the font number code (1-4). See PGPLOT docs.
fill
Set the Fill-Area Style attribute for polygons, rectangles or circles.
Solid
Outline
Hatched
CrossHatchedAlso accept the integer value identifiers (1-4). See PGPLOT docs.
align
Supported text align code names:
Left
Center
RightAlso accept the float value identifiers (0, 0.5, 1). See PGPLOT docs.
height
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".
arrow_style
Set the style to be used for arrowheads drawn by "draw_arrow".
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
},hathing_style
Set the style to be used for hatching. See "fill_style".
hatching_style => { angle => 45.0, # Default
spacing => 1.0, # Default
phase => 0.0, # Default
},NOTES
- Low level PGPLOT Library function call
-
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 ); - Attributes settings
-
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.
- Functions that provide a flag option
-
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.
References:
SEE ALSO
PGPLOT Perl Module by Karl Glazebrook.
PGPLOT Library by Tim Pearson, http://www.astro.caltech.edu/~tjp/pgplot.
AUTHOR
Florian Merges, <fmerges@cpan.org>
COPYRIGHT AND LICENSE
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.