Gallery3:Developer Handbook:Graphics Toolkits and Rules - Gallery Codex
Personal tools

Gallery3:Developer Handbook:Graphics Toolkits and Rules

From Gallery Codex

Revision as of 14:53, 13 June 2011 by Ckdake (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Graphics Toolkits and Rules

At its core, Gallery 3 is a graphical image processing application. In order to work it needs to be able to process a full size image and generate smaller resized versions, and thumbnails so that they can be properly viewed. The gallery module contains a framework for processing image rules and some basic rules.

There are only two types of intermediate images: thumb and resize. Each one has an associated set of rules stored in the graphics_rule ORM. By default there is a single rule for generating a thumbnail and it looks like this:

 target: thumb
 module_name: gallery
 operation: gallery_graphics::resize
 args: { width: 200, height: 200, master: Image::AUTO }
 priority: 100

This rule is created by the gallery module installer and specifies that when it is necessary to build a thumbnail, it will call the resize function in the gallery_graphics helper with the arguments provided. Since there is only one rule in the pipeline, the source of the operation will be the full sized image found in var/albums, and the result will be the thumbnail stored in the appropriate place in var/thumbs.

The priority field specifies the order in which operations are performed. When the watermark module is active and the admin has specified a specific watermark to use, that module introduces a new rule:

 target: thumb
 module_name: watermark
 operation: gallery_graphics::composite
 args: { file: "/path/to/watermark.gif", width: 105, height: 40, ...}
 priority: 1000

Note that this rule runs at priority 1000. So when generating a thumbnail, Gallery 3 will first run the resize function to size the image down, then it will call the composite function to add the watermark image on top.

To add a new rule, you must use the graphics::add_rule() function. It takes the following arguments:

 $module_name - the name of your module
 $target - the target image type ("thumb" or "resize")
 $operation - the static helper function to call
 $args - the arguments to the function (can be an array or a single value)
 $priority - the priority in which this operation should be called

Each module can provide its own graphics functions. A graphics function is merely a helper call which takes an input file, an output file and a set of optional values. When it's time to rebuild an image, the Gallery 3 framework will call graphics::generate() on an Item_Model that has a thumb or a resize which needs to be rebuilt, and then this code will then run every rule in order as appropriate. If you want to introduce your own rule that pre-processes the full size image to sharpen it before the thumbnail is generated, it would look like this:


class '''''example'''''_installer {
  static function install() {
    // Normal install code
    graphics::add_rule("'''''example'''''", "thumb", 
                       array("amount" => 10),

This introduces the new rule into the system. Now you must write the code for the sharpen function:


class example_graphics {
  static function sharpen($input_file, $output_file, $options) {

Note that this uses Kohana's built in Image library which provides basic functionality for simple graphics operations using the active graphics toolkit. Create a static helper as a wrapper around this code to logically group multiple operations together or introduce more complex logic if necessary. For example, gallery_graphics::resize() also makes sure that the image does not get upscaled if the input file is going to be smaller than the output file.

The following basic graphics functions are available via the gallery module in the gallery_graphics helper:


Rotate the image to a new orientation while preserving the aspect ratio.


  • degrees - any integer value from 0 to 360


Resize the image to a smaller size while preserving the aspect ratio. This will not upscale (ie: generate an image of a larger size). This function creates a box of the size that you desire, then figures out how to fit the image into it while preserving the aspect ratio. The master option allows you to specify whether you want to consider the width or the height to be the master dimension (the dimension to try to fit inside the box). If you choose Image::NONE as the master dimension, it will change the aspect ratio of the image to be the new dimensions you specify (damaging the image).


  • width - the new width of the resized image
  • height - the new height of the resized image
  • master - Image::AUTO, Image::WIDTH, Image::HEIGHT or Image:NONE


Overlay a second image on top of the first one (eg watermarking).


  • file - the path on disk to the overlay file
  • position - a string representing a cardinal direction: northwest, norh, northeast, west, center, east, southwest, south, southeast
  • transparency - an integer value from 0 to 100
  • padding - the number of pixels to pad the overlay from the edge of the source file

Notes about graphics rules:

  • Modules are free to add new graphics rules to the system at any time
  • A module's graphics rules are only obeyed if the module is active