PyTexturePacker |pypi-status| |build-status| |docs-status|
==========================================================

PyTexturePacker is an open source python package, released under the MIT License.

A subset of feature of TexturePacker_ has been implemented in this package.

**Now! the cpp version is available, visit** CppTexturePacker_ **for more infomation.**

.. _TexturePacker: https://www.codeandweb.com/texturepacker
.. _CppTexturePacker: https://github.com/wo1fsea/CppTexturePacker

Features
========

MaxRectsBinPack algorithm is used to generate sprite sheet in this package.

MaxRectsBinPack
---------------

MaxRectsBinPack is currently the best packing algorithm.
It tries to use the least texture space by applying different heuristics when placing the sprites.

- MaxRects

    - Best-known algorithm for packing textures
    - Is fast and has a high packing ratio
    - Enable rotation for best results


Installation
============

Install Pillow with pip:

.. code:: bash

    $ pip install pytexturepacker-xxl


Usage
=====

Here comes an example of using PyTexturePacker to pack texture images from a directory.

.. code:: python

    from PyTexturePacker import Packer

    def pack_test():
        # create a MaxRectsBinPacker
        packer = Packer.create(max_width=2048, max_height=2048, bg_color=0xffffff00)
        # pack texture images under directory "test_case/" and name the output images as "test_case".
        # "%d" in output file name "test_case%d" is a placeholder, which is the atlas index, starting with 0.
        # def pack(self, input_images, output_name, output_path="", input_base_path=None, ignore_image_ext=False):
        packer.pack("test_case/", "test_case%d")


Packer Setting
==============

bg_color
--------

The background color of output image. The pixels of the empty area in the output image will be filled with bg_color.
The default value is 0x00000000, which is in format of "RGBA". A tuple of values can also be accepted, like (R, G, B, A).

texture_format
--------------

Choose the texture format that the output file will use, for example ".jpg".
The default texture format is ".png".

max_width
---------

Sets the maximum width for the texture, default is 4096.

max_height
----------

Sets the maximum height for the texture, default is 4096.

enable_rotated
--------------

Allows the rotating of sprites clockwise or counterclockwise by 90 degrees if they have a better fit in the texture. Might not be supported by all game/web frameworks.

force_square
------------

Forces the texture to have a squared size.

border_padding
--------------

Border padding is the space between the sprites and the border of the sprite sheet. Value adds transparent pixels around the borders of the sprite sheet. Default is 2.

shape_padding
-------------

Shape padding is the space between sprites. Value adds transparent pixels between sprites to avoid artifacts from neighbor sprites. The transparent pixels are not added to the sprites. Default is 2.
Use a value of at least 2 to avoid dragging in pixels from neighbor sprites when using OpenGL rendering.

inner_padding
-------------

Adds transparent pixels to the inside of the sprite, growing it. Default is 0.

There are two uses for this:

- It can help in preventing cut-off artifacts near the edges of scaled sprites. E.g. if your sprite has a few pixels along its own boundaries, scaling the sprite up or down won't let these pixels appear as gaps or cuts.
- It considerably reduces aliasing along the polygon edges when rotating trimmed or cropped sprites. E.g. if your sprite has many pixels along its own boundaries, it will be drawn more smoothly when rotating it.

trim_mode
---------

Removes transparent pixels from a sprite's border.
This shrinks the sprite's size, allows tighter packing of the sheet, and speeds up rendering since transparent pixels don't need to be processed.
Pixels with an alpha value below this value will be considered transparent when trimming the sprite.
Allowed values: 0 to 255, default is 0. When it's set to 0, the trim mode is disabled.
Very useful for sprites with nearly invisible alpha pixels at the borders.

reduce_border_artifacts
-----------------------

Adds color to transparent pixels by repeating a sprite's outer color values.
These color values can reduce artifacts around sprites and removes dark halos at transparent borders. This feature is also known as "Alpha bleeding".

extrude
-------

Extrude repeats the sprite's pixels at the border. Sprite's size is not changed.

There are two uses for this:

- Reduce flickering in some cases where sprites have to be put next to each other in the final program.
- Check if sprite outlines are OK. E.g. if you want to use sprites to create tilemaps this allows you to see if there are semi-transparent pixels at the borders of the tiles.

atlas_format
------------

Choose the texture config format that file will use. Available options "plist", "json" and "csv". Aditionally, you can use a custom function that will receive a dictionary and a path and handle the format in some custom way.
The default texture config output format is "plist".

atlas_ext
---------

Forces the atlas to use this extension regardless of the format.
If not provided, the atlas will use the default extension for the chosen format.

Contribute
==========

- Issue Tracker: github.com/wo1fsea/PyTexturePacker/issues
- Source Code: github.com/wo1fsea/PyTexturePacker

Any types of contribution are welcome. Thanks.


Support
=======

If you are having issues, please let us know.
Please feel free to contact me. email: quanyongh@foxmail.com


License
=======

The project is released under the terms of MIT License. You may find the content of the license here_, or `LICENSE.txt` inside the project directory.

.. _here: http://opensource.org/licenses/MIT


.. |build-status| image:: https://github.com/wo1fsea/PyTexturePacker/actions/workflows/test.yml/badge.svg?branch=master
    :target: https://github.com/wo1fsea/PyTexturePacker/actions/workflows/test.yml
    :alt: Build status
.. |docs-status| image:: https://readthedocs.org/projects/pytexturepacker/badge/?version=master
    :target: http://pytexturepacker.readthedocs.io/
    :alt: Documentation Status
.. |pypi-status| image:: https://badge.fury.io/py/PyTexturePacker.svg
    :target: https://pypi.org/project/pytexturepacker/
    :alt: PyPI Status