-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathgd-ref.html
536 lines (402 loc) · 15.6 KB
/
gd-ref.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>Python GD Module Reference</title>
<style>
body { font-family: arial, helvetica; }
code { font-size: 110%; }
</style>
</head>
<body>
<h1>Python GD Module Reference</h1>
<h3>Description</h3>
GD module is an interface to the <a href=
"http://www.boutell.com/gd/">GD library</a> written by Thomas
Boutell.
<blockquote>
'gd is a graphics library. It allows your code to quickly draw images complete
with lines, arcs, text, multiple colors, cut and paste from other images, and
flood fills, and write out the result as a PNG or JPEG file. This is
particularly useful in World Wide Web applications, where PNG and JPEG are two
of the formats accepted for inline images by most browsers.'
</blockquote>
It has been extended in some ways from the original GD library.
<p>
<i>This documentation is slightly out of date. In particular, the patch by
Mike Romberg adds a lot of methods to the image object, which may not be fully
documented here. Use the Source, Luke.</i>
<h3>Constants</h3>
<dl>
<dt>gdFontGiant, gdFontLarge, gdFontMediumBold, gdFontSmall,
gdFontTiny</dt>
<dd>Fonts for use with the string() and stringUp() methods.</dd>
<dt>gdMaxColors(256)</dt>
<dd>Maximum number of colors in an image; GD will likely change this
figure in a future version.</dd>
<dt>gdStyled, gdStyledBrushed, gdBrushed</dt>
<dd>Draw mode for line() and lines() method.</dd>
<dt>gdTiled</dt>
<dd>Fill mode for fill(), fillToBorder()</dd>
<dt>gdTransparent, gdStyledBrushed</dt>
<dd>Special entries for setStyle()</dd>
</dl>
<h3>Image Object</h3>
<dl>
<dt><code>image</code>(<em>image</em>[,(<em>w</em>,<em>h</em>)] |
<em>file</em> | <em>file</em>,<em>type</em> |
(<em>w</em>,<em>h</em>))</dt>
<dd>create GD image from
<ul>
<li><em>file</em>.(png|jpeg|gd|gd2|xbm|xpm),
<li><em>file</em> (a filename or file-like object with a read
method), <em>type</em> (png|jpeg|gd|gd2|xbm|xpm)
<li>the existing <em>image</em>,
<ul>
<li>optionally resized to width <em>w</em> and height <em>h</em>
</ul>
<li>or blank with width <em>w</em> and height <em>h</em>
</ul>
</dd>
</dl>
<h3>Image Object Methods</h3>
<dl>
<dt><code>writePng</code>(<em>f</em>)</dt>
<dd>write the image to <em>f</em> as a PNG, where <em>f</em> is
either an open file-like object or a file name.</dd>
<dt><code>writeJpeg</code>(<em>f</em>, [ <em>q</em> ])</dt>
<dd>write the image to <em>f</em> as a JPEG file, where <em>f</em> is
either an open file-like object or a file name, and <em>q</em> is the
quality value as an integer from 0 to 100. If <em>q</em> is 0 or
omitted, a default is used.</dd>
<dt><code>writeGd</code>(<em>f</em>)</dt>
<dd>write the image to <em>f</em> as a GD file, where <em>f</em> is
either an open file-like object or a file name.</dd>
<dt><code>writeGd2</code>(<em>f</em>, [ <em>c</em>, [ <em>fmt</em> ] ])</dt>
<dd>write the image to <em>f</em> as a GD2 file, where <em>f</em> is
either an open file-like object or a file name, c is the chunksize and fmt is
the format. See the GD 1.8.3 or later documentation for an explanation.
Defaults will be supplied if omitted.</dd>
<dt><code>writeWbmp</code>(<em>f</em>, [ <em>fg</em> ])</dt>
<dd>write the image to <em>f</em> as a WBMP file, where <em>f</em> is
either an open file-like object or a file name, and <em>fg</em> is the
index of the color to "set" in the result image (see the GD 1.8.3 or
later documentation for details). <em>fg</em> defaults to 0 if omitted.</dd>
<dt>
<br>
All of the above write methods accept either a filename, file
object or a python object with a write() method. Use a StringIO
object if you want to get the image data without writing it to
a file (useful for web scripts that return generated images to
the client).
<br>
</dt>
<dt><code>setPixel</code>((<em>x</em>,<em>y</em>), <em>
color</em>)</dt>
<dd>set the pixel at (<em>x</em>,<em>y</em>) to <em>color</em></dd>
<dt><code>line</code>((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), <em>color</em>)</dt>
<dd>draw a line from (<em>x1</em>,<em>y1</em>) to
(<em>x2</em>,<em>y2</em>) in <em>color</em></dd>
<dt><code>lines</code>(((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), ..., (<em>xn</em>, <em>yn</em>)), <em>
color</em>)</dt>
<dd>draw a line along the sequence of points in the list or tuple
using <em>color</em></dd>
<dt><code>polygon</code>(((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), ..., (<em>xn</em>, <em>yn</em>)), <em>
color</em>[, <em>fillcolor</em>])</dt>
<dd>draw a polygon using the list or tuple of points (minimum 3) in
<em>color</em>, optionally filled with <em>fillcolor</em></dd>
<dt><code>rectangle</code>((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), <em>color</em>[, <em>
fillcolor</em>])</dt>
<dd>draw a rectangle with upper corner (<em>x1</em>,<em>y1</em>),
lower corner (<em>x2</em>,<em>y2</em>) in <em>color</em>,
optionally filled with <em>fillcolor</em></dd>
<dt><code>filledPolygon</code>(((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), ..., (<em>xn</em>, <em>yn</em>)), <em>
color</em>)</dt>
<dd>draw a filled polygon using the list or tuple of points
(minimum 3) in <em>color</em></dd>
<dt><code>filledRectangle</code>((<em>x1</em>,<em>y1</em>),
(<em>x2</em>,<em>y2</em>), <em>color</em>)</dt>
<dd>draw a rectangle with upper corner (<em>x1</em>,<em>y1</em>),
lower corner (<em>x2</em>,<em>y2</em>) in <em>color</em></dd>
<dt><code>arc</code>((<em>x</em>,<em>y</em>),
(<em>w</em>,<em>h</em>), <em>start</em>, <em>end</em>, <em>
color</em>)</dt>
<dd>draw an ellipse centered at (<em>x</em>,<em>y</em>) with width
<em>w</em>, height <em>h</em> from <em>start</em> degrees to <em>
end</em> degrees in <em>color</em>.</dd>
<dt><code>fillToBorder</code>((<em>x</em>,<em>y</em>), <em>
border</em>, <em>color</em>)</dt>
<dd>flood from point (<em>x</em>,<em>y</em>) to <em>border</em>
color in <em>color</em></dd>
<dt><code>fill</code>((<em>x</em>,<em>y</em>), <em>color</em>)</dt>
<dd>flood from point (<em>x</em>,<em>y</em>) in <em>color</em> for
those pixels with the same color as the starting point</dd>
<dt><code>setBrush</code>(<em>image</em>)</dt>
<dd>set the drawing brush to <em>image</em> (use <strong>
gdBrushed</strong> when drawing)</dd>
<dt><code>setTile</code>(<em>image</em>)</dt>
<dd>set the fill tile to <em>image</em> (use <strong>
gdTiled</strong> when filling)</dd>
<dt><code>setStyle</code>(<em>tuple</em>|<em>list</em>)</dt>
<dd>set the line bit-style to <em>tuple</em> or <em>list</em> of
colors (use gdStyled when drawing)</dd>
<dt><code>getPixel</code>((<em>x</em>,<em>y</em>))</dt>
<dd>color index of image at (<em>x</em>,<em>y</em>)</dd>
<dt><code>boundsSafe</code>((<em>x</em>,<em>y</em>))</dt>
<dd>returns true if (<em>x</em>,<em>y</em>) is within image</dd>
<dt><code>size</code>()</dt>
<dd>return the 2-tuple size of image</dd>
<dt><code>string</code>(<em>font</em>, (<em>x</em>,<em>y</em>),
<em>s</em>, <em>color</em>)</dt>
<dd>draw string <em>s</em> at (<em>x</em>,<em>y</em>) using one of
the pre-defined gdmodule fonts</dd>
<dt><code>stringUp</code>(<em>font</em>, (<em>x</em>,<em>y</em>),
<em>s</em>, <em>color</em>)</dt>
<dd>vertically draw string <em>s</em> at (<em>x</em>,<em>y</em>)
using one of the pre-defined gdmodule fonts</dd>
<dt><code>get_bounding_rect</code>(<em>font</em>,
<em>pointsize</em>, <em>angle</em>,
(<em>x</em>,<em>y</em>), <em>s</em>)</dt>
<dd>Get bounding rect of string <em>s</em> using the TrueType <em>font</em>
at the given <em>pointsize</em> and <em>angle</em>.
Returns
the bounding box of the given text as an eight-tuple: lower left X,
lower left Y, lower right X, lower right Y, upper right X,
upper right Y, upper left X, upper left Y.
<dt><code>string_ttf</code>(<em>font</em>, <em>pointsize</em>, <em>angle</em>,
(<em>x</em>,<em>y</em>), <em>s</em>, <em>color</em>)</dt>
<dd>draw string <em>s</em> at (<em>x</em>,<em>y</em>) using
the TrueType font at the given pointsize and angle.
Returns
the bounding box of the given text as an eight-tuple: lower left X,
lower left Y, lower right X, lower right Y, upper right X,
upper right Y, upper left X, upper left Y.
</dd>
<dt><code>string_ft</code>(<em>font</em>, <em>pointsize</em>, <em>angle</em>,
(<em>x</em>,<em>y</em>), <em>s</em>, <em>color</em>)</dt>
<dd>
Functional equivalent of <code>string_ttf</code>, which may be deprecated.
</dd>
<dt><code>
colorAllocate</code>((<em>r</em>,<em>g</em>,<em>b</em>))</dt>
<dd>allocate a color index to (<em>r</em>,<em>g</em>,<em>b</em>)
(returns -1 if unable to)</dd>
<dt><code>
colorClosest</code>((<em>r</em>,<em>g</em>,<em>b</em>))</dt>
<dd>return the color index closest to
(<em>r</em>,<em>g</em>,<em>b</em>) (returns -1 if unable to)</dd>
<dt><code>
colorExact</code>((<em>r</em>,<em>g</em>,<em>b</em>))</dt>
<dd>return an exact color index match for
(<em>r</em>,<em>g</em>,<em>b</em>) (returns -1 if unable to)</dd>
<dt><code>colorsTotal</code>()</dt>
<dd>returns the number of colors currently allocated</dd>
<dt><code>colorComponents</code>(<em>color</em>)</dt>
<dd>returns a 3-tulple of the (r,g,b) components of color</dd>
<dt><code>getInterlaced</code>()</dt>
<dd>returns true if the image is interlaced</dd>
<dt><code>getTransparent</code>()</dt>
<dd>returns transparent color index or -1</dd>
<dt><code>colorDeallocate</code>(<em>color</em>)</dt>
<dd>deallocate <em>color</em> from the image palette</dd>
<dt><code>colorTransparent</code>(<em>color</em>)</dt>
<dd>set the transparent color to <em>color</em></dd>
<dt><code>copyTo</code>(image[, (dx,dy)[, (sx,sy)[, (w,h)]]])</dt>
<dd>copy from (<em>sx</em>,<em>sy</em>), width <em>sw</em> and
height <em>sh</em> to destination <em>image</em>
(<em>dx</em>,<em>dy</em>)</dd>
<dt><code>copyResizedTo</code>(<em>image</em>[,
(<em>dx</em>,<em>dy</em>)[, (<em>sx</em>,<em>sy</em>)[,
(<em>dw</em>,<em>dh</em>)[, (<em>sw</em>,<em>sh</em>)]]]])</dt>
<dd>copy from (<em>sx</em>,<em>sy</em>), width <em>sw</em> and
height <em>sh</em> to destination <em>image</em>
(<em>dx</em>,<em>dy</em>), width <em>dw</em> and height <em>
dh</em></dd>
<dt><code>interlace</code>()</dt>
<dd>set the interlace bit</dd>
<dt><code>
origin</code>((<em>x</em>,<em>y</em>)[,<em>xmult</em>,<em>ymult</em>])</dt>
<dd>set the origin of the image to (<em>x</em>,<em>y</em>) and
multiply all x, y, width and height factors by <em>xmult</em> and
<em>ymult</em> (typically either 1 or -1)</dd>
<dt><code>getOrigin</code>()</dt>
<dd>returns the origin parameters ((x,y),xmult,ymult)</dd>
</dl>
<h3>Other Module-level functions</h3>
<dl>
<dt><code>fontstrsize(<em>font</em>, <em>string</em>)</code></dt>
<dd>return a tuple containing the size in pixels of the given <em>
string</em> in the given <em>font</em></dd>
</dl>
<hr>
Copyright © 1995 Richard Jones, Bureau of Meteorology Australia.<br>
<p>
With Richard's blessing, I have taken over support for this module;
so, send all bug reports, etc. to
<a href='mailto:[email protected]'>
<p>
This module is a python wrapper for the GD library (version 1.1.1 and later)
<p>
From the GD docs:<br>
"COPYRIGHT 1994 BY THE QUEST CENTER AT COLD SPRING HARBOR LABS. <br>
Permission granted for unlimited use, provided that
the Quest Center at Cold Spring Harbor Labs is given
credit for the library in the user-visible documentation of
your software. If you modify gd, we ask that you share the
modifications with us so they can be added to the
distribution. See gd.html for details.
<p>
<a name='releasenotes'></a>
<ul>
<li>Version 0.56<br>
Revised 03/10/2005 by Chris Gonnerman
<ul>
<li>
added support for GIF files.
<li>
the minimum gd library version for this gdmodule version is 2.0.23.
</ul>
<li>Version 0.55<br>
Revised 03/10/2005 by Chris Gonnerman
<ul>
<li>
corrected error in the gd.image() constructor, pointed out
by Betty Li.
<li>
corrected yet another obvious error reported by Greg Hewgill,
regarding an incorrect call to gdImagePolygon when fillcolor
is not equal to 1.
<li>
implemented the saveAlpha and alphaBlending features as
suggested by Christopher Stone.
<li>
fixed memory management issue regarding image deallocation
reported by Matti Jagula.
<li>
fixed memory management issue in image_filledpolygon
reported by Sadruddin Rejeb.
<li>
the minimum gd library version for this gdmodule version is 2.0.22.
</ul>
<li>Version 0.54<br>
Revised 03/03/2005 by Chris Gonnerman
<ul>
<li>
this version has been withdrawn and replaced with 0.55, above.
</ul>
<li>Version 0.53<br>
Revised 06/10/2004 by Chris Gonnerman
<ul>
<li>
corrected obvious error in image_settile(), as pointed out by Dan Mosedale.
<li>
applied some patches provided by John Hunter. Several are for Windows compatibility,
but this should be considered a "work in progress" in this version.
<li>
corrected another obvious error (and an ancient one too) reported by Greg Hewgill,
regarding the foreground color being used rather than the fill color in the image_polygon
function.
<li>
the minimum gd library version for this gdmodule version is 2.0.22.
</ul>
<li>Version 0.52<br>
Revised 02/03/2004 by Chris Gonnerman
<ul>
<li>
incorporated new functions from the matplotlib project (provided by
John Hunter)
<li>
corrected error in PyObject_HEAD_INIT() call noted by Stefan R
Kuzminski (thanks!)
</ul>
<li>Version 0.50<br>
Revised 09/13/2003 by Chris Gonnerman
<ul>
<li>
Documentation change: version 2.0.8 or higher of GD has been
required since version 0.41 of gdmodule.
<li>
The library search order has been changed; /usr/local/lib is now
the first in the search path. This is intended to support those
trying to build against newer versions of GD which might conflict
with an older version installed with the Linux or BSD distibution.
</ul>
<li>Version 0.42<br>
Revised 06/10/2003 by Chris Gonnerman
<ul>
<li>
implemented patch by Gregory P. Smith to support writing to
arbitrary objects, superceding the patch in 0.41 from
Andreas Rottman. gddemo.py contains Rottman's example
(which works with Smith's patched version) as well as an
example (by me) of reading an image from a URL. The
documentation was updated to reflect these changes.
</ul>
<li>Version 0.41<br>
Revised 05/29/2003 by Chris Gonnerman
<ul>
<li>
implemented big patch by Andreas Rottmann to support writing images
to memory via StringIO/CStringIO. Currently the only documentation is
an example in gddemo.py.
<li>
implemented patch by Bob Galloway to remove the "specialness" of
negative coordinates in the string_ttf/string_ft methods.
<li>
implemented patch by Nathan Robertson to enable MacOSX fink builds.
<li>
fixed bugs in the proxy class with regard to passing of _gd.image types.
</ul>
<li>Version 0.40<br>
Revised 09/18/2002 by Chris Gonnerman
<ul>
<li>updated to deal with incomplete library installs
</ul>
<li>Version 0.30<br>
Revised 06/12/2002 by Chris Gonnerman
<ul>
<li>initial conversion to two-tier design
</ul>
<li>Version 0.26<br>
Revised 12/10/2001 by Chris Gonnerman
<ul>
<li>made unicode optional via define Py_UNICODEOBJECT_H
</ul>
<li>Version 0.25<br>
Revised 09/15/2001 by Chris Gonnerman
<ul>
<li>implemented patch by Mike Romberg:
<ul>
<li>adds additional image methods, available
only if GD 2.0.1+ is installed.
</ul>
</ul>
<li>Version 0.24<br>
Revised 08/08/2001 by Chris Gonnerman
<ul>
<li>implemented patch by Mike Romberg:
<ul>
<li>supports GCC 3.0 and GD 2.0.1
<li>adds public C function makeGDImage()
<ul>
<li>It allows C or C++ code which uses the gd library
directly to make an imageobject instance.
</ul>
</ul>
</ul>
<li>Version 0.23<br>
Revised 11/22/2000 by Chris Gonnerman
<ul>
<li>included the patch from Tanimoto Osamu<br>
<li>updated support to GD version 1.8.3<br>
<li>cleaned up code, added ANSI prototypes
</ul>
</ul>
</body>
</html>