View on
Savio Dimatteo > CSS-SpriteMaker-0.07 > CSS::SpriteMaker



Annotate this POD


Open  0
View/Report Bugs
Module Version: 0.07   Source   Latest Release: CSS-SpriteMaker-1.01


CSS::SpriteMaker - Combine several images into a single CSS sprite


Version 0.07


    use CSS::SpriteMaker;

    my $SpriteMaker = CSS::SpriteMaker->new(
        verbose => 1, # optional

        # if provided will replace the default way of creating css classnames
        # out of image filenames.
        rc_filename_to_classname => sub { my $filename = shift; ... } # optional

        # this callback gets called after the css class name for an image is
        # generated. It is the latest possible moment at which you can modify
        # the resulting css class name (e.g., add a prefix to it).
        rc_override_classname => sub { my $css_class = shift; ... } # optional

        source_images  => ['/path/to/imagedir', '/images/img1.png', '/img2.png'];
        target_file => '/tmp/test/mysprite.png',
        layout_name => 'Packed',    # optional
        remove_source_padding => 1, # optional
        format => 'png8',           # optional




    my $SpriteMaker = CSS::SpriteMaker->new();

       source_dir => '/tmp/test/images',
       target_file => '/tmp/test/mysprite.png',




    my $SpriteMaker = CSS::SpriteMaker->new();

        parts => [
            { source_dir => 'sample_icons',
              layout_name => 'Packed' 
            { source_dir => 'more_icons',
                layout => {
                    name => 'FixedDimension',
                    options => {
                        'dimension' => 'horizontal',
                        'n' => 4,
        # the composing layout
        layout => {
            name => 'FixedDimension',
            options => {
                n => 2,
        target_file => 'composite.png',




A CSS Sprite is an image obtained by arranging many smaller images on a 2D canvas, according to a certain layout.

Transferring one larger image is generally faster than transferring multiple images separately as it greatly reduces the number of HTTP requests (and overhead) necessary to render the original images on the browser.



Create and configure a new CSS::SpriteMaker object.

The object can be initialised as follows:

    my $SpriteMaker = CSS::SpriteMaker->new({
        rc_filename_to_classname => sub { my $filename = shift; ... }, # optional
        source_dir => '/tmp/test/images',       # optional
        target_file => '/tmp/test/mysprite.png' # optional
        remove_source_padding => 1, # optional
        verbose => 1,               # optional

Default values are set to:

remove_source_padding : false,
verbose : false,
format : png

The parameter rc_filename_to_classname is a code reference to a function that allow to customize the way class names are generated. This function should take one parameter as input and return a class name


Compose many sprite layouts into one sprite. This is done by applying individual layout separately, then merging the final result together using a glue layout.

my $is_error = $SpriteMaker->compose_sprite ( parts => [ { source_images => ['some/file.png', 'path/to/some_directory'], layout_name => 'Packed', }, { source_images => ['path/to/some_directory'], layout => { name => 'DirectoryBased', } include_in_css => 0, # optional }, ], # arrange the previous two layout using a glue layout layout => { name => 'FixedDimension', dimension => 'horizontal', n => 2 } target_file => 'sample_sprite.png', format => 'png8', # optional, default is png );

Note the optional include_in_css option, which allows to exclude a group of images from the CSS (still including them in the resulting image).


Creates the sprite file out of the specifed image files or directories, and according to the given layout name.

my $is_error = $SpriteMaker->make_sprite( source_images => ['some/file.png', path/to/some_directory], target_file => 'sample_sprite.png', layout_name => 'Packed',

    # all imagemagick supported formats
    format => 'png8', # optional, default is png

returns true if an error occurred during the procedure.

Available layouts are:


Creates and prints the css stylesheet for the sprite that was previously produced.

You can specify the filename or the filehandle where the output CSS should be written:

       filehandle => $fh, 


       filename => 'relative/path/to/style.css',

Optionally you can provide the name of the image file that should be included in the CSS file:

    # within the style.css file, override the default path to the sprite image
    # with "custom/path/to/sprite.png".
       filename => 'relative/path/to/style.css',
       sprite_filename => 'custom/path/to/sprite.png', # optional

NOTE: make_sprite() must be called before this method is called.


Creates and prints an html sample page containing informations about each sprite produced.

       filehandle => $fh, 


       filename => 'relative/path/to/index.html',

NOTE: make_sprite() must be called before this method is called.


Returns an arrayref of hashrefs like:

            full_path => 'relative/path/to/file.png',
            css_class => 'file',
            width     => 16,  # pixels
            height    => 16,
            x         => 173, # offset within the layout
            y         => 234,

This structure can be used to build your own html or css stylesheet for example.

NOTE: the x y offsets within the layout, will be always positive numbers.



Returns a mapping id -> class_name out of the current information structure.

It guarantees unique class_name for each id.


Identify informations from the location of each input image, and assign numerical ids to each input image.

We use a global image identifier for composite layouts. Each identified image must have a unique id in the scope of the same CSS::SpriteMaker instance!


Returns a global numeric identifier.


Finds the location of image files within the given directory. Returns an arrayref of hashrefs containing information about the names and pathnames of each image file.

The returned arrayref looks like:

[ # pathnames of the first image to follow { name => 'image.png', pathname => '/complete/path/to/image.png', parentdir => '/complete/path/to', }, ... ]

Dies if the given directory is empty or doesn't exist.


Returns the stylesheet in a string.


This method generates the name of the CSS class for a certain image file. Takes the image filename as input and produces a css class name (excluding the prepended ".").


Inspects the input %options hash and returns a filehandle according to the parameters passed in there.

The filehandle is where something (css stylesheet for example) is going to be printed.


Makes sure the user of this module has provided a valid input parameter for sources_info and return the sources_info structure accordingly. Dies in case something goes wrong with the user input.

Parameters that allow us to obtain a $rh_sources_info structure are:

- source_images: an arrayref of files or directories, directories will be visited recursively and any image file in it becomes the input.

If none of the above parameters have been found in input options, the cache is checked before giving up - i.e., the user has previously provided the layout parameter, and was able to generate a sprite.


Makes sure the user of this module has provided valid layout options and returns a $Layout object accordingly. Dies in case something goes wrong with the user input. A Layout actually runs over the specified items on instantiation.

Parameters in %options (see code) that allow us to obtain a $Layout object are:

- layout: a CSS::SpriteMaker::Layout object already; - layout: can also be a hashref like { name => 'LayoutName', options => { 'Layout-Specific option' => 'value', ... } } - layout_name: the name of a CSS::SpriteMaker::Layout object.

If none of the above parameters have been found in input options, the cache is checked before giving up - i.e., the user has previously provided the layout parameter...


Return an hashref of information about the image at the given pathname.


Compose a layout though a glue layout: first each image set is layouted, then it is composed using the specified glue layout.


Compose a layout without glue layout: the previously lay-outed image set becomes part of the next image set.


Generate color histogram out of the information structure of all the images.


Print verbose output only if the verbose option was passed as input.


Copyright 2013 Savio Dimatteo.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.

syntax highlighting: