mkatlas
=======

[BASH][1] script to build a [texture atlas][2] for small/medium web
sites/games. Requires [ImageMagick][3].

Usage
-----

### Basic

Just run

	$ ./mkatlas img/*

which will create _atlas.png_ and outputs the corresponding sprite regions
in JSON format:

	var atlas={
	first:{x:298,y:0,w:35,h:22},
	second:{x:254,y:0,w:44,h:33},
	...
	}

### Advanced

Alternatively you may use just markers in your JavaScript to insert the
frame data in place. This way you wouldn't have to have a extra _atlas_
object and wouldn't need to do any additional mapping. For example:

	var obj = {
		name: "Jim",
		frame: {/*first*/x:0,y:0,w:0,h:0},
		live: 100 };

This file may be patched with _patchatlas_ like this:

	$ ./mkatlas img/* | ./patchatlas index.html

Switches
--------

There are a few environment variables for fine tuning.
You may simply put them before invocation, e.g.:

	$ ATLAS=atlas.jpg ./mkatlas img/*

#### ATLAS
File name (and image format) of atlas image.

#### MAX_SIZE
Maximum width/height of atlas. Default is 2048. By default, the atlas
is trimmed to the smallest possible size. MAX_SIZE just gives a maximum
boundary.

#### MIN_SIZE
Minimum width/height of atlas. Default is 0. Use it to force a certain size,
e.g. to have dimensions with a power of 2 (for OpenGL/WebGL).

#### MARGIN
Margin around each sprite. Default is 0.

#### EXPAND
If margin is greater than 0, then expand sprites whose file names match
the expression in EXPAND by mirroring their edges, e.g.:

	$ MARGIN=2 EXPAND='tile_*' ./mkatlas img/*

This is useful for textures that will be used with OpenGL/WebGL's
CLAMP_TO_EDGE.

[1]: http://en.wikipedia.org/wiki/Bash_(Unix_shell)
[2]: http://en.wikipedia.org/wiki/Texture_atlas
[3]: http://www.imagemagick.org/