NAME
Image::Base::GD -- draw images with GD
SYNOPSIS
use Image::Base::GD;
my $image = Image::Base::GD->new (-width => 100,
-height => 100);
$image->rectangle (0,0, 99,99, 'white');
$image->xy (20,20, 'black');
$image->line (50,50, 70,70, '#FF00FF');
$image->line (50,50, 70,70, '#0000AAAA9999');
$image->save ('/some/filename.png');
CLASS HIERARCHY
Image::Base::GD
is a subclass of Image::Base
,
Image::Base
Image::Base::GD
DESCRIPTION
Image::Base::GD
extends Image::Base
to create or update image files in various formats using the GD
module and library (libgd version 2 or higher).
Native GD drawing has many more features but this module is an easy way to point Image::Base
style code at a GD and is a good way to get PNG and other formats out of Image::Base
code.
Colour Names
Colour names for drawing are
GD::Simple->color_names()
"#RGB" hex upper or lower case
"#RRGGBB"
"#RRRGGGBBB"
"#RRRRGGGGBBBB"
"None" transparent
See GD::Simple for its color_names()
list. Special "None" means transparent. Colours are allocated when first used. GD works in 8-bit components so 3 and 4-digit hex forms are truncated to the high 2 digits, and 1-digit hex "#123" expands to "#112233".
File Formats
GD
can read and write
png with libpng
jpeg with libjpeg
gif unless disabled in GD.pm
wbmp wireless app bitmap
gd GD's own format, raw
gd2 GD's own format, compressed
And read-only,
xpm with libXpm
xbm
PNG, JPEG and XPM are available if libgd is compiled with the respective support libraries. GIF will be unavailable if the Perl GD
interface was built with its option to disable GIF.
load()
auto-detects the file format and calls the corresponding newFromPng()
etc. "gd" file format differs between libgd 1.x and 2.x. libgd 2.x can load the 1.x format, but always writes 2.x so that's what save()
here gives. Both "gd" formats are a byte dump mainly intended for temporary files.
WBMP is a bitmap format and is treated by GD as colours black "#000000" for 0 and white "#FFFFFF" for 1. On save any non-black is treated as white 1 too, but not sure that's a documented feature.
Other GD Modules
Some other modules implement a GD-like interface with other output types or features. To the extent they're GD-compatible they should work passed in as a -gd
object here.
GD::SVG::Image
(see GD::SVG) can be saved with -file_format
set to "svg". (Or see Image::Base::SVG
to go directly to an SVG
module object if that's desired.)
Image::WMF
(see Image::WMF) can be saved by setting -file_format
to "wmf".
GD::Window
(see GD::Window) as of its version 0.02 almost works in passThrough
mode, but look for a bug fix post 0.02.
FUNCTIONS
See "FUNCTIONS" in Image::Base for the behaviour common to all Image-Base classes.
$image = Image::Base::GD->new (key=>value,...)
-
Create and return a new image object. A new image can be started with
-width
and-height
,$image = Image::Base::GD->new (-width => 200, -height => 100);
Or an existing file can be read,
$image = Image::Base::GD->new (-file => '/some/filename.png');
Or a
GD::Image
object can be given,$image = Image::Base::GD->new (-gd => $gdimageobject);
$new_image = $image->new (key=>value,...)
-
Create and return a copy of
$image
. The GD within$image
is cloned (per$gd->clone()
). The optional parameters are applied to the new image as perset()
.# copy image, new compression level my $new_image = $image->new (-zlib_compression => 9);
$colour = $image->xy ($x, $y)
$image->xy ($x, $y, $colour)
-
Get or set an individual pixel.
Currently the
$colour
return is hex "#RRGGBB", or "None" for a fully transparent pixel. Partly transparent pixels are returned as a colour. $image->rectangle ($x1,$y1, $x2,$y2, $colour, $fill)
-
Draw a rectangle with corners at
$x1
,$y1
and$x2
,$y2
. If$fill
is true then it's filled, otherwise just the outline.GD library 2.0.36 has a bug when drawing 1-pixel high
$y1 == $y2
unfilled rectangles where it adds 3-pixel high sides to the result.Image::Base::GD
has a workaround to avoid that. The intention isn't to second guess GD, but this fix is easy to apply and makes the output consistent with otherImage::Base
modules. $image->ellipse ($x1,$y1, $x2,$y2, $colour)
$image->ellipse ($x1,$y1, $x2,$y2, $colour, $fill)
-
Draw an ellipse within the rectangle with top-left corner
$x1
,$y1
and bottom-right$x2
,$y2
. Optional$fill
true means a filled ellipse.In the current implementation ellipses with odd length sides (meaning
$x2-$x1+1
and$y2-$y1+1
both odd numbers) are drawn with GD. The rest go toImage::Base
because GD circa 2.0.36 doesn't seem to draw even widths very well. This different handling for different sizes is a bit inconsistent. $image->add_colours ($name, $name, ...)
-
Add colours to the GD palette. Colour names are the same as for the drawing functions.
$image->add_colours ('red', 'green', '#FF00FF');
The drawing functions automatically add a colour if it doesn't already exist so
add_colours()
in not needed, but it can be used to initialize the palette with particular desired colours.For a truecolor GD
add_colours()
does nothing since in that case each pixel has its own RGBA rather than an index into a palette. $image->load
$image->load ($filename)
-
Read the
-file
, or set-file
to$filename
and then read. This creates and sets a new underlying-gd
because it's not possible to read into an existing GD image object, only a new one. $image->save
$image->save ($filename)
-
Save to
-file
, or with a$filename
argument set-file
then save to that. The file format written is taken from the-file_format
(see below).
ATTRIBUTES
-width
(integer, read-only)-height
(integer, read-only)-
The size of a GD image cannot be changed once created.
-ncolours
(integer, read-only)-
The number of colours allocated in the palette, or
undef
on a truecolor GD (which doesn't have a palette).This count is similar to the
-ncolours
ofImage::Xpm
. -file_format
(string)-
The file format as a string like "png" or "jpeg". See "File Formats" above for the choices.
After
load()
the-file_format
is the format read. Setting-file_format
can change the format for a subsequentsave
.The default is "png", which means a newly created image (not read from a file) is saved as PNG by default.
-quality_percent
(0 to 100 orundef
)-
The image quality when saving to JPEG format. JPEG compresses by reducing colours and resolution. 100 means full quality, no such reductions.
undef
means the libjpeg default (which is normally 75).This becomes the
$quality
parameter to$gd->jpeg()
. -zlib_compression
(integer 0-9 or -1, default -1)-
The amount of data compression to apply when saving. The value is Zlib style 0 for no compression up to 9 for maximum effort. -1 means Zlib's default level (usually 6).
This becomes the
$compression_level
parameter to$gd->png()
. -gd
-
The underlying
GD::Image
object.
BUGS
Putting colour "None" into pixels requires GD "alpha blending" turned off. Image::Base::GD
turns off blending for GD objects it creates, but currently if you pass in a -gd
then you must set the blending yourself if you're going to use None. Is that the best way? The ideal might be to save and restore blending while drawing None, but there's no apparent way to read back the blending out of a GD to later restore. Or maybe turn blending off and leave it off on first drawing any None.
SEE ALSO
Image::Base::PNGwriter, Image::Xpm
GD::SVG, GD::Window, Image::WMF
HOME PAGE
http://user42.tuxfamily.org/image-base-gd/index.html
LICENSE
Image-Base-GD is Copyright 2010, 2011, 2012, 2019 Kevin Ryde
Image-Base-GD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3, or (at your option) any later version.
Image-Base-GD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Image-Base-GD. If not, see <http://www.gnu.org/licenses/>.