Chapter 2. The gluas environment

Gluas is a gimp plug-in providing a enviroment for testing algorithms for image processing. The environment contains a simple editor for entering the algorithms. It uses the lua interpreter.

Gluas can be downloaded from Gluas download page, to be able to use gluas properly you also need an installation of The GIMP.

Figure 2.1. Screenshot of gluas

Screenshot of gluas

Installing gluas

Windows

[Note]Note

Note that the author doesn't know the windows installation procedure in detail. Any contribution to clarify would be welcome.

System wide

The gluas installer on the website provides for a system wide installation of gluas, this is the easiest way to install gluas,

[Caution]Caution

If The GIMP has been installed in a location where the user does not have write privileges, you need to do a per user install.

Per user

Placing the gluas binary (not the installation package) in your users plug-in folder (the location of this folder was announced upon first running The GIMP.

In Linux, from source

Procedure 2.1. Installing gluas from source

  1. Preqrequisites

    You need The GIMP's developer files (headers), as well as an installed lua runtime, with development files (headers). In Debian™ the following packages, and their dependencies need to be installed:

    • liblua50
    • liblua50-dev
    • liblualib50
    • liblualib50-dev
    • gimp
    • libgimp2.0
    • libgimp2.0-dev

    For syntax highlighting libgtksourceview must be installed as well.

  2. Download

    The latest release of the gluas source can be found in the files subfolder of the gluas website. The latest version is the version with the highest version number, at the time of writing that was 0.1.19.

    At the commandline, entering:

    wget http://pippin.gimp.org/plug-ins/gluas/files/gluas-0.1.19.tar.gz

    should be sufficient to complete this step, although checking for a never version using a web browser is recommended.

  3. Extract

    tar xvzf gluas-0.1.19.tar.gz

    The characters after the command tar indicates what the tar applications should do, the meaning of the used characters are:

    x

    extract

    v

    verbose

    z

    ungzip (uncompress, replace this with j, for .tar.bz2 files)

    f

    the input to tar is a file (as opposed to data coming on standard input)

  4. Enter the gluas directory

    cd gluas-0.1.19
  5. Configure

    ./configure

    This will prepare compilation of the gluas plug-in for your specific system, if any components/packages that are needed are not found, the configure script will complain.

    [Tip]Tip

    Running configure takes a little while, prepare a cup of tea while it runs.

  6. Make

    make

    Compiling gluas should not take a long time, the binary produced can either be manually placed in the users private plug-in folder, or be installed systemwide.

    [Tip]Relax

    If you are following the previous tip, you can now drink your tea.

  7. Install

    We need to be the super user to install the application, thus we need to become root.

    su
    Password: joshua
    [Caution]Caution

    If you already are root, ask someone who knows why this is stupid.

    Now we issue the command to do the actual installation of our compiled program.

    make install

    The next time you start the Gimp, gluas should be available from the menu system at: FiltersGenericgluas.

Using gluas

The enviroment set up when processing starts, sets the global variables width and height, functions for setting and getting pixels are provided

The lua language

A programming tutorial for lua is out of scope for this document, the samples given elsewhere in this document should provide a feel for the language, some peculiarities of lua is explained here, look at The lua website, for a short overview when reading sample code Lua Short Reference might come in handy.

Multiple value return

Lua supports returning multiple values from a function, this is useful when dealing with color components. E.g a function can easily return a RGB or LAB triplet in one go.

Setting and getting pixel values

There are functions to set and get individual pixels, they are of the form:

v get_value( x,
  y);
set_value( x,
  y,
  v);

See the section called “Gluas reference” for more functions, and details.

All values used in gluas are floating point values, unless mandated by the color model, the normal range is from 0.0 to 1.0. This range is used instead of an more arbitary range like 0-255, 0-42, 0-100 or 0-65535.

Image dimensions

The width and height of the image in pixels can be accessed through global variables with those names.

Selection

The GIMP takes care of modifying only the portions that are part of the current selection, as well as blending old and new pixel values for partially selected pixels.

The coordinates of the boundingbox of the selection can be accessed through global variables, see bound_x0, bound_y0 and bound_x1, bound_y1.

Shadow buffer

When pixels are set, they don't immediatly overwrite the original pixel values. This is to facilitate area operations. When multipass algorithms are implemented, like a two pass blur, the changes can be comitted to the source buffer by issuing

Samples

Refer to Images Processing using gluas (which this gluas introduciton is a part of) for examples of how the gluas environment can be used.

A simple program

In the following sample the code needed for a simple thresholding filter is documented.

Figure 2.2. basic gluas program

basic gluas program
for y=0, height-1 do
  for x=0, width-1 do
    v = get_value (x,y)

    if v < 0.5 then
       v=1.0
    else
       v=0.0
    end

    set_value (x,y,v)
  end
  progress (y/height)
end

By either pressing the button with gears, or pressing F5 gluas will apply the algorihm described. If any processing errors occur an error panel will appear at the top of the gluas window.

Gluas reference

Functions

Gluas uses the core lua language for processing, but extends it with some functions specific to interaction with The GIMP.

get_rgba, set_rgba

r,g,b,a get_rgba( x,
  y);

Returns the Red, Green, Blue and Alpha components for the coordinates specified by the x,y parameters. The values are taken from the source image which is the original pixel data, unless flush() has been invoked.

RGB values within gluas are values between 0.0 and 1.0.

set_rgba( x,
  y,
  r,
  g,
  b,
  a);

Sets a pixel, using the specified Red, Green, Blue and Alpha component values.

get_rgb, set_rgb

r,g,b get_rgb( x,
  y);
set_rgb( x,
  y,
  r,
  g,
  b);

Functions similar to the RGBA varieties, note that the set_rgb function will not preserve the alpha value of the pixel, but boost it to 1.0 (full opacity).

get_value, set_value

v get_value( x,
  y);
set_value( x,
  y,
  v);

Setters and getters [4] for grayscale values.

get_hsl, set_hsl

h,s,l get_hsl( x,
  y);
set_hsl( x,
  y,
  h,
  s,
  l);

Hue, Saturation, Lightness pixel value setters and getters.

get_hsv, set_hsv

h,s,v get_hsv( x,
  y);
set_hsv( x,
  y,
  h,
  s,
  v);

Hue, Saturation, Value pixel value setters and getters. Value is calculated by gimp as MAX(MAX(r,g),b), i.e. the R,G or B component with the largest value.

get_lab, set_lab

l,a,b get_lab( x,
  y);
set_lab( x,
  y,
  l,
  a,
  b);

CIE Lab pixel setter and getter functions. .

progress

progress( percentage);

Update the progress bar in The GIMP's statusbar to the given percentage, useful when giving user feedback.

flush

flush( );

Copies the data from the temporary output image buffer, over the data in the source image buffer. This makes it possible to do additional processing steps (the values returned with getters will be the values previously set with setters prior to the flush() ).

flush() is mostly useful when implementing multipass algorithms, like a decomposed blur.

Variables

In order to know the dimensions, and some other aspects of the image, some numeric constants are also imported into the lua enviroment you program in.

width

The width of the input image, in pixels.

height

The height of the input image, in pixels.

user_data

When expanding the properties pane in the gluas editor, a slider shows up, the value of this slider can be accessed through this global variable.

Note that the program is run each time the mouse button is released on a new value.

It is also possible to generate animations that can be played back with The GIMP's Animation plug-ins. Then the value of user_data varies from 0.0 to 1.0.

bound_x0, bound_y0

The upper left coordinate of the bounding box of the current selection, may be used to speed up calculations by not taking unselected areas into account.

bound_x1, bound_y1

The bottom right coordinate of the bounding box of the current selection, may be used to speed up calculations by not taking unselected areas into account.

Gluas compatible software

Marco Pontello has developed a Project Dogwaffle plug-in, DogLua, , which is compatible with the core gluas functionality.

Artweaver (a freeware image painting program) also have support for gluas script. Artweaver lua scripting interface plug-in.



[4] The grayscale value is calculated as (r+g+b)/3