GEGL-0.0.4

Contents

GEGL

GEGL (Generic Graphics Library) is a graph based image processing library written in C using gobject from glib for object orientation.

GEGL original design was made to scratch GIMPs itches for a new compositing and processing core. This core is being designed to have minimal dependencies. and a simple well defined API. It is still a work in progress, but it already provides for a capable system.

Features

For examples of what GEGL is currently capable of doing, take a look at the gallery.

Dependencies

GEGL is currently building on linux, the build enviroment probably needs some fixes before all of it builds gracefully on many platforms.

Download

The latest development snapshot, and eventually stable versions of GEGL are available at ftp://ftp.gimp.org/pub/gegl/.

Bugzilla

The GEGL project uses GNOME Bugzilla, a bug-tracking system that allows us to coordinate bug reports. Bugzilla is also used for enhancement requests and the preferred way to submit patches for GEGL is to open a bug report and attach the patch to it.

Below is a list of links to get you started with Bugzilla:

Mailinglist

You can subscribe to gegl-developer and view the archives here. The GEGL developer list is the appopriate place to ask development questions, and get more information about GEGL development in general. You can email this list at gegldev at gegl.org.

Copyright

GEGL is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

Contributors

          
Code:
  Calvin Williamson
  Caroline Dahloff
  Manish Singh
  Jay Cox
  Daniel Rogers
  Sven Neumann
  Michael Natterer
  Øyvind Kolås
  Philip Lafleur
  Dominik Ernst
  Richard Kralovic
  Kevin Cozens
  Victor Bogado
  Martin Nordholts
  Geert Jordaens

Documentation:
  Garry R. Osgood
  Øyvind Kolås

Artwork:
  Jakub Steiner

Documentation

GEGLs programmer/user interface is a Directed Acyclic Graph of nodes. The DAG expresses a processing chain of operations. A DAG, or any node in it, expresses a composited and processed image. It is possible to request rectangular regions in a wide range of pixel formats from any node. See the Glossary to decode this paragraph.

The DAG is modifiable through the C API as well as a Python Binding. The XML Data model provides a tree based interface that maps to Directed Acyclic graphs (DAGs). Environment Variables can be set to tune and instrument the behavior of GEGL. gegl is small commandline tool acting as a wrapper around the XML capabilities that provides output to PNG.

The main source of documentation as GEGL grows is the Operations reference. Plug-ins themselves register information about the categories they belong to, what they do, and documentation of the available parameters.

Glossary

connection
A link/pipe routing image flow between operations within the graph goes from an output pad to an input pad, in graph glossary this might also be reffered to as an edge.
DAG
Directed Acyclic Graph, see graph.
graph
A composition of nodes, the graph is a DAG.
node
The nodes are connected in the graph. A node has an associated operation or can be constructed graph.
operation
The processing primitive of GEGL, is where the actual image processing takes place. Operations are plug-ins and provide the actual functionality of GEGL
pad
The part of a node that exchanges image content. The place where image "pipes" are used to connect the various operations in the composition.
input pad
consumes image data, might also be seen as an image parameter to the operation.
output pad
a place where data can be requested, multiple input pads can reference the same output pad.
property
Properties are what control the behavior of operations, through the use of GParamSpecs properties are self documenting through introspection.

Hello world

This is a small sample GEGL application that animates a zoom on a mandelbrot fractal


#include <gegl.h>

gint
main (gint    argc,
      gchar **argv)
{
  gegl_init (&argc, &argv);  /* initialize the GEGL library */

  {
    /* instantiate a graph */
    GeglNode *gegl = gegl_graph_new ();

/*
This is the graph we're going to construct:
 
.-----------.
| display   |
`-----------'
   |
.-------.
| layer |
`-------'
   |   \
   |    \
   |     \
   |      |
   |   .------.
   |   | text |
   |   `------'
.-----------------.
| FractalExplorer |
`-----------------'

*/

    /*< The image nodes representing operations we want to perform */
    GeglNode *display    = gegl_graph_create_node (gegl, "display");
    GeglNode *layer      = gegl_graph_new_node (gegl,
                                 "operation", "layer",
                                 "x", 2.0,
                                 "y", 4.0,
                                 NULL);
    GeglNode *text       = gegl_graph_new_node (gegl,
                                 "operation", "text",
                                 "size", 10.0,
                                 "color", gegl_color_new ("rgb(1.0,1.0,1.0)"),
                                 NULL);
    GeglNode *mandelbrot = gegl_graph_new_node (gegl,
                                "operation", "FractalExplorer",
                                "width", 256,
                                "height", 256,
                                NULL);

    gegl_node_link_many (mandelbrot, layer, display, NULL);
    gegl_node_connect_to (text, "output",  layer, "aux");
   
    /* request that the save node is processed, all dependencies will
     * be processed as well
     */
    {
      gint frame;
      gint frames = 30;

      for (frame=0; frame<frames; frame++)
        {
          gchar string[512];
          gdouble t = frame * 1.0/frames;
          gdouble cx = -1.76;
          gdouble cy = 0.0;

#define INTERPOLATE(min,max) ((max)*(t)+(min)*(1.0-t))

          gdouble xmin = INTERPOLATE(  cx-0.02, cx-2.5);
          gdouble ymin = INTERPOLATE(  cy-0.02, cy-2.5);
          gdouble xmax = INTERPOLATE(  cx+0.02, cx+2.5);
          gdouble ymax = INTERPOLATE(  cy+0.02, cy+2.5);

          if (xmin<-3.0)
            xmin=-3.0;
          if (ymin<-3.0)
            ymin=-3.0;

          gegl_node_set (mandelbrot, "xmin", xmin,
                                     "ymin", ymin,
                                     "xmax", xmax,
                                     "ymax", ymax,
                                     NULL);
          g_sprintf (string, "%1.3f,%1.3f %1.3f×%1.3f",
            xmin, ymin, xmax-xmin, ymax-ymin);
          gegl_node_set (text, "string", string, NULL);
          gegl_node_process (display);
        }
    }

    /* free resources used by the graph and the nodes it owns */
    g_object_unref (gegl);
  }

  /* free resources globally used by GEGL */
  gegl_exit ();

  return 0;
}

Compiling

GEGL uses pkg-config for passing the needed compile time options, download hello-world.c and typing what follows in a terminal after succesfully installing GEGL should produce a working binary. 

gcc hello-world.c `pkg-config --libs --cflags gegl` -o hello-world

XML data model

The tree allows clones, making it possible to express any acyclic graph where the nodes are all of the types: source, filter and composer.

GEGL can write and reads its data model to and from XML. The XML is chains of image processing commands, where some chains allow a child chain (the 'over' operator to implement layers for instance).

The type of operation associated with a node can be specified either with a class attribute or by using the operation name as the tag name for the node.

For documentation on how this XML works, take a look at the sources in the gallery. And browse the documentation for operations.

Environment

Some environment variables can be set to alter how GEGL runs, this list might not be exhaustive but it should list the most useful ones.

BABL_STATS
When set babl will write a html file (/tmp/babl-stats.html) containing a matrix of used conversions, as well as all existing conversions and which optimized paths are followed.
BABL_ERROR
The amount of error that babl tolerates, set it to for instance 0.1 to use some conversions that trade some quality for speed.
GEGL_DEBUG_BUFS
Display tile/buffer leakage statistics.
GEGL_DEBUG_RECTS
Show the results of have/need rect negotiations.
GEGL_DEBUG_TIME
Print a performance instrumentation breakdown of GEGL and it's operations.
GEGL_SWAP
Swap to disk instead of storing all pixel data in RAM, allows processing images larger than physical RAM. Check temp folder for left over files after processing is done.

gegl

GEGL provides a commandline tool called gegl, for working with the XML data model from file, stdin or the commandline. It can display the result of processing the layer tree or save it to file.

Some examples:

Render a composition to a PNG file:

gegl composition.xml -o composition.png

Invoke gegl like a viewer for gegl compositions:

gegl -ui -d 5 composition.xml

Using gegl with png's passing through stdin/stdout piping.

cat input.png | gegl -o - -x "<gegl>
<tree>
  <node class='invert'/>
  <node class='scale' x='0.5' y='0.5'/>
  <node class='png-load' path='-'/></tree></gegl>" > output.png
The latest development version is available in the gegl module in GNOME Subversion.

gegl usage

The following is the usage information of the gegl binary, this documentation might not be complete. 
    
usage: gegl [options] 

  Options:
     --help      this help information
     -h

     --file      read xml from named file
     -i

     --xml       use xml provided in next argument
     -x

     --dot       output a graphviz graph description
     --output    output generated image to named file
     -o          (file is saved in PNG format)

     -X          output the XML that was read in

     --verbose   print diagnostics while running
      -v

All parameters following -- are considered ops to be chained together
into a small composition instead of using an xml file, this allows for
easy testing of filters. Be aware that the default value will be used
for all properties.

Development

GEGL uses bugzilla to track feature requests and contributions. A description of what the various directories in the GEGL checkout is in the Code Overview. Most coders working with gegl would probably be extending it through operations.

Code Overview

Directories in the GEGL checkout:

gegl-dist-root
 │
 │
 ├──gegl             core source of GEGL, graph handling, library init/deinit,
 │   │               evaluation management. Also contains common abstract base
 │   │               classes for plug-in operations.
 │   │ 
 │   ├──buffer       contains the implementation of Bab
 │   │                - sparse (tiled)
 │   │                - recursivly subbuffer extendable
 │   │                - clipping rectangle (defaults to bounds when making
 │   │                  subbuffers)
 │   │                - storage in any babl supported pixel format
 │   │                - read/write rectangular region as linear buffer for
 │   │                  any babl supported pixel format.
 │   │
 │   └──module        The code to load plug-ins located in a colon seperated
 │                    list of paths from the environment variable GEGL_PATH
 │
 ├──operations        Runtime loaded plug-ins for image processing operations.
 │   │
 │   ├──core          Basic operations tightly coupled with GEGL.
 │   │
 │   ├──blur          Blurring operations.
 │   ├──color         Color adjustments.
 │   ├──display       Operations that show image data as a side effect.
 │   ├──meta          Operations that are made by gegl graphs.
 │   ├──file-io       File loaders.
 │   ├──render        Operations providing patters, graidents, fills, ...
 │   ├──transform     transforming/resampling operations
 │   ├──transparency  opacity/mask control
 │   ├──generated     Operations generated from scripts (currently
 │   │                ruby scripts.) (arithmetic, compositing, ...)
 │   └──workshop      Works in progress, (not compiled by default)
 │       └──generated
 │                    
 ├──bin               gegl binary, for processing XML compositions to png files.
 │
 ├──docs              A website for GEGL
 │   │
 │   └──gallery       A gallery of sample GEGL compositions.
 │       │
 │       └──data      Image data used by the sample compositions.
 │    
 │
 └──tools             some small utilities to help the build.

Directories of babl

babl-dist-root
 │
 ├──babl       the babl core
 │   └──base   reference implementations for RGB and Grayscale Color Models,
 │             8bit 16bit, and 32bit and 64bit floating point.
 ├──extensions CIE-Lab color model as well as a naive-CMYK color model.
 │             also contains a random cribbage of old conversion optimized
 │             code from gggl. Finding more exsisting conversions in third
 │             part libraries (hermes, lcms?, liboil?) would improve the
 │             speed of babl considerably.
 ├──tests      tests used to keep babl sane during development.
 └──docs       Documentation/webpage for babl.

Extending

To create your own operations you should start by looking for one that does approximatly what you already need. Copy it to a new .c source file, and replace the occurences of the filename (operation name in the source.)

Most of the operations do not use the verbose gobject syntax, but preprocessor tricks turning the boilerplate in a short chant.