PostScript::Graph::Paper - prepare blank graph for a postscript file |
PostScript::Graph::Paper - prepare blank graph for a postscript file
Let the module create its own postscript file:
use PostScript::Graph::Paper;
my $pg = new PostScript::Graph::Paper( file => { landscape => 1 }, layout => { title => "Blank grid" } );
$pg->output("testfile");
Add the chart to an existing postscript file:
use PostScript::Graph::Paper; use PostScript::File;
my $ps = new PostScript::File( left => 40, right => 40, top => 30, bottom => 30, landscape => 1, errors => 1 );
new PostScript::Graph::Paper( file => $ps, layout => { title => "Experimental results" }, x_axis => { high => 10, title => "Control variable" }, y_axis => { low => 23.6, high => 24.95, title => "Dependent variable" });
$ps->output("testfile");
Create a bar chart layout:
use PostScript::Graph::Paper;
new PostScript::Graph::Paper( layout => { title => "Survey" }, x_axis => { labels => [ "Men", "Women", "Boys", "Girls", ], }, y_axis => { low => 8, high => 37, } );
$ps->output("testfile");
new PostScript::Graph::Paper( file => $ps_file,
layout => { bottom_edge => 30, top_edge => 30, left_edge => 30, right_edge => 30, spacing => 4, top_margin => 10, right_margin => 10, key_width => 0, sub_divisions => 4, dots_per_inch => 600, font => 'Helvetica', font_color => 0, font_size => 10, heading => 'My Graph', heading_font => 'Times-Bold', heading_font_color => 0.9, heading_font_size => 20, heading_height => 30, background => [ 0.9, 0.95, 0.85 ], color => [ 0, 0, 0.7 ], heavy_color => [0, 0, 0.4], mid_color => [0.6, 0.6, 1], light_color => 0.8, heavy_width => 1, mid_width => 0.8, light_width => 0.25, no_drawing => 0, },
x_axis => { low => 74.25, high => 74.9, width => 200, height => 450, label_gap => 50, labels => [qw(this that other)], labels_req => 7, font => 'Helvetica', font_color => 0, font_size => 10, title => 'X axis', color => 0.5, heavy_color => [0, 0, 0.4], mid_color => [0.6, 0.6, 1], light_color => 0.8, heavy_width => 1, mid_width => 0.8, light_width => 0.25, mark_min => 2, mark_max => 8, smallest => 8, center => 1, offset => 1, rotate => 1, draw_fn => "myxdraw", },
y_axis => { # as x_axis }, );
This module is designed as a supporting part of the PostScript::Graph suite. For top level modules that output something useful, see
PostScript::Graph::Bar PostScript::Graph::Stock PostScript::Graph::XY
An area of graph paper is created on a postscript page. X and Y axes are labelled and there are facilities to add a title and key. This is written to a PostScript::File object (automatically created if not supplied) which can then be output. It is intended to be a static object - once the parameters are set there is little point in changing them - so all options are set in the contructor.
=head1 CONSTRUCTOR
The labelling and layout of the graph is quite flexible, but that level of control inevitably requires many options. If no options are given, graph paper labelled 0 to 100 along each axis fills an A4 page (apart from a half-inch border all round). It is up to the user how much this is altered. Either labels or high and low values will probably need to be given for each axis, with titles, a heading and perhaps some space for a key.
options
can either be a list of hash keys and values or a hash reference. In either case, the hash is expected
to have the same structure. There are a few primary keys, each of which point to sub-hashes which hold options for
that group.
For every option listed here there is a corresponding function returning its value. For example, the label
printed at the top of the y axis is set with the option x_axis =
{ title => '...' }>. x_axis_title()
would
return the string given and the option would be documented as axis_title
.
Example 1
my $gp = new PostScript::Graph::Paper( layout => { title => "Bar chart", right_edge => 500, key_width => 100, }, x_axis => { labels => [ "First bar", "Second bar", "Third bar" ], }, y_axis => { low => 123, high => 456.7, title => "Readings", }, );
This would prepare graph paper for a bar chart with 3 vertical bars and a key.
Example 2
my $gp = new PostScript::Graph::Paper( file => { landscape => 1, errors => 1, }, layout => { font_color => 1, heading_height => 0, left_axis_font_size => 0, bottom_axis_height => 0, left_axis_width => 0, mark_min => 0, mark_max => 0, }, x_axis => { smallest => 72, }, y_axis => { smallest => 72, }, );
This fills an A4 page with a plain grid of squares no smaller than 1 inch big, with no axes, marks, labels, heading or key.
The PostScript::File object which recieves the grid may either be an existing one or the module can create one for
you. Use file
to declare a pre-existing object, or file
to control how the new one is created.
This may be either a PostScript::File object or a options in hash key/value format. If options are given, a new PostScript::File object is created.
Example 1
$psf = new PostScript::File();
$pg = new PostScript::Graph::Paper( file => $psf );
Then $psf == $pg->file();
Example 2
my $ch = new PostScript::Graph::Paper( file => { landscape => 1, clipping => 1, clipcmd => "stroke", debug => 2, errors => 1, } );
These are all set within a layout
option given to the constructor. Remove the initial layout_
to get the
option name. All values are in PostScript native units (72 = 1 inch).
Example
$pg = new PostScript::Graph::Paper( layout => { right_edge => 600, heavy_color => [0, 0, 0.8], light_color => 0.6, font => "Courier", title_font_size => 14, right_margin => 20, spacing => 4 } );
$pg->layout_font() would return "Courier".
=head3 layout_bottom_edge
The bottom boundary of the whole chart area.
Background color.
Default colour for all grid lines. All colours can be either a greyscale value or an array of RGB values. All values vary from 0 = black to 1 = brightest. (Default: 0.5)
Example
layout => { background => [ 0.95, 0.95, 0.85 ], color => [ 0, 0.2, 0.8 ], light_color => 0.85 }
Grid lines will be a blue shade on a beige background, except the lightest lines which will be light grey.
Marks are spaced at a multiple of this value. If this does not match the physical output device, the appearance can be somewhat ragged. (Default: 300)
Default font for everything except titles. (Default: ``Helvetica'')
Default colour for all fonts. (Default: 0)
Default font size for everything except the title font. (Default: 10)
The title above the grid. (Default: ``'')
Font for the main heading above the graph. (Default: ``Helvetica-Bold'')
Colour for main heading. (Defaults to font_color
)
Size for main heading. (Default: 12)
Size of area above the graph holding the main title and the y axis title. (Defaults to just enough space)
The colour of the major, labelled, lines. (Defaults to color
)
Width of the labelled lines. (Default: 0.75)
Width of box at the right of the graph, allocated for the key. If this is 0, no key box is drawn. (Default: 0)
The key is drawn by a seperate PostScript::Graph::Key object. This merely allocates space within the chart edges.
The left boundary of the whole paper area.
Colour of the minor, unlabelled, lines. (Defaults to color
)
Width of the lightest lines. (Default: 0.25)
A scale of 10 will be divided into two lots of 5 seperated by a slightly heavier line at the 5 mark. This is the
'mid' line. (Defaults to color
)
Width of the mid-lines, see </mid_color>. (Default: 0.75)
If true, the call to draw_scales
is not carried out in the constructor, allowing some tinkering with labels
etc. before comitting to postscript. The only way to do this is to access the objects data directly. Use with
caution. (Default: 0)
The right boundary of the whole chart area.
Space at the right hand side of the graph area, taken up by part of the last label. (Default: 15)
Increasing this value seperates out the various parts of the chart, like leading added to text. (Default: 0)
Used by PostScript::Graph::Bar to signal the number of series per label. Not appropriate for anything else.
The top boundary of the whole chart area.
Space above the graph area taken up by part of the topmost y label. (Default: 5)
The axis_
entries below refer to four things: x_axis and y_axis options and x_axis_ and y_axis_ functions
which return those values. Remove the axis_
prefix to get the option name, and prepend x_
or y_
to get
the relevant function name. The options belong within hashes indexed by either x_axis
or y_axis
.
Example
Options documentated as:
axis_low axis_high
Would be set by:
$pg = new PostScript::Graph::Paper( x_axis => { low => 1, high => 12, }, y_axis => { low => 247, high => 980, } );
And inspected by:
$pg->x_axis_low() == 1 $pg->x_axis_high() == 14 $pg->y_axis_low() == 200 $pg->y_axis_high() == 1000
Note that the original values have been adjusted as the scales were calculated.
By default, any labels given to axis_labels
are placed centrally between the lines. Setting this to 0 puts the
labels in the normal 'number' position, next to the major lines.
Colour for grid lines on one axis. See layout_color. (Defaults to layout_color
).
The string given here should be the name of a PostScript function which will draw the axis, lines and labels. See
the code for the /xdraw
and /ydraw
functions which provide the defaults.
Font for labels and title on the axis. (Defaults to font
)
Colour for axis title and labels. (Defaults to font_color
)
Size for title and labels on the axis. (Defaults to font_size
)
The colour of the major, labelled, lines. (Defaults to layout_heavy_color
)
Width of the labelled lines. (Defaults to layout_heavy_width
)
For x: space beneath the x axis. (Defaults to just enough space for the labels and x axis title)
For y: should not be changed. (Defaults to full height of chart area, baring top and bottom space)
The highest number required to appear on the axis. This will be rounded up to suit the chosen scale. (Default: 100)
The space between the start of each label. The effect is for the program to choose more or fewer labels on the x axis. Although available to the y axis, the spacing between labels is rarely an issue. (Default: 30)
This should be a reference to a list of strings. If a list of labels is provided, the axes uses these, ignoring
axis_high
and axis_low
.
The functions x_axis_labels
and y_axis_labels
are unusual in that they set as well as return their value.
Note that any alterations made after new
and before draw_scales
, must have all strings enclosed in '()' for
postscript. The number of labels must NOT be changed.
An indication of the number of major (labelled) marks wanted along the axis. The program overrides this if it is
not suitable. (Default derived from axis_label_gap
)
Colour of the minor, unlabelled, lines. (Defaults to layout_light_color
)
Width of the lightest lines. (Defaults to layout_light_width
)
The lowest number required to appear on the axis. This will be rounded down to suit the chosen scale. (Default: 0)
A scale of 10 will be divided into two lots of 5 seperated by a slightly heavier line at the 5 mark. This is the
'mid' line. (Defaults to layout_mid_color
)
Width of the mid-lines, see </axis_mid_color>. (Defaults to layout_mid_width
)
The gap between smallest marks. This is a calculated value and cannot be set, although it may be controlled with axis_smallest.
The smallest mark on the axis. (Defaults to layout_mark_min
)
The tallest mark on the axis. (defaults to layout_mark_max
)
Setting this to 1 rotates the axis labels 90 degrees right. (Defaults to 1 on the x axis when labels are provided, 0 otherwise)
This is the smallest allowable gap between axis marks. Setting this controls how many subdivisions the program
generates. It would be wise to set this as a multiple of layout_dots_per_inch
. (Defaults to 3 dots)
The number of 0's removed at a time when adjusting the axis labels, e.g. 3 for thousands, 2 for hundreds or 0 for no adjustment. (Default: 3)
The text printed at the top of the y axis and below the right of the x axis. (Default: ``'')
For x: should not be changed. (Defaults to width between y axis and key area)
For y: width allocated for y axis marks and labels. (Default: 36)
Methods are provided which access the option values given to the constructor. Those are file, and all layout_, x_axis_ and y_axis_ methods documented under CONSTRUCTOR.
The most common PostScript::File methods are also provided as members of this class.
However, the most useful methods are those which give access to the layout calculations including conversion functions.
A few methods of the underlying PostScript::File object are provided for convenience. The others can be called via the file() function. The following both do the same thing.
$pg->newpage(); $pg->file()->newpage();
Output the chart as a file. See output in the PostScript::File manpage.
Start a new page in the underlying PostScript::File object. See newpage in the PostScript::File manpage and set_page_label in the PostScript::File manpage.
Add functions to the underlying PostScript::File object. See add_function in the PostScript::File manpage for details.
Add postscript code to the underlying PostScript::File object. See add_to_page in the PostScript::File manpage for details.
Return an array holding (x0, y0, x1, y1), the bounding box of the graph area.
Return the physical coordinates of a barchart bar. Use as:
@area = vertical_bar_area( $bar ) @area = vertical_bar_area( $bar, $y )
Where $bar
is the 0 based number of the bar and $y
is an optional coordinate indicating the top of the bar.
Return the physical coordinates of a barchart bar. Use as:
@area = horizontal_bar_area( $bar ) @area = horizontal_bar_area( $bar, $x )
Where $bar
is the 0 based number of the bar and $x
is an optional coordinate indicating the 'top' of the bar.
Return the physical, native postscript, coordinates corresponding to the logical point (x, y) on the graph.
Return the logical, graph, coordinates corresponding to a point on the postscript page.
Use as physical_x = $gp->ps( logical_x )
Use as physical_y = $gp->ps( logical_y )
Use as logical_x = $gp->ps( physical_x )
Use as logical_y = $gp->ps( physical_y )
The principal function requires 62 settings. To make this more manageable there are a number of functions which merely accept and store a small group of these. After these have been executed, drawgpaper is then called with no parameters.
Usage is given below with the functions indented after their parameters. Each function remove all its parameters from the stack. All functions and variables are within the gpaperdict dictionary. It is written out as it would appear within a perl 'here' document, with perl variables for each parameter. The '/' in front of font names, and '()' around text are required by postscript.
gpaperdict begin
$graph_left $graph_bottom $graph_right $graph_top graph_area
$heavy_width $heavy_color $mid_width $mid_color $light_width $light_color graph_colors
$heading_left $heading_bottom $heading_right $heading_top heading_area
/$heading_font $heading_font_size $heading_font_color ($heading_text) heading_labels
$x_axis_left $x_axis_bottom $x_axis_right $x_axis_top x_axis_area
$x_axis_mark_min $x_axis_mark_multiplier $x_axis_mark_max $x_axis_mark_gap xaxis_marks
$x_axis_factors_array_as_string $x_axis_labels_array_as_string $x_axis_label_depth $x_axis_flags /$x_axis_font $x_axis_font_size $x_axis_font_color ($x_axis_text) xaxis_labels
$y_axis_left $y_axis_bottom $y_axis_right $y_axis_top y_axis_area
$y_axis_mark_min $y_axis_mark_multiplier $y_axis_mark_max $y_axis_mark_gap yaxis_marks
$y_axis_factors_array_as_string $y_axis_labels_array_as_string $y_axis_label_depth $y_axis_flags /$y_axis_font $y_axis_font_size $y_axis_font_color ($y_axis_text) yaxis_labels
drawgpaper
end % gpaperdict
Most of these are self explanatory or relate to options documented elsewhere, but a few might need some explanation.
x_axis_flags
indicate how the labels are to be printed.
Bit Action if true 0 rotate text 1 centre text between marks
x_axis_labels_array_as_string
means a list of all the labels to be printed on the x axis, written out as
a postscript array, such as:
"[ (label1) (label2) (label3) ]" "[ 0 0.5 1 1.5 2 ]"
x_axis_factors_array_as_string
has the same format. However, the contents refer to the nesting of the axis
marks. For example, the x axis goes from 400 to 800 in units of 100. Each 100 is subdivided into
2 and then 5, so the smallest divisions are worth 10 each. Labels are placed at the 100 and 50 marks. The factor
array would be as follows.
[ 4 2 5 ]
x_axis_label_depth
would be 1 in the previous example (postscript arrays are zero based).
C<x_axis_mark_min> is the size of the smallest mark - the 10's above.
x_axis_mark_max
is the size of the largest mark - the 100's above.
x_axis_mark_multiplier
is the size added for each decreas in factor depth.
Convert a logical x value to a postscript x value. It is probably faster to use physical_point() to do any conversions and write postscript values into the postscript code. PostScript interpreters seem to use much slower processors.
Convert a logical y value to a postscript y value.
Set the drawing color. This expects a single parameter which may be an array of RGB values or a grayscale value.
0.5 gpapercolor [ 1 0.8 0 ] gpapercolor
Select a font for subsequent text. It expects three parameters - a font name, size and colour. The font name
should evaluate to a literal name as used by findfont
. The size is stored in the variable fontsize
for
reference later, and the color is just passed to gpapercolor
.
/Helvetica 12 0 gpaperfont /$fontname $fontsize [ $r $g $b ] gpaperfont
Fill and outlines a box. Use as follows. The colours are passed to gpapercolor
.
$left $bottom $right $top $fill_color $outline_color $outline_width fillbox
Draw an unfilled box. Use as follows. The colours are passed to gpapercolor
.
$left $bottom $right $top $outline_color $outline_width drawbox
Show text horizontally centred about the coordinated given. Use as:
$message $x $y centered
Show right justified text, ending at the point given. Use as:
$message $x $y rjustified
Show text rotated 90 degrees right, starting at the point given. Use as:
$message $x $y rotated
Do a deep copy of an array so that one can be changed without affecting the other. This works differently from
the others. It requires an array, and exits leaving both copies on the stack. The variable array_max
is also
set to the highest index allowed.
Here are some of the variables in the gpaperdict dictionary which might need to be accessed directly.
array_max largest index into copied array bgnd background colour for grid boxc colour of box outline boxw width of box outline fillc fill colour of box fontsize height of most recent gpaperfont gx0 graph left (same as xx0) gy0 graph bottom (same as yy0) gx1 graph right (same as xx1) gy1 graph top hcol font colour used on heading hfont font name used on heading hsize font size used on heading hx0 head left hx1 head right hy0 head bottom hy1 head top xlc constant for logical x xlm multiplier for logical x xmarkcen width for centering label ylc constant for logical y ylm multiplier for logical y ymarkcen width for centering label
draw_scales()
Commits to postscript the settings collected and calculted by new
. Under normal circumstances this should not
need to be called. It is only necessary if the layout option no_drawing
has been specified.
Very likely. This is still alpha software and has been tested in fairly limited conditions.
Chris Willmot, chris@willmot.org.uk
the PostScript::File manpage, the PostScript::Graph::Style manpage and the PostScript::Graph::Key manpage for the other modules in this suite.
the PostScript::Graph::Bar manpage, the PostScript::Graph::XY manpage and the Finance::Shares::Chart manpage for modules that use this one.
PostScript::Graph::Paper - prepare blank graph for a postscript file |