Kivy-examples 2.3.1.dev0__py3-none-any.whl

kivy/atlas.py

@@ -0,0 +1,456 @@
+'''
+Atlas
+=====
+
+.. versionadded:: 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>
+'''
+
+__all__ = ('Atlas', )
+
+import json
+from os.path import basename, dirname, join, splitext
+from kivy.event import EventDispatcher
+from kivy.logger import Logger
+from kivy.properties import AliasProperty, DictProperty, ListProperty
+import os
+
+
+# late import to prevent recursion
+CoreImage = None
+
+
+class Atlas(EventDispatcher):
+    '''Manage texture atlas. See module documentation for more information.
+    '''
+
+    original_textures = ListProperty([])
+    '''List of original atlas textures (which contain the :attr:`textures`).
+
+    :attr:`original_textures` is a :class:`~kivy.properties.ListProperty` and
+    defaults to [].
+
+    .. versionadded:: 1.9.1
+    '''
+
+    textures = DictProperty({})
+    '''List of available textures within the atlas.
+
+    :attr:`textures` is a :class:`~kivy.properties.DictProperty` and defaults
+    to {}.
+    '''
+
+    def _get_filename(self):
+        return self._filename
+
+    filename = AliasProperty(_get_filename, None)
+    '''Filename of the current Atlas.
+
+    :attr:`filename` is an :class:`~kivy.properties.AliasProperty` and defaults
+    to None.
+    '''
+
+    def __init__(self, filename):
+        self._filename = filename
+        super(Atlas, self).__init__()
+        self._load()
+
+    def __getitem__(self, key):
+        return self.textures[key]
+
+    def _load(self):
+        # late import to prevent recursive import.
+        global CoreImage
+        if CoreImage is None:
+            from kivy.core.image import Image as CoreImage
+
+        # must be a name finished by .atlas ?
+        filename = self._filename
+        assert filename.endswith('.atlas')
+        filename = filename.replace('/', os.sep)
+
+        Logger.debug('Atlas: Load <%s>' % filename)
+        with open(filename, 'r') as fd:
+            meta = json.load(fd)
+
+        Logger.debug('Atlas: Need to load %d images' % len(meta))
+        d = dirname(filename)
+        textures = {}
+        for subfilename, ids in meta.items():
+            subfilename = join(d, subfilename)
+            Logger.debug('Atlas: Load <%s>' % subfilename)
+
+            # load the image
+            ci = CoreImage(subfilename)
+            atlas_texture = ci.texture
+            self.original_textures.append(atlas_texture)
+
+            # for all the uid, load the image, get the region, and put
+            # it in our dict.
+            for meta_id, meta_coords in ids.items():
+                x, y, w, h = meta_coords
+                textures[meta_id] = atlas_texture.get_region(*meta_coords)
+
+        self.textures = textures
+
+    @staticmethod
+    def create(outname, filenames, size, padding=2, use_path=False):
+        '''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``.
+
+            .. versionchanged:: 1.8.0
+                Parameter use_path added
+        '''
+        # Thanks to
+        # omnisaurusgames.com/2011/06/texture-atlas-generation-using-python/
+        # for its initial implementation.
+        try:
+            from PIL import Image
+        except ImportError:
+            Logger.critical('Atlas: Imaging/PIL are missing')
+            raise
+
+        if isinstance(size, (tuple, list)):
+            size_w, size_h = list(map(int, size))
+        else:
+            size_w = size_h = int(size)
+
+        # open all of the images
+        ims = list()
+        for f in filenames:
+            fp = open(f, 'rb')
+            im = Image.open(fp)
+            im.load()
+            fp.close()
+            ims.append((f, im))
+
+        # sort by image area
+        ims = sorted(ims, key=lambda im: im[1].size[0] * im[1].size[1],
+                     reverse=True)
+
+        # free boxes are empty space in our output image set
+        # the freebox tuple format is: outidx, x, y, w, h
+        freeboxes = [(0, 0, 0, size_w, size_h)]
+        numoutimages = 1
+
+        # full boxes are areas where we have placed images in the atlas
+        # the full box tuple format is: image, outidx, x, y, w, h, filename
+        fullboxes = []
+
+        # do the actual atlasing by sticking the largest images we can
+        # have into the smallest valid free boxes
+        for imageinfo in ims:
+            im = imageinfo[1]
+            imw, imh = im.size
+            imw += padding
+            imh += padding
+            if imw > size_w or imh > size_h:
+                Logger.error(
+                    'Atlas: image %s (%d by %d) is larger than the atlas size!'
+                    % (imageinfo[0], imw, imh))
+                return
+
+            inserted = False
+            while not inserted:
+                for idx, fb in enumerate(freeboxes):
+                    # find the smallest free box that will contain this image
+                    if fb[3] >= imw and fb[4] >= imh:
+                        # we found a valid spot! Remove the current
+                        # freebox, and split the leftover space into (up to)
+                        # two new freeboxes
+                        del freeboxes[idx]
+                        if fb[3] > imw:
+                            freeboxes.append((
+                                fb[0], fb[1] + imw, fb[2],
+                                fb[3] - imw, imh))
+
+                        if fb[4] > imh:
+                            freeboxes.append((
+                                fb[0], fb[1], fb[2] + imh,
+                                fb[3], fb[4] - imh))
+
+                        # keep this sorted!
+                        freeboxes = sorted(freeboxes,
+                                           key=lambda fb: fb[3] * fb[4])
+                        fullboxes.append((im,
+                                          fb[0], fb[1] + padding,
+                                          fb[2] + padding, imw - padding,
+                                          imh - padding, imageinfo[0]))
+                        inserted = True
+                        break
+
+                if not inserted:
+                    # oh crap - there isn't room in any of our free
+                    # boxes, so we have to add a new output image
+                    freeboxes.append((numoutimages, 0, 0, size_w, size_h))
+                    numoutimages += 1
+
+        # now that we've figured out where everything goes, make the output
+        # images and blit the source images to the appropriate locations
+        Logger.info('Atlas: create an {0}x{1} rgba image'.format(size_w,
+                                                                 size_h))
+        outimages = [Image.new('RGBA', (size_w, size_h))
+                     for i in range(0, int(numoutimages))]
+        for fb in fullboxes:
+            x, y = fb[2], fb[3]
+            out = outimages[fb[1]]
+            out.paste(fb[0], (fb[2], fb[3]))
+            w, h = fb[0].size
+            if padding > 1:
+                out.paste(fb[0].crop((0, 0, w, 1)), (x, y - 1))
+                out.paste(fb[0].crop((0, h - 1, w, h)), (x, y + h))
+                out.paste(fb[0].crop((0, 0, 1, h)), (x - 1, y))
+                out.paste(fb[0].crop((w - 1, 0, w, h)), (x + w, y))
+
+        # save the output images
+        for idx, outimage in enumerate(outimages):
+            outimage.save('%s-%d.png' % (outname, idx))
+
+        # write out an json file that says where everything ended up
+        meta = {}
+        for fb in fullboxes:
+            fn = '%s-%d.png' % (basename(outname), fb[1])
+            if fn not in meta:
+                d = meta[fn] = {}
+            else:
+                d = meta[fn]
+
+            # fb[6] contain the filename
+            if use_path:
+                # use the path with separators replaced by _
+                # example '../data/tiles/green_grass.png' becomes
+                # 'data_tiles_green_grass'
+                uid = splitext(fb[6])[0]
+                # remove leading dots and slashes
+                uid = uid.lstrip('./\\')
+                # replace remaining slashes with _
+                uid = uid.replace('/', '_').replace('\\', '_')
+            else:
+                # for example, '../data/tiles/green_grass.png'
+                # just get only 'green_grass' as the uniq id.
+                uid = splitext(basename(fb[6]))[0]
+
+            x, y, w, h = fb[2:6]
+            d[uid] = x, size_h - y - h, w, h
+
+        outfn = '%s.atlas' % outname
+        with open(outfn, 'w') as fd:
+            json.dump(meta, fd)
+
+        return outfn, meta
+
+
+if __name__ == '__main__':
+    """ Main line program. Process command line arguments
+    to make a new atlas. """
+
+    import sys
+    from glob import glob
+    argv = sys.argv[1:]
+    # earlier import of kivy has already called getopt to remove kivy system
+    # arguments from this line. That is all arguments up to the first '--'
+    if len(argv) < 3:
+        print('Usage: python -m kivy.atlas [-- [--use-path] '
+              '[--padding=2]] <outname> '
+              '<size|512x256> <img1.png> [<img2.png>, ...]')
+        sys.exit(1)
+
+    options = {'use_path': False}
+    while True:
+        option = argv[0]
+        if option == '--use-path':
+            options['use_path'] = True
+        elif option.startswith('--padding='):
+            options['padding'] = int(option.split('=', 1)[-1])
+        elif option[:2] == '--':
+            print('Unknown option {}'.format(option))
+            sys.exit(1)
+        else:
+            break
+        argv = argv[1:]
+
+    outname = argv[0]
+    try:
+        if 'x' in argv[1]:
+            size = list(map(int, argv[1].split('x', 1)))
+        else:
+            size = int(argv[1])
+    except ValueError:
+        print('Error: size must be an integer or <integer>x<integer>')
+        sys.exit(1)
+
+    filenames = [fname for fnames in argv[2:] for fname in glob(fnames)]
+    ret = Atlas.create(outname, filenames, size, **options)
+    if not ret:
+        print('Error while creating atlas!')
+        sys.exit(1)
+
+    fn, meta = ret
+    print('Atlas created at', fn)
+    print('%d image%s been created' % (len(meta),
+          's have' if len(meta) > 1 else ' has'))