1gdtclft(n) gdtclft(n)
2
6 gdtclft - render images in various bitmap formats (GD, GD2, GIF, JPEG,
7 PNG, WBMP, XBM)
8
10 TCL GD EXTENSION
11 Thomas Boutell's Gd package provides a convenient way to generate
13 bitmap images with a C program. If you, like me, prefer Tcl for CGI
14 applications, you'll want my TCL GD extension. You can get it by
15 anonymous FTP from ftp://guraldi.hgp.med.umich.edu/pub/gdtcl.shar.
16 Here's a quick overview of the package.
18 * Overview
19 * Installation
20 * Reference
21 * Examples
22 + gdsample -- sample program written in Tcl.
23 + Gddemo -- demo program written in Tcl.
24 + gdshow -- procedure to display an image.
25 A TCL INTERFACE TO THE GD PACKAGE
27 Spencer W. Thomas
29 Human Genome Center
30 University of Michigan
31 Ann Arbor, MI 48109
32 spencer.thomas@med.umich.edu
34 TrueType font support using the FreeType library was added by
36 John Ellson (ellson@graphviz.org)
37 Latest sources available from:
39 http://www.graphviz.org/pub/
41 Overview
44 This package provides a simple Tcl interface to the gd (bitmap drawing)
46 package, version 1.1. It includes an interface to all the gd functions
47 and data structures from Tcl commands.
48 Installation
52 ./configure
54 make
55 make install
56 Reference
58 One Tcl command, 'gd', is added. All gd package actions are
60 sub-commands (or "options" in Tcl terminology) of this command.
61 Each active gd image is referred to with a "handle". The handle is a
63 name of the form gd# (e.g., gd0) returned by the gd create options.
64 Almost all the gd commands take a handle as the first argument (after
66 the option). All the drawing commands take a color_idx as the next
67 argument.
68 gd create <width> <height>
70 Return a handle to a new gdImage that is width X height.
71 gd createFromGD <filehandle>
73 gd createFromGD2 <filehandle>
74 gd createFromGIF <filehandle>
75 gd createFromJPEG <filehandle>
76 gd createFromPNG <filehandle>
77 gd createFromWBMP <filehandle>
78 gd createFromXBM <filehandle>
79 Return a handle to a new gdImage created by reading an
80 image in the indicate format from the file open on filehandle.
81 gd destroy <gdhandle>
83 Destroy the gdImage referred to by gdhandle.
84 gd writeGD <gdhandle> <filehandle>
86 gd writeGD2 <gdhandle> <filehandle>
87 gd writeGIF <gdhandle> <filehandle>
88 gd writeJPEG <gdhandle> <filehandle>
89 gd writePNG <gdhandle> <filehandle>
90 gd writeWBMP <gdhandle> <filehandle>
91 gd writeXBM <gdhandle> <filehandle>
92 Write the image in gdhandle to filehandle in the
93 format indicated.
94 gd writePNGvar <gdhandle> <varname>
96 Write the image in gdhandle to Tcl variable "varname" as a binary
97 coded PNG object.
98 gd interlace <gdhandle> <on-off>
100 Make the output image interlaced (if on-off is true) or not (if
101 on-off is false).
102 gd color new <gdhandle> <red> <green> <blue>
104 Allocate a new color with the given RGB values. Returns the
105 color_idx, or -1 on failure (256 colors already allocated).
106 gd color exact <gdhandle> <red> <green> <blue>
108 Find a color_idx in the image that exactly matches the given RGB
109 color. Returns the color_idx, or -1 if no exact match.
110 gd color closest <gdhandle> <red> <green> <blue>
112 Find a color in the image that is closest to the given RGB color.
113 Guaranteed to return a color idx.
114 gd color resolve <gdhandle> <red> <green> <blue>
116 Return the index of the best possible effort to get a color.
117 Guaranteed to return a color idx. Equivalent to:
118 if {[set idx [gd color exact $gd $r $g $b]] == -1} {
119 if {[set idx [gd color neW $Gd $r $g $b]] == -1} {
120 set idx [gd color closest $gd $r $g $b]
121 }
122 }
123 gd color free <gdhandle> <color_idx>
125 Free the color at the given color_idx for reuse.
126 gd color transparent <gdhandle> [<color_idx>]
128 Mark the color at <color_idx> as the transparent background color. Or,
129 return the transparent color_idx if no color_idx specified.
130 gd color get <gdhandle> [<color_idx>]
132 Return the RGB value at <color_idx>, or {} if it is not allocated.
133 If <color_idx> is not specified, return a list of {color_idx R G B}
134 values for all allocated colors.
135 gd brush <gdhandle> <brushhandle>
137 Set the brush image to be used for brushed lines. Transparent
138 pixels in the brush will not change the image when the brush is
139 applied.
140 gd style <gdhandle> <color_idx> ...
142 Set the line style to the list of color indices. This is
143 interpreted in one of two ways. For a simple styled line, each
144 color is applied to points along the line in turn. The
145 transparent color_idx value may be used to leave gaps in the line.
146 For a styled, brushed line, a 0 (or the transparent color_idx)
147 means not to fill the pixel, and a non-zero value means to
148 apply the brush.
149 gd tile <gdhandle> <tilehandle>
151 Set the tile image to be used for tiled fills. Transparent
152 pixels in the tile will not change the underlying image during
153 tiling.
154 In all drawing functions, the color_idx is a number, or may
156 be one of the strings styled, brushed, tiled, "styled brushed"
157 or "brushed styled". The style, brush, or tile currently in
158 effect will be used. Brushing and styling apply to lines,
159 tiling to filled areas.
160 gd set <gdhandle> <color_idx> <x> <y>
162 Set the pixel at (x,y) to color <color_idx>.
163 gd line <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
165 gd rectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
167 gd fillrectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
169 Draw the outline of (resp. fill) a rectangle in color <color_idx>
170 with corners at (x1,y1) and (x2,y2).
171 gd arc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
173 gd fillarc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
174 gd openarc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
175 gd chord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
176 gd fillchord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
177 gd openchord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
178 gd pie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
179 gd fillpie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
180 gd openpie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
181 All describe an arc based shape in color <color_idx>, centered at (cx,cy)
182 in a rectangle width x height, starting at start degrees and ending
183 at end degrees.
184 arc - Just the curved line.
186 fillarc - (Intented to be a fill between the curve and chord,
187 but gd doesn't do that) - Same as pie.
188 openarc - Outline shape with curve and chord.
189 chord - Straight line chord between the ends of the curve,
190 but without showing the curve.
191 fillchord - Filled triangle between chord and center.
192 openchord - Outline triangle between chord and center.
193 pie - Filled pie segment between curve and center.
194 fillpie - Same as pie.
195 openpie - Outline pie segment between curve and center.
196 gd polygon <gdhandle> <color_idx> <x1> <y1> ...
198 gd fillpolygon <gdhandle> <color_idx> <x1> <y1> ...
200 Draw the outline of, or fill, a polygon specified by the x, y
201 coordinate list. There must be at least 3 points specified.
202 gd fill <gdhandle> <color_idx> <x> <y>
204 gd fill <gdhandle> <color_idx> <x> <y> <borderindex>
206 Fill with color <color_idx>, starting from (x,y) within a region of
207 pixels all the color of the pixel at (x,y) (resp., within a
208 border colored borderindex).
209 gd size <gdhandle>
211 Returns a list {width height} of the image.
212 gd text <gdhandle> <color_idx> <fontlist> <size> <angle> <x> <y> <string>
214 Draw text using <fontlist> in color <color_idx>,
215 with pointsize <size>, rotation in radians <angle>, with lower left
216 corner at (x,y). String may contain UTF8 sequences like: "À"
217 Returns 4 corner coords of bounding rectangle.
219 Use gdhandle = {} to get boundary without rendering.
220 Use negative of color_idx to disable antialiasing.
221 <fontlist> may contain either a full pathname of a font, including
223 ".ttf" extension, or it may contain a space-separated list of
224 alternate names for a font, without the ".ttf". e.g.
225 "Times-Roman times"
226 The file <name>.ttf corresponding to one of the alternate names
227 must be found in the built-in DEFAULT_FONTPATH, or in the
228 fontpath specified in a GDFONTPATH environment variable.
229 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <w> <h>
231 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <destw> <desth> <srcw> <srch> Copy a subimage from
233 srchandle(srcx, srcy) to desthandle(destx, desty), size w x h.
234 Or, resize the subimage in copying from srcw x srch to destw x
235 desth.
236 Examples
240 The sample program from the gd documentation can be written thusly:
242 #!/bin/sh
245 # next line is a comment in tcl exec tclsh "$0" ${1+"$@"}
246 package require Gdtclft
248 ################################################################
250 # Sample gdtcl program - from gdtclft man page
251 #
252 # Create a 64 x 64 image
253 set im [gd create 64 64]
254 # Get black and white as colors. Black is the background color because
256 # it is allocated first from a new image.
257 set black [gd color new $im 0 0 0]
259 set white [gd color new $im 255 255 255]
260 # Draw a line from upper left to lower right
262 gd line $im $white 0 0 63 63
263 # Open a file for writing (Tcl on Unix, at least, doesn't support 'wb' mode)
265 set out [open test.png w]
266 # Output the image to the disk file
268 gd writePNG $im $out
269 # Close the file
271 close $out
272 # Destroy the image in memory
274 gd destroy $im
275 GDDEMO
278 Here's the gddemo.c program translated to tcl.
280 #!/bin/sh
282 # next line is a comment in tcl exec tclsh "$0" ${1+"$@"}
283 package require Gdtclft
285 ################################################################
287 #
288 # gddemo in tcl
289 #
290 # open demoin.png or die
292 if {[catch {open demoin.png r} in]} {
293 puts stderr "Can't load source image; this demo is much";
294 puts stderr "more impressive if demoin.png is available";
295 exit
296 }
297 # Create output image 128 x 128
299 set im_out [gd create 128 128]
300 # First color is background
302 set white [gd color new $im_out 255 255 255]
303 # Set transparent
305 gd color transparent $im_out $white
306 # Load demoin.png and paste part of it into the output image.
308 set im_in [gd createFromPNG $in]
309 close $in
310 # Copy and shrink
312 gd copy $im_out $im_in 16 16 0 0 96 96 128 128
313 # Get some colors
315 set red [gd color new $im_out 255 0 0]
316 set green [gd color new $im_out 0 255 0]
317 set blue [gd color new $im_out 0 0 255]
318 # Draw a rectangle
320 gd line $im_out $green 8 8 120 8
321 gd line $im_out $green 120 8 120 120
322 gd line $im_out $green 120 120 8 120
323 gd line $im_out $green 8 120 8 8
324 # Text
326 gd text $im_out $red arial 20 0 16 16 hi
327 gd text $im_out $red arial 20 90 23 23 hi
328 # Circle
330 gd arc $im_out $blue 64 64 30 10 0 360
331 # Arc
333 gd arc $im_out $blue 64 64 20 20 45 135
334 # Flood fill
336 gd fill $im_out $blue 4 4
337 # Polygon
339 gd fillpolygon $im_out $green 32 0 0 64 64 64
340 # Brush. A fairly wild example also involving a line style!
342 if {$im_in != ""} {
343 set brush [gd create 8 8];
344 eval [concat gd copy $brush $im_in 0 0 0 0 [gd size $brush] [gd size $im_in]]
345 gd brush $im_out $brush
346 # Style so they won't overprint each other.
347 gd style $im_out "0 0 0 0 0 0 0 1"
348 gd line $im_out "styled brushed" 0 0 128 128
349 }
350 # Interlace the result for "fade in" in viewers that support it
352 gd interlace $im_out true
353 # Write PNG
355 set out [open demoout.png w]
356 gd writePNG $im_out $out
357 close $out
358 gd destroy $im_out
359 GDSHOW
363 A quick Tcl procedure to display a GD image using the xv program.
365 ################################################################
367 # gdshow -- use xv to display an image.
368 #
369 # Waits until xv quits to return.
370 #
371 proc gdshow {gd} {
372 set f [open "|xv -" w]
373 catch {gd writePNG $gd $f}
374 catch {close $f} xx
375 if {$xx != {}} {
376 error "XV error: $xx"
377 }
378 }
379Tcl-Extensions 8.0 gdtclft(n)