A Tutorial for Gimp-Perl Users
Updated for Gimp 2.8 / Gimp-Perl 2.3
© Ed J
Last modified: 2014-05-02

Table of contents

1. Version notes

This work is a slightly modified version of Dov Grobgeld's excellent tutorial. It has been updated to Gimp-Perl 2.3 and GIMP 2.8.

2. Background

One of the wonderful features of GIMP is that it all its functionality may be accessed through scripting. Available scripting environments include Scheme through Script-Fu and Python.

Perl has CPAN, giving access to vast numbers of modules to get things done. Now, GIMP may also be scripted in Perl. This tutorial will describe how to write such plug-ins and scripts for Gimp.

As there are several excellent tutorial texts describing the perl language, this tutorial will assume a working knowledge of Perl, and will instead concentrate on the use of GIMP together with the perl modules Gimp and Gimp::Fu.

3. What you need

The tutorial scripts have been tested on Linux (a Windows version is in the works) with the following versions:

  1. Gimp version 2.8.10.
  2. Perl version 5.14 or later.
  3. The perl module Gtk2, version 1.249, available from http://gtk2-perl.sourceforge.net
  4. The Gimp-Perl module, version 2.3 or later, available from http://search.cpan.org/dist/Gimp/

Perl and all its associated modules are available in source form from the Comprehensive Perl Archive network, CPAN.

4. The Gimp module

Most scripts make use of the simplified interface Gimp::Fu provided with the Gimp module. Gimp::Fu provides a framework for entering parameters to the script in a dialog-box interface, just like Script-Fu, but also allows running of the script in batch mode from the command line. This tutorial will go into detailed descriptions of the construction of a Gimp::Fu script, but before we do this, here is the general framework of such a script.

basic
  1:  #!/usr/bin/perl -w 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister {
  7:    # code...
  8:  }; 
  9:   
 10:  exit main; 
 11:  __END__ 
 12:   
 13:  =head1 NAME 
 14:   
 15:  test_exception - exercise gimp-perl filter testing exceptions 
 16:   
 17:  =head1 SYNOPSIS 
 18:   
 19:  <Image>/Filters/Languages/_Perl/_Test/Exception 
 20:   
 21:  =head1 DESCRIPTION 
 22:   
 23:  Exercise Gimp-Perl exceptions. 
 24:   
 25:  =head1 AUTHOR 
 26:   
 27:  The Author. 
 28:   
 29:  =head1 DATE 
 30:   
 31:  20140310 
 33:   
 34:  =head1 LICENSE 
 35:   
 36:  The licensing terms. 

The key points to note in the script are:

  • the use of the two modules Gimp and Gimp::Fu,
  • the podregister function, which will be described in detail below,
  • the way the control is handed over to Gimp module on line 8, and
  • the POD documentation below the __END__ line.

5. The GIMP PDB

Before going into the details of the Gimp::Fu script, we will describe how to access the functionality of GIMP. All functions known to GIMP are available through the procedural database (PDB). All the PDB functions may be called from perl, as will be seen below. These PDB functions are either internal to GIMP, or have been made available through a plug-in or a script extension, but as far as the caller is concerned there is no difference. As we will see below, when a perl function is registered through the podregister function, it will appear in the PDB as well.

Gimp comes with a PDB browser available in Help/Procedure Browser. This browser provides a way of seeing all the functions in the PDB, as well as their input and output parameters. E.g. the DB Browser entry for plug-in-gauss-iir, which will be used in the example below looks like this:

Name:plug-in-gauss-iir
Blurb:Apply a gaussian blur
In:INT32run-modeThe run mode { RUN-INTERACTIVE (0), RUN-NONINTERACTIVE (1) }
IMAGEimageInput image (unused)
DRAWABLEdrawableInput drawable
FLOATradiusRadius of gaussian blur (in pixels, > 0.0)
INT32horizontalBlur in horizontal direction
INT32verticalBlur in vertical direction
Help:Applies a gaussian blur to the drawable, with specified radius of affect. The standard deviation of the normal distribution used to modify pixel values is calculated based on the supplied radius. Horizontal and vertical blurring can be independently invoked by specifying only one to run. The IIR gaussian blurring works best for large radius values and for images which are not computer-generated.

All the the constants mentioned in the PDB Explorer have been defined within Gimp::Fu and may be used within perl. E.g. a call to blur an image looks as follows:

   Gimp::Plugin->gauss_iir($image, $drawable, 50, 6, 6);

Note that Perl is using underline characters where the DB browser uses hyphens! The PDB entry above shows that plug-in-gauss-iir is called with various parameters, of various types. These will be explained below.

You will also see that the first parameter, run-mode, was omitted. This is a feature of Gimp-Perl, which will automatically supply that parameter if you leave it off. This will make your code a lot tidier-looking.

Script-Fu scripts are called just like any other script according to the PDB signature in the PDB browser. E.g. to run the script-fu-basic1-logo just do:

script_fu_basic1_logo("Hello", 72,
                      "Utopia 72", 
                      [0,0,0],[255,255,255]);

5.1. Gimp::Fu and the podregister function

Gimp::Fu is Perl's answer to Script-Fu. It provides a simplified method for accepting parameters for a script through a Gtk2 interface, just like script-fu, but as we shall see below, it has some additional bells and whistles.

The main function for a Gimp-Fu script is the podregister function. This function declares the interface of the script to GIMP. The podregister function provides GIMP with the following information, from various sections of its POD (plain old documentation):

  1. The name of the function. It comes from the first part of the NAME section, before the dash. Tells GIMP the name by which the function will be known in the PDB.
  2. A small description, from the NAME section, after the dash.
  3. A help text, from the DESCRIPTION section.
  4. The author's name, from the AUTHOR section.
  5. The copyright of the script, from the LICENSE section.
  6. Creation date - any text, from the DATE section.
  7. Menu path - a string, from the SYNOPSIS section. The path can take these forms, though there are other options:
    1. "<Image>/Filters/Menu/Script Name"
    2. "<Toolbox>/Xtns/Perl/Script Name"
    If you specify "<Image>", then the script is expecting to operate on, or create, an image. In this case Gimp::Fu will add as the first two parameters to the script the image and the drawable active when the script was invoked. If, however, the "image types" is left as blank or not specified, the plugin is expected to create and therefore return an image (and it will normally be placed under the File/Create menu).

    If you specify "<Toolbox>", then the script is a standalone script that appears in the menu hierarchy under Filters (this is a historical thing) and takes all its inputs through the Gimp::Fu interface dialog.

  8. The acceptable image types, from the IMAGE TYPES section - a string. This list contains a list of image types acceptable. This field is only used for scripts that are in the "<Image>" hieararchy. Some possible values are listed in the table below:
    valuemeaning
    *Any images are accepted
    RGB RGB images
    RGBA RGB images with alpha channels
    GREY Grey level images
    (left empty or no such section) Does not take image as input, does return an image. Gimp::Fu will automatically add that return value.
  9. Parameters, from the PARAMETERS section. This will be Perl code, which Gimp::Fu evaluates as a list of parameters. Each parameter in turn is a reference to an array containing the following four or five values (A reference to an array in Perl is simply an array written within square brackets):
    1. The type of the parameter. The types recognized by Gimp::Fu and their Perl counterparts are given in the following table:
      TypePossible forms Comment
      PF_INT32
      PF_INT16
      PF_INT8
      42An integer.
      PF_FLOAT
      3.141A floating point number.
      PF_TOGGLE 0
      1
      A boolean value.
      PF_SLIDER
      PF_SPINNER
      An integer value through a slider and a spinner interface. The range parameter should be specified and is interpreted as minimum, maximum, and step, e.g. [0,100,1].
      PF_FONT"Arial"A font name.
      PF_STRING"A string"A string
      PF_COLOR
      PF_COLOUR
      [255,127,0]
      #ff7f00
      A color may either be expressed as a reference to an array of three components, or as a hexadecimal triple, proceeded by the hash sign.
      PF_TOGGLE0
      1
      A boolean toggle
      PF_IMAGE-An image
      PF_DRAWABLE-A drawable.
      PF_BRUSHA brush
      PF_GRADIENTA gradient
      PF_PATTERNA pattern
    2. The name of the parameter - a string.
    3. A help text for the parameter.
    4. Default value for the parameter. This should be given in the form listed in the table above.
    5. An array defining allowed range for the value. This is only used for PF_SLIDER and PF_SPINNER.

  10. Optionally, the return types of the function can be provided, from a RETURN VALUES section. This is specified in the same way as the Parameters above. There is no default or extra argument required.

  11. The perl code implementing the function - most commonly with a sub-reference, surrounded by "{" and "};", as below - thanks to Perl's prototyping, you don't need to specify "sub". This will be called when the associated menu entry declared through the Menu path described above. When the sub is called it is passed a list of parameters as declared in field 9. In the case of a "<Image>..." script, the active image and drawable (layer or channel) will be passed as first and second parameters. Thanks to the magic of Perl source filtering, you do not need to declare your variables but may simply use them:

        podregister {
          $drawable->gauss_iir($radius, $horizontal, $vertical);
        };
        # ...
        =head1 PARAMETERS
        
          [ PF_FLOAT, 'radius', "Radius", 50.0 ],
          [ PF_INT32, 'horizontal', 'Horizontal blur', 6 ],
          [ PF_INT32, 'vertical', 'Vertical blur', 6 ],

    You will also note that "plug_in_" has been omitted from the method call above, and that not all its parameters appear to be getting passed! This is thanks to the object-oriented implementation in Gimp-Perl, which when given a method name, searches various prefixes for the underlying function including the plug-in related ones (including script_fu_).

    The code will normally display a new image if it creates one, and also return the new image, in accordance with the return types declared in parameter 10 of the podregister call described above. This enables Gimp::Fu scripts to be used noninteractively by other scripts. More about that behaviour below.

5.2. podregister parameters

You will have noticed above that the parameters to the function given to podregister used parameters either named in the POD, or supplied by Gimp::Fu, such as $drawable. This is because podregister automatically makes available to your function all the variables declared either in the POD documentation (the "PARAMETERS" section) or added depending on your "image types".

5.3. A commented script

The following Gimp::Fu script example shows the steps described in the previous section. It registers a script that takes two values, the size of the image and a color, and then produces an image of the requested size with the requested color. Quite useless, but it shows the important steps of how to register a script, how to create a new image, and how to access some PDB functions.

uni
  1:  #!/usr/bin/perl -w 
  2:   
  3:  use strict; 
  4:  use Gimp; 
  5:  use Gimp::Fu; 
  6:   
  7:  podregister { 
  8:    # no need to have my ($size, $color) = @_; 
  9:    my $img = Gimp::Image->new($size, $size, RGB); # Create a new image 
 10:    # Create a new layer 
 11:    my $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100, NORMAL_MODE); 
 12:    $img->insert_layer($layer, -1, 0); # add the layer to the image 
 13:    Gimp::Context->set_background($color); # Set background to required color 
 14:    $layer->edit_fill(BACKGROUND_FILL); # Paint the layer  
 15:    Gimp::Display->new($img); 
 16:    return $img; # Return image - return implied by no IMAGE TYPES 
 17:  }; 
 18:   
 19:  exit main; 
 20:  __END__ 
 21:   
 22:  =head1 NAME 
 23:   
 24:  img_uni - Create a uniform image 
 25:   
 26:  =head1 SYNOPSIS 
 27:   
 28:  <Image>/File/Create/Tutorial/Img Uni 
 29:   
 30:  =head1 DESCRIPTION 
 31:   
 32:  A tutorial script. 
 33:   
 34:  =head1 PARAMETERS 
 35:   
 36:   [PF_INT32,   "size", "Img size", 100], 
 37:   [PF_COLOR, "color", "Img color", [255,127,0]] 
 38:   
 39:  =head1 AUTHOR 
 40:   
 41:  Dov Grobgeld 
 42:   
 43:  =head1 DATE 
 44:   
 45:  2004-03-27 
 46:   
 47:  =head1 LICENSE 
 48:   
 49:  Dov Grobgeld (c) 

Most of these commands are directly copied out the PDB.

This script shows the essential steps of producing a stand-alone script:

line(s)Description
7 Registration of the extension
9 Creating a new image.
11 Creating one or more layers.
12 Attaching the layer to the image.
13-14 Do some painting operations in the layers.
15 Display the new image
16 Return the image to the caller

To test the script, save it in the directory $HOME/.gimp-2.8/plug-ins. (A more official way to add scripts is to use the gimptool-2.0 --install-bin command). It must then be made executable through the command:

     chmod +x $HOME/.gimp-2.8/plug-ins/uni

Then start GIMP. It is generally a good idea to test the syntax of the script with perl -c before starting GIMP.

Note: Due to the way GIMP works, it is not possible to add scripts once GIMP is running. On the other hand, it is possible to change a script which has already been registered, as long as the parameters don't change.

The script is now accessible through the menu system through the File/Create/Tutorial top menu:

When choosing this menu entry the following screen is popped up:

Choosing the default values results in the image:

6. Object oriented syntax

Gimp-Perl provides an alternative object-oriented syntax for the image and the drawable commands. Here is a table showing the procedural vs the object oriented syntax for a few commands:

procedural syntax object oriented syntax
gimp_image_insert_layer($drw,0,0); $img->insert_layer($drw,0,0);
gimp_drawable_width($drw); $drw->width;

The substitution rule for converting a PDB into a method is as simple as erasing ``gimp_image_'' (or sometimes ``gimp_'') from the beginning of the function call and calling this method through the image object. Similarly for the gimp_drawable_... functions. See the Gimp-Perl docs for more detail.

Note that the object-oriented syntax appears to be only syntactic sugar that makes the calling syntax cleaner. The error messages are still given in the procedural format. What is going on is that GIMP, and the library on which it is implemented (Glib), use C in an object-oriented fashion.

7. Painting areas with selections

In the uni script the function gimp_edit_fill was called to fill the whole image. Looking at the info for gimp_edit_fill in the DB browser we find the following:

Name:gimp_edit_fill
Blurb:Fill selected area of drawable
In:DRAWABLEdrawableThe drawable to fill from
INT32fill_typeThe type of fill { FOREGROUND-FILL (0), BACKGROUND-FILL (1), WHITE-FILL (2), TRANSPARENT-FILL (3), PATTERN-FILL (4), NO-FILL (5) }
Help:This procedure fills the specified drawable with the fill mode. If the fill mode is foreground, the current foreground color is used. If the fill mode is background, the current background color is used. Other fill modes should not be used. This procedure only affects regions within a selection if there is a selection active. If you want to fill the whole drawable, regardless of the selection, use 'gimp-drawable-fill'.

Thus, if a selection is active when gimp_edit_fill is called, only the selected region of the drawable is painted. Note also that you must substitute "_" for "-" in the names.

There are lots of ways of choosing a selection as can be seen when searching for a ``select'' in the PDB. The example below uses gimp_image_select_rectangle, whose entry in the PDB looks as follows:

Name:gimp-image-select-rectangle
Blurb:Create a rectangular selection over the specified image
In:IMAGEimageThe image
INT32operationThe selection operation { CHANNEL-OP-ADD (0), CHANNEL-OP-SUBTRACT (1), CHANNEL-OP-REPLACE (2), CHANNEL-OP-INTERSECT (3) }
FLOATxx coordinate of upper-left corner of rectangle
FLOATyy coordinate of upper-left corner of rectangle
FLOATwidththe width of the rectangle: width >= 0
FLOATheightthe height of the rectangle: width >= 0
Help:This tool creates a rectangular selection over the specified image. The rectangular region can be either added to, subtracted from, or replace the contents of the previous selection mask. This procedure is affected by the following context setters: 'gimp-context-set-feather', 'gimp-context-set-feather-radius'.

A simple use of this function which selects a rectangle in the middle of an image and paints that rectangle with a user defined color. This example also introduces a couple of new features we haven't seen before:
  • The script is associated with an image since its menu path starts with "<Image>/...". Note that as a result of this the callback sub in line 6 receives two additional parameters, the active image and the selected drawable.
  • The use of the PDB functions gimp_image_undo_group_start and gimp_image_undo_group_end. These functions declare an undo group. When an undo is done on the image, instead of having the individual operators undo, all the actions between the undo start and the undo end calls will be undone at once.
paint-select
  1:  #!/usr/bin/perl -w 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister { 
  7:    my ($width, $height) = ($image->width, $image->height); 
  8:    # Select a rectangle inside the image and paint it with color 
  9:    $image->undo_group_start; 
 10:    $image->select_rectangle( 
 11:      CHANNEL_OP_REPLACE, $width/4, $height/4, $width/2, $height/2, 
 12:    ); 
 13:    Gimp::Context->set_background($color); 
 14:    $drawable->edit_fill(BACKGROUND_FILL); 
 15:    $image->selection_none; 
 16:    $image->undo_group_end; 
 17:    (); 
 18:  }; 
 19:   
 20:  exit main; 
 21:  __END__ 
 22:   
 23:  =head1 NAME 
 24:   
 25:  img_paint_select - Paints the selection 
 26:   
 27:  =head1 SYNOPSIS 
 28:   
 29:  <Image>/Filters/Tutorial/Paint Select 
 30:   
 31:  =head1 DESCRIPTION 
 32:   
 33:  Paints the selection 
 34:   
 35:  =head1 PARAMETERS 
 36:   
 37:   [PF_COLOR, "color", "Rectangle color", [0,0,255]], 
 38:   
 39:  =head1 RETURN VALUES 
 40:   
 41:  =head1 IMAGE TYPES 
 42:   
 43:  * 
 44:   
 45:  =head1 AUTHOR 
 46:   
 47:  Dov Grobgeld 
 48:   
 49:  =head1 DATE 
 50:   
 51:  1999-05-14 
 52:   
 53:  =head1 LICENSE 
 54:   
 55:  Dov Grobgeld 

The result when run on our previous image:

7.1. Complex selections

Besides rectangular selections elliptical selections may also be created through the PDB functions gimp_image_select_ellipse and gimp_image_select_polygon which allows the selection of ellipses and polygons.

More complex selections may be created through the channel mechanism. The PDB gimp_channel_new() (Gimp::Channel->new) creates a new channel. The channel is a drawable that may be painted into, just like any other drawable, but with the difference that it is always a grey level image. Once the channel is finished, the channel may be loaded into the selection through the PDB function gimp_image_select_item.

Search for ``select'' in the DB Browser to see a list of all the selection related functions.

7.2. Loops

In perl it is trivial to write loops that together with the various selection tools gives powerful creative possibilities. Here is an example that mixes colors in circles. There is nothing really new here, but it shows the power of what we have described above.

circles
  1:  #!/usr/bin/perl 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister { 
  7:    # Create the background 
  8:    my $img = Gimp::Image->new($size, $size, RGB); 
  9:    $layer = $img->layer_new($size, $size, RGB, "Layer 1", 100, NORMAL_MODE); 
 10:    $img->insert_layer($layer, -1, 0); 
 11:    Gimp::Context->set_background($bgcolor); 
 12:    $layer->edit_fill(BACKGROUND_FILL); 
 13:    my $ncircles = int($size/$radius/2); 
 14:    for ($i=0; $i<$ncircles; $i++) { 
 15:      for ($j=0; $j<$ncircles; $j++) { 
 16:        # Select a circle 
 17:        $img->select_ellipse( 
 18:  	CHANNEL_OP_REPLACE, $i*$radius*2, $j*$radius*2, $radius*2, $radius*2 
 19:        ); 
 20:        my $color = [$i*30, ($ncircles-$j)*25, ($i+$j)*15]; # mix colors 
 21:        Gimp::Context->set_background($color); 
 22:        $layer->edit_fill(BACKGROUND_FILL); 
 23:      } 
 24:    } 
 25:    Gimp::Display->new($img); 
 26:    return $img; 
 27:  }; 
 28:   
 29:  exit main; 
 30:  __END__ 
 31:   
 32:  =head1 NAME 
 33:   
 34:  circles - a loop 
 35:   
 36:  =head1 SYNOPSIS 
 37:   
 38:  <Image>/File/Create/Tutorial/Circles 
 39:   
 40:  =head1 DESCRIPTION 
 41:   
 42:  a loop 
 43:   
 44:  =head1 PARAMETERS 
 45:   
 46:   [PF_INT32, "size", "Image size", 100], 
 47:   [PF_COLOR, "bgcolor", "Background color", [40,180,60]], 
 48:   [PF_INT32, "radius", "Circle radius", 10] 
 49:   
 50:  =head1 AUTHOR 
 51:   
 52:  Dov 
 53:   
 54:  =head1 DATE 
 55:   
 56:  1999-05-14 
 57:   
 58:  =head1 LICENSE 
 59:   
 60:  Dov 

The result:

8. Creating text

8.1. Hello World - writing text in an image

To create text the PDB function gimp_text_fontname() may be used.

Here is an example of a script that creates an image containing "Hello world".

hello-world1
  1:  #!/usr/bin/perl 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister { 
  7:    my $img = Gimp::Image->new(350, 100, RGB); 
  8:    my $drw = $img->layer_new($img->width, $img->height, 
  9:  			RGB, "BG", 100, NORMAL_MODE); 
 10:    $img->insert_layer($drw, -1, 0); 
 11:    Gimp::Context->set_background("black"); 
 12:    $drw->edit_fill(BACKGROUND_FILL); 
 13:    Gimp::Context->set_foreground([255,255,0]); # Choose color of text 
 14:    # Create the text 
 15:    my $textlayer = $drw->text_fontname(0, 0, $text, 10, 1, $size, POINTS, $font); 
 16:    $textlayer->floating_sel_anchor; 
 17:    Gimp::Display->new($img); 
 18:    return $img; 
 19:  }; 
 20:   
 21:  exit main; 
 22:  __END__ 
 23:   
 24:  =head1 NAME 
 25:   
 26:  hello_world1 - basic text 
 27:   
 28:  =head1 SYNOPSIS 
 29:   
 30:  <Image>/File/Create/Tutorial/Basic text 1 
 31:   
 32:  =head1 DESCRIPTION 
 33:   
 34:  basic text 
 35:   
 36:  =head1 PARAMETERS 
 37:   
 38:   [PF_FONT, "font", "Font", "Sans"], 
 39:   [PF_INT32, "size", "Font size", 70], 
 40:   [PF_STRING, "text", "Text", "Hello world!"] 
 41:   
 42:  =head1 AUTHOR 
 43:   
 44:  Dov 
 45:   
 46:  =head1 DATE 
 47:   
 48:  2004-03-27 
 49:   
 50:  =head1 LICENSE 
 51:   
 52:  Dov 

The result:

One thing to note in this script is that the text that is created on line 15 is a floating layer, that needs to be anchored to its parent layer. This is done in line 16 through the call to gimp_floating_sel_anchor().

This script suffers from the problem that the image size is unrelated to the text size. This is taken care of in the following more complex example which shows the basic steps for a logo generating script:

  • Creation of an image of arbitrary size
  • Creation of a background drawable of an arbitrary size
  • Creation of text layer which exactly fits the text with the command gimp_text_fontname.
  • Resizing the image and the background to the size of the text layer.

The result is an image composed of two layers; a transparent text layer on top of a uniform background.

basic-logo
  1:  #!/usr/bin/perl 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister { 
  7:    my $img = Gimp::Image->new(100, 100, RGB); # any old size 
  8:    my $background = $img->layer_new( 
  9:      100, 100, RGB, "Background", 100, NORMAL_MODE 
 10:    ); 
 11:    $img->insert_layer($background, 0, 0); 
 12:    Gimp::Context->set_foreground($fgcolor); # Choose color of text 
 13:    # Create the text layer. Using -1 as the drawable creates a new layer. 
 14:    my $text_layer = $img->text_fontname( 
 15:      -1, 0, 0, $text, $border, 1, $size, POINTS, $font 
 16:    ); 
 17:    # Get size of the text drawable and resize the image and the 
 18:    # background layer to this size. 
 19:    my ($width, $height) = ($text_layer->width, $text_layer->height); 
 20:    $img->resize($width, $height, 0, 0); 
 21:    $background->resize($width, $height, 0, 0); 
 22:    # Fill the background layer now when it has the right size. 
 23:    Gimp::Context->set_background($bgcolor); 
 24:    $background->edit_fill(BACKGROUND_FILL); 
 25:    Gimp::Display->new($img); 
 26:    return $img; 
 27:  }; 
 28:   
 29:  exit main; 
 30:  __END__ 
 31:   
 32:  =head1 NAME 
 33:   
 34:  basic_logo - Basic logo 
 35:   
 36:  =head1 SYNOPSIS 
 37:   
 38:  <Image>/File/Create/Tutorial/Basic Logo 
 39:   
 40:  =head1 DESCRIPTION 
 41:   
 42:  Make a basic logo. 
 43:   
 44:  =head1 PARAMETERS 
 45:   
 46:   [PF_FONT, "font", "Font",   "Utopia Bold"], 
 47:   [PF_INT32, "size", "Font size", 10], 
 48:   [PF_INT32, "border", "Border", 10], 
 49:   [PF_STRING, "text", "Text", "Hello world!"], 
 50:   [PF_COLOR, "bgcolor", "Background color", [40,180,160]], 
 51:   [PF_COLOR, "fgcolor", "Foreground color", [255,255,0]], 
 52:   
 53:  =head1 AUTHOR 
 54:   
 55:  Dov Grobgeld 
 56:   
 57:  =head1 DATE 
 58:   
 59:  2004-03-27 
 60:   
 61:  =head1 LICENSE 
 62:   
 63:  Dov Grobgeld 

Note the special syntax of gimp_image_text_fontname in line 14 in basic-logo with the drawable = -1. The special case drawable=-1 means that instead of creating a floating layer, a new image layer will be created.

The dialog and the resulting image:

9. Floating selections

When a region has been selected through one of the selection routines, the area outlined by the selection may be copied to the cut-buffer through the gimp_edit_copy command. The cut-buffer may subsequently be pasted into a different layer through the gimp_edit_paste command. When a layer is pasted it becomes a floating selection. This floating selection may be moved to its required position by the command gimp_layer_set_offsets, and finally it is pasted by the gimp_floating_sel_anchor command. Another way of determining the position of a pasted layer is to create a selection in the target image before the cut-buffer is pasted.

This is illustrated in the following program, which works on one image and takes as a parameter another image, which it concatenates to the right of the first image. The lines 28-38 shows how the second image is copied and glued into the first image.

horiz-cat
  1:  #!/usr/bin/perl 
  2:   
  3:  use Gimp; 
  4:  use Gimp::Fu; 
  5:   
  6:  podregister { 
  7:    die "Must select layer.\n" unless $drawable->is_layer; 
  8:    $drawable->become('Gimp::Layer'); 
  9:    my $image2 = $drawable2->get_image; 
 10:    my ($w1, $h1) = ($drawable->width, $drawable->height); 
 11:    my ($w2, $h2) = ($drawable2->width, $drawable2->height); 
 12:    my $hmax = $h1 > $h2 ? $h1 : $h2; # new height is maximum height of the images 
 13:    $image->undo_group_start; # Create an undo group 
 14:    # Resize the drawable layer to make room for the image 
 15:    $image->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2); 
 16:    $drawable->resize($w1+$w2, $hmax, 0, ($hmax-$h1)/2); 
 17:    # Copy $drawable2 and paste it into the new space of $drawable1 
 18:    $image2->selection_all; # select all of image2 
 19:    $drawable2->edit_copy; 
 20:    $image2->selection_none; 
 21:    # make a selection in image 1 where $drawable2 is to be pasted 
 22:    $image->select_rectangle(CHANNEL_OP_ADD, $w1, ($hmax-$h2)/2, $w2, $h2); 
 23:    $drawable->edit_paste(0)->floating_sel_anchor; # paste and then anchor it 
 24:    $image->undo_group_end; # Close the undo group 
 25:    return; 
 26:  }; 
 27:   
 28:  exit main; 
 29:  __END__ 
 30:   
 31:  =head1 NAME 
 32:   
 33:  horiz_cat - Horizontal concat 
 34:   
 35:  =head1 SYNOPSIS 
 36:   
 37:  <Image>/Filters/Tutorial/Horizontal Concat 
 38:   
 39:  =head1 DESCRIPTION 
 40:   
 41:  Horizontal concatenation of images. 
 42:   
 43:  =head1 PARAMETERS 
 44:   
 45:   [PF_DRAWABLE,   "drawable2", "Drawable to concatenate", undef], 
 46:   
 47:  =head1 IMAGE TYPES 
 48:   
 49:  * 
 50:   
 51:  =head1 AUTHOR 
 52:   
 53:  Dov Grobgeld 
 54:   
 55:  =head1 DATE 
 56:   
 57:  2004-03-27 
 58:   
 59:  =head1 LICENSE 
 60:   
 61:  Dov Grobgeld 

You might notice something very important on lines 7 and 8: we "know" that we'll always pass a layer as the first drawable, but we're checking that anyway. Then we're telling Gimp-Perl the drawable definitely is a layer. The reason for that is that (obviously) Gimp::Layer and Gimp::Drawable have different methods available to them, and what matters here is that Gimp::Drawable does not have a resize method. (i.e. The PDB does not have a gimp_drawable_resize function)

10. The Perl Server and stand-alone scripts

So far the scripts have all been started from the menu structure within GIMP. But using Gimp::Fu there is another possibility, and that is to run the scripts from the command line, as a normal Perl program. When run this way the script tries to connect to the Perl-Server, and if it fails it will launch a GIMP of its own. If you plan to run several scripts this way, it is obviously much faster to run the Perl-Server since launching GIMP takes quite a bit of time. The Perl-Server may be started from the Filters/Perl menu.

When a Gimp::Fu script is run from the command line, the result is the same as when it is run through the menus, except that it may be run with the --output parameter. This will save the result to a file instead of displaying it within GIMP. This is great for batch creation of logos, etc.

The filename for the --output has some special magic that allows to set some special image saving parameters, like interlace, quality factor, etc. See the Gimp::Fu docs for more detail

Here are two invocations of the scripts declared above, but with output written to a jpg file and a png file.

perl-gimp-from-shell
  1:  uni -o /tmp/uni.png --size 100 --color purple 
  2:  basic-logo --font 'utopia 100' -o /tmp/bl.ppm --size 20 --text "Perl rules" 

Another important use of this interface is that it enables running the Perl debugger on the perl scripts.

10.1. A shell for Gimp-Perl

When using the Perl-Server it is not necessary to use Gimp::Fu and the podregister function. Instead you may call Gimp::on_net, which takes as a parameter a reference to a sub routine that is called when your script has connected to a GIMP (or started one up).

For a simple but powerful example of the use of the Gimp without Fu, here is a an interactive Gimp-Perl shell that may be run from the command line:

pg-shell
  1:  #!/usr/bin/perl 
  2:   
  3:  #  An interactive command line shell to GIMP. 
  4:  use Gimp; 
  5:  use Term::ReadLine; 
  6:   
  7:  Gimp::on_net { 
  8:      $term = new Term::ReadLine("Gimp"); 
  9:      while( defined ($_ = $term->readline("Gimp> "))) { 
 10:          $res = eval($_) . "\n"; 
 11:          print("Error: $@"), next if $@; 
 12:          print "\n"; 
 13:          Gimp->displays_flush(); 
 14:      } 
 15:  }; 
 16:   
 17:  exit Gimp::main; 

Here is an example of an interactive session with this shell:

interact
  1:  Gimp> $img = Gimp::Image->new(100,100,RGB) 
  2:  Gimp> $drw = $img->layer_new(100,100,RGB_IMAGE, "bg", 100, NORMAL_MODE) 
  3:  Gimp> $img->insert_layer($drw,-1, 0) 
  4:  Gimp> Gimp::Display->new($img) 
  5:  Gimp> $drw->edit_clear 
  6:  Gimp> print Gimp::Image->list 
  7:  Gimp::Image->existing(1) 

11. End notes

This tutorial has covered only a small part of the possibilities available to a script writer. In particular the following issues available to Gimp::Perl scripts have not been covered:

  • The possibility of writing customized Gtk interfaces (see examples/example-no-fu in the Gimp-Perl distribution).
  • Writing fully-fledged plug-ins that manipulate the tile data through the Perl Data Language (PDL) module (see examples/map_to_gradient in the Gimp-Perl distribution).
  • Using Gimp-Perl in a CGI environment.
  • How to fill with gradients in a plugin (see examples/randomblends in the Gimp-Perl distribution).
  • How to do polygon selections (see examples/triangle in the Gimp-Perl distribution).

The Gimp-Perl distribution also has over 50 more example scripts supplied. Take a look through those for further inspiration!

12. Links and references


Please send your comments to dov.grobgeld@gmail.com

Tutorial © 1999-2002 Dov Grobgeld dov@imagic.weizmann.ac.il