### Install Zebrafy

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/index.md

Install the Zebrafy library using pip. This command installs the package and its dependencies.

```console
pip install zebrafy
```

--------------------------------

### Install Zebrafy using pip

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/usage.md

Install the Zebrafy library using pip. This command should be run in your project's virtual environment.

```console
(.venv) $ pip install zebrafy
```

--------------------------------

### Convert Image to ZPL using ZebrafyImage

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Use ZebrafyImage to convert image bytes or PIL Image objects into ZPL strings. Supports various encoding formats and customization options. Set `complete_zpl=False` to get only the raw `^GF` field.

```python
from PIL import Image
from zebrafy import ZebrafyImage

# --- From file bytes (minimal) ---
with open("label.png", "rb") as f:
    zpl = ZebrafyImage(f.read()).to_zpl()
with open("label.zpl", "w") as f:
    f.write(zpl)
# Output: "^XA\n^FO0,0^GFA,...^FS\n^XZ\n"
```

```python
# --- From file bytes (all options) ---
with open("label.png", "rb") as f:
    zpl = ZebrafyImage(
        f.read(),
        format="Z64",          # Best compression
        invert=False,          # Keep original black/white
        dither=False,          # Hard threshold instead of dithering
        threshold=128,         # Pixels > 128 become white
        width=720,             # Scale to 720 px wide
        height=1280,           # Scale to 1280 px tall
        pos_x=50,              # Place field 50 px from left
        pos_y=50,              # Place field 50 px from top
        rotation=90,           # Rotate 90 degrees clockwise
        string_line_break=80,  # Insert newline every 80 chars
        complete_zpl=True,     # Include ^XA / ^XZ wrapper
    ).to_zpl()
```

```python
# --- From a PIL Image directly ---
pil_image = Image.new(mode="RGB", size=(200, 100), color=(255, 255, 255))
zpl = ZebrafyImage(pil_image, format="B64").to_zpl()
```

```python
# --- Get only the graphic field (no ^XA/^XZ) ---
with open("label.png", "rb") as f:
    gf_only = ZebrafyImage(f.read(), complete_zpl=False).to_zpl()
# Output: "^FO0,0^GFA,...^FS"
```

```python
# --- Error handling ---
try:
    bad = ZebrafyImage(b"", format="ASCII")
except ValueError as e:
    print(e)  # "Image cannot be empty."

try:
    bad = ZebrafyImage(b"\x89PNG...", format="INVALID")
except ValueError as e:
    print(e)  # 'Format must be "ASCII","B64", or "Z64". INVALID was given.'
```

--------------------------------

### Round-trip ZPL conversion: Image to ZPL, then ZPL to Image

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Demonstrates converting a PNG image to ZPL format using ZebrafyImage, and then converting the generated ZPL back into an image using ZebrafyZPL. This verifies the integrity of the conversion process.

```python
from zebrafy import ZebrafyImage

with open("original.png", "rb") as f:
    zpl = ZebrafyImage(f.read(), format="ASCII").to_zpl()

recovered_images = ZebrafyZPL(zpl).to_images()
recovered_images[0].save("recovered.png", "PNG")
```

--------------------------------

### ZebrafyImage Class Initialization

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Initializes the ZebrafyImage object to convert an image into ZPL format. It accepts various parameters to control the conversion process, including image source, ZPL format, dithering, thresholding, dimensions, positioning, rotation, and ZPL completeness.

```APIDOC
## Class: ZebrafyImage

### Description
Convert a PIL Image or image bytes into Zebra Programming Language (ZPL).

### Parameters
* **image** (bytes | Image) - Required - Image as a PIL Image or bytes object.
* **format** (str) - Optional - ZPL format parameter that accepts the following values, defaults to "ASCII":
  - "ASCII": ASCII hexadecimal - most compatible (default)
  - "B64": Base64 binary
  - "Z64": LZ77 / Zlib compressed base64 binary - best compression
* **invert** (bool) - Optional - Invert the black and white in resulting image, defaults to `False`
* **dither** (bool) - Optional - Dither the pixels instead of hard limit on black and white, defaults to `True`
* **threshold** (int) - Optional - Black pixel threshold for undithered image (`0-255`), defaults to `128`
* **width** (int) - Optional - Width of the image in the resulting ZPL. If `0`, use default image width, defaults to `0`
* **height** (int) - Optional - Height of the image in the resulting ZPL. If `0`, use default image height, defaults to `0`
* **pos_x** (int) - Optional - X position of the image on the resulting ZPL, defaults to `0`
* **pos_y** (int) - Optional - Y position of the image on the resulting ZPL, defaults to `0`
* **rotation** (int) - Optional - Additional rotation in degrees `0`, `90`, `180`, or `270`, defaults to `0`
* **string_line_break** (int) - Optional - Number of characters in graphic field content after which a new line is added, defaults to None.
* **complete_zpl** (bool) - Optional - Return a complete ZPL with header and footer included. Otherwise return only the graphic field, defaults to `True`

### Deprecated Parameters
* **compression_type** (str) - Deprecated since version 1.1.0: The compression_type parameter is deprecated in favor of format and will be removed in version 2.0.0.

### Properties
* **complete_zpl** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **dither** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **format** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **height** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **image** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **invert** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
* **pos_x** (property) - Returns a callable object that fetches the given attribute(s) from its operand.
```

--------------------------------

### Build ZPL Graphic Field with Line Breaks

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Demonstrates how to create a ZPL `^GFA` command string with specified line breaks for better readability or compatibility, using the ASCII format.

```python
# With line breaks every 40 characters
gf_lb = GraphicField(img, format="ASCII", string_line_break=40).get_graphic_field()
```

--------------------------------

### to_zpl() Method

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Converts a PIL Image or image bytes into Zebra Programming Language (ZPL) format.

```APIDOC
## to_zpl()

### Description
Convert PIL Image or image bytes into Zebra Programming Language (ZPL).

### Returns
* **str**: A complete ZPL file string which can be sent to a ZPL compatible printer or a ZPL graphic field if complete_zpl is not set.
```

--------------------------------

### Convert Image to ZPL with Optional Parameters

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/index.md

Converts image bytes to a ZPL string with various optional parameters for customization. These include format, inversion, dithering, threshold, dimensions, position, rotation, and line break settings.

```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,
        string_line_break=80,
        complete_zpl=True,
    ).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)
```

--------------------------------

### ZebrafyZPL Class

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Initializes a ZebrafyZPL object with ZPL data, enabling conversion of ZPL graphic fields to PDF and images.

```APIDOC
## class ZebrafyZPL(zpl_data: str)

### Description
Convert Zebra Programming Language (ZPL) graphic fields to PDF and images.

### Parameters
- **zpl_data** (str) - Required - A valid ZPL string.
```

--------------------------------

### Build ZPL Graphic Field in Z64 format

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Constructs a ZPL `^GFA` command string using the Z64 encoding, which provides the most compact representation of the bitmap data. Note that Z64 encoding is specific to Zebra printers.

```python
gf_z64 = GraphicField(img, format="Z64").get_graphic_field()
print(gf_z64[:40])
# ^GFA,48,256,8,:Z64:...
```

--------------------------------

### Build ZPL Graphic Field in ASCII format

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Creates a 1-bit PIL Image and uses the GraphicField class to generate a ZPL `^GFA` command string in ASCII format. This is useful for embedding raw bitmap data into ZPL.

```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

# Create a 1-bit image (required by GraphicField)
img = Image.new("1", (64, 32), color=1)  # White 64x32 bitmap

# ASCII format (most compatible)
gf_ascii = GraphicField(img, format="ASCII").get_graphic_field()
print(gf_ascii)
# ^GFA,256,256,8,ffffffffffffffff...^FS
```

--------------------------------

### Convert ZPL to PDF using ZebrafyZPL

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Reads a ZPL file and converts its content, including graphic fields, into a PDF document. The resulting PDF bytes are then written to a file.

```python
with open("label.zpl", "r") as f:
    pdf_bytes = ZebrafyZPL(f.read()).to_pdf()
with open("output.pdf", "wb") as f:
    f.write(pdf_bytes)
```

--------------------------------

### to_zpl()

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Converts PDF bytes into Zebra Programming Language (ZPL) format. The output can be a complete ZPL file or a ZPL graphic field.

```APIDOC
## to_zpl()

### Description
Convert PDF bytes to Zebra Programming Language (ZPL).

### Method
[Method signature: to_zpl() -> str]

### Returns
- **str**: A complete ZPL file string or a ZPL graphic field.
```

--------------------------------

### Handle ZebrafyPDF Errors

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Demonstrates how to catch exceptions when creating ZebrafyPDF objects with invalid data or parameters.

```python
try:
    bad = ZebrafyPDF(b"not a pdf")
except Exception as e:
    print(e)  # pypdfium2 raises on invalid PDF data
```

```python
try:
    bad = ZebrafyPDF(b"%PDF-1.4...", dpi=0)
except ValueError as e:
    print(e)  # "DPI must be a positive value. 0 was given."
```

```python
try:
    bad = ZebrafyPDF(b"%PDF-1.4...", dpi=800)
except ValueError as e:
    print(e)  # "DPI must be less than 720..."
```

--------------------------------

### Convert ZPL to Images using ZebrafyZPL

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Reads a ZPL file and converts its graphic fields (^GF) into a list of PIL Image objects. Each image is then saved to a PNG file.

```python
from zebrafy import ZebrafyZPL

# --- ZPL → PIL Images ---
with open("label.zpl", "r") as f:
    zpl_string = f.read()

images = ZebrafyZPL(zpl_string).to_images()
for i, img in enumerate(images):
    img.save(f"page_{i}.png", "PNG")
    print(f"Saved page_{i}.png — size: {img.size}")  # e.g. (720, 1280)
```

--------------------------------

### ZebrafyZPL — Convert ZPL graphic fields back to images or PDF

Source: https://context7.com/miikanissi/zebrafy/llms.txt

`ZebrafyZPL(zpl_data)` parses `^GF` commands from a ZPL string and reconstructs the original bitmap. `.to_images()` returns a list of PIL.Image.Image objects, and `.to_pdf()` returns PDF bytes. All three encoding formats (`ASCII`, `B64`, `Z64`) are supported.

```APIDOC
## ZebrafyZPL

### Description
Parses `^GF` commands from a ZPL string and reconstructs the original bitmap. Supports `ASCII`, `B64`, and `Z64` encoding formats with CRC validation for `B64`/`Z64` data.

### Methods
- **`to_images()`**: Returns a `list[PIL.Image.Image]` (one per matched `^GF` field).
- **`to_pdf()`**: Returns PDF bytes.

### Usage Examples

#### ZPL → PIL Images
```python
from zebrafy import ZebrafyZPL

with open("label.zpl", "r") as f:
    images = ZebrafyZPL(f.read()).to_images()
for i, img in enumerate(images):
    img.save(f"page_{i}.png", "PNG")
```

#### ZPL → PDF
```python
from zebrafy import ZebrafyZPL

with open("label.zpl", "r") as f:
    pdf_bytes = ZebrafyZPL(f.read()).to_pdf()
with open("output.pdf", "wb") as f:
    f.write(pdf_bytes)
```

#### Round-trip: image → ZPL → image
```python
from zebrafy import ZebrafyImage, ZebrafyZPL

with open("original.png", "rb") as f:
    zpl = ZebrafyImage(f.read(), format="ASCII").to_zpl()

recovered_images = ZebrafyZPL(zpl).to_images()
recovered_images[0].save("recovered.png", "PNG")
```

### Error Handling
- `ValueError`: Raised if no graphic field (`^GF`) is found or if CRC validation fails.
- `TypeError`: Raised if the input ZPL data is not a valid string.
```

--------------------------------

### Convert ZPL to PDF

Source: https://github.com/miikanissi/zebrafy/blob/master/README.rst

Converts ZPL code to PDF bytes and saves it to a file. Ensure ZPL data is read correctly before conversion.

```python
pdf_bytes = ZebrafyZPL(zpl.read()).to_pdf()

with open("output.pdf", "wb") as pdf:
    pdf.write(pdf_bytes)
```

--------------------------------

### Build ZPL Graphic Field in B64 format

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Generates a ZPL `^GFA` command string using base64 encoding for the bitmap data. This format is more compact than ASCII but requires decoding.

```python
gf_b64 = GraphicField(img, format="B64").get_graphic_field()
print(gf_b64[:40])
# ^GFA,60,256,8,:B64:...
```

--------------------------------

### Convert PDF to ZPL using ZebrafyPDF

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Use ZebrafyPDF to render PDF pages and convert them into ZPL strings. The `dpi` parameter controls rendering resolution, and `split_pages` can create separate ZPL labels for each PDF page.

```python
from zebrafy import ZebrafyPDF

# --- Single-page or multi-page PDF, all pages in one ZPL label ---
with open("document.pdf", "rb") as f:
    zpl = ZebrafyPDF(f.read()).to_zpl()
with open("document.zpl", "w") as f:
    f.write(zpl)
```

```python
# --- Multi-page PDF split into separate ZPL labels ---
with open("multi_page.pdf", "rb") as f:
    zpl = ZebrafyPDF(
        f.read(),
        split_pages=True,   # Each page becomes ^XA...^XZ
        complete_zpl=True,
    ).to_zpl()
# Output: "^XA\n^FO0,0^GFA,...^FS\n^XZ\n^XA\n^FO0,0^GFA,...^FS\n^XZ\n"
```

```python
# --- High-resolution rendering with Z64 compression ---
with open("document.pdf", "rb") as f:
    zpl = ZebrafyPDF(
        f.read(),
        format="Z64",
        dpi=150,           # Render at 150 DPI (stretches the image)
        invert=False,
        dither=True,
        width=812,
        height=1218,
        pos_x=0,
        pos_y=0,
        rotation=0,
        split_pages=True,
        complete_zpl=True,
    ).to_zpl()
```

```python
# --- Get raw graphic fields without wrapper ---
with open("document.pdf", "rb") as f:
    raw = ZebrafyPDF(f.read(), complete_zpl=False).to_zpl()
```

--------------------------------

### Convert ZPL to PIL Images

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/index.md

Converts graphic fields from a ZPL string into a list of PIL Image objects. Each image is then saved to a PNG file.

```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")
```

--------------------------------

### Handle ZebrafyZPL Errors

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Shows how to handle potential errors when using ZebrafyZPL, such as when no graphic field is found in the ZPL data, or when invalid input types are provided.

```python
try:
    ZebrafyZPL("^XA^XZ").to_images()
except ValueError as e:
    print(e)  # "Could not find a graphic field (^GF) in ZPL content."
```

```python
try:
    ZebrafyZPL(None)
except TypeError as e:
    print(e)  # "ZPL data must be a valid ZPL string..."
```

```python
# --- ZPL with broken CRC raises ValueError ---
broken_zpl = "^XA^FO0,0^GFA,4,4,1,:Z64:SGVsbG8=:FFFF^FS^XZ"
try:
    ZebrafyZPL(broken_zpl).to_images()
except ValueError as e:
    print(e)  # "CRC mismatch."
```

--------------------------------

### Convert PDF to ZPL with Optional Parameters and Page Splitting

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/index.md

Converts PDF bytes to a ZPL string with optional parameters, including page splitting. This allows each PDF page to be converted into a separate ZPL graphic field.

```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,
        string_line_break=80,
        complete_zpl=True,
        split_pages=True,
    ).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)
```

--------------------------------

### ZebrafyZPL Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/modules.md

Methods for processing and converting ZPL data within the Zebrafy library.

```APIDOC
## ZebrafyZPL.to_images()

### Description
Converts ZPL data to a list of images.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyZPL.to_pdf()

### Description
Converts ZPL data to PDF format.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyZPL.zpl_data

### Description
Gets the raw ZPL data.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)
```

--------------------------------

### Convert PDF to ZPL with Advanced Options

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/usage.md

Convert PDF bytes to ZPL string with advanced options like format, inversion, dithering, resolution, dimensions, position, rotation, and line break settings. The `split_pages` parameter can be used to split PDF pages into separate ZPL graphic fields. The output is saved to a .zpl file.

```python
from zebrafy import ZebrafyPDF

with open("source.pdf", "rb") as pdf:
    zpl_string = ZebrafyZPL(
        pdf.read(),
        format="Z64",
        invert=True,
        dither=False,
        threshold=128,
        dpi=72,
        width=720,
        height=1280,
        pos_x=100,
        pos_y=100,
        rotation=90,
        string_line_break=80,
        complete_zpl=True,
        split_pages=True,
    ).to_zpl()

with open("output.zpl", "w") as zpl:
    zpl.write(zpl_string)
```

--------------------------------

### Convert ZPL to PDF

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/index.md

Converts graphic fields from a ZPL string into PDF bytes, which are then saved to a PDF file.

```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)
```

--------------------------------

### GraphicField Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Methods for converting PIL images to ZPL graphic fields.

```APIDOC
## GraphicField.get_graphic_field()

### Description
Get a complete graphic field string for ZPL.

### Method
This is a method of the GraphicField class.

### Returns
- **str**: Complete graphic field string for ZPL.
```

--------------------------------

### ZebrafyPDF - Convert PDF to ZPL

Source: https://context7.com/miikanissi/zebrafy/llms.txt

The ZebrafyPDF class renders PDF pages and converts them into ZPL strings, delegating per-page conversion to ZebrafyImage. It offers options for DPI, page splitting, and ZPL formatting.

```APIDOC
## ZebrafyPDF

### Description
Renders each PDF page and converts it into a ZPL string. Supports per-page splitting and various customization options.

### Parameters
- `pdf_bytes` (bytes) - The PDF data to convert.
- `format` (str, optional) - Encoding format: "ASCII", "B64", or "Z64". Defaults to "ASCII".
- `invert` (bool, optional) - Whether to invert black and white. Defaults to False.
- `dither` (bool, optional) - Whether to apply dithering. Defaults to False.
- `threshold` (int, optional) - Threshold for dithering (0-255). Defaults to 128.
- `dpi` (int, optional) - Resolution for PDF rendering. Defaults to 72.
- `width` (int, optional) - Target width in pixels.
- `height` (int, optional) - Target height in pixels.
- `pos_x` (int, optional) - X position of the graphic field.
- `pos_y` (int, optional) - Y position of the graphic field.
- `rotation` (int, optional) - Rotation angle (0, 90, 180, 270).
- `string_line_break` (int, optional) - Maximum characters per line for ASCII format.
- `split_pages` (bool, optional) - Whether to wrap each page in its own `^XA`/`^XZ` pair. Defaults to False.
- `complete_zpl` (bool, optional) - Whether to include `^XA`/`^XZ` headers. Defaults to True.

### Method
`.to_zpl()` - Returns the ZPL string representation of the PDF pages.

### Request Example
```python
from zebrafy import ZebrafyPDF

# Single-page or multi-page PDF, all pages in one ZPL label
with open("document.pdf", "rb") as f:
    zpl = ZebrafyPDF(f.read()).to_zpl()

# Multi-page PDF split into separate ZPL labels
with open("multi_page.pdf", "rb") as f:
    zpl = ZebrafyPDF(f.read(), split_pages=True, complete_zpl=True).to_zpl()

# High-resolution rendering with Z64 compression
with open("document.pdf", "rb") as f:
    zpl = ZebrafyPDF(f.read(), format="Z64", dpi=150, split_pages=True, complete_zpl=True).to_zpl()

# Get raw graphic fields without wrapper
with open("document.pdf", "rb") as f:
    raw = ZebrafyPDF(f.read(), complete_zpl=False).to_zpl()
```
```

--------------------------------

### Compute CRC with Custom Polynomial

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Shows how to compute a CRC checksum using a non-default polynomial, which can be useful for specific ZPL variants or custom implementations.

```python
# Custom polynomial
crc_custom = CRC(b"test", poly=0x1021)
print(crc_custom.get_crc_hex_string())
```

--------------------------------

### ZebrafyPDF Class

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

The ZebrafyPDF class provides methods for converting PDFs to ZPL. It accepts various parameters to control the conversion process, such as resolution, dimensions, and ZPL formatting.

```APIDOC
## class zebrafy.zebrafy_pdf.ZebrafyPDF

### Description
Provides a method for converting PDFs to Zebra Programming Language (ZPL).

### Parameters
* **pdf_bytes** (bytes) - Required - PDF as a bytes object.
* **format** (str) - Optional - ZPL format parameter that accepts the following values, defaults to "ASCII":
  - "ASCII": ASCII hexadecimal - most compatible (default)
  - "B64": Base64 binary
  - "Z64": LZ77 / Zlib compressed base64 binary - best compression
* **invert** (bool) - Optional - Invert the black and white in resulting image, defaults to `False`
* **dither** (bool) - Optional - Dither the pixels instead of hard limit on black and white, defaults to `True`
* **threshold** (int) - Optional - Black pixel threshold for undithered PDF (0-255), defaults to `128`
* **dpi** (int) - Optional - Pixels per PDF canvas unit. This defines the resolution scaling of the image (<72: compress, >72: stretch), defaults to `72`
* **width** (int) - Optional - Width of the PDF in the resulting ZPL. If `0`, use default PDF width, defaults to `0`
* **height** (int) - Optional - Height of the PDF in the resulting ZPL. If `0`, use default PDF height, defaults to `0`
* **pos_x** (int) - Optional - X position of the PDF on the resulting ZPL, defaults to `0`
* **pos_y** (int) - Optional - Y position of the PDF on the resulting ZPL, defaults to `0`
* **rotation** (int) - Optional - Additional rotation in degrees 0, 90, 180, or 270, defaults to `0`
* **string_line_break** (int) - Optional - Number of characters in graphic field content after which a new line is added, defaults to None.
* **split_pages** (bool) - Optional - Split each PDF page as a new ZPL label (only applies if complete_zpl is set), defaults to `False`
* **complete_zpl** (bool) - Optional - Return a complete ZPL with header and footer included. Otherwise return only the graphic field, defaults to `True`

### Deprecated
Deprecated since version 1.1.0: The compression_type parameter is deprecated in favor of format and will be removed in version 2.0.0.
```

--------------------------------

### Embed Graphic Field in a Custom ZPL Label

Source: https://context7.com/miikanissi/zebrafy/llms.txt

Shows how to combine a generated ZPL graphic field (`^GFA`) with other ZPL commands (like `^FO` for position and `^FD` for text) to create a complete ZPL label, which is then written to a file.

```python
# Embed the field in a custom ZPL document
label = f"^XA\n^FO10,10{gf_ascii}\n^FO10,60^A0N,30,30^FDHello World^FS\n^XZ"
with open("custom_label.zpl", "w") as f:
    f.write(label)
```

--------------------------------

### GraphicField — Low-level ZPL graphic field builder

Source: https://context7.com/miikanissi/zebrafy/llms.txt

`GraphicField(pil_image, *, format, string_line_break)` is used to produce the raw `^GFA,...^FS` ZPL command from a 1-bit PIL Image. `.get_graphic_field()` returns the formatted `^GF` string.

```APIDOC
## GraphicField

### Description
Internal class used to generate ZPL `^GF` commands from a 1-bit PIL Image. It supports `ASCII`, `B64`, and `Z64` formats, with an option for line breaks.

### Methods
- **`get_graphic_field()`**: Returns the formatted `^GF` string.

### Parameters
- **`pil_image`** (PIL.Image.Image) - Required - A 1-bit PIL Image.
- **`format`** (str) - Optional - Encoding format (`ASCII`, `B64`, `Z64`). Defaults to `ASCII`.
- **`string_line_break`** (int) - Optional - Number of characters per line for ASCII format.

### Usage Examples

#### ASCII format
```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

img = Image.new("1", (64, 32), color=1)
gf_ascii = GraphicField(img, format="ASCII").get_graphic_field()
print(gf_ascii)
# ^GFA,256,256,8,ffffffffffffffff...^FS
```

#### B64 format
```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

img = Image.new("1", (64, 32), color=1)
gf_b64 = GraphicField(img, format="B64").get_graphic_field()
print(gf_b64[:40])
# ^GFA,60,256,8,:B64:...
```

#### Z64 format
```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

img = Image.new("1", (64, 32), color=1)
gf_z64 = GraphicField(img, format="Z64").get_graphic_field()
print(gf_z64[:40])
# ^GFA,48,256,8,:Z64:...
```

#### With line breaks
```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

img = Image.new("1", (64, 32), color=1)
gf_lb = GraphicField(img, format="ASCII", string_line_break=40).get_graphic_field()
```

#### Embedding in custom ZPL
```python
from PIL import Image
from zebrafy.graphic_field import GraphicField

img = Image.new("1", (64, 32), color=1)
gf_ascii = GraphicField(img, format="ASCII").get_graphic_field()
label = f"^XA\n^FO10,10{gf_ascii}\n^FO10,60^A0N,30,30^FDHello World^FS\n^XZ"
with open("custom_label.zpl", "w") as f:
    f.write(label)
```
```

--------------------------------

### GraphicField Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/modules.md

Methods for handling graphic fields in ZPL generation.

```APIDOC
## GraphicField.format

### Description
Gets or sets the format for graphic fields.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## GraphicField.get_graphic_field()

### Description
Retrieves the graphic field data.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## GraphicField.pil_image

### Description
Gets or sets the PIL (Python Imaging Library) image associated with the graphic field.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## GraphicField.string_line_break

### Description
Handles string line breaks for graphic field content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)
```

--------------------------------

### ZebrafyPDF Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/modules.md

Methods available for manipulating PDF data within the Zebrafy library.

```APIDOC
## ZebrafyPDF.complete_zpl

### Description
Completes the ZPL string with necessary commands for PDF content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.dither

### Description
Applies dithering to the PDF content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.dpi

### Description
Gets or sets the DPI (dots per inch) for PDF rendering.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.format

### Description
Gets or sets the format for PDF processing.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.height

### Description
Gets the height of the PDF content.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.invert

### Description
Inverts the colors of the PDF content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.pdf_bytes

### Description
Gets the PDF content as bytes.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.pos_x

### Description
Gets or sets the X position for PDF content.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.pos_y

### Description
Gets or sets the Y position for PDF content.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.rotation

### Description
Gets or sets the rotation for PDF content.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.split_pages

### Description
Splits the PDF into individual pages.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.string_line_break

### Description
Handles string line breaks for PDF content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.threshold

### Description
Applies a threshold to the PDF content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.to_zpl()

### Description
Converts the PDF content to ZPL format.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyPDF.width

### Description
Gets the width of the PDF content.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)
```

--------------------------------

### ZebrafyImage - Convert image to ZPL

Source: https://context7.com/miikanissi/zebrafy/llms.txt

The ZebrafyImage class converts image bytes or PIL Image objects into ZPL strings. It supports various parameters for customization, including encoding format, dimensions, position, and rotation.

```APIDOC
## ZebrafyImage

### Description
Converts image bytes or a `PIL.Image.Image` into a ZPL string via `.to_zpl()`.

### Parameters
- `image` (bytes or PIL.Image.Image) - The image data or object to convert.
- `format` (str, optional) - Encoding format: "ASCII", "B64", or "Z64". Defaults to "ASCII".
- `invert` (bool, optional) - Whether to invert black and white. Defaults to False.
- `dither` (bool, optional) - Whether to apply dithering. Defaults to False.
- `threshold` (int, optional) - Threshold for dithering (0-255). Defaults to 128.
- `width` (int, optional) - Target width in pixels.
- `height` (int, optional) - Target height in pixels.
- `pos_x` (int, optional) - X position of the graphic field.
- `pos_y` (int, optional) - Y position of the graphic field.
- `rotation` (int, optional) - Rotation angle (0, 90, 180, 270).
- `string_line_break` (int, optional) - Maximum characters per line for ASCII format.
- `complete_zpl` (bool, optional) - Whether to include `^XA`/`^XZ` headers. Defaults to True.

### Method
`.to_zpl()` - Returns the ZPL string representation of the image.

### Request Example
```python
from PIL import Image
from zebrafy import ZebrafyImage

# From file bytes (minimal)
with open("label.png", "rb") as f:
    zpl = ZebrafyImage(f.read()).to_zpl()

# From a PIL Image directly
pil_image = Image.new(mode="RGB", size=(200, 100), color=(255, 255, 255))
zpl = ZebrafyImage(pil_image, format="B64").to_zpl()

# Get only the graphic field (no ^XA/^XZ)
with open("label.png", "rb") as f:
    gf_only = ZebrafyImage(f.read(), complete_zpl=False).to_zpl()
```

### Error Handling
- `ValueError`: Raised for invalid image data, empty image, or invalid format.
```

--------------------------------

### ZebrafyImage Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/modules.md

Methods available for manipulating image data within the Zebrafy library.

```APIDOC
## ZebrafyImage.complete_zpl

### Description
Completes the ZPL string with necessary commands.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.dither

### Description
Applies dithering to the image.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.format

### Description
Gets or sets the image format.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.height

### Description
Gets the height of the image.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.image

### Description
Gets the image data.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.invert

### Description
Inverts the image colors.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.pos_x

### Description
Gets or sets the X position of the image.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.pos_y

### Description
Gets or sets the Y position of the image.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.rotation

### Description
Gets or sets the rotation of the image.

### Method
(Not specified, likely a property getter/setter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.string_line_break

### Description
Handles string line breaks for image content.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.threshold

### Description
Applies a threshold to the image.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.to_zpl()

### Description
Converts the image to ZPL format.

### Method
(Not specified, likely a method call)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)

## ZebrafyImage.width

### Description
Gets the width of the image.

### Method
(Not specified, likely a property getter)

### Endpoint
(Not applicable for SDK methods)

### Parameters
(No parameters specified)

### Request Example
(Not applicable)

### Response
(Not specified)
```

--------------------------------

### Convert ZPL to PDF Bytes

Source: https://github.com/miikanissi/zebrafy/blob/master/README.rst

Convert ZPL graphic fields to PDF bytes. The `ZebrafyZPL` class reads ZPL content from a file.

```python
from zebrafy import ZebrafyZPL

with open("source.zpl", "r") as zpl:
    pdf_bytes = ZebrafyZPL(zpl.read()).to_pdf()
```

--------------------------------

### CRC Class Methods

Source: https://github.com/miikanissi/zebrafy/blob/master/docs/zebrafy.md

Methods for calculating CRC-16-CCITT checksums.

```APIDOC
## CRC.get_crc_hex_string()

### Description
Get CRC-16-CCITT as a four-digit zero-padding hexadecimal string.

### Method
This is a method of the CRC class.

### Returns
- **str**: CRC-16-CCITT as a four-digit zero-padding hexadecimal string.
```