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:
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:
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:
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:
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.; 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).; 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:
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()`