Python Fu #3: The Procedure Database

See the other tutorials in this series.

In the last two videos we looked at the basics of programming: what variables are, what functions are and how to pass variables into functions to change the output of the function. One of the things Python is great for is it’s range of extensive modules that extend the functionality of the language. We won’t look at how these modules are made or what’s in them in much detail, we just need to know how to refer to their functions. For example, in the console or shell we can:

>>>import math

Which allows us to access the Math module. We can use the math module to access some values and functions that make math easier.

Now that we have imported math we can use it to access the value of pi. To do this we use the name of the module, followed by a dot followed by the object we want to access in the module, in this case the variable pi.

>>>print math.pi
3.14159265359

We can use this to calculate the area of a circle for which we know the radius, using the formula pi (r)squared

>>>print math.pi * (5 * 5)
78.5398163397

So why do we need to know how to import modules? Well, all of the GIMP functionality we want access to from Python is stored in a group of modules collectively known as gimpfu.

To use these we write:

>>>from gimpfu import *

Which means it will import all of the relevant GIMP modules in one go for us to use in our script. Most Python programmers usually steer clear of a bulk import like this since they can cause issues you might not foresee, but most GIMP scripts use this format anyway, so we’ll stick with it.

So what does that give us access to? Well the easiest way to get a sense of what we can do now is to open up the Procedure Database. We can access the PDB two ways. If the Python console is open, we can press the browse button. Or we can find it in the regular GIMP menus under help, called the Procedure Browser. You may notice that opening it up from the Console is slightly different to opening it through the help menu. The title of the window changes. If we launch it from the Console it is called the ‘Python Procedure browser.’ This is actually the one we want to use for now, because it can give us some extra information that is helpful. More on that in a minute.

With that open we can see every function specific to GIMP that we can use in our scripts. There are roughly 1200 by default, and the more plug-ins you install, or write yourself, the more of these you will see. Finding the function you are after is easy with a little common-sense. Let’s say I want to find the function for desaturating an image. Simply type ‘desat’ in the search box and by default, two options will appear. You pick the one that is most suitable and you can use it in your script.

How do we use it? Well, we use the same dot notation we used for math.pi. If we opened up the Python Procedure Browser from the console, we can actually get the line of code we need very easily. Simply double click the procedure name and it will print a Pythonic version to the console. You will notice that it converts the dashes to underscores, which is the preffered way to write out function names in Python.

So if we double click gimp-desaturate-full, it will print the following in the console:

>>>pdb.gimp_desaturate_full(drawable, desaturate_mode)

If you remember from the last video, some functions have variables passed to them in parentheses. So the desaturation function has two variables it needs. We need to remember that if we use it in our script. We can look that up in the PDB for more information about the variables, most importantly, what TYPE of variable is expected. There is more help available online that can answer other questions we may have, but we’ll look at those once we start scripting real plug-ins for ourselves.

So that’s all we need from this video. The key things to remember are that Python uses modules to access some special variables and pre-made functions, and these are referenced in our scripts using dot notation. We also learned that we can launch the Procedure Database, otherwise known as the Procedure Browser, and if we do this from the Browse… button in the Python console, we can actually get correctly formatted Python functions to copy and paste.

In the next video we are going to look at an extremely simple example of a Python script.

Related posts: Python Fu GIMP tutorials

Python Fu #3: The Procedure Database