NAME

GD::XYScale - Draw a 2D X-Y scale and use it.

SYNOPSIS

use GD;
use GD::XYScale;

$image = GD::Image->new($width,$height);
$white = $image->colorAllocate(255,255,255);
$black = $image->colorAllocate(0,0,0);
$blue  = $image->colorAllocate(0,0,255);
# continue using your GD image object.

$scale = GD::XYScale->new($image);

# put the origin at x=50, y=80 and zoom-out with .5
$scale->origin(50,80,.5); 
$scale->draw(1.5,$black);
$scale->name('up',
             'x scale',
             'y scale',
             $blue,
             gdSmallFont,
             'show_zoom',
             $blue);

# draw some geomethric objects, curves, 
# plot something... etc...

DESCRIPTION

This module adds a 2D scale to your GD image. It needs a GD::Image object to work.

First versions were modifying GD::Image namespace and I then realized that this is not a good thing. In this version and future versions, the module will use it's own namespace, so check your codes if you tried this module before version 1.2

METHODS

There are three main methods that you can use to control & draw the scale:

origin

Sets the origin to the point P(X,Y). And zoom in/out option of the graphic.

$scale->origin(POINT_X, POINT_Y, ZOOM);
$scale->origin(50, 218, .2);

You must set the origin coordinates before drawing the scale. Or the origin will be at point (50,50). If your graphic/plot is too big, or too small, you can pass a ZOOM parameter. All the values will be multiplied with that zoom parameter, if you pass it. For example; you can pass .2 to zoom-out and 2 to zoom-in.

Note that, any other module/code that uses this module, must use this module's origin and zoom values/calculations to get the correct result(s).

If you call this method without parameters, it returns the x and y values of the origin:

($ox,$oy) = $scale->origin;

This may be necessary. And, if you want to put something on the scale (why do you use this module, if you dont't want to?) you created, you have to fix the point to the origin with $ox,$oy values and the dimension values you get with:

($width,$height) = $image->getBounds;

The module also uses these, to correct/fix the coordinates.

However, you can use the fix() methods listed in the "fix() METHODS" part to get the correct point values.

draw

Draws the x-y scale with the scale pipes:

$scale->draw(PIPE_HEIGHT,SCALE_COLOR);

$scale->draw(1.5,$pink);

The so called pipes' mediation is 10 pixels for each (with 1:1 zoom ratio). If you don't want to see them, just set the height to zero:

$scale->draw(0,$pink);

Also, there is an extended interface. If you pass an array reference as the first parameter, you can control all the behaviour of the pipes:

$scale->draw([PIPE_LENGTH,PIPE_WIDTH,PIPE_COLOR],SCALE_COLOR);

$scale->draw([800,50,$gray],$black);

None of the parameters are mandatory. Alias is draw_xyscale.

name

Puts a name to X scale and Y scale. Also, you can select the Y-Scale name to be horizontal or vertical. If the first parameter is set to "up", it'll be vertical. Second and third are the names of the X and Y scales respectively. Fourth parameter is the color of the scale names, fifth is the font of the scale names. If you set zoom to a value other than 1 and pass a true value as the sixth parameter, you'll see the zoom ratio on the graphic's upper right corner. If you pass the last value, it'll be the color of the zoom text.

$scale->name(UPWARDS, Y_NAME, X_NAME, COLOR, FONT, SHOW_ZOOM_STRING,
             ZOOM_STRING_COLOR);

$scale->name('up', 'X-Scale', 'Y-Scale', $red, undef, 'show_zoom', undef);

None of the parameters are mandatory. Alias is name_xyscale.

fix() METHODS

The coordinate system of the scale is a little different than the GD's coordinate system. Normally, the point (0,0) is at the upper left corner of the image, while this module's scale puts the origin to the lower left. So, if you set origin' s coordinate to (0,0), the point (0,0) will be at the lower corner of the left side. To display the correct points on the x-y scale, we need to fix/correct them to the origin of the scale. You may do that manually yourself, with the help of GD's standard getBounds() method and this module's origin() method, but this module also has several methods to use on this job.

fixp2o()

Will fix the X and Y values of a point. Long alias is: fix_point_to_origin()

$scale->fixp2o(X, Y);

$scale->fixp2o(15, 56);

So, if you want to draw a line:

$image->line($scale->fixp2o(15, 56),
             $scale->fixp2o(44, 365),
             $blue);

fix_vx2o()

Will fix the X value of a point. Long alias is: fix_value_x_to_origin()

$scale->fix_vx2o(X);

fix_vy2o()

Will fix the Y value of a point. Long alias is: fix_value_y_to_origin()

$scale->fix_vy2o(Y);

So, if you want to draw a line:

$scale->line($scale->fix_vx2o(30),  $scale->fix_vy2o(30),
             $scale->fix_vx2o(100), $scale->fix_vy2o(150),
             $black);

zs()

Alias: zoom_scale()

Re-calculates the numbers to match the current zoom value. You have to fix the X and Y values seperately with this method.

$image->arc($scale->fix_vx2o(124),
            $scale->fix_vy2o(0),
            $scale->zs(78),
            $scale->zs(78),
            180,
            0,
            $black);

zoom_value()

Returns the current zoom value. Does not accept any arguments and you can not set zoom value with this method.

EXAMPLES

See the tests in ./t directory in the distribution. Download the distribution from CPAN, if you don't have the files on your computer.

BUGS

Contact the author, if you find any. If you have suggestions for this module, you can also send them to the author.

SEE ALSO

GD.

AUTHOR

Burak Gürsoy, <burak@cpan.org>

COPYRIGHT

Copyright 2003 Burak Gürsoy. All rights reserved.

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm GD::XYScale

perl -MCPAN -e shell
install GD::XYScale