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
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.
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
Raw data
{
"_id": null,
"home_page": "https://github.com/wo1fsea/PyTexturePacker",
"name": "PyTexturePacker",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "TexturePacker,cocos2d-x,sprite-sheet,texture-pack",
"author": "Quanyong Huang",
"author_email": "quanyongh@foxmail.com",
"download_url": "https://files.pythonhosted.org/packages/a8/c0/c26969414cd23c13d8e68fc74b1a2766478397d91eb6a46cab0042af2b94/PyTexturePacker-1.2.1.tar.gz",
"platform": null,
"description": "PyTexturePacker |pypi-status| |build-status| |docs-status|\n==========================================================\n\nPyTexturePacker is an open source python package, released under the MIT License.\n\nA subset of feature of TexturePacker_ has been implemented in this package.\n\n**Now! the cpp version is available, visit** CppTexturePacker_ **for more infomation.**\n\n.. _TexturePacker: https://www.codeandweb.com/texturepacker\n.. _CppTexturePacker: https://github.com/wo1fsea/CppTexturePacker\n\nFeatures\n========\n\nMaxRectsBinPack algorithm is used to generate sprite sheet in this package.\n\nMaxRectsBinPack\n---------------\n\nMaxRectsBinPack is currently the best packing algorithm.\nIt tries to use the least texture space by applying different heuristics when placing the sprites.\n\n- MaxRects\n\n - Best-known algorithm for packing textures\n - Is fast and has a high packing ratio\n - Enable rotation for best results\n\n\nInstallation\n============\n\nInstall Pillow with pip:\n\n.. code:: bash\n\n $ pip install PyTexturePacker\n\n\nUsage\n=====\n\nHere comes an example of using PyTexturePacker to pack texture images from a directory.\n\n.. code:: python\n\n from PyTexturePacker import Packer\n\n def pack_test():\n # create a MaxRectsBinPacker\n packer = Packer.create(max_width=2048, max_height=2048, bg_color=0xffffff00)\n # pack texture images under directory \"test_case/\" and name the output images as \"test_case\".\n # \"%d\" in output file name \"test_case%d\" is a placeholder, which is the atlas index, starting with 0.\n packer.pack(\"test_case/\", \"test_case%d\")\n\n\nPacker Setting\n==============\n\nbg_color\n--------\n\nThe background color of output image. The pixels of the empty area in the output image will be filled with bg_color.\nThe default value is 0x00000000, which is in format of \"RGBA\". A tuple of values can also be accepted, like (R, G, B, A).\n\ntexture_format\n--------------\n\nChoose the texture format that the output file will use, for example \".jpg\".\nThe default texture format is \".png\".\n\nmax_width\n---------\n\nSets the maximum width for the texture, default is 4096.\n\nmax_height\n----------\n\nSets the maximum height for the texture, default is 4096.\n\nenable_rotated\n--------------\n\nAllows 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.\n\nforce_square\n------------\n\nForces the texture to have a squared size.\n\nborder_padding\n--------------\n\nBorder 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.\n\nshape_padding\n-------------\n\nShape 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.\nUse a value of at least 2 to avoid dragging in pixels from neighbor sprites when using OpenGL rendering.\n\ninner_padding\n-------------\n\nAdds transparent pixels to the inside of the sprite, growing it. Default is 0.\n\nThere are two uses for this:\n\n- 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.\n- 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.\n\ntrim_mode\n---------\n\nRemoves transparent pixels from a sprite's border.\nThis shrinks the sprite's size, allows tighter packing of the sheet, and speeds up rendering since transparent pixels don't need to be processed.\nPixels with an alpha value below this value will be considered transparent when trimming the sprite.\nAllowed values: 0 to 255, default is 0. When it's set to 0, the trim mode is disabled.\nVery useful for sprites with nearly invisible alpha pixels at the borders.\n\nreduce_border_artifacts\n-----------------------\n\nAdds color to transparent pixels by repeating a sprite's outer color values.\nThese color values can reduce artifacts around sprites and removes dark halos at transparent borders. This feature is also known as \"Alpha bleeding\".\n\nextrude\n-------\n\nExtrude repeats the sprite's pixels at the border. Sprite's size is not changed.\n\nThere are two uses for this:\n\n- Reduce flickering in some cases where sprites have to be put next to each other in the final program.\n- 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.\n\natlas_format\n------------\n\nChoose 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.\nThe default texture config output format is \"plist\".\n\natlas_ext\n---------\n\nForces the atlas to use this extension regardless of the format.\nIf not provided, the atlas will use the default extension for the chosen format.\n\nContribute\n==========\n\n- Issue Tracker: github.com/wo1fsea/PyTexturePacker/issues\n- Source Code: github.com/wo1fsea/PyTexturePacker\n\nAny types of contribution are welcome. Thanks.\n\n\nSupport\n=======\n\nIf you are having issues, please let us know.\nPlease feel free to contact me. email: quanyongh@foxmail.com\n\n\nLicense\n=======\n\nThe 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.\n\n.. _here: http://opensource.org/licenses/MIT\n\n\n.. |build-status| image:: https://github.com/wo1fsea/PyTexturePacker/actions/workflows/test.yml/badge.svg?branch=master\n :target: https://github.com/wo1fsea/PyTexturePacker/actions/workflows/test.yml\n :alt: Build status\n.. |docs-status| image:: https://readthedocs.org/projects/pytexturepacker/badge/?version=master\n :target: http://pytexturepacker.readthedocs.io/\n :alt: Documentation Status\n.. |pypi-status| image:: https://badge.fury.io/py/PyTexturePacker.svg\n :target: https://pypi.org/project/pytexturepacker/\n :alt: PyPI Status\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "an package to create sprite sheets or sprite atlases",
"version": "1.2.1",
"project_urls": {
"Download": "https://github.com/wo1fsea/PyTexturePacker/releases/tag/v1.2.1",
"Homepage": "https://github.com/wo1fsea/PyTexturePacker"
},
"split_keywords": [
"texturepacker",
"cocos2d-x",
"sprite-sheet",
"texture-pack"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5988326a1459e27cfa470d9f0bc3343c47c1bfd2e1d6766705387cc7b9da7f34",
"md5": "486a85123f0d67a1a344ba726c391aaf",
"sha256": "53db04d8ea130c4cf1bd48343997914a7ed2d63effd424e452bb8195f5c74a45"
},
"downloads": -1,
"filename": "PyTexturePacker-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "486a85123f0d67a1a344ba726c391aaf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 18229,
"upload_time": "2024-02-14T15:34:33",
"upload_time_iso_8601": "2024-02-14T15:34:33.523569Z",
"url": "https://files.pythonhosted.org/packages/59/88/326a1459e27cfa470d9f0bc3343c47c1bfd2e1d6766705387cc7b9da7f34/PyTexturePacker-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a8c0c26969414cd23c13d8e68fc74b1a2766478397d91eb6a46cab0042af2b94",
"md5": "693318ebd0b832adacc710f958c875a7",
"sha256": "9a3b512c8644f462bd3b974d71f60a0083734e13df5308b75f01f3e744b2b55c"
},
"downloads": -1,
"filename": "PyTexturePacker-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "693318ebd0b832adacc710f958c875a7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16075,
"upload_time": "2024-02-14T15:34:35",
"upload_time_iso_8601": "2024-02-14T15:34:35.244636Z",
"url": "https://files.pythonhosted.org/packages/a8/c0/c26969414cd23c13d8e68fc74b1a2766478397d91eb6a46cab0042af2b94/PyTexturePacker-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 15:34:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "wo1fsea",
"github_project": "PyTexturePacker",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pytexturepacker"
}
JSON
