NAME

Image::Magick::Chart - Use Image::Magick to create charts.

Synopsis

        #!/usr/bin/perl

        use Image::Magick::Chart::HorizontalBars;

        Image::Magick::Chart::HorizontalBars -> new
        (
                antialias            => 0, # 0 => No antialias; 1 => Antialias.
                bar_width            => 8, # Pixels.
                bg_color             => 'white',
                colorspace           => 'RGB',
                depth                => 8, # Bits per channel.
                fg_color             => 'blue',
                font                 => 'Courier',
                frame_color          => 'black',
                frame_option         => 1, # 0 => None; 1 => Draw it.
                height               => 0,
                image                => '',
                output_file_name     => 'image-1.png',
                padding              => [30, 30, 30, 30], # [12 noon, 3, 6, 9].
                pointsize            => 14, # Points.
                tick_length          => 4,  # Pixels.
                title                => 'Percent (%)',
                width                => 0,
                x_axis_data          => [0, 20, 40, 60, 80, 100],
                x_axis_labels        => [0, 20, 40, 60, 80, 100],
                x_axis_labels_option => 1, # 0 => None; 1 => Draw them.
                x_axis_ticks_option  => 2, # 0 => None; 1 => Below x-axis; 2 => Across frame.
                x_data               => [15, 5, 70, 25, 45, 20, 65],
                x_data_option        => 1,
                x_pixels_per_unit    => 3, # Horizontal width of each data unit.
                y_axis_data          => [1 .. 7, 8], # 7 data points, plus 1 to make image pretty.
                y_axis_labels        => [(map{"($_)"} reverse (1 .. 7) ), ''],
                y_axis_labels_option => 1, # 0 => None; 1 => Draw them.
                y_axis_ticks_option  => 1, # 0 => None; 1 => Left of y-axis; 2 => Across frame.
                y_pixels_per_unit    => 20,
        ) -> draw();

This code is part of examples/test-chart.pl.

Note: You do not need to specify all the options above, of course, but only those you wish to differ from the defaults. I've included all options in examples/test-chart.pl just to save you the effort of having to type them in.

See Image::Magick's documentation page www/perl.html for the list of values supported by each Image::Magick option.

Description

Image::Magick::Chart is a pure Perl module.

This module uses Image::Magick as the base of a set of modules which create simple images of various types. Only Image::Magick::Chart::HorizontalBars is available at this time.

See examples/image-*.png for sample output, and examples/test-chart.pl for the program which created those samples.

You control the size of the image by specifying the data values for X and Y, and also by specifying the scaling factors in the X and Y directions in terms of pixels per unit of data.

Eg: In the above code, the x-axis data ranges up to 100 (sic), and the x-axis scaling factor is 3 pixels/unit, so the part of the image occupied by the data will be 3 * 100 + 1 pixels wide. The 1 is for the y-axis.

The 100 comes from max(last value in @$x_axis_data, last value in @$x_data).

Distributions

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

Constructor and initialization

new(...) returns an Image::Magick::Chart object.

This is the class's contructor.

Usage: Image::Magick::Chart -> new().

Note: Actually, you don't normally do this.

Instead, you call: Image::Magick::Chart::HorizontalBars -> new(...) -> draw().

This method takes a set of parameters. Only the output_file_name parameter is mandatory.

For each parameter you wish to use, call new as new(param_1 => value_1, ...).

Parameters:

antialias

The value, 0 or 1, is passed to Image::Magick, if this module creates the image.

See the 'image' option if you wish to use a pre-existing object of type Image::Magick.

Using a value of 1 will make your output file slightly larger.

The default value is 0.

This parameter is optional.

bar_width

This is the thickness of the bars, in pixels.

The default value is 8 pixels.

This parameter is optional.

bg_color

This is the background color of the image, if this module creates the image.

See the 'image' option if you wish to use a pre-existing object of type Image::Magick.

The default value is 'white'.

This parameter is optional.

colorspace

The value, 'RGB' etc, is passed to Image::Magick, if this module creates the image.

See the 'image' option if you wish to use a pre-existing object of type Image::Magick.

This parameter is optional.

depth

This is the number of bits per color channel.

The default value is 8.

This parameter is optional.

fg_color

This is the color of the horizontal bars, when using Image::Magick::Chart::HorizontalBars.

The default value is 'black'.

This parameter is optional.

font

This is the font used for:

The x-axis labels
The y-axis labels
The title on top of the image
The labels (values) on top of (to the right of) the horizontal bars

The default value is 'Courier'.

This parameter is optional.

frame_color

This is the color used to draw a frame around the area of the image which is actually occupied by the data.

The default color is 'black'.

This parameter is optional.

frame_option

The value, 0 or 1, determines whether (1) or not (0) the frame will be drawn.

The default value is 1.

This parameter is optional.

height

This is the calculated height of the image, taking into account the area occupied by the data (the framed area), and the padding on the 4 sides of the frame.

If you use a pre-existing object of type Image::Magick, this module will get the values for width and height from that image.

This parameter is optional.

image

This is the object of type Image::Magick used to manage the image.

This module creates this object by default, but you can pass in to the constructor a pre-existing object of type Image::Magick, and this module will use your object.

If you use you own object, I assume you have set these parameters for your image:

antialias
bg_color
colorspace
depth

By which I mean this module will not attempt to set those 4 options when you pass in a pre-existing object.

This parameter is optional.

output_file_name

This is the path, filename and extension to the file where the image will be written.

There is no default.

This parameter is mandatory.

padding

This is a array ref of values, in pixels, to leave on all 4 sides of the image, between the edge of the image and the part occupied by data (the framed part).

You must provide an array ref of 4 values for this parameter.

A clockface is used to define the meanings of the 4 values, thus:

$$padding[0], the first value, is at the top of the frame

Top corresponds to 12 noon.

$$padding[1], the second value, is at the right of the frame

Right corresponds to 3 pm.

Or, if you prefer 3 am, and you think in Spanish, then it's the hour beloved by facists and other psychopaths: 'de la madrugada'.

$$padding[2], the third value, is at the bottom of the frame

Bottom corresponds to 6 pm.

$$padding[3], the fourth value, is at the left of the frame

Left corresponds to 9 pm.

The default value is [30, 30, 30, 30].

This parameter is optional.

pointsize

This is the size of the text used wherever the 'font' option is used.

The default value is 14.

This parameter is optional.

tick_length

This is the length, in pixels, of the tick marks on the x and y axes.

The default value is 4 pixels.

This parameter is optional.

title

This is the text written at the top centre of the image.

The default value is '' (the empty string).

This parameter is optional.

width

This is the calculated width of the image, taking into account the area occupied by the data (the framed area), and the padding on the 4 sides of the frame.

If you use a pre-existing object of type Image::Magick, this module will get the values for width and height from that image.

This parameter is optional.

x_axis_data

This is an array ref of X values (abscissas) where you want the x-axis labels and x-axis tick marks to be drawn.

The values in this array ref are multiplied by the value of the x_pixels_per_unit parameter, to determine where the x-axis labels and x-axis tick marks are drawn.

The default value is [], meaning neither labels nor tick marks will be drawn along the x-axis.

This parameter is optional.

Warning: Do not confuse this parameter with the x_data parameter.

x_axis_labels

This is an array ref of labels to draw below the x-axis. The X values - around which these labels are centered - are supplied by the value of the x_axis_data option.

In order to draw the x_axis_data values (abscissas) themselves as x-axis labels, just pass in the same array ref for both the x_axis_data parameter and the x_axis_labels parameter.

The default value is [], meaning no labels are drawn below the x-axis.

This parameter is optional.

x_axis_labels_option

The value, 0 or 1, determines whether (1) or not (0) the x-axis labels will be drawn.

The default value is 1.

This parameter is optional.

x_axis_ticks_option

Values:

'0'

Do not draw x-axis tick marks.

The quotes are just to stop the zero disappearing when POD is converted to HTML.

1

Draw x-axis tick marks below the x-axis.

2

Draw x-axis tick marks across the frame and below the x-axis.

The lengths of the tick marks below the x-axis is given by the value of the tick_length parameter.

The default value is 1.

This parameter is optional.

x_data

This is the array ref of data to use to draw the horizontal bars.

Also, these values are drawn on top of (to the right of) the bars. This can be turned off with the x_data_option parameter.

This parameter is optional.

x_data_option

The value, 0 or 1, determines whether (1) or not (0) the X values given by the x_data parameter will be drawn on top of (to the right of) the bars.

The default value is 1.

This parameter is optional.

x_pixels_per_unit

This is the scaling factor in the x-axis direction.

The default value is 3, meaning each unit of data in the x-axis direction will occupy 3 pixels horizontally.

This value is used in conjunction with the x_axis_data and x_data parameters.

The 100 comes from max(last value in @$x_axis_data, last value in @$x_data).

This parameter is optional.

y_axis_data

This is an array ref of Y values (ordinates) where you want the y-axis labels and y-axis tick marks to be drawn.

The values in this array ref are multiplied by the value of the y_pixels_per_unit parameter, to determine where the y-axis labels and y-axis tick marks are drawn.

The number of elements in this array ref should be the same as the number of elements in the array ref given by the x_data parameter.

Or, if you want the image to look pretty, put one more value into the y_axis_data array ref, as seen in the code above. Do the same with the y_axis_labels parameter - just make the final value in @$y_axis_labels a '' (the empty string).

The default value is [], meaning neither labels nor tick marks will be drawn along the y-axis.

This parameter is optional.

y_axis_labels

This is an array ref of labels to draw left of the y-axis. The Y values where these labels are drawn is supplied by the value of the y_axis_data option.

The default value is [], meaning no labels are drawn left of the y-axis.

This parameter is optional.

y_axis_labels_option

The value, 0 or 1, determines whether (1) or not (0) the y-axis labels will be drawn.

The default value is 1.

This parameter is optional.

y_axis_labels_x

The value, if not undef, determines the x-axis value (abscissa) at which y-axis labels are written.

The special value undef means this module calculates an abscissa at which to start writing y-axis labels.

This calculation will only produce a pretty-looking column of y-axis labels when all labels are the same width in pixels. See sub draw_y_axis_labels() for the calculation.

The default value is undef.

This parameter is optional.

y_axis_ticks_option

Values:

'0'

Do not draw y-axis tick marks.

The quotes are just to stop the zero disappearing when POD is converted to HTML.

1

Draw y-axis tick marks left the y-axis.

2

Draw y-axis tick marks across the frame and left of the y-axis.

The lengths of the tick marks left of the y-axis is given by the value of the tick_length parameter.

The default value is 1.

This parameter is optional.

y_pixels_per_unit

This is the scaling factor in the y-axis direction.

The default value is 20, meaning each unit of data in the y-axis direction will occupy 20 pixels vertically.

This value is used in conjunction with the y_axis_data parameter.

Eg: In the above code, the y-axis data ranges up to 8, and the y-axis scaling factor is 20 pixels/unit, so the part of the image occupied by the data will be 20 * 8 + 1 pixels high. The 1 is for the x-axis.

The 8 comes from the last value in @$y_axis_data.

Notice how the label corresponding this value of 8 is '', just to make the image pretty by making the area occupied by the data (the framed area) a bit higher.

This parameter is optional.

Method: draw_frame()

Called by method draw() in Image::Magick::Chart::HorizontalBars.