Atlas

New in version 1.1.0.

Atlas is a class for managing textures atlases: packing multiple texture into one. With it, you are reducing the number of image to load and speedup the application loading.

An Atlas is composed of:

  • a json file (.atlas) that contain all the information about the image contained inside the atlas.
  • one or multiple atlas image associated to 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

Warning

The atlas creation require Imaging/PIL. This will be removed in the future when Kivy core Image will be able to support loading / blitting / save operation.

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

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

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

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

You can combine all the png 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
myatlas-0.png

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

Note

When using this script, the ids referenced in the atlas is the basename of the image, without the extension. So if you are going to give a filename ../images/button.png, the id for this image will be button.

How to use an atlas

Usually, you are doing something like this:

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

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

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

In our case, it will be:

atlas://images/myatlas/button

Note

In the atlas url, their is no need to put 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)

Bases: kivy.event.EventDispatcher

Manage texture atlas. See module documentation for more information.

static create(outname, filenames, size, padding=2)

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

Parameters :
outname: str

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

filenames: list

List of filename to put in the atlas

size: int

Size of an atlas image

padding: int, default to 2

Padding to put around each image.

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

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

filename

Filename of the current Atlas

filename is a AliasProperty, default to None

textures

List of available textures within the atlas.

textures is a DictProperty, default to {}