图集¶

在 1.1.0 版本加入.

Atlas 管理纹理图集：将多个纹理打包成一个。通过它，您可以减少加载的图像数量并加快应用程序的加载速度。此模块包含 Atlas 类以及从一组单独的 PNG 文件创建图集的命令行处理功能。命令行部分要求安装 Pillow 库，或已废弃的 Python Imaging Library (PIL)。

Atlas 由两个或更多文件组成：

一个JSON文件（.atlas），其中包含图集（atlas）的图像文件名和纹理位置。
一个或多个包含纹理的图像文件，这些纹理由.atlas文件引用。

.atlas 文件的定义¶

一个以``<basename>.atlas``为名的文件是一个格式如下的JSON文件:

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

来自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 ...
    }
}

在这个例子中，“defaulttheme-0.png”是一张大图，其中从(431, 224)到(431 + 59, 224 + 24)的矩形区域内的像素，可以在任何图像参数中用作``atlas://data/images/defaulttheme/progressbar_background``。

如何创建Atlas？¶

警告

创建图集需要 Pillow 库（或已废弃的 Imaging/PIL 库）。未来当 Kivy 核心图像能够支持加载、位块传输和保存操作时，这一要求将被移除。

你可以直接使用此模块，通过以下命令创建图集文件：：

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

假设你有一组想要放入Atlas中的图片。该目录名为``images``，里面包含许多64x64像素的PNG文件:

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

你可以将所有 PNG 合并为一个，并使用以下命令生成 atlas 文件：

$ 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

如您所见，我们得到了两个新文件：myatlas.atlas 和 myatlas-0.png。myatlas-0.png 是一个新的256x256像素的.png文件，由您的所有图像组成。如果您指定的大小不足以容纳所有源图像，将根据需要创建更多的图集图像，例如 myatlas-1.png、myatlas-2.png 等。

备注

使用此脚本时，atlas中引用的id是图片的基础名称（不含扩展名）。因此，如果你打算将文件命名为``../images/button.png``，该图片的id将是``button``。

如果你需要包含路径信息，应按如下方式添加 use_path:

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

在哪种情况下，../images/button.png 的 id 会是 images_button。

如何使用Atlas？¶

通常，您会通过提供路径来指定图像：

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

在我们之前的示例中，我们创建了包含两张图片的图集，并将其放置在``images/myatlas.atlas``中。您可以使用URL表示法来引用它们：：

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

换句话说，图片的路径被替换为:

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

备注

在atlas的URL中，无需添加``.atlas``扩展名。系统会自动将其附加到文件名后。

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)[源代码]¶

基类：EventDispatcher

管理纹理图集。更多信息请参阅模块文档。

static create(outname, filenames, size, padding=2, use_path=False)[源代码]¶

该方法可用于从一组图像手动创建图集。

参数:

outname：str

用于创建``.atlas``文件及关联的``-<idx>.png``图像时使用的基础名称。

filenames：列表

要放入图集中的文件名列表。

size：整数或列表（宽度，高度）

图集图像的大小。如果该尺寸不足以容纳所有源图像，将根据需要创建更多的图集图像。

padding：整数，默认值为2

每个图像周围要添加的内边距。

请注意。如果您使用的内边距小于2，可能会遇到图像边框的问题。由于OpenGL线性化处理，它可能会使用相邻图像的像素。

如果你使用的内边距（padding）大于等于2，我们会在你的图片周围自动生成一个1像素的“边框”。查看结果时，如果里面的图片与你的原图不完全一致，请不要惊慌。

use_path：布尔值，默认为 False

如果为 True，则源 PNG 文件名的相对路径将包含在 atlas 的 id 中，而不仅仅是文件名本身。路径中的前导点和斜杠将被排除，路径中的所有其他斜杠将替换为下划线。例如，如果 use_path 为 False（默认值），且文件名为 ../data/tiles/green_grass.png，则 id 将为 green_grass。如果 use_path 为 True，则 id 将为 data_tiles_green_grass。

在 1.8.0 版本发生变更: 参数 use_path 已添加。

filename¶

当前Atlas的文件名。

filename 是一个 AliasProperty，默认值为 None。

original_textures¶

原始图集纹理列表（包含 textures）。

original_textures 是一个 ListProperty，默认值为 []。

在 1.9.1 版本加入.

textures¶

图集中可用的纹理列表。

textures 是一个 DictProperty，默认值为 {}。

« 异步数据加载器

缓存管理器 »

Version

Quick search

目录

图集¶

.atlas 文件的定义¶

如何创建Atlas？¶

如何使用Atlas？¶

Atlas 的手动使用¶