|zebrafy_icon_64| Zebrafy
=========================

.. |zebrafy_icon_64| image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-64.png
   :alt: Zebrafy Logo

**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                                                                                                  |
+======================+==============================================================================================================+
| ``compression_type`` | ZPL graphic field compression type (default ``"A"``)                                                         |
|                      |                                                                                                              |
|                      | - ``"A"`` — ASCII hexadecimal (most compatible)                                                              |
|                      | - ``"B"`` — Base64 Binary                                                                                    |
|                      | - ``"C"`` — 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``)                                       |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``complete_zpl``     | Add ZPL header and footer or only get the ZPL graphic field output (``True`` or ``False``, default ``True``) |
+----------------------+--------------------------------------------------------------------------------------------------------------+

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 to
  `PDFium <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(),
          compression_type="C",
          invert=True,
          dither=False,
          threshold=128,
          width=720,
          height=1280,
          pos_x=100,
          pos_y=100,
          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:

.. code-block:: python

  from zebrafy import ZebrafyPDF

  with open("source.pdf", "rb") as pdf:
      zpl_string = ZebrafyPDF(
          pdf.read(),
          compression_type="C",
          invert=True,
          dither=False,
          threshold=128,
          width=720,
          height=1280,
          pos_x=100,
          pos_y=100,
          complete_zpl=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
