1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
5
>Gimp Python Documentation</TITLE
8
CONTENT="Modular DocBook HTML Stylesheet Version 1.77+"></HEAD
25
>Gimp Python Documentation</H1
38
> <TT
41
HREF="mailto:james@daa.com.au"
45
</P
50
>v0.4, 5 July 1999<BR></P
60
>This document outlines the interfaces to Gimp-Python,
61
which is a set of Python modules that act as a wrapper to
65
> allowing the writing of
66
plug-ins for Gimp. In this way, Gimp-Python is similar to
67
Script-Fu, except that you can use the full set of Python
68
extension modules from the plug-in.</P
102
HREF="#STRUCTURE-OF-PLUGIN"
103
>The Structure Of A Plugin</A
109
HREF="#EXAMPLE-PLUGIN"
110
>An Example Plugin</A
114
HREF="#IMPORTANT-MODULES"
119
HREF="#PLUGIN-FRAMEWORK"
126
HREF="#PROCEDURAL-DATABASE"
127
>The Procedural Database</A
133
HREF="#GIMP-PYTHON-MODEL"
134
>The Gimp-Python Model</A
138
HREF="#PDB-PROCEDURES"
139
>Procedural Database Procedures</A
143
HREF="#MORE-INFORMATION"
150
HREF="#GIMP-MODULE-PROCEDURES"
151
>Gimp Module Procedures</A
157
HREF="#CONSTRUCTORS-AND-DESTRUCTORS"
158
>Constructors and Object Deletion</A
162
HREF="#CONFIGURATION-INFORMATION"
163
>Configuration Information</A
167
HREF="#PALETTE-OPERATIONS"
168
>Palette Operations</A
172
HREF="#GRADIENT-OPERATIONS"
173
>Gradient Operations</A
177
HREF="#PDB-REGISTRATION-FUNCTIONS"
178
>PDB Registration Functions</A
182
HREF="#OTHER-FUNCTIONS"
208
HREF="#IMAGE-OBJECT-MEMBERS"
213
HREF="#IMAGE-OBJECT-METHODS"
220
HREF="#CHANNEL-OBJECT"
227
HREF="#CHANNEL-OBJECT-MEMBERS"
232
HREF="#CHANNEL-OBJECT-METHODS"
246
HREF="#LAYER-OBJECT-MEMBERS"
251
HREF="#LAYER-OBJECT-METHODS"
258
HREF="#DRAWABLE-OBJECT"
265
HREF="#DRAWABLE-OBJECT-MEMBERS"
270
HREF="#DRAWABLE-OBJECT-METHODS"
284
HREF="#TILE-OBJECT-MEMBERS"
289
HREF="#TILE-OBJECT-METHODS"
294
HREF="#TILE-OBJECT-MAPPING"
295
>Tile Mapping Behaviour</A
301
HREF="#PREGION-OBJECT"
308
HREF="#PREGION-OBJECT-MEMBERS"
309
>Pixel Region Members</A
313
HREF="#PREGION-OBJECT-METHODS"
314
>Pixel Region Methods</A
318
HREF="#PREGION-OBJECT-MAPPING"
319
>Pixel Region Mapping Behaviour</A
327
HREF="#SUPPORT-MODULES"
334
HREF="#GIMPENUMS-MODULE"
335
>The gimpenums Module</A
340
>The gimpfu Module</A
344
HREF="#GIMPPLUGIN-MODULE"
345
>The gimpplugin Module</A
349
HREF="#GIMPSHELF-MODULE"
350
>The gimpshelf Module</A
376
>1.1. What is it?</H3
378
>Gimp-Python is a scripting extension for Gimp, similar to
379
Script-Fu. The main difference is in what is called first. In
380
Script-Fu, the script-fu plugin executes the script, while in
381
Gimp-Python the script is in control.</P
383
>In fact, you will find that the Gimp-Python scripts start
386
>#!/usr/bin/python</TT
388
gimp extension is loaded with the familiar
394
>Another point of difference between Gimp-Python and
395
Script-Fu is that Gimp-Python stores images, layers, channels
396
and other types as objects rather than just storing their ID.
397
This allows better type checking that is missing from Script-Fu,
398
and allows those types to act as objects, complete with
399
attributes and methods.</P
401
>Also, Gimp-Python is not limited to just calling
402
procedures from the PDB. It also implements the rest of
406
>, including tiles and pixel regions,
407
and access to other lower level functions.</P
416
>1.2. Installation</H3
418
>Gimp-python consists of a Python module written in C and
419
some native python support modules. You can build pygimp with
422
CLASS="PROGRAMLISTING"
427
>This will build and install gimpmodule and its supporting
428
modules, and install the sample plugins in gimp's plugin
437
NAME="STRUCTURE-OF-PLUGIN"
439
>2. The Structure Of A Plugin</H2
441
>The majority of code in this package resides in
445
>, but this provides a poor
446
interface for implementing some portions of a plugin. For this
447
reason, there is a python module called
451
> that sets out a structure for
452
plugins and implements some things that were either too dificult
453
or impossible to do in C.</P
455
>The main purpose of <TT
459
implement an object oriented structure for plug-ins. As well as
460
this, it handles tracebacks, which are otherwise ignored by
464
>, and gives a method to call
465
other Gimp-Python plug-ins without going through the procedural
472
NAME="EXAMPLE-PLUGIN"
474
>2.1. An Example Plugin</H3
476
>As in a lot of manuals, the first thing you examine is an
477
example, so here is an example. I have included it before
478
explaining what it does to allow more advanced programmers to
479
see the structure up front. It is a translation of the clothify
480
Script-Fu extension:</P
488
>Example 1. A sample python plugin</B
491
CLASS="PROGRAMLISTING"
496
have_gimp11 = gimp.major_version > 1 or \
497
gimp.major_version == 1 and gimp.minor_version >= 1
499
def python_clothify(timg, tdrawable, bx=9, by=9,
500
azimuth=135, elevation=45, depth=3):
501
bx = 9 ; by = 9 ; azimuth = 135 ; elevation = 45 ; depth = 3
502
width = tdrawable.width
503
height = tdrawable.height
504
img = gimp.image(width, height, RGB)
505
layer_one = gimp.layer(img, "X Dots", width, height, RGB_IMAGE,
509
pdb.gimp_edit_fill(layer_one)
511
pdb.gimp_edit_fill(img, layer_one)
512
img.add_layer(layer_one, 0)
513
pdb.plug_in_noisify(img, layer_one, 0, 0.7, 0.7, 0.7, 0.7)
514
layer_two = layer_one.copy()
515
layer_two.mode = MULTIPLY_MODE
516
layer_two.name = "Y Dots"
517
img.add_layer(layer_two, 0)
518
pdb.plug_in_gauss_rle(img, layer_one, bx, 1, 0)
519
pdb.plug_in_gauss_rle(img, layer_two, by, 0, 1)
521
bump_layer = img.active_layer
522
pdb.plug_in_c_astretch(img, bump_layer)
523
pdb.plug_in_noisify(img, bump_layer, 0, 0.2, 0.2, 0.2, 0.2)
524
pdb.plug_in_bump_map(img, tdrawable, bump_layer, azimuth,
525
elevation, depth, 0, 0, 0, 0, TRUE, FALSE, 0)
529
"python_fu_clothify",
530
"Make the specified layer look like it is printed on cloth",
531
"Make the specified layer look like it is printed on cloth",
535
"<Image>/Python-Fu/Alchemy/Clothify",
538
(PF_INT, "x_blur", "X Blur", 9),
539
(PF_INT, "y_blur", "Y Blur", 9),
540
(PF_INT, "azimuth", "Azimuth", 135),
541
(PF_INT, "elevation", "elevation", 45),
542
(PF_INT, "depth", "Depth", 3)
555
NAME="IMPORTANT-MODULES"
557
>2.2. Import Modules</H3
559
>In this plugin, a number of modules are imported. The
560
important ones are:</P
569
>: this module provides a
570
simple interface for writing plugins, similar to what
571
script-fu provides. It provides the GUI for entering in
572
parameters in interactive mode and performs some sanity
573
checks when registering the plugin.</P
575
>By using "from gimpfu import *", this module also
576
provides an easy way to get all the commonly used symbols
577
into the plugin's namespace.</P
584
>: the main part of the gimp
585
extension. This is imported with gimpfu.</P
592
>: a number of useful
593
constants. This is also automatically imported with
598
>The pdb variable is a variable for accessing the
599
procedural database. It is imported into the plugin's namespace
600
with gimpfu for convenience.</P
607
NAME="PLUGIN-FRAMEWORK"
609
>2.3. Plugin Framework</H3
611
>With pygimp-0.4, the gimpfu module was introduced. It
612
simplifies writing plugins a lot. It handles the run mode
613
(interactive, non interactive or run with last values),
614
providing a GUI for interactive mode and saving the last used
617
>Using the gimpfu plugin, all you need to do is write the
618
function that should be run, make a call to
622
>, and finally a call to
626
> to get the plugin started.</P
628
>If the plugin is to be run on an image, the first
629
parameter to the plugin function should be the image, and the
630
second should be the current drawable (do not worry about the
631
run_mode parameter). Plugins that do not act on an existing
632
image (and hence go in the toolbox's menus) do not need these
633
parameters. Any other parameters are specific to the
636
>After defining the plugin function, you need to call
640
> to register the plugin with gimp
641
(When the plugin is run to query it, this information is passed
642
to gimp. When it is run interactively, this information is used
643
to construct the GUI). The parameters to
702
>Most of these parameters are quite self explanatory. The
703
menupath option should start with <Image%gt;/ for image
704
plugins and <Toolbox>/ for toolbox plugins. The remainder
705
of the menupath is a slash separated path to its menu item.</P
707
>The params parameter holds a list parameters for the
708
function. It is a list of tuples. Note that you do not have to
709
specify the run_type, image or drawable parameters, as gimpfu
710
will add these automatically for you. The tuple format is
711
(type, name, description, default [, extra]). The allowed type
843
>These values map onto the standard PARAM_* constants. The
844
reason to use the extra constants is that they give gimpfu more
845
information, so it can produce a better interface (for instance,
846
the PF_FONT type is equivalent to PARAM_STRING, but in the GUI
847
you get a small button that will bring up a font selection
850
>The PF_SLIDER, PF_SPINNER and PF_ADJUSTMENT types require
851
the extra parameter. It is of the form (min, max, step), and
852
gives the limits for the spin button or slider.</P
854
>The results parameter is a list of 3-tuples of the form
855
(type, name, description). It defines the return values for the
856
function. If there is only a single return value, the plugin
857
function should return just that value. If there is more than
858
one, the plugin function should return a tuple of results.</P
860
>The final parameter to <TT
864
the plugin function itself.</P
866
>After registering one or more plugin functions, you must
870
> function. This will cause
871
the plugin to start running. A GUI will be displayed when
872
needed, and your plugin function will be called at the
873
appropriate times.</P
881
NAME="PROCEDURAL-DATABASE"
883
>3. The Procedural Database</H2
885
>The procedural database is a registry of things gimp and its
886
plugins can do. When you install a procedure for your plugin, you
887
are extending the procedural database.</P
889
>The procedural database is self documenting, in that when
890
you install a procedure in it, you also add documentation for it,
891
its parameters and return values.</P
897
NAME="GIMP-PYTHON-MODEL"
899
>3.1. The Gimp-Python Model</H3
901
>In Gimp-Python, the procedural database is represented by
908
plugins, I make an assignment from <TT
919
> for convenience.</P
921
>You can query the procedural database with
934
>pdb.query(name, [blurb, [help, [author, [copyright, [date, [type]]]]]])</PRE
936
>Each parameter is a regular expression that is checked
937
against the corresponding field in the procedural database. The
938
method returns a list of the names of matching procedures. If
942
> is called without any arguments, it will
943
return every procedure in the database.</P
950
NAME="PDB-PROCEDURES"
952
>3.2. Procedural Database Procedures</H3
954
>Procedures can be accessed as procedures, or by treating
960
> as a mapping objest. As an example,
965
accessed as either <TT
967
>pdb.gimp_edit_fill</TT
971
>pdb['gimp_edit_fill']</TT
972
>. The second form is
973
mainly for procedures whose names are not valid Python names (eg
974
in script-fu-..., the dashes are interpreted as minuses).</P
976
>These procedure objects have a number of attribute:</P
986
>The name of the procedure.</P
992
>A short peice of information about the procedure.</P
998
>More detailed information about the procedure.</P
1004
>The author of the procedure.</P
1010
>The copyright holder for the procedure (usually the
1011
same as the author).</P
1017
>The date when the procedure was written.</P
1023
>The type of procedure. This will be one of
1024
PROC_PLUG_IN, PROC_EXTENSION or PROC_TEMPORARY.</P
1030
>The number of parameters the procedure takes.</P
1036
>The number of return values the procedure gives.</P
1042
>A description of parameters of the procedure. It
1043
takes the form of a tuple of 3-tuples, where each 3-tuple
1044
describes a parameter. The items in the 3-tuple are a
1045
parameter type (one of the PARAM_* constants), a
1046
name for the parameter, and a description of the
1053
>A description of the return values. It takes the
1054
same form as the <TT
1063
>A procedure object may also be called. At this point,
1064
Gimp-Python doesn't support keyword arguments for PDB
1065
procedures. Arguments are passed to the procedure in the normal
1066
method. The return depends on the number of return values:</P
1072
>If there are zero return values,
1080
>If there is only a single return value, it is
1085
>If there are more return values, then they are
1086
returned as a tuple.</P
1095
NAME="MORE-INFORMATION"
1097
>3.3. More Information</H3
1099
>For more information on invoking PDB procedures, please
1100
see the example plugins. For information on individual
1101
procedures, please see the PDB Browser plugin (in the Xtns
1102
menu). It alows you to peruse to the database
1111
NAME="GIMP-MODULE-PROCEDURES"
1113
>4. Gimp Module Procedures</H2
1118
> module contains a number of
1119
procedures and functions, as well as the definitions of many gimp
1120
types such as images, and the procedural database. This section
1121
explains the base level procedures.</P
1127
NAME="CONSTRUCTORS-AND-DESTRUCTORS"
1129
>4.1. Constructors and Object Deletion</H3
1131
>There are a number of functions in the
1135
> module that are used to create the objects
1136
used to make up an image in Gimp. Here is a set of descriptions
1137
of these constructors:</P
1141
CLASS="VARIABLELIST"
1167
>This procedure creates an image with the given
1168
dimensions and type (type is one of
1227
>Create a new layer called
1233
>, with the given dimensions and
1247
> (float between 0 and 100) and
1255
> constants). The layer can
1256
then be added to the image with the
1303
>Create a new channel object with the given
1319
> constants). This channel can
1320
then be added to an image.</P
1334
>Create a new display window for the given image.
1335
The window will not be displayed until a call to
1338
>gimp.displays_flush</TT
1344
>gimp.parasite(name, flags, data)</TT
1348
>Create a new parasite. The parasite can then be
1349
attached to gimp, an image or a drawable. This is only
1350
available in gimp >= 1.1</P
1355
>When any of these objects get removed from memory (such as
1356
when their name goes out of range), the gimp thing it represents
1357
does not get deleted with it (otherwise when your plugin
1358
finished running, it would delete all its work). In order to
1359
delete the thing the Python object represents, you should use
1363
> procedure. It deletes the
1364
gimp thing associated with the Python object given as a
1365
parameter. If the object is not an image, layer, channel,
1366
drawable or display <TT
1377
NAME="CONFIGURATION-INFORMATION"
1379
>4.2. Configuration Information</H3
1381
>There are a number of functions that can be used to gather
1382
information about the environment the plugin is running in:</P
1386
CLASS="VARIABLELIST"
1391
>gimp.color_cube</TT
1395
>gimp.colour_cube</TT
1399
>Returns the current colour cube.</P
1408
>Returns the current gamma correction.</P
1413
>gimp.install_cmap</TT
1417
>Returns non-zero if a colour map has been
1427
>Returns non-zero if Gimp is using X shared
1437
>Returns the file name of the GTK configuration
1448
NAME="PALETTE-OPERATIONS"
1450
>4.3. Palette Operations</H3
1452
>These functions alter the currently selected foreground
1457
CLASS="VARIABLELIST"
1462
>gimp.get_background</TT
1466
>Returns a 3-tuple containing the current background
1467
colour in RGB form.</P
1472
>gimp.get_foreground</TT
1476
>Returns a 3-tuple containing the current foreground
1477
colour in RGB form.</P
1482
>gimp.set_background</TT
1502
>Sets the current background colour. The three
1503
arguments can be replaced by a single 3-tuple like that
1506
>gimp.get_background</TT
1512
>gimp.set_foreground</TT
1532
>Sets the current foreground colour. Like
1535
>gimp.set_background</TT
1536
>, the arguments may
1537
be replaced by a 3-tuple.</P
1547
NAME="GRADIENT-OPERATIONS"
1549
>4.4. Gradient Operations</H3
1551
>These functions perform operations on gradients:</P
1555
CLASS="VARIABLELIST"
1560
>gimp.gradients_get_active</TT
1564
>Returns the name of the active gradient.</P
1569
>gimp.gradients_set_active</TT
1578
>Sets the active gradient.</P
1583
>gimp.gradients_get_list</TT
1587
>Returns a list of the names of the available
1593
>gimp.gradients_sample_uniform</TT
1602
>Returns a list of <TT
1608
samples, where samples consist of 4-tuples of floats
1609
representing the red, green, blue and alpha values for the
1615
>gimp.gradients_sample_custom</TT
1627
>gimp.gradients_sample_uniform</TT
1629
the samples are taken at the positions given in the list
1635
> instead of uniformly
1636
through the gradient.</P
1646
NAME="PDB-REGISTRATION-FUNCTIONS"
1648
>4.5. PDB Registration Functions</H3
1650
>These functions either install procedures into the PDB or
1651
alert gimp to their special use (eg as file handlers).</P
1653
>For simple plugins, you will usually only need to use
1661
CLASS="VARIABLELIST"
1666
>gimp.install_procedure</TT
1733
>This procedure is used to install a procedure into
1734
the PDB. The first eight parameters are strings,
1744
> constants, and the last two
1745
parameters are sequences describing the parameters and
1746
return values. Their format is the same as the param and
1747
ret_vals methods or PDB procedures.</P
1752
>gimp.install_temp_proc</TT
1813
>This procedure is used to install a procedure into
1814
the PDB temporarily. That is, it must be added again
1815
every time gimp is run. This procedure will be called the
1816
same way as all other procedures for a plugin.</P
1821
>gimp.uninstall_temp_proc</TT
1830
>This removes a temporary procedure from the
1836
>gimp.register_magic_load_handle</TT
1863
>This procedure tells Gimp that the PDB procedure
1869
> can load files with
1881
> (eg http:) with magic
1892
>gimp.register_load_handler</TT
1913
>This procedure tells Gimp that the PDB procedure
1919
> can load files with
1936
>gimp.register_save_handler</TT
1957
>This procedure tells Gimp that the PDB procedure
1963
> can save files with
1985
NAME="OTHER-FUNCTIONS"
1987
>4.6. Other Functions</H3
1989
>These are the other functions in the
1997
CLASS="VARIABLELIST"
2029
>This function is the one that controls the execution
2030
of a Gimp-Python plugin. It is better to not use this
2031
directly but rather subclass the plugin class, defined in
2033
HREF="#GIMPPLUGIN-MODULE"
2046
>The procedural database object.</P
2051
>gimp.progress_init</TT
2060
>(Re)Initialise the progress meter with
2066
> (or the plugin name) as a
2067
label in the window.</P
2072
>gimp.progress_update</TT
2081
>Set the progress meter to
2092
>gimp.query_images</TT
2096
>Returns a list of all the image objects.</P
2105
>Stops execution imediately and exits.</P
2110
>gimp.displays_flush</TT
2114
>Update all the display windows.</P
2119
>gimp.tile_width</TT
2123
>The maximum width of a tile.</P
2128
>gimp.tile_height</TT
2132
>The maximum height of a tile.</P
2137
>gimp.tile_cache_size</TT
2146
>Set the size of the tile cache in kilobytes.</P
2151
>gimp.tile_cache_ntiles</TT
2160
>Set the size of the tile cache in tiles.</P
2174
>Get the information associated with
2180
>. The data will be a string.
2181
This function should probably be used through the <A
2182
HREF="#GIMPSHELF-MODULE"
2204
>Set the information in the string
2216
>. The data will persist for the
2217
whole gimp session. Rather than directly accessing this
2218
function, it is better to go through the <A
2219
HREF="#GIMPSHELF-MODULE"
2226
>gimp.extension_ack</TT
2230
>Tells gimp that the plugin has finished its work,
2231
while keeping the plugin connection open. This is used by
2232
an extension plugin to tell gimp it can continue, while
2233
leaving the plugin connection open. This is what the
2234
script-fu plugin does so that only one scheme interpretter
2240
>gimp.extension_process</TT
2249
>Makes the plugin check for messages from gimp.
2250
generally this is not needed, as messages are checked
2251
during most calls in the gimp module.</P
2265
>In gimp >= 1.1, it is possible to attach arbitrary data to
2266
an image through the use of parasites. Parasites are simply
2267
wrappers for the data, containing its name and some flags.
2268
Parasites have the following parameters:</P
2272
CLASS="VARIABLELIST"
2278
>The data for the parasite -- a string</P
2284
>The flags for the parasite</P
2290
>True if this parasite is persistent</P
2296
>True if this parasite is undoable</P
2302
>The name of the parasite</P
2307
>Parasites also have the methods <TT
2320
>There is a set of four functions that are used to
2321
manipulate parasites. They exist as functions in the
2325
> module, and methods for image and
2326
drawable objects. They are:</P
2330
CLASS="VARIABLELIST"
2344
>find a parasite by its name.</P
2349
>parasite_attach</TT
2358
>Attach a parasite to this object.</P
2363
>attach_new_parasite</TT
2382
>Create a new parasite and attach it.</P
2387
>parasite_detach</TT
2396
>Detach the named parasite</P
2409
>5. Gimp Objects</H2
2411
>Gimp-Python implements a number of special object types that
2412
represent the different types of parameters you can pass to a PDB
2413
procedure. Rather than just making these place holders, I have
2414
added a number of members and methods to them that allow a lot of
2415
configurability without directly calling PDB procedures.</P
2417
>There are also a couple of extra objects that allow low
2418
level manipulation of images. These are tile objects (working)
2419
and pixel regions (not quite finished).</P
2427
>5.1. Image Object</H3
2429
>This is the object that represents an open image. In this
2435
> represents a generic
2442
NAME="IMAGE-OBJECT-MEMBERS"
2444
>5.1.1. Image Members</H4
2450
CLASS="VARIABLELIST"
2466
>This is the active channel of the image. You can
2467
also assign to this member, or
2473
> if there is no active
2490
>This is the active layer of the image. You can
2491
also assign to this member, or
2497
> if there is no active
2514
>This is the type of the image (eg RGB, INDEXED).</P
2530
>This is a list of the channels of the image.
2531
Altering this list has no effect, and you can not assign
2548
>This is the colour map for the image.</P
2564
>This is the filename for the image. A file load
2565
or save handler might assign to this.</P
2581
>This is the height of the image. You can't assign
2593
>floating_selection</I
2598
>The floating selection layer, or
2604
> if there is no floating
2621
>This is a list of the layers of the image.</P
2637
>The selection mask for the image.</P
2653
>This is the width of the image. You can't assign
2664
NAME="IMAGE-OBJECT-METHODS"
2666
>5.1.2. Image Methods</H4
2672
CLASS="VARIABLELIST"
2806
>Unsets the dirty flag on the image.</P
2840
>Enables undo for <TT
2846
You might use these commands round a plugin, so that the
2847
plugin's actions can be undone in a single step.</P
2861
>Returns the resulting layer after merging all the
2862
visible layers, discarding non visible ones and
2863
stripping the alpha channel.</P
2873
>get_component_active</TT
2882
>Returns true if <TT
2902
>get_component_visible</TT
2911
>Returns true if <TT
2927
>set_component_active</TT
2942
>Sets the activeness of
2958
>set_component_visible</TT
2973
>Sets the visibility of
3037
>merge_visible_layers</TT
3046
>Merges the visible layers of
3052
> using the given merge
3063
>pick_correlate_layer</TT
3078
>Returns the layer that is visible at the point
3090
> if no layer matches.</P
3208
>remove_layer_mask</TT
3223
>Removes the mask from
3272
>Resizes the image to size <TT
3278
> and places the old contents at
3295
NAME="CHANNEL-OBJECT"
3297
>5.2. Channel Objects</H3
3299
>These objects represent a Gimp Image's colour channels.
3300
In this section, <TT
3306
to a generic channel object.</P
3312
NAME="CHANNEL-OBJECT-MEMBERS"
3314
>5.2.1. Channel Members</H4
3320
CLASS="VARIABLELIST"
3348
>The colour of the channel.</P
3364
>The height of the channel.</P
3380
>The width of the channel.</P
3396
>The image the channel belongs to, or
3402
> if it isn't attached
3419
>The channel's layer (??) or
3425
> if one doesn't exist.</P
3441
>Non zero if the channel is a layer mask.</P
3457
>The name of the channel.</P
3473
>The opacity of the channel.</P
3489
>The show_masked value of the channel.</P
3505
>Non-zero if the channel is visible.</P
3515
NAME="CHANNEL-OBJECT-METHODS"
3517
>5.2.2. Channel Methods</H4
3523
CLASS="VARIABLELIST"
3537
>returns a copy of the channel.</P
3550
>5.3. Layer Objects</H3
3552
>Layer objects represent the layers of a Gimp image. In
3553
this section I will refer to a generic layer called
3565
NAME="LAYER-OBJECT-MEMBERS"
3567
>5.3.1. Layer Members</H4
3573
CLASS="VARIABLELIST"
3589
>The apply mask setting. (non zero if the layer
3590
mask is being composited with the layer's alpha
3607
>The number of bytes per pixel.</P
3623
>The edit mask setting. (non zero if the mask is
3624
active, rather than the layer).</P
3640
>The height of the layer.</P
3656
>The image the layer is part of, or
3662
> if the layer isn't
3674
>is_floating_selection</I
3679
>Non zero if this layer is the image's floating
3696
>The layer's mask, or <TT
3702
if it doesn't have one.</P
3718
>The mode of the layer.</P
3734
>The name of the layer.</P
3750
>The opacity of the layer.</P
3761
>preserve_transparency</I
3766
>The layer's preserve transparency setting.</P
3776
NAME="LAYER-OBJECT-METHODS"
3778
>5.3.2. Layer Methods</H4
3784
CLASS="VARIABLELIST"
3798
>Adds an alpha component to the layer.</P
3817
>Creates a copy of the layer, optionally with an
3837
>Creates a layer mask of type
3879
>Resizes the layer to <TT
3885
>, positioning the original contents at
3922
>Scales the layer to <TT
3928
using the specified <TT
3959
>Sets the offset of the layer, relative to the
3985
>Moves the layer to <TT
3991
relative to its current position.</P
4002
NAME="DRAWABLE-OBJECT"
4004
>5.4. Drawable Objects</H3
4006
>Both layers and channels are drawables. Hence there are a
4007
number of operations that can be performed on both objects.
4008
They also have some common attributes and methods. In the
4009
description of these attributes, I will refer to a generic
4021
NAME="DRAWABLE-OBJECT-MEMBERS"
4023
>5.4.1. Drawable Members</H4
4029
CLASS="VARIABLELIST"
4045
>The number of bytes per pixel.</P
4085
>Non zero if the drawable is colour.</P
4113
>Non zero if the drawable is greyscale.</P
4129
>Non zero if the drawable has an alpha channel.</P
4145
>The height of the drawable.</P
4161
>The image the drawable belongs to.</P
4177
>Non zero if the drawable uses an indexed colour
4194
>The bounds of the drawable's selection.</P
4210
>The name of the drawable.</P
4226
>The offset of the top left hand corner of the
4243
>The type of the drawable.</P
4259
>Non zero if the drawable is visible.</P
4275
>The width of the drawable.</P
4285
NAME="DRAWABLE-OBJECT-METHODS"
4287
>5.4.2. Drawable Methods</H4
4293
CLASS="VARIABLELIST"
4312
>Fills the drawable with given
4336
>Flush the changes to the drawable.</P
4383
>Creates a pixel region for the drawable. It will
4384
cover the region with origin
4390
> and dimensions <TT
4402
argument sets whether any changes to the pixel region
4403
will be reflected in the drawable (default is TRUE).
4409
> argument sets whether
4410
the pixel region acts on the shadow tiles or not
4411
(default is FALSE). If you draw on the shadow tiles,
4422
for changes to take effect.</P
4459
>. Either on or off the
4495
>Get the tile that contains the pixel
4515
>Merge the shadow buffer back into the
4552
>Update the given portion of the drawable.</P
4565
>5.5. Tile Objects</H3
4567
>Tile objects represent the way Gimp stores information. A
4568
tile is basically just a 64x64 pixel region of the drawable.
4569
The reason Gimp breaks the image into small pieces like this is
4570
so that the whole image doesn't have to be loaded into memory in
4571
order to alter one part of it. This becomes important with
4574
>In Gimp-Python, you would use Tiles if you wanted to
4575
perform some low level operation on the image, instead of using
4576
procedures in the PDB. This type of object gives a Gimp-Python
4577
plugin the power of a C plugin, rather than just the power of a
4578
Script-Fu script. Tile objects are created with either the
4598
functions. In this section, I will refer to a generic tile
4610
NAME="TILE-OBJECT-MEMBERS"
4612
>5.5.1. Tile Members</H4
4614
>All tile members are read only.</P
4618
CLASS="VARIABLELIST"
4634
>The number of bytes per pixel.</P
4650
>If there have been changes to the tile since it
4651
was last flushed.</P
4667
>The drawable that the tile is from.</P
4683
>The actual height of the tile.</P
4699
>The actual width of the tile.</P
4715
>The reference count of the tile. (this is
4716
independent of the Python object reference
4733
>Non zero if the tile is part of the shadow
4744
NAME="TILE-OBJECT-METHODS"
4746
>5.5.2. Tile Methods</H4
4752
CLASS="VARIABLELIST"
4766
>Flush any changes in the tile. Note that the tile
4767
is automatically flushed when the Python object is
4768
deleted from memory.</P
4778
NAME="TILE-OBJECT-MAPPING"
4780
>5.5.3. Tile Mapping Behaviour</H4
4782
>Tile objects also act as a mapping, or sequence. You
4783
can access the pixels in the tile in one of two ways. You can
4784
either access them with a single number, which refers to its
4785
position in the tile
4795
refers to the first pixel in the second row of a 64x64 pixel
4796
tile). The other way is with a tuple, representing the
4797
coordinates on the tile
4807
refers to the first pixel on the second row of the
4810
>The type of these subscripts is a string of length
4822
When you assign to a subscript, the dirty flag is
4823
automatically set on the tile, so you don't have to explicitly
4824
set the flag, or flush the tile.</P
4832
NAME="PREGION-OBJECT"
4834
>5.6. Pixel Regions</H3
4836
>Pixel region objects give an interface for low level
4837
operations to act on large regions of an image, instead of on
4838
small 64x64 pixel tiles. In this section I will refer to a
4839
generic pixel region called <TT
4845
an example of a pixel region's use, please see the example
4855
NAME="PREGION-OBJECT-MEMBERS"
4857
>5.6.1. Pixel Region Members</H4
4863
CLASS="VARIABLELIST"
4879
>The drawable this pixel region is for.</P
4895
>The number of bytes per pixel for the drawable.</P
4911
>The rowstride for the pixel region.</P
4927
>The x coordinate of the top left hand corner.</P
4943
>The y coordinate of the top left hand corner.</P
4959
>The width of the pixel region.</P
4975
>The height of the pixel region.</P
4991
>Non zero if changes to the pixel region will be
4992
reflected in the drawable.</P
5008
>Non zero if the pixel region acts on the shadow
5009
tiles of the drawable.</P
5019
NAME="PREGION-OBJECT-METHODS"
5021
>5.6.2. Pixel Region Methods</H4
5027
CLASS="VARIABLELIST"
5063
>resize the pixel region so that it operates on the
5064
the region with corner <TT
5085
NAME="PREGION-OBJECT-MAPPING"
5087
>5.6.3. Pixel Region Mapping Behaviour</H4
5089
>The pixel region acts as a mapping. The index is a
5090
2-tuple with components that are either integers or slices.
5091
The subscripts may be read and assigned to. The type of the
5092
subscripts is a string containing the binary data of the
5093
requested region. Here is a description of the posible
5098
CLASS="VARIABLELIST"
5120
>Get/Set the pixel at
5153
>Get/Set the row starting at <TT
5192
>Get/Set the column starting at <TT
5236
>Get/Set the rectangle starting at <TT
5265
NAME="SUPPORT-MODULES"
5267
>6. Support Modules</H2
5269
>This section describes the modules that help make using the
5273
> module easier. These range from a set
5274
of constants to storing persistent data.</P
5280
NAME="GIMPENUMS-MODULE"
5282
>6.1. The gimpenums Module</H3
5284
>This module contains all the constants found in the header
5287
>libgimp/gimpenums.h</TT
5288
>, as well as some extra
5289
constants that are available in Script-Fu.</P
5298
>6.2. The gimpfu Module</H3
5300
>This module was fully described in an earlier section. It
5301
provides an easy interface for writing plugins, where you do not
5302
need to worry about run_modes, GUI's and saving previous values.
5303
It is the recommended module for writing plugins.</P
5310
NAME="GIMPPLUGIN-MODULE"
5312
>6.3. The gimpplugin Module</H3
5314
>This module provides the framework for writing Gimp
5315
plugins in Python. It gives more flexibility for writing
5316
plugins than the gimpfu module, but does not offer as many
5317
features (such as automatic GUI building).</P
5319
>To use this framework you subclass
5322
>gimpplugin.plugin</TT
5325
CLASS="PROGRAMLISTING"
5327
class myplugin(gimpplugin.plugin):
5329
# initialisation routines
5330
# called when gimp starts.
5333
# called when gimp exits (normally).
5335
# called to find what functionality the plugin provides.
5336
gimp.install_procedure("procname", ...)
5337
# note that this method name matches the first arg of
5338
# gimp.install_procedure
5339
def procname(self, arg1, ...):
5340
# do what ever this plugin should do</PRE
5347
NAME="GIMPSHELF-MODULE"
5349
>6.4. The gimpshelf Module</H3
5351
>This module gives a nicer interface to the persistent
5352
storage interface for Gimp plugins. Due to the complicated
5353
nature of Python objects (there is often a lot of connections
5354
between them), it can be dificult to work out what to store in
5355
gimp's persistent storage. The python interface only allows
5356
storage of strings, so this module wraps pickle and unpickle to
5357
allow persistentstorage of any python object.</P
5359
>Here is some examples of using this module:</P
5362
>>>> from gimpshelf import shelf
5363
>>> shelf['james'] = ['forty-two', (42, 42L, 42.0)]
5364
>>> shelf.has_key('james')
5366
>>> shelf['james']
5367
['forty-two', (42, 42L, 42.0)]</PRE
5369
>Anything you store with
5372
>gimpshelf.shelf</TT
5373
> will exist until Gimp
5374
exits. This makes this interface perfect for when a plugin is
5375
executed with the run mode
5378
>RUN_WITH_LAST_VALS</TT
5391
>This package is not yet complete, but it has enough in it to
5392
be useful for writing plugins for Gimp. If you write any plugins
5393
that might be useful as examples, please mail me at <A
5394
HREF="mailto:james@daa.com.au"
5396
>james@daa.com.au</A
b'\\ No newline at end of file'
added
removed
plug-ins/pygimp/doc/pygimp.html
