Payan Canaran > GD-Icons-0.04 > GD::Icons

Download:
GD-Icons-0.04.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.04   Source  

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 icons

There 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::list

Note: "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    arrayref

Methods:

 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.

syntax highlighting: