Table Of Contents
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 {}