mrowdy / spritePacker

SpritePacker is a PHP tool to create sprite atlases automatically from an existing image folder.

SpritePacker

SpritePacker packs many small images on to larger images to reduce the HTTP overhead produced by many image downloads. It stores the locations of the smaller images as CSS or JSON so they are easily referenced by their filename in your code.

SpritePacker is based on the bin packing algorithm.

Demo

http://slemgrim.github.io/spritePacker/

Usage

Create an instance from SpritePacker class and add your images.

require_once 'spritePacker/SpritePacker.php';

$spritePacker = new SpritePacker();

//Add all images from directory
$spritePacker->addFromDir('images/sprites');

//Add single image
$spritePacker->addSprite('images/sprite.png');
$spritePacker->addSprite('images/logo-sprite.png');

$spritePacker->run();

Without config a 500x500px atlas will be generated under atlas/atlas.png with the corresponding css atlas/atlas.css.

The folder 'atlas' has to be writable.

<!-- load generated css -->
<link rel="stylesheet" type="text/css" href="atlas/example-sprite.css">

<!-- use your sprites -->
<span class="atlas sprite"></span>
<span class="atlas logo-sprite"></span>

Example Atlas

Example images from:

• http://openiconlibrary.sourceforge.net/
• http://unrestrictedstock.com/

Usage with config

$options = array(
    'name' => 'gui-atlas',
    'path' => '/image/atlas/',
);

$spritePacker = new SpritePacker($options);
$spritePacker->addFromDir('image/sprites/gui');
$spritePacker->run();

Creates /image/atlas/gui-atlas.png and /image/atlas/gui-atlas.css.

The folder 'image/atlas/' has to be writable.

<!-- load generated css -->
<link rel="stylesheet" type="text/css" href="/image/atlas/gui-atlas.css">

<!-- use your sprites -->
<span class="gui-atlas sprite"></span>
<span class="gui-atlas logo-sprite"></span>

Options:

Option	Description	Default	Type
name	Name of the generated files and CSS class	atlas	String
path	path for generated files	atlas	String
atlas-width	Width of generated atlas in px	500	Int
atlas-height	Height of generated atlas in px	500	Int
gutter	space between sprites (prevents overlapping in animations)	0	Int
render	Files to render	array('RenderPNG', 'RenderCSS')	Array
save	save generated files to disk	true	Boolean

Available Renderer

Name	Description
RenderPNG	Create PNG atlas
RenderCSS	Create CSS file from atlas. Sprite names generated from file names
RenderJSON	Create CSS file from atlas. Sprite names generated from file names

Use custom renderer

If CSS doesn't fit your needs, you can create your own renderer:

Class RenderDerp extends iRenderer {
    public function __construct($name, $path){}

    public function render(Atlas $atlas, array $sprites){
        //Render your custom format
    }

    public function show(){
        //output your format
    }

    public function save(){
        //save your format to disk
    }

}

$options = array(
    'render' => 'RenderDerp',
);

$spritePacker = new SpritePacker($options);