Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mborgerson/textureatlas

A simple, cross-platform Python-based tool and C library for creating and using a texture atlas in your application or game. Distributed under the terms of the MIT license.
https://github.com/mborgerson/textureatlas

atlas c gamedev python tools

Last synced: 11 months ago
JSON representation

A simple, cross-platform Python-based tool and C library for creating and using a texture atlas in your application or game. Distributed under the terms of the MIT license.

Awesome Lists containing this project

README 

          
textureatlas

============



A simple, cross-platform tool and C library for creating and using a texture

atlas in your application or game. Distributed under the terms of the MIT

license.



What is a Texture Atlas?

------------------------



![](atlas.png)



A **Texture Atlas** is a texture (raster image) composed of multiple smaller

textures. By loading a single large texture, you can reduce resource load time

and improve performance by minimizing the number texture bind calls during

rendering. A texture atlas is accompanied by a map file that identifies the

coordinates and dimensions of each texture in the atlas.



textureatlas

---------------



**textureatlas** is a Python-based command line tool that can be used to

generate a texture atlas and accompanying map file from one or more images.

Images can be grouped together as individual frames of the same texture (for

animated sequences, for instance). Each texture has a name that is used to

identify the texture in the atlas map file.



### Map File



The **.map file** generated by textureatlas is a simple binary file or JSON file

intended to be loaded with libtextureatlas from your application. The format of

the map file is documented in the source code.



### Supported Image Formats 



textureatlas uses the [Python Imaging

Library](http://www.pythonware.com/products/pil/) to handle image manipulation,

loading, and saving and hence supports many commonly used image file formats

including **PNG, BMP, GIF, JPEG, and TGA**.



### System Requirements



* [Python 3.10+](http://www.python.org/)

* [Pillow](http://pillow.readthedocs.org/en/latest/)



### Usage



    usage: __main__.py [-h] [-o output-image-filename] [-m output-map-filename] [-mf {binary,json}]

                       [-im mode]

                       texture [texture ...]



    Packs many smaller images into one larger image, a Texture Atlas. A

    companion file (.map), is created that defines where each texture is

    mapped in the atlas.



    positional arguments:

      texture               filename of texture



    options:

      -h, --help            show this help message and exit

      -o output-image-filename, --output-image-filename output-image-filename

                            output image filename (atlas.png)

      -m output-map-filename, --output-map-filename output-map-filename

                            output map filename (atlas.map)

      -mf {binary,json}, --map-format {binary,json}

                            format of map output

      -im mode, --image-mode mode

                            output file mode (RGBA)



#### Texture Parameter Format



The format of a **texture parameter** is as follows:



    [=]

    [=]" "



The `` of a texture is used to identify the texture in the texture atlas

map file. If you omit the `` of the texture, the filename of the first

frame, without the extension, will be used.



##### Example 1



    python -m textureatlas crate=texture1.png texture2.png



This example generate an atlas containing two textures, each of one frame,

with names 'crate' and 'texture2', respectively.



You may specify additional frames of a texture (e.g. for animated sequences) by

enclosing the filenames of the frames in quotes.



##### Example 2



    python -m textureatlas "texture_frame0.png texture_frame1.png" texture2.png



This example generate an atlas containing two textures. The first texture,

named 'texture_frame0', contains two frames. The second texture, named

'texture2', contains only a single frame.



##### Example 3



    python -m textureatlas apple=picture_of_an_apple.png fire="fire0.png fire1.png"



This example generate an atlas containing two textures. The first texture,

named 'apple', contains only a single frame. The second texture, named

'fire', contains two frames.



Using command-line tools, you can easily specify multiple frames for a texture

from a directory listing.



##### Example 4



    python -m textureatlas fire="`ls sample/fire/*.png | xargs`"



This example list all the .png files in the sample/fire directory as frames

for the 'fire' texture.



libtextureatlas

---------------



**libtextureatlas** is a small C library with a simple API for loading and

accessing a binary texture atlas map file created by textureatlas. It has no

dependencies on other libraries and can be easily integrated with your existing

project, especially if you are using [CMake](http://www.cmake.org/).



Please note that libtextureatlas will *not* load the image data of the texture,

just the map file. There exist several good libraries for loading images; for

loading and decompressing PNG images, you may be interested in

[LodePNG](http://lodev.org/lodepng/).



### Example Usage



#### Loading a Texture Atlas Map File



    texture_atlas_t *ta;

    int result;



    result = texture_atlas_load("atlas.map", &ta);

    if (result) return 1;



#### Looking Up a Texture by Name



    texture_atlas_texture_t *texture;



    texture = texture_atlas_lookup(ta, "blaster");

    if (texture == NULL)

    {

        free(ta);

        return 1;

    }



#### Stepping Through Texture Frames



    texture_atlas_texture_t *texture;

    texture_atlas_frame_t *frame;

    unsigned int i;



    for (i=0; i < texture->num_frames; i++)

    {

        frame = texture->frames + i;

        printf("Frame %d is at %d, %d.\n", i, frame->x, frame->y);

    }



License

-------



Licensed under the terms of the MIT license:



    The MIT License (MIT)



    Copyright (c) 2014-2025 Matt Borgerson



    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.



Resources

---------



* [nVidia Whitepaper](https://developer.nvidia.com/sites/default/files/akamai/tools/files/Texture_Atlas_Whitepaper.pdf) on

  batching using texture atlases.