GEGL-0.0.6

Contents

  • GEGL
  •   Features
  •   Gallery
  •   Dependencies
  •   Download
  •   Bugzilla
  •   Mailinglist
  •   Copyright
  •  
  • Documentation
  •   Operations
  •   Glossary
  •   Hello World
  •   XML data model
  •   Environment
  •   gegl
  •  
  • Development
  •   Code Overview
  •  
  •  
  • changes
  • bugzilla
  • mailarchive

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

  • 8bit, 16bit integer and 32bit floating point, RGB, CIE Lab, YCbCr
    and naive CMYK output.
  • Extendable through plug-ins.
  • XML, C and Python interfaces.
  • Memory efficient evaluation of subregions.
  • Tiled, sparse, pyramidial and larger than RAM buffers.
  • Hit detection.
  • Rich core set of processing operations
      □ PNG, JPEG, SVG, EXR, RAW and other image sources.
      □ Arithmetic operations, porter duff compositing operations, SVG
        blend modes, other blend modes, apply mask.
      □ Gaussian blur.
      □ Basic color correction tools.
      □ 32bit floating point for intermediate values.
      □ Text layouting using pango

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.

  • Core
      □ glib (including gobject, and gmodule) 2.10 or newer
      □ babl 0.0.8 or newer (for pixel-format agnostisism).
      □ libpng (png load/export ops, and image magick fallback import)
  • GUI (sandbox for testing ops and the API)
      □ GTK+
  • Optional dependencies for operations.
      □ SDL (display op)
      □ libjpeg (jpg loader op)
      □ libopenexr (exr loader op)
      □ cairo, pango (text source op)
      □ librsvg

Download

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

The current code under development can be browsed online and checked
out from GNOME Subversion using:

svn co
http://svn.gnome.org/svn/gegl/trunk/gegl/trunk 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:

  • List of Open Bugs
  • List of Open Bugs (excluding enhancement requests)
  • List of Enhancement Proposals
  • Bugzilla Weekly Summary

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_node_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_node_create_child (gegl, "display");
    GeglNode *layer      = gegl_node_new_child (gegl,
                                 "operation", "layer",
                                 "x", 2.0,
                                 "y", 4.0,
                                 NULL);
    GeglNode *text       = gegl_node_new_child (gegl,
                                 "operation", "text",
                                 "size", 10.0,
                                 "color", gegl_color_new ("rgb(1.0,1.0,1.0)"),
                                 NULL);
    GeglNode *mandelbrot = gegl_node_new_child (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.
