NAME

GD::Dashboard - Perl module to create JPEG graphics of meters and dials

SYNOPSIS

   my $dash = new GD::Dashboard();

   my $g1 = new GD::Dashboard::Gauge(
                      MIN=>0,
                      MAX=>$empcnt,
                      VAL=>$nopwp_cnt,
                      NA1=>3.14/2+0.85,
                      NA2=>3.14/2-0.85,
                      NX=>51,NY=>77,NLEN=>50                      
            );

   $dash->add_meter('RPM', $g1);
   $dash->write_jpeg('dash.jpg');

The Dashboard module aims at providing users with a quick and easy way to create dashboard or cockpit like JPGs to display key information.

Dashboard supports the following instruments:

  * Gauges with needles
  * Bar type gauges
  * Warning Lights

Dashboard is built on top of GD.pm, Licoln Stein's interface to the GD library.

Classes

The dashboard module contains several classes. These classes typically represent either a dashboard or an instrument on the dashboard. The Dashboard object serves as a collection for the instruments.

Dashboard

The Dashboard object serves as the collection object that contains the various instruments in the display. You can add instruments to the dashboard, access instruments through it, or tell it to draw itself.

   my $dash = new Dashboard();
   $dash->add_meter('RPM', $g1);
   $dash->add_meter('Speedo', $g2);
   $dash->write_jpeg('dash.jpg');

• FNAME

  This is the name of a JPG file to use for the background. This graphic will typically have one or more gauges on it, upon which this module will draw needles or other indicators.

• QUALITY

  The quality of the output JPEG, from 1 (low) to 100 (high). Defaults to 100. This value is passed directly to GD.

add_meter(name, meter)

Adds a meter to the dash. Create the meter using one of the new() constructors first. You can add Gauges, HorizontalBars, and WarningLights. The name is used by the get_meter() function if you need to access the meter later.

get_meter()

Gets a meter by name. When adding a meter, you must give it a name. You can then use get_meter to get the meter object. This is useful when you want to change a setting later, such as the meter's value.

jpeg()

Returns a JPG as a scalar value.

write_jpeg(fname)

Draws the dashboard to a jpg file given by fname.

png()

Returns a PNG as a scalar value.

write_png(fname)

Draws the dashboard to a PNG file given by fname.

Dashboard::Gauge

This class describes a typical dashboard gauge; that is, an instrument that has a needle that rotates. The needle may rotate clockwise or counterclockwise. This gauge is similar to a car speedometer or and airspeed indicator.

new()

Most gauge configuration is done in the constructor. Here is a sample for the gauge included with this package (m1.jpg):

   my $g1 = new GD::Dashboard::Gauge(FNAME=>base_path().'\icons\m1.jpg',
                      MIN=>0,
                      MAX=>$empcnt,
                      VAL=>$nopwp_cnt,
                      NA1=>3.14/2+0.85,
                      NA2=>3.14/2-0.85,
                      NX=>51,NY=>77,NLEN=>50                      
            );

• VAL

  This indicates where the needle is pointing. Generally it should be somewhere between MIN and MAX.

• MIN

  This is the minimum VAL is ever expected to reach. It corresponds to a needle position of NA1. Lower values are not truncated; however, they will generate warnings.

• MAX

  This is the maximum VAL is ever expected to reach. It corresponds to a needle position of NA2. Higher values are not truncated; however, they will generate warnings.

• NX

  This is the X coordinate of the base of the needle.

• NY

  This is the Y coordinate of the base of the needle.

• NLEN

  This is the length of the needle to draw.

• NWIDTH

  This is the width of the needle.

• NA1

  NA1 and NA2 are potentially the most confusing parameters. They represent the angle of the needle at its MIN and MAX points. NA1 is the angle that corresponds to VAL=MIN, while NA2 is VAL=MAX. The angle is expressed in radians, the same way you would express an angle to one of perl's trigonometric functions.

• NA2

  See NA1.

• NCOLOR

  This is the color of the needle. This value should be passed as a reference to an array of RGB values.

• COUNTERCLOCKWISE

  Set to 1 if needle moves from MIN to MAX in a counterclockwise direction. Otherwise you can ignore it.

Dashboard::HorizontalBar

This class describes an LED bargraph display of the type often found in a graphical equalizer or, on some cars, the oil condition indicator. It may be all one color, or it may use different colors in different ranges.

The graph goes from left to right and consists of a number of bars, meant to represent LEDs. Bars can be identical or you can configure different bars, for example to have the last couple of bars be red instead of green.

   my $m1 = new GD::Dashboard::HorizontalBar(
                  NX => 235,
                  NY => 348,
                  SPACING => 1
                  );
   $m1->add_bars(20,base_path().'\icons\barlight_on.jpg','\icons\barlight_off.jpg');
   $dash->add_meter('m1',$m1);

new()

• MIN = N The value representing zero bars illuminated. Defaults to 0.

• MAX = N The value representing all bars illuminated. Defaults to 100.

• VAL = N The value to display. Number of bars illuminated will be val / (max-min) percent of total.

• TRANSPARENT = [ r,g,b ]

  This is currently not implemented correctly. If you pass any array reference to this parameter, WHITE will be transparent. This allows you to have non-rectangular bars. Email me if the white bit is a problem.

• SPACING = N

  If you would like bars to be separated by a number of pixles, specify the number in this parameter.

add_bars(count, fname, fnameoff)

Call this for each different group of bars you would like to add. Count is the number of bars. Fname is the path to a JPG that represents the bars in their ON state. Fnameoff is an optional filename to a JPG that represents the bar in the off state (these are often just built into the dashboard background, however).

set_reading(val)

Sets the number of bars that are illuminated. So if you have 20 bars defined, 'val' should be between 0 and 20 inclusive.

Dashboard::WarningLight

This behaves like a warning light on a car dashboard. It can be turned on or off. When VAL is 0, this gauge has basically no effect. When VAL is 1, it draws another graphic on the dashboard (this would typically be the warning light on graphic). Consequently, the dashboard graphic should contain the warning light in its "off" state.

new()

Most configuration of the warning light is done via the constructor.

• FNAME

  This is a JPG file that will be drawn at NX,NY when the warning light is turned on.

• VAL

  This can be 0 or 1. A value of 1 turns the warning light on, i.e., it causes the graphic FNAME to be drawn at NX,NY.

• NX

  X position of lower right of graphic FNAME.

• NY

  Y position of lower right of graphic FNAME.

• TRANSPARENT

  Currently, set this to 1 to make WHITE transparent. I probably should make this take an RGB array ref. Email me if you want it.

set_reading(val)

Sets the VAL parameter. This can be 0 (warning light off) or 1 (warning light on).

NOTES

This is the first release. There are a few things on my mind for 0.02. First, PNG support would be easy to add in. I don't use it so I haven't added it (yet). Email if you want it. Second, all of the meters are probably going to derive from a base class. Haven't had time to change it yet.

Eventually I should pay more attention to the needle drawing in the Gauge class. If your art is really good, the needles bring it down :(

I'm sure the docs could be better.

AUTHOR

David Ferrance (dave@ferrance.com)

LICENSE

Dashboard: A module for creating dashboard graphics.

Copyright (C) 2002 David Ferrance (dave@ferrance.com). All Rights Reserved.

This module is free software. It may be used, redistributed and/or modified under the same terms as perl itself.

Sample graphics provided by rabia@rabia.com. This module isn't worth much without a good graphics person to provide you with sweet dashboard layouts.

cpanm GD::Dashboard

perl -MCPAN -e shell
install GD::Dashboard