NAME
GD::Icons - Utility for generating series of icons of varying color and shapes
SYNOPSIS
my $icon;
$icon = GD::Icons->new(
shape_keys => ['accident', 'flooding', 'construction'],
icon_dir => '.',
icon_prefix => 'test-set-A',
);
$icon->generate_icons;
print $icon->icon('accident', ':default', ':default');DESCRIPTION
GD::Icons generates an arbitrary number of icons that vary by shape, color and color intensity. This is intended to be used in cases for which a series of related icons are needed. For example, if you want to generate icons to represent traffic congestion on a geographical map, you can generate icons having shape of the icon represent the cause of congestion (accident, flooding and construction) and the color of the icon to represent the severity of the congestion (e.g. red for severe and blue for not severe congestion). In addition to these two dimensions of coding (shape and color) you can use a third dimension, intensity of color.
USAGE
To generate a series of icons, you first create a GD::Icons object and then call the "generate_icons" method on the object. This creates the images. Then you can call the "icon" method on the object to retrieve the file names of the icon generated for a given set of parameters.
When creating a GD::Icons object, the following needs to be provided:
- the information on which the icons will be coded on
- where to place the generated icons
- a name prefix to use when generating iconsThere are 3 dimensions that can be coded into the icons generated.
- shape (represented by "shape_keys" & "shape_values")
- color (represented by "color_keys" & "color_values")
- color intensity (represented by "sval_keys" & "sval_values")Let's use the traffic congestion example described earlier to experiment with different options provided by the module. We would like to represent 3 types of traffic congestion on a geographical map and generate 3 different icons to be used to represent each.
Example 1 - Basic data with keys coded by icon shape
Let's begin with the following code. As described earlier, we create a GD::Icon object and call its "generate_icons" method.
my $icon = GD::Icons->new(
shape_keys => ['accident', 'flooding', 'construction'],
icon_dir => '.',
icon_prefix => 'test-set-A',
);
$icon->generate_icons;shape_keys
In the example above, 3 keys that are to be coded by the shape of the icon are specified. No "shape_values" is specified so these are retrieved from the default configuration (configuration and default values are later described in more detail).
icon_dir
This param specifies the directory in which the icons will be generated in. In this example, they are generated in the current directory ".".
icon_prefix (and file names)
The file name of each icon is prefixed with "icon_prefix" and the rest of the file name contains the index of each of the dimensions it is coded on.
For example, an icon generated based on the 0th (this is the array index) shape index, 2nd color index and 0st sval (color intensity index) index, would have a file name "<icon_prefix>-0-2-0.png".
In this example, 3 icons will be generated:
- ./test-set-A-0-0-0.png (representing "accident")
- ./test-set-A-1-0-0.png (representing "flooding")
- ./test-set-A-2-0-0.png (representing "construction")Please note that, in this example we have not specified any color or sval dimensions. These default to the special ':default' key.
Also, we have not specified any actual shape, color or sval values that correspond to our dimension keys. In this case, GD::Icons assigns values itself.
Example 2 - Adding explicit shape values
Let's extend the previous example and specify the shapes explicitly.
my $icon = GD::Icons->new(
shape_keys => ['accident', 'flooding', 'construction'],
shape_values => ['square', 'triangle', 'diamond'],
icon_dir => '.',
icon_prefix => 'test-set-B',
);
$icon->generate_icons;shape_values
We add "shape_values" parameter to explicitly specify shapes that we would like to use. The shape values must be available shape names (configuration and default values are later described in more detail). In this particular example, we specify 3 shape values, "square", "triangle" and "diamond", one for each shape key.
Example 3 - Additional keys coded on color
Let's now add a second dimension, the color of the icon to code for the severity of the congestion.
my $icon = GD::Icons->new(
shape_keys => ['accident', 'flooding', 'construction'],
shape_values => ['square', 'triangle', 'diamond'],
color_keys => ['not-severe', 'severe'],
color_values => ['Blue', 'Orange'],
icon_dir => '.',
icon_prefix => 'test-set-D',
);
$icon->generate_icons;color_keys & color_values
Similar to "shape_keys" and "shape_values" parameters, with "color_keys" and "color_values" parameters, we specify that the color of the icon will represent one of "not-severe" and "severe".
This example generates the following files
- test-set-D-0-0-0.png (accident - square & not-severe - Blue )
- test-set-D-0-1-0.png (accident - square & severe - Orange)
- test-set-D-1-0-0.png (flooding - triangle & not-severe - Blue )
- test-set-D-1-1-0.png (flooding - triangle & severe - Orange)
- test-set-D-2-0-0.png (construction - diamond & not-severe - Blue )
- test-set-D-2-1-0.png (construction - diamond & severe - Orange)Example 4 - Incorporating sval (color intensity) values
In this example, we are going to demonstrate incorporation of sval (color intensity).
Let's say that you would like to code the severity of the congestion by the color intensity of the icon. For example, a square icon to describe an accident with a light orange color to indicate a "not-severe", medium orange color to indicate "medium-severe" and orange color to indicate "severe" congestions.
my $icon = GD::Icons->new(
shape_keys => ['accident', 'flooding', 'construction'],
shape_values => ['square', 'triangle', 'diamond'],
color_keys => ['severity'],
color_values => ['Orange'],
sval_keys => ['not-severe', 'medium', 'severe'],
sval_values => [20, 50, 100],
icon_dir => '.',
icon_prefix => 'test-set-F',
);
$icon->generate_icons;In this example, we reduce the number of color_keys to one. Please note that there may be cases that call for a complete 3-dimensional matrix (shape x color x sval). However, in this example, 2 dimensions would be sufficient.
sval_keys & sval_values
In this example, we provide 3 "sval_keys" values for each congestion level and corresponding 3 "sval_values" values.
"sval_values" values are integers between 0-100. When a sval variation of a color is to be generated (in this case the color "Orange"), the color is converted into HSV and the "sval_values" value is applied as the S value in HSV triplet.
An implication of this is that, in cases that two colors are specified as "color_keys" and these two color differ only by their V value, their sval-transformed forms will not be distinguishable. This is unlikely to happen intentionally as it wouldn't be applicable to specify for example a light and a darker shade of the same color and try to apply a color gradient on each of them. However, this should be taken into consideration when specifying multiple "color_values" values.
Similar to "shape_values" and "color_values", if "sval_values" is not specified in the constructor, it is automatically calculated based on the number of available "sval_keys" values.
With this example, the following files are generated:
- test-set-F-0-0-0.png (accident - square & not-severe - light Orange (20/100) )
- test-set-F-0-0-1.png (accident - square & not-severe - light Orange (20/100) )
- test-set-F-0-0-2.png (accident - square & not-severe - light Orange (20/100) )
- test-set-F-1-0-0.png (flooding - square & medium - med. Orange (50/100) )
- test-set-F-1-0-1.png (flooding - square & medium - med. Orange (50/100) )
- test-set-F-1-0-2.png (flooding - square & medium - med. Orange (50/100) )
- test-set-F-2-0-0.png (construction - square & severe - dark Orange (100/100))
- test-set-F-2-0-1.png (construction - square & severe - dark Orange (100/100))
- test-set-F-2-0-2.png (construction - square & severe - dark Orange (100/100))Retrieving file names for icons
Running the "generate_icons" method on th GD::Icons object, creates the icons in the specified directory.
You can run the "icon" method on the object to retrieve file names. This is particularly useful if you are creating transient icon images interactively. You can then create the icons, use them in your application and then remove/override them as needed.
For example:
my $file_name = $icon->icon('accident', 'severe', ':default');will get back the file name of the icon coded for shape on 'accident' and color on 'severe'. The third parameter stands for the default for sval coding.
By adding a 4th parameter. you can use icon method as a set method. This is mainly used internally.
CONFIGURATION AND DEFAULT VALUES
The icon generation requires a set of shapes and a set of colors.
The shapes are provided as a set of instructions, separated by spaces, to create an image.
For example, the instructions for creating a triangle are as follows:
sl[11] lt[1] lc[_Black] py[0,0 10,0 10,10 0,10 0,0] fl[5,5]
sl[11] instructs to create the image as a 11x11 square.
"sl" stands for "side length".
lt[1] indicates that the thickness of the line used for drawing
the icon will be 1 pixel.
"lt" stands for "line thickness".
lc[_Black] indicates that the color of the line used for drawing the
icon is the color labeled as "_Black".
"lc" stands for "line color".
py[0,0 10,0 10,10 0,10 0,0] draws a polygon with the points listed
in brackets. Points are in the format (x,y),
upper-left corner being (0,0), increasing
to the right in X axis and to the bottom in
Y axis.
"py" stands for "polygon".
fl[5,5] instructs the image to be filled by the color
(from "color_values") at point (5,5).
"fl" stands for "fill".The colors are provided by their RGB values as a string of hexadecimals.
A few examles are provided below:
Blue => '#0000FF'
BlueViolet => '#8A2BE2'
Brown => '#A52A2A'By default, GD::Icons retrieves colors and shapes from GD::Icons::Config. All colors and shapes are provided as an array. If the number of keys is are more than the number of shapes/colors, shapes/colors are rotated and used in the same order until all keys are assigned.
The default values can be obtained by:
perl -MGD::Icons::Config -e GD::Icons::Config::listNote: "sval_values" values, if not provided to the constructor, are calculated automatically based on number of keys.
When values for shape, color or sval are provided to the constructor, the same rotation rule applies as it applies to default values for shapes and keys.
You can also pass a custom config file to the constructor and override default configuration. A sample config file is shown below:
<shape>
square sl[11] lt[1] lc[_Black] py[0,0 10,0 10,10 0,10 0,0] fl[5,5]
triangle sl[11] lt[1] lc[_Black] py[5,0 10,10 0,10 5,0] fl[5,5]
diamond sl[11] lt[1] lc[_Black] py[5,0 0,5 5,10 10,5 5,0] fl[5,5]
sand-clock sl[11] lt[1] lc[_Black] py[0,0 10,0 5,5 10,10 0,10 5,5 0,0] fl[5,2] fl[5,8]
_padded-square sl[11] lt[1] lc[:fill] py[0,0 0,9 9,9 0,9 0,0] fl[5,5]
_letter-m sl[11] lt[1] lc[_Black] py[0,1 3,1 5,3 7,1 10,1 10,9 7,9 7,4 5,6 3,4 3,9 0,9 0,1] fl[2,2]
</shape>
<color>
Blue \#0000FF
BlueViolet \#8A2BE2
Brown \#A52A2A
BurlyWood \#DEB887
CadetBlue \#5F9EA0
Chartreuse \#7FFF00
_Black \#000000
</color> Color and shape names that start with an underscore (_) are special names. These can be used in drawing shapes as any other one. However, they are not considered for icon generation by default.
The special color name ":fill" means the same color as the icon.
QUICK REFERENCE
The constructor parameters and their descriptions follow:
Parameter Description Format
--------- ----------- ------
alpha Alpha level of icon (0-127) scalar
color_keys Keys to code by color arrayref
color_values Values for color coding arrayref
config External configuration file scalar
icon_dir Directory to create icons scalar
icon_prefix Prefix to name icon files scalar
shape_keys Keys to code by shape arrayref
shape_values Values for shape coding arrayref
sval_keys Keys to code by color intensity arrayref
sval_values Values for color intensity coding arrayrefMethods:
Parameter Description Parameters Returns
--------- ----------- ---------- -------
all_colors Get all colors excl. None hashref
private ones
all_shapes Get all shapes excl. None hashref
private ones
generate_icons Generate icons None 1
icon Get/set file name for ($shape_key, $color_key, scalar
an icon $sval_key, $value)
* $value for set only AUTHOR
Payan Canaran <pcanaran@cpan.org>
BUGS
VERSION
Version 0.04
ACKNOWLEDGEMENTS
This module incorporates two subroutines from GD::Simple (written by Lincoln Stein) for RGB to HSV conversion and vice versa.
Thanks to Sheldon McKay for recommending to use HSV color space instead of RGB color space for color transitions.
COPYRIGHT & LICENSE
Copyright (c) 2006-2007 Cold Spring Harbor Laboratory
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See DISCLAIMER.txt for disclaimers of warranty.