Spritemapper

Spritemapper is an application that merges multiple images into one and generates CSS positioning for the corresponding slices.

Improve loading times. Only 10% of a webpage's loading time is due to the actual page—the other 90% is spent downloading styles, scripts and images. By reducing the amount of images and better utilizing the connection, CSS spritemapping can reduce your website's loading time.

Just plain old CSS. You don't have to write any extra syntax to make Spritemapper work. Just define the directories of images you want spritemapped and use the CSS background declaration as usual.

Batteries included. The package consists of a simple command-line tool that does the job via a Python package including its own PNG and CSS parser. There are no 3rd-party dependencies. Anybody who has ever had the pleasant job of installing PIL should have a pretty good idea about what we're trying to avoid.

No space wasted. Spritemapper's image packer implements simulated annealing to ensure that the images are packed tightly.

Installation

Mac OS X (and Linux, anything but Windows)

Open a terminal—Terminal, urxvt or whatever—and run sudo easy_install spritemapper. Let stir for five seconds. Done.

The latest source release is available as a tarball on Spritemapper's PyPI page.

Microsoft Windows

Make sure you have Python installed and that it is in your PATH, also include the 'Scripts' directory inside of your Python installation if you want to run spritemapper directly from the Command Prompt.

Pre-built .msi installer

Go to Spritemapper's GitHub download page, download the latest .msi installer and run it.

From Source

You'll need Git and Python setuptools.

1. Open a shell in a directory where you want the source
2. git clone git://github.com/yostudios/Spritemapper.git — copy the source code
3. cd Spritemapper — enter directory
4. python setup.py install — install Spritemapper

Usage

Run spritemapper /path/to/myfile.css and it does its magic. Give the old --help a quick look, too.

Command-line

-h, --help

show a help message and exit

-c INI, --conf=INI

read base configuration from INI (see Configuration options)

--padding=N

keep N pixels of padding between sprites

Configuration options

Configuration options can be specified in one of two ways: inline in the CSS, or using passing an INI file with defaults. For CSS it looks something like:

/* spritemapper.output_css = foofile.css */

You can do the exact equivalent using an INI file, like this:

[spritemapper]
  output_css = foofile.css

Paths are always relative to the CSS file being processed.

base_url

a url at which the resulting css and image files can be reached. by default uses file-relative paths (recommended).

sprite_dirs

a list of directories within which to allow spritemaps to be generated. by default all directories are eligible.

recursive

set if sub-spritemaps should be generated when sub-directories are found. set by default.

output_image

the name of output spritemap image. sprite_dirs is incompatible with this because both tell the spritemapper how to sort sprites into spritemaps. by default <dir> + .png.

output_css

the name for the rewritten CSS file. by default sm_{basename}{extension}.

padding

amount of padding space between two images. this is mostly useful to counteract subpixel rendering artifacts on iOS devices. by default 1.

anneal_steps

a larger number here makes the box packer algorithm try more combinations. by default 9200.

Example

Creating a webfont using spritemapper.

Output