gdtclft(3tcl)

1gdtclft(3tcl)                                                    gdtclft(3tcl)
2
3
4

NAME

6       gdtclft  - render images in various bitmap formats (GD, GD2, GIF, JPEG,
7       PNG, WBMP, XBM)
8

DESCRIPTION

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

NAME

DESCRIPTION

SEE ALSO