zebrafy
zebrafy copied to clipboard
Python library for converting PDF and images to and from Zebra Programming Language (ZPL).
|zebrafy_icon_64| Zebrafy
.. |zebrafy_icon_64| image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-64.png :alt: Zebrafy Logo
.. image:: https://github.com/miikanissi/zebrafy/actions/workflows/ci.yml/badge.svg :target: https://github.com/miikanissi/zebrafy/actions/workflows/ci.yml :alt: CI
.. image:: https://readthedocs.org/projects/zebrafy/badge/?version=latest :target: https://zebrafy.readthedocs.io/en/latest/?badge=latest :alt: Documentation Status
.. image:: https://img.shields.io/pypi/v/zebrafy :target: https://pypi.org/project/zebrafy :alt: Zebrafy PyPi Package
.. image:: https://img.shields.io/badge/license-LGPLv3-green :target: https://www.gnu.org/licenses/lgpl-3.0.en.html#license-text :alt: License
Zebrafy is a Python 3 library for converting PDF and images to and from
Zebra Programming Language (ZPL) <https://en.wikipedia.org/wiki/Zebra_Programming_Language>
_
graphic fields (^GF).
Zebrafy consists of three conversion tools:
- ZebrafyImage — convert an image into valid ZPL
- ZebrafyPDF — convert a PDF into valid ZPL
- ZebrafyZPL — convert valid ZPL graphic fields into images or PDF
If you want more control over the resulting ZPL data, ZebrafyImage and ZebrafyPDF support the following optional parameters:
+----------------------+--------------------------------------------------------------------------------------------------------------+
| Parameter | Description |
+======================+==============================================================================================================+
| format
| ZPL graphic field format type (default "ASCII"
) |
| | |
| | - "ASCII"
— ASCII hexadecimal (most compatible) |
| | - "B64"
— Base64 Binary |
| | - "Z64"
— Z64 compressed binary (best compression) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| invert
| Invert the black and white in the image/PDF output. (True
or False
, default False
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| dither
| Dither the result instead of hard limit on black pixels. (True
or False
, default True
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| threshold
| Black pixel threshold for image without dithering (0-255
, default 128
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| width
| Width of the image in the resulting ZPL, 0
to use original image/PDF width (default 0
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| height
| Height of the image in the resulting ZPL, 0
to use original image/PDF height (default 0
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| pos_x
| Pixel x position of the graphic field in resulting ZPL (default 0
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| pos_y
| Pixel y position of the graphic field in resulting ZPL (default 0
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| rotation
| Rotates the image by the specified degree (0
, 90
, 180
or 270
, default 0
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| complete_zpl
| Add ZPL header and footer or only get the ZPL graphic field output (True
or False
, default True
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
Additionally, ZebrafyPDF supports the following optional parameters:
+----------------------+--------------------------------------------------------------------------------------------------------------+
| Parameter | Description |
+======================+==============================================================================================================+
| split_pages
| Split the PDF into separate ZPL labels for each page (True
or False
, default False
) |
+----------------------+--------------------------------------------------------------------------------------------------------------+
Getting Started
Installation ^^^^^^^^^^^^
.. code-block:: console
pip install zebrafy
Dependencies ^^^^^^^^^^^^
Pip handles all dependencies automatically. This library is built on top of:
-
Pillow <https://pillow.readthedocs.io/>
_ — Python Imaging Library -
pypdfium2 <https://github.com/pypdfium2-team/pypdfium2>
_ — Python 3 binding toPDFium <https://pdfium.googlesource.com/pdfium/+/refs/heads/main>
_
Example Usage ^^^^^^^^^^^^^
Image to ZPL Graphic Field with ZebrafyImage """"""""""""""""""""""""""""""""""""""""""""""""
Convert image bytes into a complete ZPL string and save to file:
.. code-block:: python
from zebrafy import ZebrafyImage
with open("source.png", "rb") as image: zpl_string = ZebrafyImage(image.read()).to_zpl()
with open("output.zpl", "w") as zpl: zpl.write(zpl_string)
Example usage with optional parameters:
.. code-block:: python
from zebrafy import ZebrafyImage
with open("source.png", "rb") as image: zpl_string = ZebrafyImage( image.read(), format="Z64", invert=True, dither=False, threshold=128, width=720, height=1280, pos_x=100, pos_y=100, rotation=90, complete_zpl=True, ).to_zpl()
with open("output.zpl", "w") as zpl: zpl.write(zpl_string)
Alternatively, ZebrafyImage also accepts PIL Image as the image parameter instead of image bytes:
.. code-block:: python
from PIL import Image from zebrafy import ZebrafyImage
pil_image = Image.new(mode="RGB", size=(100, 100)) zpl_string = ZebrafyImage(pil_image).to_zpl()
with open("output.zpl", "w") as zpl: zpl.write(zpl_string)
PDF to ZPL Graphic Field with ZebrafyPDF """"""""""""""""""""""""""""""""""""""""""""
Convert PDF bytes into a complete ZPL string and save to file:
.. code-block:: python
from zebrafy import ZebrafyPDF
with open("source.pdf", "rb") as pdf: zpl_string = ZebrafyPDF(pdf.read()).to_zpl()
with open("output.zpl", "w") as zpl: zpl.write(zpl_string)
ZebrafyPDF conversion supports the same optional parameters as ZebrafyImage
conversion, with the addition of the split_pages
parameter to split the PDF pages:
.. code-block:: python
from zebrafy import ZebrafyPDF
with open("source.pdf", "rb") as pdf: zpl_string = ZebrafyPDF( pdf.read(), format="Z64", invert=True, dither=False, threshold=128, width=720, height=1280, pos_x=100, pos_y=100, rotation=90, complete_zpl=True, split_pages=True, ).to_zpl()
with open("output.zpl", "w") as zpl: zpl.write(zpl_string)
ZPL to PDF or Images with ZebrafyZPL """"""""""""""""""""""""""""""""""""""""
Convert all graphic fields from a valid ZPL file to PIL Images and save to image files:
.. code-block:: python
from zebrafy import ZebrafyZPL
with open("source.zpl", "r") as zpl: pil_images = ZebrafyZPL(zpl.read()).to_images() for count, pil_image in enumerate(pil_images): pil_image.save(f"output_{count}.png", "PNG")
Convert all graphic fields from a valid ZPL file to PDF bytes and save to PDF file:
.. code-block:: python
from zebrafy import ZebrafyZPL
with open("source.zpl", "r") as zpl: pdf_bytes = ZebrafyZPL(zpl.read()).to_pdf()
with open("output.pdf", "wb") as pdf: pdf.write(pdf_bytes)
Contributing and Issues
Contributions and bug reports are welcome and can be submitted on the
GitHub page <https://github.com/miikanissi/zebrafy>
_.
The project does not yet have a well-defined scope, and I'm open to new feature requests. Features currently in consideration are:
- HTML to ZPL conversion by implementing standard HTML elements into ZPL commands
- Extract text from a PDF to render it as a native ZPL command instead of graphic field
License
This source is released under the
GNU Lesser General Public License v3.0 <https://www.gnu.org/licenses/lgpl-3.0.en.html#license-text>
_.
Logo
.. image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-long.png :alt: Zebrafy Logo