GIMP Scripting: Difference between revisions

From Elvanör's Technical Wiki
Jump to navigation Jump to search
(New page: == Basics == * Scripting the GIMP can be done easily using the Python API. You can write pure Python scripts, and you don't need to use Scheme at all. * In order to make your Python scri...)
 
Line 2: Line 2:


* Scripting the GIMP can be done easily using the Python API. You can write pure Python scripts, and you don't need to use Scheme at all.
* Scripting the GIMP can be done easily using the Python API. You can write pure Python scripts, and you don't need to use Scheme at all.
* The Python API actually wraps the PDB. The PDB code is written in C so is fast. You can use PDB calls in your Python code, or use the object oriented API. The only advantage in using the OO API is cleaner code - no performance gain there, since the Python API wraps PDB anyway.


* In order to make your Python script accessible from within the GIMP, you need to save it in ~/.gimp-2.4/plug-ins/. You need to make it executable or GIMP won't recognize it.
* In order to make your Python script accessible from within the GIMP, you need to save it in ~/.gimp-2.4/plug-ins/. You need to make it executable or GIMP won't recognize it.

Revision as of 13:44, 25 April 2008

Basics

  • Scripting the GIMP can be done easily using the Python API. You can write pure Python scripts, and you don't need to use Scheme at all.
  • The Python API actually wraps the PDB. The PDB code is written in C so is fast. You can use PDB calls in your Python code, or use the object oriented API. The only advantage in using the OO API is cleaner code - no performance gain there, since the Python API wraps PDB anyway.
  • In order to make your Python script accessible from within the GIMP, you need to save it in ~/.gimp-2.4/plug-ins/. You need to make it executable or GIMP won't recognize it.
  • In your script, you need to have the register() function and a main() function which can be empty, in addition to your actual function which executes what you want. Here are the arguments for the register function (with an example):
    • "generate_rounded_corners": Name of the plugin (how to call it programmatically with Script-Fu)
    • "This is a test Python plugin." : Textual description
    • "It creates and saves an image.": Other description (extended, not sure here)
    • "Elvanör": Author
    • "Jean-Noël Rivasseau": Copyright owner
    • "2007": Date
    • "_Rounded Corners...": Name of the plugin (in the GIMP menus)
    • "RGB*, GRAY*": Modes accepted (??)
    • []: Arguments to this plugin
    • []: Return values of this plugin, only useful in non interactive mode
    • generateRoundedCorners: Python callback function (essential!)
    • menu="<Image>/Filters/Render/Rounder Corners": Path in the menus
  • In the previous list, the arguments list has the following syntax:
    • PF_STRING: type of argument
    • "targetDirectory": argument name
    • "The directory in which will be saved the images": description
    • "/srv/": Default value. This is used *only* in the interface, eg. when using the plugin non interactively you must always pass the correct number of arguments.
  • The _() function that you can see used in example plug-ins is for internationalization. The "_R" in "_Rounded Corners..." is for the mnemonic, eg the key that will be associated as a shortcut in the interface.

Writing and Debugging Python Scripts

  • You can make your image appear on the GUI with the following command:
display = pdb.gimp_display_new(image)
  • A recommended way to debug your scripts is to run each command separately in the Python console. You can also exit from a Python script by using the return() statement.
  • A primitive way to get basic information displayed by your scripts is to use the gimp_message function, which will display a string on the GIMP's GUI.
  • Fore more advanced debugging, writing to a log file (from within Python) is mandatory.

Python API / Bindings

  • For operations on a layer, you must add the layer to the image first. Else you will get an execution error.
  • In the PDB, some functions like pdb.gimp_text_fontname allows to specify -1 as a DRAWABLE argument (to create a new layer). Using the Python API this does not work, and should be replaced with None.

Selections

  • Don't forget that selection operations must specify an operation mode (CHANNEL_OP_ADD CHANNEL_OP_REPLACE...).

Help

  • You can obtain built-in documentation about the API by using dir (gimp) in the Python Gimp shell. You should import gimpfu first.
  • Another way is to use help() on a defined variable, for example a layer.

List of types in Python

  • PF_INT8 = PDB_INT8
  • PF_INT16 = PDB_INT16
  • PF_INT32 = PDB_INT32
  • PF_INT = PF_INT32
  • PF_FLOAT = PDB_FLOAT
  • PF_STRING = PDB_STRING
  • PF_VALUE = PF_STRING
  • PF_COLOR = PDB_COLOR
  • PF_COLOUR = PF_COLOR
  • PF_REGION = PDB_REGION
  • PF_DISPLAY = PDB_DISPLAY
  • PF_IMAGE = PDB_IMAGE
  • PF_LAYER = PDB_LAYER
  • PF_CHANNEL = PDB_CHANNEL
  • PF_DRAWABLE = PDB_DRAWABLE
  • PF_VECTORS = PDB_VECTORS
  • PF_TOGGLE = 1000
  • PF_BOOL = PF_TOGGLE
  • PF_SLIDER = 1001
  • PF_SPINNER = 1002
  • PF_ADJUSTMENT = PF_SPINNER
  • PF_FONT = 1003
  • PF_FILE = 1004
  • PF_BRUSH = 1005
  • PF_PATTERN = 1006
  • PF_GRADIENT = 1007
  • PF_RADIO = 1008
  • PF_TEXT = 1009
  • PF_PALETTE = 1010
  • PF_FILENAME = 1011
  • PF_DIRNAME = 1012

Obsolete:

  • #PF_INT8ARRAY = PDB_INT8ARRAY
  • #PF_INT16ARRAY = PDB_INT16ARRAY
  • #PF_INT32ARRAY = PDB_INT32ARRAY
  • #PF_INTARRAY = PF_INT32ARRAY
  • #PF_FLOATARRAY = PDB_FLOATARRAY
  • #PF_STRINGARRAY = PDB_STRINGARRAY
  • #PF_SELECTION = PDB_SELECTION
  • #PF_BOUNDARY = PDB_BOUNDARY
  • #PF_PATH = PDB_PATH
  • #PF_STATUS = PDB_STATUS
  • Note that you cannot currently pass an array to a Python Gimp script, since PF_STRINGARRAY has been removed (see this bug for reference). One workaround is to pass a string with special separators (like slashes), and split it into an array inside the Python code.

Launching GIMP from outside

  • When loading GIMP with gimp-console for example, it will load an interpreter (the default is the Script-Fu one - but you can change that to the Python one if you want). This interpreter will then execute commands given to it (via the -b command line option for example).
  • If you call Gimp from Java (via an external process), don't surround the Script-fu commands with single quotes. These are only needed if you launch Gimp from the shell, so that Gimp knows it's a string. If you use them in Java, it won't work since you will pass a string to script-fu rather than a command (Bash did not act the same way).
  • You can change the base directory of Gimp (for settings, tile cache, plugins etc) by setting the environment variable GIMP2_DIRECTORY. This is very useful as it allows you to run Gimp when the user does not have a home directory (for example the Tomcat user). In Java there is an convenient way to set the environment variables for running a native process.