Quick search


New in version 1.1.0.

Atlas is a class for managing texture atlases: packing multiple textures into one. With it, you reduce the number of images loaded and speedup the application loading.

An Atlas is composed of:

  • a json file (.atlas) that contains all the information about the images contained inside the atlas.
  • one or multiple atlas images associated with the atlas definition.

Definition of .atlas

A file with <basename>.atlas is a json file formatted like this:

    "<basename>-<index>.png": {
        "id1": [ <x>, <y>, <width>, <height> ],
        "id2": [ <x>, <y>, <width>, <height> ],
        # ...
    # ...

Example of the Kivy defaulttheme.atlas:

    "defaulttheme-0.png": {
        "progressbar_background": [431, 224, 59, 24],
        "image-missing": [253, 344, 48, 48],
        "filechooser_selected": [1, 207, 118, 118],
        "bubble_btn": [83, 174, 32, 32],
        # ... and more ...

How to create an Atlas


The atlas creation requires Imaging/PIL. This will be removed in the future when the Kivy core Image is able to support loading / blitting / saving operations.

You can directly use this module to create atlas files with this command:

$ python -m kivy.atlas <basename> <size> <list of images...>

Let’s say you have a list of images that you want to put into an Atlas. The directory is named images with lots of png files inside:

$ ls
$ cd images
$ ls
bubble.png bubble-red.png button.png button-down.png

You can combine all the png’s into one and generate the atlas file with:

$ python -m kivy.atlas myatlas 256 *.png
Atlas created at myatlas.atlas
1 image have been created
$ ls
bubble.png bubble-red.png button.png button-down.png myatlas.atlas

As you can see, we get 2 new files: myatlas.atlas and myatlas-0.png.


When using this script, the ids referenced in the atlas are the base names of the images without the extension. So, if you are going to name a file ../images/button.png, the id for this image will be button.

If you need path information included, you should include use_path as follows:

$ python -m kivy.atlas use_path myatlas 256 *.png

In which case the id for ../images/button.png will be images_button

How to use an Atlas

Usually, you would use the atlas as follows:

a = Button(background_normal='images/button.png',

In our previous example, we have created the atlas containing both images and put them in images/myatlas.atlas. You can use url notation to reference them:

# will search for the ``path/to/myatlas.atlas`` and get the image ``id``

In our case, it would be:



In the atlas url, there is no need to add the .atlas extension. It will be automatically append to the filename.

Manual usage of the Atlas

>>> from kivy.atlas import Atlas
>>> atlas = Atlas('path/to/myatlas.atlas')
>>> print(atlas.textures.keys())
['bubble', 'bubble-red', 'button', 'button-down']
>>> print(atlas['button'])
<kivy.graphics.texture.TextureRegion object at 0x2404d10>
class kivy.atlas.Atlas(filename)[source]

Bases: kivy.event.EventDispatcher

Manage texture atlas. See module documentation for more information.

static create(outname, filenames, size, padding=2, use_path=False)[source]

This method can be used to create an atlas manually from a set of images.

Parameters :
outname: str

Basename to use for .atlas creation and -<idx>.png associated images.

filenames: list

List of filenames to put in the atlas.

size: int or list (width, height)

Size of the atlas image.

padding: int, defaults to 2

Padding to put around each image.

Be careful. If you’re using a padding < 2, you might have issues with the borders of the images. Because of the OpenGL linearization, it might use the pixels of the adjacent image.

If you’re using a padding >= 2, we’ll automatically generate a “border” of 1px around your image. If you look at the result, don’t be scared if the image inside is not exactly the same as yours :).

use_path: bool, defaults to False

If True, the relative path of the source png file names will be included in the atlas ids rather that just in the file names. Leading dots and slashes will be excluded and all other slashes in the path will be replaced with underscores. For example, if use_path is False (the default) and the file name is ../data/tiles/green_grass.png, the id will be green_grass. If use_path is True, it will be data_tiles_green_grass.

Changed in version 1.8.0: Parameter use_path added


Filename of the current Atlas.

filename is an AliasProperty and defaults to None.


List of available textures within the atlas.

textures is a DictProperty and defaults to {}.