1gdtclft(3tcl) gdtclft(3tcl)
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 createTrueColor <width> <height>
73 Return a handle to a new trueColor gdImage that is width X height.
74 gd createFromGD <filehandle>
76 gd createFromGD2 <filehandle>
77 gd createFromGIF <filehandle>
78 gd createFromJPEG <filehandle>
79 gd createFromPNG <filehandle>
80 gd createFromWBMP <filehandle>
81 gd createFromXBM <filehandle>
82 Return a handle to a new gdImage created by reading an
83 image in the indicate format from the file open on filehandle.
84 gd destroy <gdhandle>
86 Destroy the gdImage referred to by gdhandle.
87 gd writeGD <gdhandle> <filehandle>
89 gd writeGD2 <gdhandle> <filehandle>
90 gd writeGIF <gdhandle> <filehandle>
91 gd writeJPEG <gdhandle> <filehandle>
92 gd writePNG <gdhandle> <filehandle>
93 gd writeWBMP <gdhandle> <filehandle>
94 gd writeXBM <gdhandle> <filehandle>
95 Write the image in gdhandle to filehandle in the
96 format indicated.
97 gd writePNGvar <gdhandle> <varname>
99 Write the image in gdhandle to Tcl variable "varname" as a binary
100 coded PNG object.
101 gd interlace <gdhandle> <on-off>
103 Make the output image interlaced (if on-off is true) or not (if
104 on-off is false).
105 gd color new <gdhandle> <red> <green> <blue>
107 Allocate a new color with the given RGB values. Returns the
108 color_idx, or -1 on failure (256 colors already allocated).
109 gd color exact <gdhandle> <red> <green> <blue>
111 Find a color_idx in the image that exactly matches the given RGB
112 color. Returns the color_idx, or -1 if no exact match.
113 gd color closest <gdhandle> <red> <green> <blue>
115 Find a color in the image that is closest to the given RGB color.
116 Guaranteed to return a color idx.
117 gd color resolve <gdhandle> <red> <green> <blue>
119 Return the index of the best possible effort to get a color.
120 Guaranteed to return a color idx. Equivalent to:
121 if {[set idx [gd color exact $gd $r $g $b]] == -1} {
122 if {[set idx [gd color neW $Gd $r $g $b]] == -1} {
123 set idx [gd color closest $gd $r $g $b]
124 }
125 }
126 gd color free <gdhandle> <color_idx>
128 Free the color at the given color_idx for reuse.
129 gd color transparent <gdhandle> [<color_idx>]
131 Mark the color at <color_idx> as the transparent background color. Or,
132 return the transparent color_idx if no color_idx specified.
133 gd color get <gdhandle> [<color_idx>]
135 Return the RGB value at <color_idx>, or {} if it is not allocated.
136 If <color_idx> is not specified, return a list of {color_idx R G B}
137 values for all allocated colors.
138 gd brush <gdhandle> <brushhandle>
140 Set the brush image to be used for brushed lines. Transparent
141 pixels in the brush will not change the image when the brush is
142 applied.
143 gd style <gdhandle> <color_idx> ...
145 Set the line style to the list of color indices. This is
146 interpreted in one of two ways. For a simple styled line, each
147 color is applied to points along the line in turn. The
148 transparent color_idx value may be used to leave gaps in the line.
149 For a styled, brushed line, a 0 (or the transparent color_idx)
150 means not to fill the pixel, and a non-zero value means to
151 apply the brush.
152 gd tile <gdhandle> <tilehandle>
154 Set the tile image to be used for tiled fills. Transparent
155 pixels in the tile will not change the underlying image during
156 tiling.
157 In all drawing functions, the color_idx is a number, or may
159 be one of the strings styled, brushed, tiled, "styled brushed"
160 or "brushed styled". The style, brush, or tile currently in
161 effect will be used. Brushing and styling apply to lines,
162 tiling to filled areas.
163 gd set <gdhandle> <color_idx> <x> <y>
165 Set the pixel at (x,y) to color <color_idx>.
166 gd line <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
168 gd rectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
170 gd fillrectangle <gdhandle> <color_idx> <x1> <y1> <x2> <y2>
172 Draw the outline of (resp. fill) a rectangle in color <color_idx>
173 with corners at (x1,y1) and (x2,y2).
174 gd arc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
176 gd fillarc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
177 gd openarc <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
178 gd chord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
179 gd fillchord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
180 gd openchord <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
181 gd pie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
182 gd fillpie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
183 gd openpie <gdhandle> <color_idx> <cx> <cy> <width> <height> <start> <end>
184 All describe an arc based shape in color <color_idx>, centered at (cx,cy)
185 in a rectangle width x height, starting at start degrees and ending
186 at end degrees.
187 arc - Just the curved line.
189 fillarc - (Intented to be a fill between the curve and chord,
190 but gd doesn't do that) - Same as pie.
191 openarc - Outline shape with curve and chord.
192 chord - Straight line chord between the ends of the curve,
193 but without showing the curve.
194 fillchord - Filled triangle between chord and center.
195 openchord - Outline triangle between chord and center.
196 pie - Filled pie segment between curve and center.
197 fillpie - Same as pie.
198 openpie - Outline pie segment between curve and center.
199 gd polygon <gdhandle> <color_idx> <x1> <y1> ...
201 gd fillpolygon <gdhandle> <color_idx> <x1> <y1> ...
203 Draw the outline of, or fill, a polygon specified by the x, y
204 coordinate list. There must be at least 3 points specified.
205 gd fill <gdhandle> <color_idx> <x> <y>
207 gd fill <gdhandle> <color_idx> <x> <y> <borderindex>
209 Fill with color <color_idx>, starting from (x,y) within a region of
210 pixels all the color of the pixel at (x,y) (resp., within a
211 border colored borderindex).
212 gd size <gdhandle>
214 Returns a list {width height} of the image.
215 gd text <gdhandle> <color_idx> <fontlist> <size> <angle> <x> <y> <string>
217 Draw text using <fontlist> in color <color_idx>,
218 with pointsize <size>, rotation in radians <angle>, with lower left
219 corner at (x,y). String may contain UTF8 sequences like: "À"
220 Returns 4 corner coords of bounding rectangle.
222 Use gdhandle = {} to get boundary without rendering.
223 Use negative of color_idx to disable antialiasing.
224 <fontlist> may contain either a full pathname of a font, including
226 ".ttf" extension, or it may contain a space-separated list of
227 alternate names for a font, without the ".ttf". e.g.
228 "Times-Roman times"
229 The file <name>.ttf corresponding to one of the alternate names
230 must be found in the built-in DEFAULT_FONTPATH, or in the
231 fontpath specified in a GDFONTPATH environment variable.
232 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <w> <h>
234 gd copy <desthandle> <srchandle> <destx> <desty> <srcx> <srcy> <destw> <desth> <srcw> <srch> Copy a subimage from
236 srchandle(srcx, srcy) to desthandle(destx, desty), size w x h.
237 Or, resize the subimage in copying from srcw x srch to destw x
238 desth.
239 Examples
243 The sample program from the gd documentation can be written thusly:
245 #!/bin/sh
248 # next line is a comment in tcl exec tclsh "$0" ${1+"$@"}
249 package require Gdtclft
251 ################################################################
253 # Sample gdtcl program - from gdtclft man page
254 #
255 # Create a 64 x 64 image
256 set im [gd create 64 64]
257 # Get black and white as colors. Black is the background color because
259 # it is allocated first from a new image.
260 set black [gd color new $im 0 0 0]
262 set white [gd color new $im 255 255 255]
263 # Draw a line from upper left to lower right
265 gd line $im $white 0 0 63 63
266 # Open a file for writing (Tcl on Unix, at least, doesn't support 'wb' mode)
268 set out [open test.png w]
269 # Output the image to the disk file
271 gd writePNG $im $out
272 # Close the file
274 close $out
275 # Destroy the image in memory
277 gd destroy $im
278 GDDEMO
281 Here's the gddemo.c program translated to tcl.
283 #!/bin/sh
285 # next line is a comment in tcl exec tclsh "$0" ${1+"$@"}
286 package require Gdtclft
288 ################################################################
290 #
291 # gddemo in tcl
292 #
293 # open demoin.png or die
295 if {[catch {open demoin.png r} in]} {
296 puts stderr "Can't load source image; this demo is much";
297 puts stderr "more impressive if demoin.png is available";
298 exit
299 }
300 # Create output image 128 x 128
302 set im_out [gd create 128 128]
303 # First color is background
305 set white [gd color new $im_out 255 255 255]
306 # Set transparent
308 gd color transparent $im_out $white
309 # Load demoin.png and paste part of it into the output image.
311 set im_in [gd createFromPNG $in]
312 close $in
313 # Copy and shrink
315 gd copy $im_out $im_in 16 16 0 0 96 96 128 128
316 # Get some colors
318 set red [gd color new $im_out 255 0 0]
319 set green [gd color new $im_out 0 255 0]
320 set blue [gd color new $im_out 0 0 255]
321 # Draw a rectangle
323 gd line $im_out $green 8 8 120 8
324 gd line $im_out $green 120 8 120 120
325 gd line $im_out $green 120 120 8 120
326 gd line $im_out $green 8 120 8 8
327 # Text
329 gd text $im_out $red arial 20 0 16 16 hi
330 gd text $im_out $red arial 20 90 23 23 hi
331 # Circle
333 gd arc $im_out $blue 64 64 30 10 0 360
334 # Arc
336 gd arc $im_out $blue 64 64 20 20 45 135
337 # Flood fill
339 gd fill $im_out $blue 4 4
340 # Polygon
342 gd fillpolygon $im_out $green 32 0 0 64 64 64
343 # Brush. A fairly wild example also involving a line style!
345 if {$im_in != ""} {
346 set brush [gd create 8 8];
347 eval [concat gd copy $brush $im_in 0 0 0 0 [gd size $brush] [gd size $im_in]]
348 gd brush $im_out $brush
349 # Style so they won't overprint each other.
350 gd style $im_out "0 0 0 0 0 0 0 1"
351 gd line $im_out "styled brushed" 0 0 128 128
352 }
353 # Interlace the result for "fade in" in viewers that support it
355 gd interlace $im_out true
356 # Write PNG
358 set out [open demoout.png w]
359 gd writePNG $im_out $out
360 close $out
361 gd destroy $im_out
362 GDSHOW
366 A quick Tcl procedure to display a GD image using the xv program.
368 ################################################################
370 # gdshow -- use xv to display an image.
371 #
372 # Waits until xv quits to return.
373 #
374 proc gdshow {gd} {
375 set f [open "|xv -" w]
376 catch {gd writePNG $gd $f}
377 catch {close $f} xx
378 if {$xx != {}} {
379 error "XV error: $xx"
380 }
381 }
382 Tcl Extensions gdtclft(3tcl)