Skip to content

Commit

Permalink
completly refreshed and updated
Browse files Browse the repository at this point in the history
  • Loading branch information
@Seng3694
Seng3694 committed Dec 9, 2018
1 parent ee9ffe4 commit 0ed880a
Show file tree
Hide file tree
Showing 761 changed files with 20,184 additions and 2,178 deletions.
3 changes: 1 addition & 2 deletions .gitattributes
View file
Original file line number Diff line number Diff line change
@@ -1,2 +1 @@
cmake/modules/* linguist-vendored=true
example/include/json.hpp linguist-vendored=true
ext/* linguist-vendored=true
6 changes: 6 additions & 0 deletions .gitmodules
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
[submodule "ext/CLI"]
path = ext/CLI
url = https://github.com/Seng3694/CLI
[submodule "ext/Catch2"]
path = ext/Catch2
url = https://github.com/catchorg/Catch2
17 changes: 13 additions & 4 deletions CMakeLists.txt
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,19 @@
cmake_minimum_required(VERSION 3.5)

project (TexturePacker)
project (TXPK)
set(ENGINE_NAME TXPKCore)

set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake/modules/")
set(CMAKE_CXX_STANDARD 14)
if(CMAKE_SIZEOF_VOID_P EQUAL 8)
set(CONFIGURATION "x64")
else()
set(CONFIGURATION "x86")
endif()

add_subdirectory(engine)
set(LUA_INCLUDE_DIR "${CMAKE_SOURCE_DIR}/ext/LuaJIT/include")
set(LUA_LIBRARIES "${CMAKE_SOURCE_DIR}/ext/LuaJIT/lib/${CONFIGURATION}/lua51_s.lib")

add_subdirectory(ext)
add_subdirectory(core)
add_subdirectory(tests)
add_subdirectory(app)
add_subdirectory(example)
21 changes: 21 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2018 Seng

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
217 changes: 150 additions & 67 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,108 +1,191 @@
# Sprite Sheet Packer #
# TXPK - Texture Packer #

Small project to pack textures into an atlas. Data is stored in JSON files.
Inspired by [aggsol][1]. Algorithm for packing from [blackspawn][2].
Highly configurable texture packer.

## How it works ##
## Preview ##

Packing many random images with random size

<img src="resources/textures.png" width="500"/>

Folder with 500 random generated rectangle images:
into one single image

<img src="resources/atlas.png" width="500"/>

## How it works ##

<img src="https://cdn.discordapp.com/attachments/425728769236664350/428126812619669505/images.PNG" width="500">
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][1] is a more detailed version how the CLI can be used.

Dragging the folder on the TexturePacker.exe will create an `atlas.png` and an `atlas.json`:
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`

<img src="https://cdn.discordapp.com/attachments/425728769236664350/428126828184600586/atlas.png"
width="500">
This will generate a default `.txpk` project file which is nothing more than a `.json` file and looks like this:

```json
{
"path": "path/to/textures",
"bin": [
{
"path": "202.png",
"x": 0,
"y": 0,
"w": 97,
"h": 97,
"flip": 0
},
{
"path": "444.png",
"x": 0,
"y": 97,
"w": 92,
"h": 100,
"flip": 0
},

"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 packer can be executed via command line with the following arguments:
The project file has the same properties as the CLI. But is easier to use.

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

`arg2: allowFlip (default=0 => no flip)` (90° spin)
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"`.

`arg3: outputName (default="atlas")`
Or you can just drop the project file onto the `txpk.exe` file.

`arg4: fileRegex (default="" => take all)`
## But what are all these properties? ##

`arg5: atlasBackgroundColor (default="00000000" => transparent)` (RGBA)
- `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][2]). `Default` is the `Blackspawn` packer. The detailed explanation for each packing algorithm can be found [here][3].
- `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][4].
- `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][5].
- `allowRotation`: whether the packing algorithm is allowed to rotate images or not. Visualized [here](#TextureRotation).
- `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](#TextureTrimming).
- `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][6].

Example:
```
>TexturePacker.exe "path/to/textures" "atlas" "1" "[2]{1}[0-9]{2}(.png)$" "ff00ffff"
```
### <a name="TextureTrimming"></a> Texture Trimming ###

<img src="resources/texturetrimming.png" width="400"/>

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][14] does exactly that.

Here all images with a file name like "2`xx`.png" in the directory "path/to/images" will be packed into an image named `atlas.png`. They will be flipped if it's appropriate and the resulting atlas will be cleared with magenta.
### <a name="TextureRotation"></a> Texture Rotation ###

Result atlas:
![rotation][7]

<img src="https://cdn.discordapp.com/attachments/425728769236664350/428126843707719680/atlas_args.png" width="500">
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][6] for more insight.

Looking at the atlas.json, there are some images which got flipped.
### How to import packed textures containing rotated and trimmed images? ###
Please have a look at the [example][6].

### Did you just say Lua scripts? ###
The [LuaExporter][9] is able to load lua scripts so you can define custom exporters. More about the small scripting API can be found [here][4] and an example implementation can be found [here][10]. 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][11] 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:

![sgb_unpacked][12]

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

```json
{
"path": "215.png",
"x": 456,
"y": 0,
"w": 82,
"h": 90,
"flip": 1
"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
}
```

The dimensions of the resulting atlas will always be squared except when all the textures share the same size. The dimensions will then be precalculated. For example 12 textures with 64x64 will be packed like this:
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:

<img src="https://cdn.discordapp.com/attachments/425728769236664350/428136997232836609/atlas.png">
![sgb][13]

## Build ##

Project uses [CMake][3] to generate platform and compiler-specific build files.
## External ##

- [Catch2][18] used for unit testing.
- [dirent][16] used for cross platform directory access.
- [stb_image][15] used for reading and writing images.
- [json][17] used for reading json files.
- [LuaJIT][19] used for the Lua API.

### Dependencies ###
## Build ##

Before building, make sure that [SFML 2.0+][4] is installed. 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.
This project uses [CMake][20] 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.

### Building on Windows (Visual Studio) ###
1. Ensure SFML is installed (if CMake fails to find SFML automatically, edit the `SFML_ROOT` variable in the [CMakeLists.txt][4])
**Warning**: The LuaJIT files which are included are built with a Visual Studio 2017 compiler for Windows x86 and x64. You probably have to build LuaJIT yourself if you are not on Windows.

2. Clone the repository
1. Clone the repository
```
git clone https://github.com/Seng3694/TexturePacker
git clone https://github.com/Seng3694/TXPK
```

3. Generate the build files (depending on your Visual Studio Version the `cmake` command differs. In this case `"Visual Studio 15"` will generate the Visual Studio 2017 project files)
2. Generate the build files
```
mkdir bin
cd bin
cmake -G "Your Generator" ../TXPK
```
mkdir build
cd build
cmake -G "Visual Studio 15" ../TexturePacker
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.

## License ##
This software is licensed under the MIT License. See [LICENSE][8] for more information.

4. Open the `.sln` file in Visual Studio and build the `ALL_BUILD` target.

[1]:https://github.com/aggsol/sprite-sheet-packer
[1]:app/CLI.md
[2]:http://blackpawn.com/texts/lightmaps/default.html
[3]:http://www.cmake.org/
[4]:http://www.sfml-dev.org/
[3]:core/include/TXPK/Packers/PACKERS.md
[4]:core/include/TXPK/Exporters/EXPORTERS.md
[5]:core/include/TXPK/KeyConverters/KEYCONVERTERS.md
[6]:example/README.md
[7]:resources/texturerotation.gif
[8]:LICENSE
[9]:core/include/TXPK/Exporters/LuaExporter.hpp
[10]:example/content/scripts/CustomCppHeaderExporter.lua
[11]:example/content/txpk/skeleton.txpk
[12]:resources/sgb_unpacked.png
[13]:resources/sgb.png
[14]:core/include/TXPK/Exporters/EXPORTERS.md

[15]:https://github.com/nothings/stb
[16]:https://github.com/tronkko/dirent/blob/master/include/dirent.h
[17]:https://github.com/nlohmann/json
[18]:https://github.com/catchorg/Catch2
[19]:http://luajit.org/
[20]:https://cmake.org/
Loading

0 comments on commit 0ed880a

Please sign in to comment.