User Guide
Prerequisites
- Linux or Windows
- PHP (version 5.1 or higher)
- PHP CLI (command line interface)
- GDLib
- Readable input folder
- Writeable output folder
Installation
To install the software unzip the downloaded file into any directory on your harddisk. The arising folder containes all required files to run the program.
Explanation of the software cycle
- Start with parameters
- Read in all images from input folder
- Calculate position of each image on the big resulting image
- Position all small images on the big one
- Create confguration file with all image attributes
- Write big image and configuration file into output folder
First start
To start the software with Linux type the following line into your terminal:
php -f spriting.php <input folder> <output folder> <calculating method> <configuration method>
In case you use Windows type the following line into your prompt:
C:\path\to\php.exe spriting.php <input folder> <output folder> <calculating method> <configuration method>
Parameter
Input folder
Place all your static images into this folder. They will become read in and processed by the software.
Output folder
All resulting files will be written into this folder. Make sure, that it's writable for the PHP script executing user.
Calculating method
All small images will be placed on one big image. The position, where the images have to be placed must be calculated. The software offers two calculating methodes for this by default. Each has it's own advantages. You can use one of them.
Normal
Calculating the image positions with the “normal” method is very fast but not much productive. It causes much free space called “offcut”.
Better
The “better” calculating method has a better exploitation of the free space but is not as fast as the normal method.
Configuration method
For binding the resulting image into your website you will need a configuration file. The type of configuration file can be selected by this parameter.
Stylesheet
If you use “stylesheet” as parameter the software will output a CSS file. To use this file include it in your website header like other stylesheet files and give all your existing (or maybe new) images the class names written in this file.
Placeholder
If you use the “placeholder” you are free in using the resulting file. It containes an array of image tags which have completely all information to bind them into the DOM of your website. As example you can replace any type of placeholder in your website dynamically replacing it with the PHP method preg_replace.
Configuration
To configure the software you need PHP knowledge!
Options
In the file “config.php” you can configure several options like maximal proportions of the resulting image or error handling. You can find this file in same folder like the, for program start needed, file “spriting.php”.
Maximal picture size
Set the maximal width and height of the resulting image. But do not configure more then 2048 x 2048 pixel because a problem with Opera browser.
Grid size
If you use the “better” method to calculate image positions, the whole free space will be divided into a grid.
After that all images get parts of this grid depending on their size. Finally all images will be placed on any free
space on the grid.
If you change the grid size, you can reduce the offcut. Try it 
Class path
The “class path” is the directory path to the program kernel. Don't touch that if you not really need to!
Error handling
Type of error output (debug, error, warn). Depending on the selected type you get more or less messages.
- DEBUG: Shows really detailed messages. Select this if you e.g. implement a new calculating method.
- ERROR: Shows only errors
- WARN: Shows warn messages which not automatically induce the program termination and errors.
Each message type has it's own symbol at line start:
- DEBUG: !!
- ERROR: X
- WARN: #
Final steps
Bind image in an existing webpage
The resulting image will be binded into your website depending on the used configuration method.
Stylesheet
The “stylesheet” method generates a CSS file which you only have to include in the page header of your website:
<head> <link rel="stylesheet" type="text/css" href="path/to/stylesheet" /> </head>
Use the supplied image “blank.gif” as ressource of all your used images and give them the class you got for it in the CSS file.
Image tag:
<img src="path/to/blank.gif" class="demo_png" />
CSS class:
.demo_png { background: url(ImageSpriting_2009-02-06_12-00-00_0.png) -0px -320px no-repeat; height:320px; width:640px; }
The negative left-top-position of the background moves the background image to that position, where the wanted image is placed on the big image.
Placeholder
The “placeholder” method generates a PHP file which containes an array of image tags which have completely all information to bind them into the DOM of your website. As example you can replace any type of placeholder in your website dynamically replacing it with the PHP method preg_replace.
<?php $aStyleInformation = array( 'demo_png' => '<img src="blank.gif" height="320" width="640" style="..." /> ... ); ?>
