Posts tagged: unchaos

UnChaos and CSS

UnChaos can now generate a CSS file for the sprite sheet. A class is created for each image on the sprite sheet.

Go here to download the latest version (or to find out more about UnChaos):
http://www.diorgo.com/v1/?p=198


Below is an example of a sprite sheet and the CSS file created by UnChaos.
The grey rectangles in the background represent the transparent pixels.

UnChaos sprite sheet example
spritesheet.png



The .css file:

.button_down {
background: url(‘imgs/spritesheet.png’) no-repeat -1px -1px;
width: 135px;
height: 53px;
}
 
.button_mouseover {
background: url(‘imgs/spritesheet.png’) no-repeat -1px -55px;
width: 135px;
height: 53px;
}
 
.button_up {
background: url(‘imgs/spritesheet.png’) no-repeat -1px -109px;
width: 135px;
height: 53px;
}
 
.icon_smiley {
background: url(‘imgs/spritesheet.png’) no-repeat -137px -1px;
width: 76px;
height: 76px;
}
 
.border_bottomleft {
background: url(‘imgs/spritesheet.png’) no-repeat -214px -1px;
width: 40px;
height: 40px;
}
 
.border_bottomright {
background: url(‘imgs/spritesheet.png’) no-repeat -214px -42px;
width: 40px;
height: 40px;
}
 
.border_topleft {
background: url(‘imgs/spritesheet.png’) no-repeat -137px -78px;
width: 40px;
height: 40px;
}
 
.border_topright {
background: url(‘imgs/spritesheet.png’) no-repeat -178px -83px;
width: 40px;
height: 40px;
}
 
.border_horizontal {
background: url(‘imgs/spritesheet.png’) no-repeat -219px -83px;
width: 20px;
height: 20px;
}
 
.border_vertical {
background: url(‘imgs/spritesheet.png’) no-repeat -219px -104px;
width: 20px;
height: 20px;
}


UnChaos

I've made a few changes to UnChaos.
The latest version can be downloaded here:
UnChaos (version 1.0.3)

Older versions:
UnChaos (version 1.0.2)

Changes include cropping of images, exporting image source rects to .xml, .json and .css files. UnChaos now also has an installer and a help file.

UnChaos uses BMGLib 2.5 by M. Scott Heiman.


Below are extracts from the help file.

What is UnChaos?

UnChaos is a program which takes all the images in a folder and packs them onto a single image (i.e. texture). It also creates a text file (.txt, .xml, .json, .css) which contains the source rectangles (source rects) of the images on the texture. In addition, it can also crop the images on the texture. It crops the transparent pixels around the edges of each image, which makes the image smaller and saves space on the texture.

User interface

UnChaos screen shot
A screen shot of UnChaos.


Settings

Input Folder:

The folder which contains the source images to pack onto a single texture.

Output Image File:

The location and name of the texture to save after it has been created.

Output Text File (.txt, .xml, .json, .css):

The location and name of the text file to create, which will contain information (i.e. variables) about the images.

UnChaos can create 4 types of text files:

1) .txt: A basic text file with limited information.
2) .xml: A standard XML file with more information than the .txt file.
3) .json: A standard JSON file with the same information as the .xml file.
4) .css: A standard CSS file with specifically formatted information.

The following table describes the variables, and the files in which they are found:

Variable
Description
In files
id / class name
The image's unique ID. This is created from the image's file name (e.g. if the file name is “frame05.png” then the ID will be “frame05”). This is the class name in the .css file. Optionally, a prefix and a postfix can be added to the ID. (See Prefix and Postfix below.)
.xml, .json, .txt, .css
sourceRect
The image's source rect on the texture. This is basically a rectangle which describes where on the texture the image can be found. The rectangle's top-left position is used for the background's position in the .css file. There are 3 formats available for the source rect. (See Output Format below.)
.xml, .json, .txt, .css
drawOffset
The drawOffset contains an “x” and a “y” value. When the image is drawn to screen, then the drawOffset is added to the image's world position to calculate the image's screen position.

This is used to ensure cropped images are drawn in the correct positions. In other words, it draws the image in the same position it would have been if it was not cropped.

If the image is not cropped then drawOffset will have zero values for “x” and “y”.

.xml, .json
size
The dimensions of the image on the texture. It includes the “width” and “height”.
.xml, .json, .css
originalSize
The original dimensions of the image before it was cropped. It includes the “width” and “height”.

If the image is not cropped then this will have the same values as the “size” variable.

.xml, .json


Output Width:

The width of the texture to create. This is in pixels.

Output Height:

The height of the texture to create. This is in pixels.

Border Size:

The size of a border to leave empty around the edges of the texture. All the images will be placed on the inside of the border. This can be zero and it is in pixels.

Spaces Between Size:

The empty space to leave between the images on the texture. This can be used to prevent the images touching each other on the texture. This can be zero and it is in pixels.

Pixel Grid Align X:

The grid X intervals at which to place the images on the texture. This can be used when the texture will be compressed by a third-party program which compresses better when the images are aligned on a grid. This can be zero.
For example: If it is set to 4 then images will only be placed at X position 4, 8, 12, 16, 20, etc.

Pixel Grid Align Y:

The grid Y intervals at which to place the images on the texture. (See Pixel Grid Align X above.)

Crop Images:

This setting specifies whether the images should be cropped.
The available crop options are:

1) No: No cropping.
2) Yes: Crops all the images.
3) Crop all to same dimension: This crops all the images to the same dimension. This is mainly used for animations (e.g. when creating a sprite sheet). All the source images must be the same size for this to work (e.g. when an animation sequence is rendered by a 3D program then each rendered frame is the same size). This option will crop the animation sequence to the best size in which all the animations will fit. (See the example images below.)


Crop this alpha and less (0 to 255):

The alpha value to use when cropping the images. Pixels will only be cropped if they have this alpha value or less.

Create an additional mask image

If checked, then a mask texture will also be created. The mask texture is transparent and has solid white rectangles to indicate the source rects of the images. This can be used to see how the images have been packed onto the texture. It is saved in the same location as the texture and has the same file name with “_mask” appended to it.

File Sort Order:

The order in which the images will be added to the texture.
There are 3 options available:

1) Alphabetical: Sort the images alphabetically. This can be useful for adding an animation sequence when the files have been named sequentially (e.g. “frame1.png”, “frame2.png”, “frame3.png”).
2) Image Size (best): Sort the images based on their dimensions. It adds the biggest images to the texture first. This usually produces the best results (i.e. images are compactly packed on the texture) when the images have various sizes.
3) Random: Sort the images in a random order. It uses the Random Seed setting to initialise the random sequence. In theory, if the images in the folder remain the same and the seed is the same, then the images should always be positioned in the same locations on the texture.


Output Format:

NOTE: This is not used in the .css file.
The format of the sourceRect variable in the text file.
There are 5 formats available:

1) x y width height: The x and y position is the top-left position of the source rect on the texture. The width and height are the dimensions of the source rect. This is in pixels.
2) x, y, width, height: This is exactly the same as format #1 when it is used with the .xml and .json files. It only changes in the .txt file by adding a comma between the variables.
3) left top right bottom: The source rect's top-left and bottom-right positions on the texture. This is in pixels.
4) left, top, right, bottom: This is exactly the same as format #3 when it is used with the .xml and .json files. It only changes in the .txt file by adding a comma between the variables.
5) u1, v1, u2, v2: The UV coordinates of the source rect on the texture. The u1 and v1 are the top-left coordinates and the u2 and v2 are the bottom-right coordinates. These are in the range 0.0 to 1.0.


Prefix:

This behaves differently in the .txt file than in the .xml, .json and .css files. In the .txt file this is added to the front of each line of text. In the .xml, .json and .css files this is added to the front of each “id” variable. Illegal characters are replaced with an underscore “_” in the .xml, .json and .css files. The Prefix can also be empty.

For example, if the Prefix is “player_” and the source images are named “frame1.png”, “frame2.png” and “frame3.png”:

The lines in the .txt file will be:
player_frame1=”1 1 20 25”
player_frame2=”22 1 35 26”
player_frame3=”37 1 50 25”

The ids in the .xml file will be:
id = "player_frame1"
id = "player_frame2"
id = "player_frame3"

The ids in the .json file will be:
"id": "player_frame1"
"id": "player_frame2"
"id": "player_frame3"

The class names in the .css file will be:
.player_frame1
.player_frame2
.player_frame3

Postfix:

This behaves differently in the .txt file than in the .xml, .json and .css files. In the .txt file this is added to the end of each line of text. In the .xml, .json and .css files this is added to the end of each “id” variable. Illegal characters are replaced with an underscore “_” in the .xml and .json files. The Postfix can also be empty.

For example, if the Postfix is “;” and the source images are named “frame1.png”, “frame2.png” and “frame3.png”:

The lines in the .txt file will be:
frame1=”1 1 20 25”;
frame2=”22 1 35 26”;
frame3=”37 1 50 25”;

The ids in the .xml file will be:
id = "frame1_"
id = "frame2_"
id = "frame3_"

The ids in the .json file will be:
"id": "frame1_"
"id": "frame2_"
"id": "frame3_"

The class names in the .css file will be:
.frame1_
.frame2_
.frame3_

Convert tabs to spaces

If checked, then all tabs in the text file will be replaced with spaces.

Tab Size:

The number of spaces to use when replacing a tab with spaces.

Change Case:

This option changes the case (e.g. upper case) of the image's file name (in memory, not on disk) before it is used for the “id” variable. It also changes the case of the Prefix and Postfix.

The following examples are used to illustrate the options below:
Image file name = stoneCastle.tga
Prefix = ForestLevel_
Postfix = _Small

The available options are:

1) No: The cases remain unchanged. (Example: id = “ForestLevel_stoneCastle_Small”)
2) Make UPPER case: This changes the image's file name, Prefix and Postfix to upper case. The “id” variable will therefore be upper case. (Example: id = “FORESTLEVEL_STONECASTLE_SMALL”)
3) Make lower case: This changes the image's file name, Prefix and Postfix to lower case. The “id” variable will therefore be lower case. (Example: id = “forestlevel_stonecastle_small”)
4) UnChaos v1.0.1: This is for backwards compatibility with UnChaos version 1.0.1. It changes the file name to upper case. It does not change the Prefix and Postfix. (Example: id = “ForestLevel_STONECASTLE_Small”)


CSS background url path prefix:

This is added to the front of the background url path in the .css file. This can also be empty.

Example images

Below are example images which illustrate how UnChaos packs images onto a texture.

The grey rectangles in the background represent the transparent pixels. The green rectangles represent the source rects.

The source images
The source images. Each image's size is 78 x 96.


No cropping
The images packed onto a 512 x 256 texture, using the “No” cropping option. Each source rect size is 78 x 96.


Cropped
The images packed onto a 512 x 256 texture, using the “Yes” cropping option. Each source rect is a different size.


Cropped to the same size
The images packed onto a 512 x 256 texture, using the “Crop all to same dimension” cropping option. Each source rect size is 66 x 90.


Text file example

Here is an example of a .txt file created by UnChaos.

// Sorting order: Alphabetical

player_frame01 = "3 3 51 87";
player_frame02 = "57 3 45 90";
player_frame03 = "105 3 39 90";
player_frame04 = "147 3 51 87";
player_frame05 = "201 3 66 87";
player_frame06 = "270 3 48 90";
player_frame07 = "321 3 39 90";
player_frame08 = "363 3 42 87";


XML file example

Here is an example of an .xml file created by UnChaos.

<?xml version="1.0" encoding="ISO-8859-1"?>
<root>

<image id = "player_frame01">

<sourceRect x = "3" y = "3" width = "51" height = "87"></sourceRect>
<drawOffset x = "9" y = "9"></drawOffset>
<size width = "51" height = "87"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame02">
<sourceRect x = "57" y = "3" width = "45" height = "90"></sourceRect>
<drawOffset x = "9" y = "6"></drawOffset>
<size width = "45" height = "90"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame03">
<sourceRect x = "105" y = "3" width = "39" height = "90"></sourceRect>
<drawOffset x = "15" y = "6"></drawOffset>
<size width = "39" height = "90"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame04">
<sourceRect x = "147" y = "3" width = "51" height = "87"></sourceRect>
<drawOffset x = "9" y = "9"></drawOffset>
<size width = "51" height = "87"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame05">
<sourceRect x = "201" y = "3" width = "66" height = "87"></sourceRect>
<drawOffset x = "3" y = "9"></drawOffset>
<size width = "66" height = "87"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame06">
<sourceRect x = "270" y = "3" width = "48" height = "90"></sourceRect>
<drawOffset x = "12" y = "6"></drawOffset>
<size width = "48" height = "90"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame07">
<sourceRect x = "321" y = "3" width = "39" height = "90"></sourceRect>
<drawOffset x = "15" y = "6"></drawOffset>
<size width = "39" height = "90"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
<image id = "player_frame08">
<sourceRect x = "363" y = "3" width = "42" height = "87"></sourceRect>
<drawOffset x = "15" y = "9"></drawOffset>
<size width = "42" height = "87"></size>
<originalSize width = "78" height = "96"></originalSize>
</image>
</root>


JSON file example

Here is an example of a .json file created by UnChaos.

[

{

"id": "player_frame01",
"sourceRect": {"x": 3, "y": 3, "width": 51, "height": 87},
"drawOffset": {"x": 9, "y": 9},
"size": {"width": 51, "height": 87},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame02",
"sourceRect": {"x": 57, "y": 3, "width": 45, "height": 90},
"drawOffset": {"x": 9, "y": 6},
"size": {"width": 45, "height": 90},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame03",
"sourceRect": {"x": 105, "y": 3, "width": 39, "height": 90},
"drawOffset": {"x": 15, "y": 6},
"size": {"width": 39, "height": 90},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame04",
"sourceRect": {"x": 147, "y": 3, "width": 51, "height": 87},
"drawOffset": {"x": 9, "y": 9},
"size": {"width": 51, "height": 87},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame05",
"sourceRect": {"x": 201, "y": 3, "width": 66, "height": 87},
"drawOffset": {"x": 3, "y": 9},
"size": {"width": 66, "height": 87},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame06",
"sourceRect": {"x": 270, "y": 3, "width": 48, "height": 90},
"drawOffset": {"x": 12, "y": 6},
"size": {"width": 48, "height": 90},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame07",
"sourceRect": {"x": 321, "y": 3, "width": 39, "height": 90},
"drawOffset": {"x": 15, "y": 6},
"size": {"width": 39, "height": 90},
"originalSize": {"width": 78, "height": 96}
},
{
"id": "player_frame08",
"sourceRect": {"x": 363, "y": 3, "width": 42, "height": 87},
"drawOffset": {"x": 15, "y": 9},
"size": {"width": 42, "height": 87},
"originalSize": {"width": 78, "height": 96}
}
]




CSS file example

Here is an example of a .css file created by UnChaos.

.player_frame01 {
background: url('imgs/player.png') no-repeat -3px -3px;
width: 51px;
height: 87px;
}
 
.player_frame02 {
background: url('imgs/player.png') no-repeat -57px -3px;
width: 45px;
height: 90px;
}
 
.player_frame03 {
background: url('imgs/player.png') no-repeat -105px -3px;
width: 39px;
height: 90px;
}
 
.player_frame04 {
background: url('imgs/player.png') no-repeat -147px -3px;
width: 51px;
height: 87px;
}
 
.player_frame05 {
background: url('imgs/player.png') no-repeat -201px -3px;
width: 66px;
height: 87px;
}
 
.player_frame06 {
background: url('imgs/player.png') no-repeat -270px -3px;
width: 48px;
height: 90px;
}
 
.player_frame07 {
background: url('imgs/player.png') no-repeat -321px -3px;
width: 39px;
height: 90px;
}
 
.player_frame08 {
background: url('imgs/player.png') no-repeat -363px -3px;
width: 42px;
height: 87px;
}


BMGLib details

BMGLib
Copyright 2000, 2001 M. Scott Heiman
All Rights Reserved

libTIFF is Copyright Sam Leffler and SGI
libJPEG is Copyright (C) 1991-1998, Thomas G. Lane and is part of the

Independent JPEG Group's software.
libPNG is Copyright (c) 1995, 1996 Guy Eric Schalnat, Group 42, Inc.
(libpng versions 0.5, May 1995, through 0.89c, May 1996)
Copyright (c) 1996, 1997 Andreas Dilger
(libpng versions 0.90, December 1996, through 0.96, May 1997)
Copyright (c) 1998, 1999 Glenn Randers-Pehrson
(libpng versions 0.97, January 1998, through 1.0.5, October 15, 1999)
zLib Copyright (C) 1995-1998 Jean-loup Gailly.
GeoTIFF is Copyright (c) 1999, Frank Warmerdam
libPROJ (used by GeoTIFF) is Copytight (c) 2000, Frank Warmerdam
libUnGif is Copyright (c) 1997, Eric S. Raymond


LouiseBrooks theme byThemocracy