Gimp::Fu - "easy to use" framework for Gimp scripts
use Gimp; use Gimp::Fu;
Currently, there are only three functions in this module. This fully suffices to provide a professional interface and the ability to run this script from within GIMP and standalone from the command line.
Dov Grobgeld has written an excellent tutorial for Gimp-Perl. You can find it at http://www.gimp.org/tutorials/Basic_Perl/.
http://www.gimp.org/tutorials/Basic_Perl/
In general, a Gimp::Fu script looks like this:
#!/path/to/your/perl use Gimp; use Gimp::Fu; register <many arguments>, sub { your code; } exit main;
(This distribution comes with example scripts. One is examples/example-fu.pl, which is a small Gimp::Fu-script you can take as a starting point for your experiments)
examples/example-fu.pl
register "function_name", "blurb", "help", "author", "copyright", "date", "menu path", "image types", [ [PF_TYPE,name,desc,optional-default,optional-extra-args], [PF_TYPE,name,desc,optional-default,optional-extra-args], # etc... ], [ # like above, but for return values (optional) ], sub { code };
The PDB name of the function, i.e. the name under which it will be registered in the GIMP database. If it doesn't start with "perl_fu_", "file_", "plug_in_" or "extension_", it will be prepended. If you don't want this, prefix your function name with a single "+". The idea here is that every Gimp::Fu plug-in will be found under the common perl_fu_-prefix.
perl_fu_
A small description of this script/plug-in. Defaults to "=pod(NAME)" (see the section on EMBEDDED POD DOCUMENTATION for an explanation of this string).
A help text describing this script. Should be longer and more verbose than blurb. Default is "=pod(HELP)".
blurb
The name (and also the e-mail address if possible!) of the script-author. Default is "=pod(AUTHOR)".
The copyright designation for this script. Important! Save your intellectual rights! The default is "=pod(AUTHOR)".
The "last modified" date of this script. There is no strict syntax here, but I recommend ISO format (yyyymmdd or yyyy-mm-dd). Default value is "=pod(DATE)".
The menu entry GIMP should create. Note this is different from Script-Fu, which asks only for which menu in which to place the entry, using the second argument to (its equivalent of) register as the actual label; here, you spell out the full menu entry including label name.
register
It should start with one of the following:
If the plugin works on or produces an image.
If the "image types" argument (see below) is defined and non-zero-length, Gimp::Fu will supply a PF_IMAGE and PF_DRAWABLE as the first two parameters to the plugin.
PF_IMAGE
PF_DRAWABLE
If the plugin is intending to create an image rather than to work on an existing one, make sure you supply undef or "" as the "image types". In that case, Gimp::Fu will supply a PF_IMAGE return value if the first return value is not a PF_IMAGE.
undef
""
In any case, the plugin will be installed in the specified menu location; almost always under File/Create or Filters.
File/Create
Filters
If the script is an export-handler. Make sure you also have something like:
Gimp::on_query { Gimp->register_save_handler("file_filetype_save", "filetype", ""); };
This will place the plugin in a special section (as of GIMP 2.8) of the "Filters" menu. This type of plugin will also not have the image and drawable passed, nor will it require it.
If the script does not need to have a menu entry.
The types of images your script will accept. Examples are "RGB", "RGB*", "GRAY, RGB" etc... Most scripts will want to use "*", meaning "any type". Either undef or "" will mean "none".
An array reference containing parameter definitions. These are similar to the parameter definitions used for gimp_install_procedure but include an additional default value used when the caller doesn't supply one, and optional extra arguments describing some types like PF_SLIDER.
gimp_install_procedure
PF_SLIDER
Each array element has the form [type, name, description, default_value, extra_args].
[type, name, description, default_value, extra_args]
<Image>-type plugins get two additional parameters, image (PF_IMAGE) and drawable (PF_DRAWABLE) if and only if the "image types" are defined and non-zero-length. Do not specify these yourself - see the menupath entry above. Also, the run_mode argument is never given to the script but its value can be accessed in the package-global $Gimp::Fu::run_mode. The name is used in the dialog box as a hint. The description will be used as a tooltip.
menupath
run_mode
$Gimp::Fu::run_mode
See the section PARAMETER TYPES for the supported types.
The default values have an effect when called from a menu in GIMP, and when the script is called from the command line. However, they have a limited effect when called from Gimp::Net; data types that do not have an "invalid" value, like text does, may not be passed as an undefined value; this is because while Perl can use undef instead of anything, GIMP cannot. For instance, it is possible to pass a PF_STRING as undef, which will then be set to the supplied default value, but not a PF_COLOR.
PF_STRING
PF_COLOR
This is just like the parameter array except that it describes the return values. Specify the type and variable name only. This argument is optional. If you wish your plugin to return an image, you must specify that, e.g.:
use Gimp; use Gimp::Fu; register 'function_name', "help", "blurb", "author", "copyright", "2014-04-11", "<Image>/Filters/Render/Do Something...", "*", [ [PF_INT32, "input", "Input value", 1] ], [ [PF_IMAGE, "output image", "Output image"] ], sub { Gimp::Image->new($_[0], $_[0], RGB) };
If your "image types" is false, then Gimp::Fu will ensure your first return parameter is a PF_IMAGE.
This is either an anonymous sub declaration (sub { your code here; }, or a coderef, which is called when the script is run. Arguments (including the image and drawable for <Image> plug-ins) are supplied automatically.
sub { your code here; }
You must make sure your plugin returns the correct types of value, or none:
sub { # no return parameters were specified (); };
If you want to display images, you must have your script do that. Gimp::Fu plugins will thereby be good GIMP "citizens", able to fit in with plugins/filters written in other languages.
Gimp::Fu
All mapped to sliders or spinners with suitable min/max.
For PF_FLOAT (or PF_VALUE, a synonym), you should probably use a PF_ADJUSTMENT with suitable values.
PF_FLOAT
PF_VALUE
PF_ADJUSTMENT
A string.
Will accept a colour argument. In dialogs, a colour preview will be created which will open a colour selection box when clicked. The default value needs to be a suitable Gimp-Perl colour; see Gimp::canonicalize_colour.
[ PF_COLOR, 'colour', 'Input colour', 'white' ], [ PF_COLOR, 'colour2', 'Input colour 2', [ 255, 128, 0 ] ],
A gimp image.
A gimp drawable (channel or layer).
A boolean value (anything Perl would accept as true or false). The description will be used for the toggle-button label.
Uses a horizontal scale. To set the range and stepsize, append an array ref (see Gtk2::Adjustment for an explanation) [range_min, range_max, step_size, page_increment, page_size] as "extra argument" to the description array. Default values will be substitued for missing entries, like in:
[range_min, range_max, step_size, page_increment, page_size]
[PF_SLIDER, "alpha value", "the alpha value", 100, [0, 255, 1] ]
The same as PF_SLIDER, except that this one uses a spinbutton instead of a scale.
In addition to a default value, an extra argument describing the various options must be provided. That extra argument must be a reference to an array filled with Option-Name => Option-Value pairs. Gimp::Fu will then generate a horizontal frame with radio buttons, one for each alternative. For example:
Option-Name => Option-Value
[PF_RADIO, "direction", "direction to move to", 5, [Left => 5, Right => 7]]]
draws two buttons, when the first (the default, "Left") is activated, 5 will be returned. If the second is activated, 7 is returned.
Lets the user select a font whose name is returned as a string.
Lets the user select a brush/pattern/gradient whose name is returned as a string. The default brush/pattern/gradient-name can be preset.
PF_CUSTOM is for those of you requiring some non-standard-widget. You have to supply a code reference returning three values as the extra argument:
(widget, settor, gettor)
widget is Gtk widget that should be used.
widget
settor is a function that takes a single argument, the new value for the widget (the widget should be updated accordingly).
settor
gettor is a function that should return the current value of the widget.
gettor
While the values can be of any type (as long as it fits into a scalar), you should be prepared to get a string when the script is started from the command line or via the PDB.
This represents a file system object. It usually is a file, but can be anything (directory, link). It might not even exist at all.
Similar to PF_STRING, but the entry widget is much larger and has Load, Save, and Edit (in external editor) buttons.
The register functions expects strings (actually scalars) for documentation, and nobody wants to embed long parts of documentation into a string, cluttering the whole script.
Therefore, Gimp::Fu utilizes the Gimp::Pod module to display the full text of the pod sections that are embedded in your scripts (see perlpod for an explanation of the POD documentation format) when the user hits the "Help" button in the dialog box.
Since version 1.094, you can embed specific sections or the full pod text into any of the blurb, help, author, copyright and date arguments to the register functions. Gimp::Fu will look into all these strings for sequences of the form "=pod(section-name)". If found, they will be replaced by the text of the corresponding section from the pod documentation. If the named section is not found (or is empty, as in "=pod()"), the full pod documentation is embedded.
Most of the mentioned arguments have default values (see THE REGISTER FUNCTION) that are used when the arguments are undefined, making the register call itself much shorter.
save_image(img,options_and_path)
This is the internal function used to save images. As it does more than just gimp_file_save, I thought it would be handy in other circumstances as well.
The img is the image you want to save (which might get changed during the operation!), options_and_path denotes the filename and optional options. If there are no options, save_image tries to deduce the filetype from the extension. The syntax for options is
img
options_and_path
save_image
[IMAGETYPE[OPTIONS...]:]filespec
IMAGETYPE is one of GIF, JPG, JPEG, PNM or PNG, options include
options valid for all images +F flatten the image (default depends on the image) -F do not flatten the image options for GIF and PNG images +I do save as interlaced -I do not save as interlaced (default) options for GIF animations (use with -F) +L save as looping animation -L save as non-looping animation (default) -Dn default frame delay (default is 0) -Pn frame disposal method: 0=don't care, 1 = combine, 2 = replace options for PNG images -Cn use compression level n -E Do not skip ancillary chunks (default) +E Skip ancillary chunks options for JPEG images -Qn use quality "n" to save file (JPEG only) -S do not smooth (default) +S smooth before saving
some examples:
test.jpg save the image as a simple jpeg JPG:test.jpg the same JPG-Q70:test.jpg the same but force a quality of 70 GIF-I-F:test.jpg save a gif image(!) named test.jpg non-interlaced and without flattening
Marc Lehmann <pcg@goof.com>
perl(1), Gimp.
To install Gimp, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Gimp
CPAN shell
perl -MCPAN -e shell install Gimp
For more information on module installation, please visit the detailed CPAN module installation guide.