About This File
Go to GitHub for the latest version!
Stexatlaser (Stex)
Stexatlaser (stex-atlaser, a play on 'spectacular'), or simply Stex, is a simple tool for generating a (Klei) TEX format atlas and its key from a simple folder structure with no external dependencies required.
It uses an implementation of the MaxRects algorithm to efficiently pack each input element image into a larger atlas image, with as little wasted space as possible. Some empty space is inevitable given that atlases must have power-of-two dimensions.
It can also reverse the process and extract element images from an atlas using its key.
Usage
Stex uses the following syntax scheme:
stex <global options> [command] <command options>
The order of switches within each options section does not matter.
Basic Usage
Creating an Atlas
To create an atlas/key, start by setting up an input folder with the following structure:
.atlas_name |-- element1_name.png |-- element2_name.png |-- element3_name.png |-- ...
The available input formats can vary between systems, but most common formats are supported. See All Commands/Options (on GitHub) for more information.
As implied by the above, the folder name will be used as the atlas/key name, and the file names (with the extension ".tex", see Additional Information on GitHub) of each image will be used as their respective element names. All sub-folders and other files will be ignored.
Then run Stex with the pack command:
stex pack -i "X:\Path\To\Input\Directory" -o "X:\Path\To\Output\Directory"
When finished, the resultant atlas.tex and key.xml files will be placed in the specified output directory. You can then refer to each element by its name in LUA without concerning yourself where they actually were placed within the atlas.
If you want to see the element arrangement, try viewing the output with a TEX viewer.
Extracting an Atlas
To extract an atlas, run Stex with the unpack command:
stex unpack -i "X:\Path\To\Input\key.xml" -o "X:\Path\To\Output\Directory"
The key's corresponding atlas, which must be located alongside it, will be read automatically using the name specified within the key.
When finished, a subfolder with the name of the atlas will be created within the specified output directory that contains each individual element as a separate image. This results in the same structure used as input when packing an atlas.
Example
When packed, a folder of images that looks like this:
Will produce the files "test.tex" and "test.xml", which will look like:
test.tex (in a TEX capable viewer)
test.xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <Atlas> <Texture filename="test.tex"/> <Elements> <Element name="ear-0" u1="0.4375" u2="0.478027" v1="0.329102" v2="0.391113"/> <Element name="ear-0 - Copy" u1="0.472656" u2="0.513184" v1="0.266113" v2="0.328125"/> <Element name="ear-1" u1="0.372559" u2="0.40918" v1="0.941406" v2="0.999512"/> <Element name="ear-1 - Copy" u1="0.372559" u2="0.40918" v1="0.882324" v2="0.94043"/> <Element name="eye-0" u1="0.949707" u2="0.996094" v1="0.622559" v2="0.670898"/> <Element name="eye-0 - Copy" u1="0.413574" u2="0.459961" v1="0.580566" v2="0.628906"/> <Element name="eye-1" u1="0.198242" u2="0.244629" v1="0.173828" v2="0.216309"/> <Element name="eye-1 - Copy" u1="0.245605" u2="0.291992" v1="0.173828" v2="0.216309"/> <Element name="eye-2" u1="0.505859" u2="0.554199" v1="0.831055" v2="0.865723"/> ... (etc)
Special Feature
Stex has a mechanism for recording if atlases it creates are using pre-multiplied alpha so that it can be handled automatically when unpacking. See GitHub.
View on GitHub for more info: https://github.com/oblivioncth/Stexatlaser
If you believe you've found a bug, please file an issue there instead of just mentioning it here. Discussion otherwise is fine.
Edited by oblivioncth
What's New in Version 0.2.0.2 See changelog
Released
This release has existed for some time, but I forgot to upload it here in addition to GitHub. Woops.
Original Notes:
A couple bug fixes and a feature tweak:
- Fixed an off-by-one error when unpacking a TEX file that caused the output PNG files to be one pixel wider and taller than they were supposed to
- Changed the feature of adding a safety margin of transparent pixels to input images when packing a TEX to be optional, since it is generally not required and sometimes could cause TEX dimensions to be much larger than necessary (see -m switch in README.md)
- Debian binaries now correctly use static Qt libs so that the tool can be used without installing them on the end user's system
Recommended Comments
Create an account or sign in to comment
You need to be a member in order to leave a comment
Create an account
Sign up for a new account in our community. It's easy!
Register a new accountSign in
Already have an account? Sign in here.
Sign In Now