OVERVIEW

The GD graphics drawing library is a software library that programmers use to draw, paint, create graphs and tables, resize images, draw text and add watermarks, and so forth.

tcl.gd aka tclgd is a Tcl C extension that brings nearly 100% of GD's capabilities to Tcl programmers. Although there are a couple of other Tcl interfaces to GD around, they haven't been updated in recent years and are missing many of GD's more recent abilities such as True Type font rendering and alpha channel support, among others.

Tcl coders can use GD to read and write GIFs, JPEGs, PNGs, and native GD images. From Tcl you can draw pixels, lines, polygons, rectangles, arcs, and ellipses. You can do fills, create text, resize, resample, rotate, sharpen, compare and merge images, and create animated GIFs, all following a familiar Tk-style object model.

OBTAINING TCLGD

Obtain tcl.gd as a gzipped tar source code archive at http://code.google.com/p/flightaware-tcltools/downloads/list or checkout the subversion source tree at http://code.google.com/p/flightaware-tcltools/source/checkout

PROVENANCE

GD was developed by Thomas Boutelle and has been kind of handed over to the community at http://www.libgd.org/. tcl.gd was developed by Karl Lehenbauer of FlightAware for internal company use and released to the public under the BSD open source license in January of 2009.

SYNOPSIS

package require gdtcl

GD create objName width height

GD create_truecolor objName width height

GD create_from_jpeg objName channel

GD create_from_jpeg_data objName data

GD create_from_png objName channel

GD create_from_png_data objName data

GD create_from_gif objName channel

GD create_from_gif_data objName data

GD create_from_gd objName channel

GD create_from_gd_data objName data

GD create_from_gd2 objName channel

GD create_from_gd2_data objName data

GD create_from_gd2_part objName channel x y width height

GD create_from_gd2_part_data objName data x y width height

GD create_from_wbmp objName channel

GD create_from_wbmp_data objName data

GD create_from_xbm objName fileHandle

GD create_from_xpm objName fileHandle

objName pixel x y ?color?

objName line x1 y1 x2 y2 color

objName polygon ?filled|open? pointList color

objName rectangle x1 y1 x2 y2 color

objName filled_rectangle x1 y1 x2 y2 color

objName arc cx cy width height startDegrees endDegrees color

objName filled_arc cx cy width height startDegrees endDegrees color ?arc? ?chord? ?pie? ?nofill? ?edged?

objName filled_ellipse cx cy width height color

objName fill_to_border x y borderColor color

objName fill x y color

objName fill x y color

objName text color font pointSize angle x y text

objName text_bounds color font pointSize angle x y text

objName allocate_color r g b ?alpha?

objName closest_color r g b ?alpha?

objName closest_color_hwb r g b

objName exact_color r g b ?alpha?

objName resolve_color r g b ?alpha?

objName total_colors

objName deallocate_color color

objName true_color r g b ?alpha?

objName interlace ?boolean?

objName transparent ?color?

objName set_anti_aliased color

objName set_anti_aliased_dont_blend color

objName set_brush BROKE

objName set_tile BROKE

objName set_style BROKE

objName set_thickness thickness

objName alpha_blending blending

objName save_alpha boolean

objName get_alpha

objName bounds_safe x y

objName green_component color

objName red_component color

objName blue_component color

objName width

objName height

objName copy srcImageCommand destX destY srcX srcY width height

objName copy_resized srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight

objName copy_resampled srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight

objName copy_rotated srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight angle

objName copy_merge srcImageCommand destX destY srcX srcY width height percent

objName copy_merge_grey srcImageCommand destX destY srcX srcY width height percent

objName copy_palette srcImageCommand

objName sharpen percent

objName compare something

objName square_to_circle name radius

objName write_jpeg channel quality

objName jpeg_data quality

objName write_gif channel

objName gif_data

objName gif_anim_begin channel global_color_map loops

objName gif_anim_add channel local_color_map left_offset top_offset delay disposal ?previous_image?

objName gif_anim_end channel

objName write_png channel compressionLevel

objName png_data compressionLevel

objName write_wbmp channel fgcolor

objName wbmp_data fgcolor

objName write_gd fileHandle

objName gd_data

objName write_gd2 channel chunkSize format

objName gd2_data chunkSize format

DESCRIPTION

tclgd gives Tcl programs the ability to read, manipulate, and generate graphic images in a number of popular formats.

The GD command creates a new Tcl command, either prepping it with an empty graphic for the case of create and create_truecolor, or by reading file data either from a Tcl channel, from in-memory data, or from a Tcl file handle (in a couple of cases where a channel interface can't be provided due to limitations of the underlying gd library routines).

IMPORTANT: The channel being read should be configured for binary translation using something like

    set fp [open parrots.png]
    fconfigure $fp -translation binary
    GD create_from_png parrots $fp

If you get corrupt image errors on images that you feel pretty sure are OK, like you can load them into Photoshop, you probably are not setting translation to binary.

For formats where channels are support (the majority), any type of channel can be used, including files, sockets, and, if so equipped, alternate channel interfaces such as reading the data directly from zip files.

Tweezer gives Tcl programs the ability to examine and manipulate the state of Tcl objects, the core building blocks of Tcl in versions 8 and above.

Once an image has been created or loaded, it can be manipulated via the named object, or if the object name is #auto, a unique command name is returned and should be grabbed into a variable and executed using a reference to that variable, in the same manner as Incr Tcl.

    GD create img 100 100
    img pixel 5 5

DRAWING FUNCTIONS

objName pixel x y returns the color index of the pixel located at coordinates x and y, while objName pixel x y color sets that pixel location to the specified color index.

objName line x1 y1 x2 y2 color draws a line from the coordinates x1, y1 to x2, y2 using color color. If thickness is set to 1 and antialiasing is enabled, the line will be drawn antialiased.

objName polygon ?filled|open? pointList color draws a polygon of color color using points from the point list pointList which must contain an even number of xy pairs.

objName rectangle x1 y1 x2 y2 color draws a rectangle of the given color from the corner at x1, y2 to the corner at x2, y2.

objName filled_rectangle x1 y1 x2 y2 color same as rectangle except the rectangle is filled.

objName arc cx cy width height startDegrees endDegrees color draws an arc centered on cx, cy, of the specified width and heigtht, starting and ending at the specified degrees, and using the specified color.

objName filled_arc cx cy width height startDegrees endDegrees color ?arc? ?chord? ?pie? ?nofill? ?edged? draws an arc centered on cx, cy, of the specified width and heigtht, starting and ending at the specified degrees, and using the specified color. Additional options can be specified and are logically or'ed together, chord, pie, nofill and/or edged.

objName filled_ellipse cx cy width height color draws a filled ellipse centered at cx, cy, of the given width, height and color.

objName fill_to_border x y borderColor color fills to the border matching the specified borderColor, starting at x, y, using the specified color.

objName fill x y color does a flood fill starting at x, y using the specified color.

objName text color font pointSize angle x y text renders text using the specified font and point size, at the specified angle, starting at x, y. Font is the full or relative pathname to a TrueType font file (.ttf or .ttc file). (Tclgd does not support GD's optionally built-in, non-antialiased, non-TrueType fonts.)

objName text_bounds color font pointSize angle x y text determines the bounds of text given the specified font and point size, at the specified angle, starting at x, y. The bounds are returned as an 8-element list giving the x and y coordinates of the four corners of a box the text will be within.

objName allocate_color r g b ?alpha? allocates a color given the specified red, green and blue values, and optional alpha value, and returns the color index. For truecolor images it returns a value that can be used to draw the specified color, but it's not really an index per se.

objName closest_color r g b ?alpha? returns the closest color index that can be found among the currently allocated colors.

objName closest_color_hwb r g b

objName exact_color r g b ?alpha?

objName resolve_color r g b ?alpha?

objName total_colors

objName deallocate_color color

objName true_color r g b ?alpha?

objName interlace ?boolean? if set to 1, t, etc, causes the image to be saved interlaced if the output format supports it, if 0, f, etc, causes the image to be saved noninterlaced. If boolean isn't specified, returns the current interlace setting for the image.

objName transparent color says what color index will be generated as transparent when the image is saved, assuming the outputted image format supports it. If color is not specified, the current color is returned. -1 means transparency is disabled.

objName set_anti_aliased color

objName set_anti_aliased_dont_blend color

objName set_brush BROKE

objName set_tile BROKE

objName set_style BROKE

objName set_thickness thickness

objName alpha_blending blending

objName save_alpha boolean

objName get_alpha

objName bounds_safe x y

objName bounds_safe x y

objName green_component color - returns the green component of the color.

objName red_component color - returns the red component of the color.

objName blue_component color - returns the blue component of the color.

objName width returns the width of the image, while objName height returns the height.

objName copy srcImageCommand destX destY srcX srcY width height

objName copy_resized srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight

objName copy_resampled srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight

objName copy_rotated srcImageCommand destX destY srcX srcY destWidth destHeight srcWidth srcHeight angle

objName copy_merge srcImageCommand destX destY srcX srcY width height percent

objName copy_merge_grey srcImageCommand destX destY srcX srcY width height percent

objName copy_palette srcImageCommand

objName sharpen percent

objName square_to_circle name radius

IMAGE OUTPUT ROUTINES

objName write_jpeg channel quality writes the image in JPEG format, with the specified quality level, to the specified Tcl channel, while objName jpeg_data quality will return it as binary data. Quality can range from 0 to 100, where higher numbers give higher quality.

objName write_gif channel writes the image to the specified channel in GIF format, while objName gif_data returns it as binary data.

objName write_png channel compressionLevel write the image to the specified channel, with the compression level of -1 for the default set when gd was built, 0 to indicate no compression, 1 to compress quickly, all the way to 9 to select the best possible compression. Likewise objName png_data compressionLevel returns the image as binary data, with the specified compression.

objName write_wbmp channel fgcolor write the image to the specified channel in Windows bitmap format, selecting only pixels matching the specified foreground color. objName wbmp_data fgcolor returns the image in wbmp format as binary data.

objName write_gd fileHandle writes the image out in the high-performance but non-portable gd format, while objName gd_data returns the image as binary data.

objName write_gd2 channel chunkSize format

objName gd2_data chunkSize format writes the image out in the high-performance but non-portable gd2 format, with chunkSize determining the size of each chunk, and format being either compressed or raw.

ANIMATED GIFS

objName gif_anim_begin channel global_color_map loops begins an animated GIF by specifying the file channel to be written to, a 1 if the global color map is to be used, and the number of times to play the animation. If loops is zero, the animation will repeat indefinitely.

objName gif_anim_add channel local_color_map left_offset top_offset delay disposal ?previous_image? adds a GIF image to an animated GIF that is under construction. Set local_color_map to 1 to add a local palette for this image to the animation, else the global palette is used.

If you use local palettes, you must make sure they match the global palette; use the copy_palette method to copy palettes between images.

left_offset and top_offset let you place the frame with an offset into the parent frame, where (0, 0) puts it in the corner.

Delay specifies the delay between the previous frame and this frame in hundredths of a second. Disposal can be 0 for unknown, 1 for none, 2 for restore background, or 3 for restore previous. Unknown is not recommended. Restore background restores the first allocated color of the global palette. Restore previous restores the appearance of the affected area before teh frame was rendered. Only none is a sensible choice for the first frame.

If the previous image is passed, the built-in GIF optimizer is automatically engaged and the disposal method specified is ignored. The optimizer comapres the images and only writes the changed pixels to the new frame of the animation. To achieve good optimization, it is usually best to use a single global color map. To allow gif_anim|add to compress unchanged pixels via the use of a transparent color, the image must include a transparent color. See gd documentation for details.

objName gif_anim_end channel is self-explanatory.