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:
modules/example/helpers/example_installer.php:
<?
class example_installer {
static function install() {
// Normal install code
graphics::add_rule(example, "thumb",
example_graphics::sharpen",
array("amount" => 10),
80);
}
}
This introduces the new rule into the system. Now you must write the code for the sharpen function:
modules/example/helpers/example_graphics.php
<?
class example_graphics {
static function sharpen($input_file, $output_file, $options) {
Image::factory($input_file)
->sharpen($options["amount"])
->save($output_file)
}
}
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.
Options:
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).
Options:
Overlay a second image on top of the first one (eg watermarking).
Options:
Notes about graphics rules:
