Atlas¶

New in version 1.1.0.

Atlas manages texture atlases: packing multiple textures into one. With it, you reduce the number of images loaded and speedup the application loading. This module contains both the Atlas class and command line processing for creating an atlas from a set of individual PNG files. The command line section requires the Pillow library, or the defunct Python Imaging Library (PIL), to be installed.

An Atlas is composed of 2 or more files:

a json file (.atlas) that contains the image file names and texture locations of the atlas.
one or multiple image files containing textures referenced by the .atlas file.

Definition of .atlas files¶

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 from the Kivy data/images/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 ...
    }
}

In this example, “defaulttheme-0.png” is a large image, with the pixels in the rectangle from (431, 224) to (431 + 59, 224 + 24) usable as atlas://data/images/defaulttheme/progressbar_background in any image parameter.

How to create an Atlas¶

Warning

The atlas creation requires the Pillow library (or the defunct Imaging/PIL library). This requirement will be removed in the future when the Kivy core Image is able to support loading, blitting, and 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 64x64 png files inside:

$ ls
images
$ 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 256x256 *.png
Atlas created at myatlas.atlas
1 image has been created
$ ls
bubble.png bubble-red.png button.png button-down.png myatlas.atlas
myatlas-0.png

As you can see, we get 2 new files: myatlas.atlas and myatlas-0.png. myatlas-0.png is a new 256x256 .png composed of all your images. If the size you specify is not large enough to fit all of the source images, more atlas images will be created as required e.g. myatlas-1.png, myatlas-2.png etc.

Note

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 specify the images by supplying the path:

a = Button(background_normal='images/button.png',
           background_down='images/button_down.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:

a = Button(background_normal='atlas://images/myatlas/button',
           background_down='atlas://images/myatlas/button_down')

In other words, the path to the images is replaced by:

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

Note

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. If the size is not large enough to fit all of the source images, more atlas images will created as required.

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¶

Filename of the current Atlas.

filename is an AliasProperty and defaults to None.

original_textures¶

List of original atlas textures (which contain the textures).

original_textures is a ListProperty and defaults to [].

New in version 1.9.1.

textures¶

List of available textures within the atlas.

textures is a DictProperty and defaults to {}.

« Asynchronous data loader

Cache manager »

Version

Quick search

Table Of Contents