Help-Site Computer Manuals
Software
Hardware
Programming
Networking
  Algorithms & Data Structures   Programming Languages   Revision Control
  Protocols
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

PGPLOT::Simple
Simple Interface to PGPLOT

PGPLOT::Simple - Simple Interface to PGPLOT


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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGBEG

set_end

Close and release any open graphics devices. This is the same as calling pgend directly.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGEND

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

    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.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSVP

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSWIN

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGTBOX

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPANL

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGRNGE

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGLAB

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPTXT

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGMTXT

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.

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGMOVE

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGDRAW

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGLINE

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPOLY

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGRECT

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGCIRC

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGARRO

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 'Foreground' if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCI

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSTBG

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCRN

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSLW

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSLS

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCF

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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSFS

set_arrow_style

Set the style to be used for arrowheads drawn by draw_arrow.

See arrow_style to see the accepted options.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSAH

set_hatching_style

Set the style to be used for hatching. See fill_style.

See hatching_style to see the accepted options.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSHS


OPTIONS

color

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.

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

    DashDotDotDot

Also accept the number line style code (1-5). See PGPLOT docs.

font

Font type for text.

Supported font type code names:


    Normal

    Roman

    Italic

    Symbol

Also 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

    CrossHatched

Also accept the integer value identifiers (1-4). See PGPLOT docs.

align

Supported text align code names:


    Left

    Center

    Right

Also 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.

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSAVE
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGUNSA
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:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV


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.

Programminig
Wy
Wy
yW
Wy
Programming
Wy
Wy
Wy
Wy