TXPK - Texture Packer

Highly configurable texture packer.

Preview

Packing many random images with random size

into one single image

How it works

The TXPK has a very large and complex command line interface to configure many properties. I don't advise using it, but if you want to, here is a more detailed version how the CLI can be used.

The easiest way to use the TXPK is to let it generate a project file. This can be done via the command line: >txpk.exe -g

This will generate a default .txpk project file which is nothing more than a .json file and looks like this:

{
	"recursiveFiles" : false,
	"inputDirectory" : "",
	"inputRegex" : ".+((.png)|(.jpg)|(.jpeg))$",
	"scriptDirectory" : "",
	"outputImageDirectory" : "",
	"outputDataDirectory" : "",
	"outputName" : "txpk_export",
	"outputImageFormat" : "png",
	"packingAlgorithm" : "Default",
	"dataExportAlgorithms" : [
		"Default"
		],
	"keyConversionAlgorithm" : "Default",
	"allowRotation" : false,
	"sizeConstraint" : 0,
	"constraintType" : 0,
	"clearColor" : "0",
	"trimImages" : false,
	"replaceSameTextures" : false
}

The project file has the same properties as the CLI. But is easier to use.

You can use the CLI to load the project: >txpk.exe -p"path/to/project.txpk"

The first CLI argument is implemented as a positional argument for the project. This allows you to just write: >txpk.exe "path/to/project.txpk".

Or you can just drop the project file onto the txpk.exe file.

But what are all these properties?

• recursiveFiles: whether the images should be searched recursively in the input directory or not.
• inputDirectory: the directory where to search the images.
• inputRegex: the regular expression to filter you images. You could actually allow every file (even non image files). The TXPK will report errors while loading.
• scriptDirectory: the directory where the TXPK will look for any Lua script files.
• outputImageDirectory: the directory where to put the packed resulting image.
• outputDataDirectory: the directory where to put any data file which are generated by data export algorithms.
• outputName: the name all data files will have.
• outputImageFormat: the format in which the resulting packed image will be saved as. Currently only .png, .jpg/.jpeg are supported.
• packingAlgorithm: the algorithm to pack the input textures with. You can use the CLI to learn more about which packing algorithms are supported: >txpk.exe -h. In the current version there are only two different packers SameSize and Blackspawn (named after and inspired by jimscott). Default is the Blackspawn packer. The detailed explanation for each packing algorithm can be found here.
• dataExportAlgorithms: none or more algorithms which can export data related to the packing process. Default exporter is the Json exporter, which exports the positions and sizes of the textures. Detailed explanation of any exporter can be found here.
• keyConversionAlgorithm: algorithm which converts the path/name of the texture to a key. Default is the FileWithoutExt converter which returns only the file name without extension. Detailed explanation of any key converter can be found here.
• allowRotation: whether the packing algorithm is allowed to rotate images or not. Visualized here.
• sizeConstraint: constrains the size of either width or height of the packed image.
• constraintType: None=0, Width=1, Height=2. The sizeConstraint will be ignored if the type is None.
• clearColor: the color to clear the resulting image with. Default is 0 (transparent black) which could also be written as 00000000 or 0x00000000. This number should represent a hexadecimal number. ff0000ff would clear the packed image with red.
• trimImages: if this option is enabled, any excess transparency will be cut at the texture borders. Visualized here.
• replaceSameTextures: this option removes every redundant image. This will be done after trimming the textures and can result in a smaller packed texture. Let's say you have an animation of a ball jumping up and down. There are probably some frames where the ball is slightly below the ball one frame earlier. After trimming they are mostly all on the same level, so it's the same texture, so they will all be replaced with one. An example can be found here.

Texture Trimming

The ox is the offset in x direction. This is a result of the source texture being trimmed on the left side. Same with the oy being the offset in y direction. The sw (source width) and sh (source height) are there so you can do stuff like moving the origin of the source texture to the center which would be impossible without knowing how large the texture was before. This data is hold by any texture. The texture still has the current x, y, width and height. These are the four you need to crop the image. The data can be exported by any exporter and for example the JsonExporter does exactly that.

Texture Rotation

This gif shows exactly whats happening when an image gets rotated. It gets rotated by 90° counter clockwise. If you wanted to crop and load the texture you had to rotate it back 90° clockwise. If not changed, the rotation point is by default in the upper left corner. So when importing the texture you have to rotate it and have to adjust the position because the rotation point is different. You can look at the example for more insight.

How to import packed textures containing rotated and trimmed images?

Please have a look at the example.

Did you just say Lua scripts?

The LuaExporter is able to load lua scripts so you can define custom exporters. More about the small scripting API can be found here and an example implementation can be found here. If you have created a valid lua script file you can add the file name without extension as an exporter in your project file. See the example for more insights.

I just want to pack my same sized textures in one image without any extras

Ok let's assume you have these 64x64 images with a lot of unnecessary transparency:

And you just want them to be packed in that order without trimming, rotating, replacing or whatever. You can use the following project file:

{
  "recursiveFiles": false,
  "inputDirectory": "",
  "inputRegex": ".+(.png)$",
  "scriptDirectory": "",
  "outputImageDirectory": "",
  "outputDataDirectory": "",
  "outputName": "sgb",
  "outputImageFormat": "png",
  "packingAlgorithm": "SameSize",
  "dataExportAlgorithms": [ ],
  "keyConversionAlgorithm": "",
  "allowRotation": false,
  "sizeConstraint": 0,
  "constraintType": 0,
  "clearColor": "0",
  "trimImages": false,
  "replaceSameTextures": false
}

Notice how inputDirectory and outputImageDirectory are not set. This can only work if the project file is in the same directory. Also notice the SameSize packing algorithm. This project outputs a sgb.png in the same directory which looks like this:

External

• Catch2 used for unit testing.
• dirent used for cross platform directory access.
• stb_image used for reading and writing images.
• json used for reading json files.
• Lua used for the Lua API.

Build

This project uses CMake to generate platform and compiler-specific build files. Also note that this project uses C++14 features such as auto and lambdas and therefore requires a C++14 compliant compiler in order to build successfully.

1. Clone the repository (and submodules)

   git clone --recurse-submodules -j8 https://github.com/Seng3694/TXPK
   

2. Generate the build files

   mkdir bin
   cd bin
   cmake -G "Your Generator" ../TXPK
   

   With Visual Studio 2017 you could for example use "Visual Studio 15" or "Visual Studio 15 Win64" generators.
3. Build the files

   cmake --build . --config Release
   

Alternatively if you have python installed, you could just execute the build.py file in the root directory.

If you want to build the tests you can pass cmake the -DBUILD_TXPK_TESTS=ON argument. If you want to build the example which is dependant on SFML 2.5 you need to pass cmake the -DBUILD_TXPK_EXAMPLE=ON and -DSFML_DIR=PATH/TO/SFML. Example for building everything:

cmake -G "Your Generator" -DBUILD_TXPK_TESTS=ON -DBUILD_TXPK_EXAMPLE=ON -DSFML_DIR="C:/Program Files/SFML/lib/cmake/SFML" ../TXPK

License

This software is licensed under the MIT License. See LICENSE for more information.