Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/miikanissi/zebrafy
Python library for converting PDF and images to and from Zebra Programming Language (ZPL).
https://github.com/miikanissi/zebrafy
gfa pdf-converter python zebra-printer zebra-programming-language zpl zpl-programming-language
Last synced: 7 days ago
JSON representation
Python library for converting PDF and images to and from Zebra Programming Language (ZPL).
- Host: GitHub
- URL: https://github.com/miikanissi/zebrafy
- Owner: miikanissi
- License: lgpl-3.0
- Created: 2023-08-04T17:02:56.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-05-16T06:15:42.000Z (6 months ago)
- Last Synced: 2024-05-16T06:31:48.246Z (6 months ago)
- Topics: gfa, pdf-converter, python, zebra-printer, zebra-programming-language, zpl, zpl-programming-language
- Language: Python
- Homepage: https://zebrafy.readthedocs.io/
- Size: 2.44 MB
- Stars: 20
- Watchers: 2
- Forks: 4
- Open Issues: 1
-
Metadata Files:
- Readme: README.rst
- License: LICENSE.txt
Awesome Lists containing this project
README
|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) `_
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 |
+======================+=======================================================================================================================+
| ``dpi`` | Pixels per PDF canvas unit, defines resolution scaling of the PDF image (<72: compress, >72: stretch, default ``72``) |
+----------------------+-----------------------------------------------------------------------------------------------------------------------+
| ``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 `_ — Python Imaging Library
- `pypdfium2 `_ — Python 3 binding to
`PDFium `_
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,
dpi=72,
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 `_.
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 `_.
Logo
----
.. image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-long.png
:alt: Zebrafy Logo