1 TCL GD EXTENSION
2
3 TrueType font support using the FreeType library was added by
4 John Ellson (ellson@graphviz.org)
5
6 Assumes unicode strings in UTF8 format.
7
8 Compatible with:
9 tcl7.6 tcl8.0 tcl8.1 tcl8.2 (supports Stubs)
10
11 The latest Gdtclft sources are available from:
12
13 http://www.graphviz.org/pub/
14
15 The latest gd and freetype sources are available from:
16
17 http://www.boutell.com/gd/
18 http://www.freetype.org/
19
20 A collection of TrueType fonts are available from:
21
22 http://www.ora.com/homepages/comp.fonts/ifa/index.htm
23
24 Also, Microsoft offer some free and very clean fonts, except that
25 thay can't be redistributed.
26
27 http://www.microsoft.com/typography/fontpack/default.htm
28
29 ---------------------------------------------------------------------
30
31 Spencer Thomas said about the original TCL GD:
32
33 Thomas Boutell's Gd package provides a convenient way to generate
34 PNG images with a C program. If you, like me, prefer Tcl for CGI
35 applications, you'll want my TCL GD extension. You can get it by
36 anonymous FTP from ftp://guraldi.hgp.med.umich.edu/pub/gdtcl.shar.
37
38 Here's a quick overview of the package.
39 * Overview
40 * Installation
41 * Reference
42 * Examples
43 + gdsample -- sample program written in Tcl.
44 + Gddemo -- demo program written in Tcl.
45 + gdshow -- procedure to display an image.
46
47 A TCL INTERFACE TO THE GD PACKAGE
48
49 Spencer W. Thomas
50 Human Genome Center
51 University of Michigan
52 Ann Arbor, MI 48109
53
54 spencer.thomas@med.umich.edu
55
56 ---------------------------------------------------------------------
57
58 Overview
59
60 This package provides a simple Tcl interface to the gd (PNG drawing)
61 package, version 1.3. It includes an interface to all the gd functions
62 and data structures from Tcl commands.
63
64 Installation
65
66 ./configure
67 make
68 make install
69
70 (Note. Eric Melski <jmelski@cs.wisc.edu> reports that tclsh must
71 have been built using --enable-shared or the symbols Tcl_Alloc and
72 Tcl_Free are not exported.)
73
74 Reference
75
76 One Tcl command, 'gd', is added. All gd package actions are
77 sub-commands (or "options" in Tcl terminology) of this command.
78
79 Each active gd image is referred to with a "handle". The handle is a
80 name of the form gd# (e.g., gd0) returned by the gd create options.
81
82 Almost all the gd commands take a handle as the first argument (after
83 the option). All the drawing commands take a color_idx as the next
84 argument.
85
86 gd create <width> <height>
87 Return a handle to a new gdImage that is width X height.
88
89 gd createFromPNG <filehandle>
90
91 gd createFromGD <filehandle>
92
93 gd createFromXBM <filehandle>
94 Return a handle to a new gdImage created by reading a PNG
95 (resp. GD or XBM) image from the file open on filehandle.
96
97 gd destroy <gdhandle>
98 Destroy the gdImage referred to by gdhandle.
99
100 gd writePNG <gdhandle> <filehandle>
101
102 gd writeGD <gdhandle> <filehandle>
103 Write the image in gdhandle to filehandle as a PNG (resp. GD)
104 file.
105
106 gd writePNGvar <gdhandle> <varname>
107 Write the image in gdhandle to Tcl variable "varname" as a binary
108 coded PNG object.
109
110 gd interlace <gdhandle> <on-off>
111 Make the output image interlaced (if on-off is true) or not (if
112 on-off is false).
113
114 gd color new <gdhandle> <red> <green> <blue>
115 Allocate a new color with the given RGB values. Returns the
116 color_idx, or -1 on failure (256 colors already allocated).
117
118 gd color exact <gdhandle> <red> <green> <blue>
119 Find a color_idx in the image that exactly matches the given RGB
120 color. Returns the color_idx, or -1 if no exact match.
121
122 gd color closest <gdhandle> <red> <green> <blue>
123 Find a color in the image that is closest to the given RGB color.
124 Guaranteed to return a color idx.
125
126 gd color resolve <gdhandle> <red> <green> <blue>
127 Return the index of the best possible effort to get a color.
128 Guaranteed to return a color idx. Equivalent to:
129 if {[set idx [gd color exact $gd $r $g $b]] == -1} {
130 if {[set idx [gd color neW $Gd $r $g $b]] == -1} {
131 set idx [gd color closest $gd $r $g $b]
132 }
133 }
134
135 gd color free <gdhandle> <color_idx>
136 Free the color at the given color_idx for reuse.
137
138 gd color transparent <gdhandle> [<color_idx>]
139 Mark the color at <color_idx> as the transparent background color. Or,
140 return the transparent color_idx if no color_idx specified.
141
142 gd color get <gdhandle> [<color_idx>]
143 Return the RGB value at <color_idx>, or {} if it is not allocated.
144 If <color_idx> is not specified, return a list of {color_idx R G B}
145 values for all allocated colors.
146
147 gd brush <gdhandle> <brushhandle>
148 Set the brush image to be used for brushed lines. Transparent
149 pixels in the brush will not change the image when the brush is
150 applied.
151
152 gd style <gdhandle> <color_idx> ...
153 Set the line style to the list of color indices. This is
154 interpreted in one of two ways. For a simple styled line, each
155 color is applied to points along the line in turn. The
156 transparent color_idx value may be used to leave gaps in the line.
157 For a styled, brushed line, a 0 (or the transparent color_idx)
158 means not to fill the pixel, and a non-zero value means to
159 apply the brush.
160
161 gd tile <gdhandle> <tilehandle>
162 Set the tile image to be used for tiled fills. Transparent
163 pixels in the tile will not change the underlying image during
164 tiling.
165
166 In all drawing functions, the color_idx is a number, or may
167 be one of the strings styled, brushed, tiled, "styled brushed"
168 or "brushed styled". The style, brush, or tile currently in
169 effect will be used. Brushing and styling apply to lines,
170 tiling to filled areas.
171
172 gd set <gdhandle> <color_idx> <x> <y>
173 Set the pixel at (x,y) to color <color_idx>.
174
175 gd line <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
176
177 gd rectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
178
179 gd fillrectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
180 Draw the outline of (resp. fill) a rectangle in color <color_idx>
181 with corners at (x1,y1) and (x2,y2).
182
183 gd arc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
184 Draw an arc in color <color_idx>, centered at (cx,cy) in a rectangle width
185 x height, starting at start degrees and ending at end degrees.
186 start must be > end.
187
188 gd polygon <gdhandle> <color_idx> <x1> <y1> ...
189
190 gd fillpolygon <gdhandle> <color_idx> <x1> <y1> ...
191 Draw the outline of, or fill, a polygon specified by the x, y
192 coordinate list. There must be at least 3 points specified.
193
194 gd fill <gdhandle> <color_idx> <x> <y>
195
196 gd fill <gdhandle> <color_idx> <x> <y> <borderindex>
197 Fill with color <color_idx>, starting from (x,y) within a region of
198 pixels all the color of the pixel at (x,y) (resp., within a
199 border colored borderindex).
200
201 gd size <gdhandle>
202 Returns a list {width height} of the image.
203
204 gd text <gdhandle> <color_idx> <fontpath> <size> <angle> <x> <y> <string>
205 Draw text using the .ttf font in <fontpath> in color <color_idx>,
206 with pointsize <size>, rotation in radians <angle>, with lower left
207 corner at (x,y). String may contain UTF8 sequences like: "À"
208 Returns 4 corner coords of bounding rectangle.
209 Use gdhandle = {} to get boundary without rendering.
210 Use negative of color_idx to disable antialiasing.
211
212 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <w> <h>
213
214 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <destw> <desth> <srcw> <srch>
215 Copy a subimage from srchandle(srcx, srcy) to
216 desthandle(destx, desty), size w x h. Or, resize
217 the subimage in copying from srcw x srch to destw x desth.
218
219
220
221 Examples
222
223 The sample program from the gd documentation can be written thusly:
224
225 ################################################################
226 # Sample gdtcl program
227 #
228 # Create a 64 x 64 image
229 set im [gd create 64 64]
230
231 # Get black and white as colors. Black is the background color because
232 # it is allocated first from a new image.
233
234 set black [gd color new $im 0 0 0]
235 set white [gd color new $im 255 255 255]
236
237 # Draw a line from upper left to lower right
238 gd line $im $white 0 0 63 63
239
240 # Open a file for writing (Tcl on Unix, at least, doesn't support 'wb' mode)
241 set out [open test.png w]
242
243 # Output the image to the disk file
244 gd writePNG $im $out
245
246 # Close the file
247 close $out
248
249 # Destroy the image in memory
250 gd destroy $im
251
252
253
254 GDDEMO
255
256 Here's the gddemo.c program translated to tcl.
257
258 ################################################################
259 #
260 # gddemo in tcl
261 #
262
263 # Create output image 128 x 128
264 set im_out [gd create 128 128]
265
266 # First color is background
267 set white [gd color new $im_out 255 255 255]
268
269 # Set transparent
270 gd color transparent $im_out $white
271
272 # Load demoin.png and paste part of it into the output image.
273 if {[catch {set in [open demoin.png]}]} {
274 puts stderr "Can't load source image; this demo is much";
275 puts stderr "more impressive if demoin.png is available";
276 set im_in "";
277 } else {
278 set im_in [gd createFromPNG $in]
279 close $in
280 # Copy and shrink
281 gd copy $im_out $im_in 16 16 0 0 96 96 128 128
282 }
283
284 # Get some colors
285 set red [gd color new $im_out 255 0 0]
286 set green [gd color new $im_out 0 255 0]
287 set blue [gd color new $im_out 0 0 255]
288
289 # Draw a rectangle
290 gd line $im_out $green 8 8 120 8
291 gd line $im_out $green 120 8 120 120
292 gd line $im_out $green 120 120 8 120
293 gd line $im_out $green 8 120 8 8
294
295 # Text
296 gd text $im_out $red /usr/lib/ttf/times.ttf 20 0 16 16 hi
297 gd text $im_out $red /usr/lib/ttf/times.ttf 20 90 23 23 hi
298
299 # Circle
300 gd arc $im_out $blue 64 64 30 10 0 360
301
302 # Arc
303 gd arc $im_out $blue 64 64 20 20 45 135
304
305 # Flood fill
306 gd fill $im_out $blue 4 4
307
308 # Polygon
309 gd fillpolygon $im_out $green 32 0 0 64 64 64
310
311 # Brush. A fairly wild example also involving a line style!
312 if {$im_in != ""} {
313 set brush [gd create 8 8];
314 eval [concat gd copy $brush $im_in 0 0 0 0 [gd size $brush] [gd size $im_in]]
315 gd brush $im_out $brush
316 # Style so they won't overprint each other.
317 gd style $im_out [concat [replicate "0 " 7] 1]
318 gd line $im_out "styled brushed" 0 0 128 128
319 }
320
321 # Interlace the result for "fade in" in viewers that support it
322 gd interlace $im_out true
323
324 # Write PNG
325 set out [open demoout.png w]
326 gd writePNG $im_out $out
327 close $out
328 gd destroy $im_out
329
330
331
332 GDSHOW
333
334 A quick Tcl procedure to display a GD image using the xv program.
335
336 ################################################################
337 # gdshow -- use xv to display an image.
338 #
339 # Waits until xv quits to return.
340 #
341 proc gdshow {gd} {
342 set f [open "|xv -" w]
343 catch {gd writePNG $gd $f}
344 catch {close $f} xx
345 if {$xx != {}} {
346 error "XV error: $xx"
347 }
348 }
349