### Installation

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Install the PDFtoZPL NuGet package using the .NET CLI.

```APIDOC
## Installation

```bash
dotnet add package PDFtoZPL
```
```

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

### Install PDFtoZPL via NuGet

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Use the .NET CLI to add the library package to your project.

```bash
dotnet add package PDFtoZPL
```

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

### Convert PDF to ZPL and Print via TCP

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Demonstrates the end-to-end process of loading a PDF, configuring conversion options, generating ZPL, and sending it to a network printer.

```csharp
using PDFtoZPL;
using PDFtoImage;
using System.Net.Sockets;

// Load PDF label template
byte[] pdfBytes = File.ReadAllBytes("shipping-label.pdf");

// Configure for 4x6 inch label at 203 DPI
var pdfOptions = new PdfOptions(
    Dpi: 203,                           // Standard Zebra DPI
    Width: 812,                         // 4 inches * 203 DPI
    Height: 1218,                       // 6 inches * 203 DPI
    WithAspectRatio: false,             // Use exact dimensions
    AntiAliasing: PdfAntiAliasing.Text, // Anti-alias text only
    BackgroundColor: SkiaSharp.SKColors.White
);

// Configure ZPL output
var zplOptions = new ZplOptions(
    EncodingKind: BitmapEncodingKind.Base64Compressed,  // Smallest size
    SetLabelLength: true,                               // For continuous media
    SetPrintWidth: true,                                // Set print width
    Threshold: 140,                                     // Slightly lighter
    DitheringKind: DitheringKind.None,                 // No dithering for text
    PrintQuantity: 1                                    // Single copy
);

// Convert PDF to ZPL
string zplCode = Conversion.ConvertPdfPage(
    pdfBytes,
    page: 0,
    password: null,
    pdfOptions: pdfOptions,
    zplOptions: zplOptions
);

Console.WriteLine($"Generated ZPL: {zplCode.Length} characters");

// Send to Zebra printer via raw TCP (port 9100)
using var client = new TcpClient("192.168.1.100", 9100);
using var stream = client.GetStream();
byte[] zplBytes = System.Text.Encoding.UTF8.GetBytes(zplCode);
stream.Write(zplBytes, 0, zplBytes.Length);
Console.WriteLine("Label sent to printer!");

// Alternative: Save ZPL to file for later use
File.WriteAllText("label.zpl", zplCode);
```

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

### Using Open Iconic standalone

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/css/open-iconic/README.md

Include the default stylesheet and use the data-glyph attribute for icons.

```html
<link href="/open-iconic/font/css/open-iconic.css" rel="stylesheet">
```

```html
<span class="oi" data-glyph="icon-name" title="icon name" aria-hidden="true"></span>
```

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

### Configure PDF Rendering Options

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Sets parameters for rendering PDF pages to images before ZPL conversion, such as DPI, rotation, and cropping.

```csharp
using PDFtoZPL;
using PDFtoImage;
using SkiaSharp;
using System.Drawing;

// Default options - 203 DPI (standard Zebra printer resolution)
var defaultOptions = new PdfOptions();

// Full configuration for high-quality output
var options = new PdfOptions(
    Dpi: 300,                              // Higher DPI for detailed labels
    Width: 812,                            // Fixed width in pixels
    Height: null,                          // Auto-calculate height
    WithAnnotations: true,                 // Render PDF annotations
    WithFormFill: true,                    // Render form field values
    WithAspectRatio: true,                 // Maintain aspect ratio
    Rotation: PdfRotation.Rotate90,        // Rotate 90 degrees
    AntiAliasing: PdfAntiAliasing.All,     // Full anti-aliasing
    BackgroundColor: SKColors.White,       // White background
    Bounds: new RectangleF(0, 0, 4, 6),   // Crop to specific region (inches at 72 DPI)
    UseTiling: false,                      // Tile large PDFs to prevent memory issues
    DpiRelativeToBounds: false,
    Grayscale: true                        // Render in grayscale
);

byte[] pdfBytes = File.ReadAllBytes("document.pdf");
string zplCode = Conversion.ConvertPdfPage(pdfBytes, page: 0, pdfOptions: options);

// Standard label sizes (203 DPI Zebra printer)
var labelOptions = new PdfOptions(
    Dpi: 203,
    Width: 812,   // 4 inches at 203 DPI
    Height: 1218  // 6 inches at 203 DPI
);
```

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

### ZplOptions Configuration

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net8.0/PublicAPI.Shipped.txt

Details the configurable options for ZPL generation.

```APIDOC
## ZplOptions

### Description
Allows customization of ZPL output parameters.

### Constructor

- **ZplOptions(BitmapEncodingKind EncodingKind = HexadecimalCompressed, bool GraphicFieldOnly = false, bool SetLabelLength = false, byte Threshold = 128, DitheringKind DitheringKind = None, uint PrintQuantity = 0, sbyte LabelTop = 0, short LabelShift = 0, bool SetPrintWidth = false)**

### Properties

- **EncodingKind** (BitmapEncodingKind) - Specifies the bitmap encoding method.
- **GraphicFieldOnly** (bool) - If true, only graphic fields are included.
- **SetLabelLength** (bool) - If true, the label length is set.
- **Threshold** (byte) - Threshold value for image processing.
- **DitheringKind** (DitheringKind) - Specifies the dithering method.
- **PrintQuantity** (uint) - The number of labels to print.
- **LabelTop** (sbyte) - The top margin of the label.
- **LabelShift** (short) - The horizontal shift for the label.
- **SetPrintWidth** (bool) - If true, the print width is set.

### Methods

- **GetHashCode() -> int**: Returns the hash code for the options.
- **Deconstruct(...) -> void**: Deconstructs the options into individual variables.
- **Equals(ZplOptions other) -> bool**: Compares this instance with another ZplOptions object.
- **operator !=(ZplOptions left, ZplOptions right) -> bool**: Compares two ZplOptions objects for inequality.
- **operator ==(ZplOptions left, ZplOptions right) -> bool**: Compares two ZplOptions objects for equality.
- **Equals(object obj) -> bool**: Overrides the base Equals method.
- **ToString() -> string**: Returns a string representation of the options.
```

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

### PDFtoZPL Configuration Classes

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net481/PublicAPI.Shipped.txt

Overview of the configuration classes used to control PDF conversion and ZPL generation settings.

```APIDOC
## PDFtoZPL Configuration

### Description
The library uses `PdfOptions` to define how PDFs are processed (DPI, rotation, anti-aliasing) and `ZplOptions` to define how the resulting ZPL is formatted (encoding, dithering, label dimensions).

### Key Components
- **BitmapEncodingKind**: Defines the encoding format for ZPL bitmaps (Hexadecimal, Base64, etc.).
- **DitheringKind**: Defines the dithering algorithm applied during image processing.
- **PdfOptions**: Configuration for PDF-to-image conversion.
- **ZplOptions**: Configuration for ZPL output generation.

### PdfOptions Properties
- **Dpi** (int) - Resolution of the output.
- **Width/Height** (int?) - Dimensions of the output.
- **Rotation** (PdfRotation) - Rotation applied to the PDF.
- **BackgroundColor** (SKColor?) - Background color for the rendered image.

### ZplOptions Properties
- **EncodingKind** (BitmapEncodingKind) - Encoding format for the ZPL output.
- **DitheringKind** (DitheringKind) - Dithering algorithm to use.
- **PrintQuantity** (uint) - Number of labels to print.
- **LabelShift** (short) - Horizontal shift for the label.
- **LabelTop** (sbyte) - Vertical offset for the label.
```

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

### PDFtoZPL Configuration Classes

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net10.0/PublicAPI.Shipped.txt

Overview of the configuration classes used to control PDF-to-ZPL conversion processes.

```APIDOC
## PDFtoZPL Configuration

### Description
The library uses `PdfOptions` to define how a PDF is processed and `ZplOptions` to define how the resulting ZPL is formatted.

### Key Components
- **BitmapEncodingKind**: Defines the encoding format (Hexadecimal, HexadecimalCompressed, Base64, Base64Compressed).
- **DitheringKind**: Defines the dithering algorithm (None, FloydSteinberg, Atkinson).
- **PdfOptions**: Configuration for PDF rendering (DPI, rotation, anti-aliasing, background color, bounds, etc.).
- **ZplOptions**: Configuration for ZPL output (dithering, encoding, label positioning, print quantity, etc.).
```

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

### ZPL Options

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net471/PublicAPI.Shipped.txt

Configuration options for generating ZPL output.

```APIDOC
## ZPL Options

### Description
Provides properties to configure the ZPL generation process, including dithering, encoding, and label properties.

### Properties
- **DitheringKind** (PDFtoZPL.DitheringKind): Gets or sets the dithering algorithm to use.
- **EncodingKind** (PDFtoZPL.BitmapEncodingKind): Gets or sets the bitmap encoding type.
- **GraphicFieldOnly** (bool): Gets or sets a value indicating whether to include only graphic fields.
- **LabelShift** (short): Gets or sets the label shift value.
- **LabelTop** (sbyte): Gets or sets the label top position.
- **PrintQuantity** (uint): Gets or sets the number of labels to print.
- **SetLabelLength** (bool): Gets or sets a value indicating whether to set the label length.
- **SetPrintWidth** (bool): Gets or sets a value indicating whether to set the print width.
- **Threshold** (byte): Gets or sets the threshold value for monochrome conversion.
```

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

### ZPL Options Configuration

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net9.0/PublicAPI.Shipped.txt

Configuration options for generating ZPL output.

```APIDOC
## ZplOptions

### Description
Represents configuration options for ZPL generation.

### Constructor
`ZplOptions(BitmapEncodingKind EncodingKind = HexadecimalCompressed, bool GraphicFieldOnly = false, bool SetLabelLength = false, byte Threshold = 128, DitheringKind DitheringKind = None, uint PrintQuantity = 0, sbyte LabelTop = 0, short LabelShift = 0, bool SetPrintWidth = false)`

### Methods
- `Deconstruct(...)`
- `Equals(ZplOptions other)`
- `operator !=(ZplOptions left, ZplOptions right)`
- `operator ==(ZplOptions left, ZplOptions right)`
- `Equals(object obj)` (override)
- `ToString()` (override)

### Properties (from constructor)
- **EncodingKind** (BitmapEncodingKind) - The encoding kind for bitmaps.
- **GraphicFieldOnly** (bool) - Whether to include only graphic fields.
- **SetLabelLength** (bool) - Whether to set the label length.
- **Threshold** (byte) - The threshold for binarization.
- **DitheringKind** (DitheringKind) - The dithering kind.
- **PrintQuantity** (uint) - The number of labels to print.
- **LabelTop** (sbyte) - The top margin for the label.
- **LabelShift** (short) - The horizontal shift for the label.
- **SetPrintWidth** (bool) - Whether to set the print width.
```

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

### Using Open Iconic with Foundation

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/css/open-iconic/README.md

Include the Foundation-specific stylesheet and use the icon span class.

```html
<link href="/open-iconic/font/css/open-iconic-foundation.css" rel="stylesheet">
```

```html
<span class="fi-icon-name" title="icon name" aria-hidden="true"></span>
```

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

### Toggle Theme Based on System Preference

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/index.html

Listens for changes in the system's preferred color scheme (dark/light) and updates the 'data-bs-theme' attribute on the document element accordingly. It also sets the initial theme on load.

```javascript
window.matchMedia('(prefers-color-scheme: dark)').onchange = event => { if (event.matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } else { document.documentElement.setAttribute('data-bs-theme', 'light'); } }; if (window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } else { document.documentElement.setAttribute('data-bs-theme', 'light'); } document.body.classList.remove('body-dummy'); if (window.matchMedia('(prefers-color-scheme: dark)').matches) { document.documentElement.setAttribute('data-bs-theme', 'dark'); } else { document.documentElement.setAttribute('data-bs-theme', 'light'); }
```

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

### Apply Image Dithering Algorithms

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Configures dithering algorithms to improve monochrome image quality. Threshold adjustments can be combined with dithering for finer control.

```csharp
using PDFtoZPL;

// No dithering (default) - simple threshold
var noDither = new ZplOptions(DitheringKind: DitheringKind.None, Threshold: 128);
string zpl1 = Conversion.ConvertBitmap("photo.jpg", noDither);

// Floyd-Steinberg dithering - classic error diffusion
var floydSteinberg = new ZplOptions(DitheringKind: DitheringKind.FloydSteinberg);
string zpl2 = Conversion.ConvertBitmap("photo.jpg", floydSteinberg);

// Atkinson dithering - preserves more detail, used by classic Mac
var atkinson = new ZplOptions(DitheringKind: DitheringKind.Atkinson);
string zpl3 = Conversion.ConvertBitmap("photo.jpg", atkinson);

// Combine dithering with threshold adjustment
var customDither = new ZplOptions(
    DitheringKind: DitheringKind.FloydSteinberg,
    Threshold: 100  // Lower threshold = darker output
);
string zpl4 = Conversion.ConvertBitmap("grayscale-logo.png", customDither);
```

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

### Convert PDF and Bitmap to ZPL

Source: https://github.com/sungaila/pdftozpl/blob/master/README.md

Static methods provided by the Conversion class to handle PDF page, full PDF, asynchronous PDF, and bitmap conversions.

```csharp
PDFtoZPL.Conversion.ConvertPdfPage()
```

```csharp
PDFtoZPL.Conversion.ConvertPdf()
```

```csharp
PDFtoZPL.Conversion.ConvertPdfAsync()
```

```csharp
PDFtoZPL.Conversion.ConvertBitmap()
```

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

### Asynchronously Convert PDF Pages

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Asynchronously converts all PDF pages using IAsyncEnumerable for streaming processing with cancellation support.

```csharp
using PDFtoZPL;

// Async conversion with cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
using var fileStream = new FileStream("large-document.pdf", FileMode.Open, FileAccess.Read);

await foreach (string pageZpl in Conversion.ConvertPdfAsync(fileStream, cancellationToken: cts.Token))
{
    Console.WriteLine($"Converted page with {pageZpl.Length} characters");
    await SendToPrinterAsync(pageZpl);
}

// Async with all options
byte[] pdfBytes = await File.ReadAllBytesAsync("labels.pdf");
var pdfOptions = new PdfOptions(Dpi: 203, Grayscale: true);
var zplOptions = new ZplOptions(SetLabelLength: true, SetPrintWidth: true);

await foreach (string zpl in Conversion.ConvertPdfAsync(
    pdfBytes,
    password: null,
    pdfOptions: pdfOptions,
    zplOptions: zplOptions,
    cancellationToken: default))
{
    // Process asynchronously
}
```

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

### Configure Bitmap Encoding Formats

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Selects the encoding method for bitmap data within the ZPL ^GF command. Base64Compressed is recommended for optimal output size.

```csharp
using PDFtoZPL;

// Hexadecimal (not recommended - large output)
var hexOptions = new ZplOptions(EncodingKind: BitmapEncodingKind.Hexadecimal);
// Output: ^GFA,<bytes>,<bytes>,<width>,FFFFFFFFFFFF000000...

// HexadecimalCompressed (default - good compression)
var hexCompOptions = new ZplOptions(EncodingKind: BitmapEncodingKind.HexadecimalCompressed);
// Output: ^GFA,<bytes>,<bytes>,<width>,gR0G1HF...

// Base64 (moderate size, MIME encoding)
var b64Options = new ZplOptions(EncodingKind: BitmapEncodingKind.Base64);
// Output: ^GFA,<bytes>,<bytes>,<width>,:B64:<base64data>:<checksum>

// Base64Compressed / Z64 (recommended - smallest output)
var z64Options = new ZplOptions(EncodingKind: BitmapEncodingKind.Base64Compressed);
// Output: ^GFA,<bytes>,<bytes>,<width>,:Z64:<deflate+base64data>:<checksum>

// Compare output sizes
byte[] pdfBytes = File.ReadAllBytes("label.pdf");

string hexZpl = Conversion.ConvertPdfPage(pdfBytes, 0, zplOptions: hexOptions);
string compZpl = Conversion.ConvertPdfPage(pdfBytes, 0, zplOptions: z64Options);

Console.WriteLine($"Hexadecimal: {hexZpl.Length} chars");
Console.WriteLine($"Z64 Compressed: {compZpl.Length} chars");
// Z64 is typically 3-10x smaller than raw hexadecimal
```

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

### IZplOptions Interface

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net9.0/PublicAPI.Shipped.txt

Interface defining common ZPL options for ZPL generation.

```APIDOC
## PDFtoZPL.IZplOptions Interface

### Description
An interface that outlines the configurable options for generating ZPL output.

### Properties
- **DitheringKind** (PDFtoZPL.DitheringKind) - Gets or initializes the dithering kind.
- **EncodingKind** (PDFtoZPL.BitmapEncodingKind) - Gets or initializes the bitmap encoding kind.
- **GraphicFieldOnly** (bool) - Gets or initializes a value indicating whether to include only graphic fields.
- **LabelShift** (short) - Gets or initializes the label shift value.
- **LabelTop** (sbyte) - Gets or initializes the label top position.
- **PrintQuantity** (uint) - Gets or initializes the number of print quantities.
- **SetLabelLength** (bool) - Gets or initializes a value indicating whether to set the label length.
- **SetPrintWidth** (bool) - Gets or initializes a value indicating whether to set the print width.
- **Threshold** (byte) - Gets or initializes the threshold value.
```

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

### PdfOptions - Configure PDF Rendering

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Controls how PDF pages are rendered to images before ZPL conversion, including DPI, rotation, size, and anti-aliasing.

```APIDOC
## PdfOptions - Configure PDF Rendering

### Description
Controls how PDF pages are rendered to images before ZPL conversion, including DPI, rotation, size, and anti-aliasing.

### Method
`PdfOptions` constructor and `Conversion.ConvertPdfPage` overload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Default options - 203 DPI (standard Zebra printer resolution)
var defaultOptions = new PdfOptions();

// Full configuration for high-quality output
var options = new PdfOptions(
    Dpi: 300,                              // Higher DPI for detailed labels
    Width: 812,                            // Fixed width in pixels
    Height: null,                          // Auto-calculate height
    WithAnnotations: true,                 // Render PDF annotations
    WithFormFill: true,                    // Render form field values
    WithAspectRatio: true,                 // Maintain aspect ratio
    Rotation: PdfRotation.Rotate90,        // Rotate 90 degrees
    AntiAliasing: PdfAntiAliasing.All,     // Full anti-aliasing
    BackgroundColor: SKColors.White,       // White background
    Bounds: new RectangleF(0, 0, 4, 6),   // Crop to specific region (inches at 72 DPI)
    UseTiling: false,                      // Tile large PDFs to prevent memory issues
    DpiRelativeToBounds: false,
    Grayscale: true                        // Render in grayscale
);

byte[] pdfBytes = File.ReadAllBytes("document.pdf");
string zplCode = Conversion.ConvertPdfPage(pdfBytes, page: 0, pdfOptions: options);

// Standard label sizes (203 DPI Zebra printer)
var labelOptions = new PdfOptions(
    Dpi: 203,
    Width: 812,   // 4 inches at 203 DPI
    Height: 1218  // 6 inches at 203 DPI
);
```

### Response
#### Success Response (200)
- **options** (PdfOptions) - An object containing configuration settings for PDF rendering.
- **zplCode** (string) - The generated ZPL code for the PDF page.
```

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

### PDFtoZPL.IZplOptions Interface

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/netstandard2.1/PublicAPI.Shipped.txt

Interface defining common ZPL options for PDF to ZPL conversion.

```APIDOC
## PDFtoZPL.IZplOptions Interface

### Description
Interface for ZPL conversion options.

### Properties
- **DitheringKind** (PDFtoZPL.DitheringKind) - Gets or initializes the dithering kind.
- **EncodingKind** (PDFtoZPL.BitmapEncodingKind) - Gets or initializes the bitmap encoding kind.
- **GraphicFieldOnly** (bool) - Gets or initializes a value indicating whether to include only graphic fields.
- **LabelShift** (short) - Gets or initializes the label shift value.
- **LabelTop** (sbyte) - Gets or initializes the label top value.
- **PrintQuantity** (uint) - Gets or initializes the print quantity.
- **SetLabelLength** (bool) - Gets or initializes a value indicating whether to set the label length.
- **SetPrintWidth** (bool) - Gets or initializes a value indicating whether to set the print width.
- **Threshold** (byte) - Gets or initializes the threshold value.
```

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

### ZplOptions - Configure ZPL Output

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Controls how images are converted to ZPL, including encoding format, dithering algorithm, threshold, and printer-specific commands.

```APIDOC
## ZplOptions - Configure ZPL Output

### Description
Controls how images are converted to ZPL, including encoding format, dithering algorithm, threshold, and printer-specific commands.

### Method
`ZplOptions` constructor and `Conversion.ConvertBitmap` overload

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Default options - HexadecimalCompressed encoding, threshold 128
var defaultOptions = new ZplOptions();

// Full configuration
var options = new ZplOptions(
    EncodingKind: BitmapEncodingKind.Base64Compressed,  // Z64 - smallest output
    GraphicFieldOnly: false,      // Include ^XA and ^XZ wrapper commands
    SetLabelLength: true,         // Add ^LL command for continuous media
    SetPrintWidth: true,          // Add ^PW command for print width
    Threshold: 128,               // 0-255, pixels below this are black
    DitheringKind: DitheringKind.FloydSteinberg,  // Dithering algorithm
    PrintQuantity: 5,             // Print 5 copies (^PQ command)
    LabelTop: 10,                 // Shift label down 10 dots (^LT)
    LabelShift: -20               // Shift label right 20 dots (^LS)
);

// Get only the ^GF graphic field (for embedding in existing ZPL templates)
var gfOnly = new ZplOptions(GraphicFieldOnly: true);
string graphicField = Conversion.ConvertBitmap("logo.png", gfOnly);
```

### Response
#### Success Response (200)
- **options** (ZplOptions) - An object containing configuration settings for ZPL conversion.
- **graphicField** (string) - The generated ZPL graphic field code when `GraphicFieldOnly` is true.
```

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

### ConvertPdfAsync - Async PDF Conversion (.NET 6+)

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Asynchronously converts all PDF pages with cancellation support, returning an IAsyncEnumerable for efficient streaming. Supports various options for PDF rendering and ZPL generation.

```APIDOC
## ConvertPdfAsync - Async PDF Conversion (.NET 6+)

Asynchronously converts all PDF pages with cancellation support. Returns an IAsyncEnumerable for efficient streaming processing.

```csharp
using PDFtoZPL;

// Async conversion with cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
using var fileStream = new FileStream("large-document.pdf", FileMode.Open, FileAccess.Read);

await foreach (string pageZpl in Conversion.ConvertPdfAsync(fileStream, cancellationToken: cts.Token))
{
    Console.WriteLine($"Converted page with {pageZpl.Length} characters");
    await SendToPrinterAsync(pageZpl);
}

// Async with all options
byte[] pdfBytes = await File.ReadAllBytesAsync("labels.pdf");
var pdfOptions = new PdfOptions(Dpi: 203, Grayscale: true);
var zplOptions = new ZplOptions(SetLabelLength: true, SetPrintWidth: true);

await foreach (string zpl in Conversion.ConvertPdfAsync(
    pdfBytes,
    password: null,
    pdfOptions: pdfOptions,
    zplOptions: zplOptions,
    cancellationToken: default))
{
    // Process asynchronously
}
```
```

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

### PdfOptions Class

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net8.0/PublicAPI.Shipped.txt

Configuration options for converting PDF documents to an image format suitable for ZPL.

```APIDOC
## Class: PDFtoZPL.PdfOptions

### Description
Provides a comprehensive set of options for controlling the PDF to image conversion process, influencing aspects like resolution, size, color, and rendering.

### Constructors
- **PdfOptions()**: Initializes a new instance of the `PdfOptions` class with default settings.
- **PdfOptions(int Dpi = 203, int? Width = null, int? Height = null, bool WithAnnotations = false, bool WithFormFill = false, bool WithAspectRatio = false, PDFtoImage.PdfRotation Rotation = PDFtoImage.PdfRotation.Rotate0, PDFtoImage.PdfAntiAliasing AntiAliasing = PDFtoImage.PdfAntiAliasing.All, SkiaSharp.SKColor? BackgroundColor = null, System.Drawing.RectangleF? Bounds = null, bool UseTiling = false, bool DpiRelativeToBounds = false, bool Grayscale = false)**: Initializes a new instance with specified PDF conversion parameters.

### Properties
- **AntiAliasing** (PDFtoImage.PdfAntiAliasing): Gets or sets the anti-aliasing mode for rendering.
- **BackgroundColor** (SkiaSharp.SKColor?): Gets or sets the background color for the PDF page.
- **Bounds** (System.Drawing.RectangleF?): Gets or sets the specific bounds of the PDF page to render.
- **Dpi** (int): Gets or sets the dots per inch (DPI) for rendering.
- **DpiRelativeToBounds** (bool): Gets or sets a value indicating whether DPI is relative to the bounds.
- **Grayscale** (bool): Gets or sets a value indicating whether to render in grayscale.
- **Height** (int?): Gets or sets the desired height of the rendered output.
- **Rotation** (PDFtoImage.PdfRotation): Gets or sets the rotation applied to the PDF page.
- **UseTiling** (bool): Gets or sets a value indicating whether to use tiling for rendering.
- **Width** (int?): Gets or sets the desired width of the rendered output.
- **WithAnnotations** (bool): Gets or sets a value indicating whether to include annotations.
- **WithAspectRatio** (bool): Gets or sets a value indicating whether to maintain the aspect ratio.
- **WithFormFill** (bool): Gets or sets a value indicating whether to fill form fields.

### Methods
- **Deconstruct(out int Dpi, out int? Width, out int? Height, out bool WithAnnotations, out bool WithFormFill, out bool WithAspectRatio, out PDFtoImage.PdfRotation Rotation, out PDFtoImage.PdfAntiAliasing AntiAliasing, out SkiaSharp.SKColor? BackgroundColor, out System.Drawing.RectangleF? Bounds, out bool UseTiling, out bool DpiRelativeToBounds, out bool Grayscale)**: Deconstructs the `PdfOptions` object into its constituent properties.
- **Equals(PDFtoZPL.PdfOptions other)**: Determines whether the specified `PdfOptions` object is equal to the current object.
- **GetHashCode()**: Serves as a hash function for the `PdfOptions` object.
- **ToString()**: Returns a string that represents the current object.

### Operators
- **operator !=(PDFtoZPL.PdfOptions left, PDFtoZPL.PdfOptions right)**: Compares two `PdfOptions` objects for inequality.
- **operator ==(PDFtoZPL.PdfOptions left, PDFtoZPL.PdfOptions right)**: Compares two `PdfOptions` objects for equality.
```

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

### ZplOptions Class

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net8.0/PublicAPI.Shipped.txt

Configuration options specific to generating ZPL output from PDFtoZPL.

```APIDOC
## Class: PDFtoZPL.ZplOptions

### Description
Encapsulates ZPL-specific conversion options, allowing fine-tuning of the output format and characteristics.

### Constructors
- **ZplOptions()**: Initializes a new instance of the `ZplOptions` class with default settings.

### Properties
- **DitheringKind** (PDFtoZPL.DitheringKind): Gets or sets the dithering algorithm to apply.
- **EncodingKind** (PDFtoZPL.BitmapEncodingKind): Gets or sets the encoding format for bitmap data.
- **GraphicFieldOnly** (bool): Gets or sets a value indicating whether to output only graphic fields.
- **LabelShift** (short): Gets or sets the shift applied to the label.
- **LabelTop** (sbyte): Gets or sets the top position of the label.
- **PrintQuantity** (uint): Gets or sets the number of labels to print.
- **SetLabelLength** (bool): Gets or sets a value indicating whether to explicitly set the label length.
- **SetPrintWidth** (bool): Gets or sets a value indicating whether to explicitly set the print width.
- **Threshold** (byte): Gets or sets the threshold value used in image processing.
```

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

### ConvertBitmap Methods

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/netstandard2.1/PublicAPI.Shipped.txt

Converts various bitmap input formats into a ZPL string.

```APIDOC
## ConvertBitmap

### Description
Converts a bitmap (provided as byte array, SKBitmap, file path, or stream) into a ZPL string.

### Parameters
#### Request Body
- **bitmapAsByteArray/bitmap/bitmapPath/bitmapAsStream** (byte[]/SKBitmap/string/Stream) - Required - The source bitmap data.
- **zplOptions** (ZplOptions) - Optional - Configuration options for the ZPL output.
- **leaveOpen** (bool) - Optional - Whether to keep the stream open after processing (for stream input only).

### Response
- **Returns** (string) - The resulting ZPL string.
```

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

### PdfOptions Class

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net9.0/PublicAPI.Shipped.txt

Configuration options for converting PDF documents to image formats suitable for ZPL.

```APIDOC
## PDFtoZPL.PdfOptions Class

### Description
Provides a comprehensive set of options for configuring the conversion of PDF pages into a format suitable for ZPL printing, including resolution, dimensions, and appearance settings.

### Constructors
- **PdfOptions()**: Initializes a new instance of the PdfOptions class with default settings.
- **PdfOptions(int Dpi = 203, int? Width = null, int? Height = null, bool WithAnnotations = false, bool WithFormFill = false, bool WithAspectRatio = false, PDFtoImage.PdfRotation Rotation = PDFtoImage.PdfRotation.Rotate0, PDFtoImage.PdfAntiAliasing AntiAliasing = PDFtoImage.PdfAntiAliasing.All, SkiaSharp.SKColor? BackgroundColor = null, System.Drawing.RectangleF? Bounds = null, bool UseTiling = false, bool DpiRelativeToBounds = false, bool Grayscale = false)**: Initializes a new instance with specified conversion parameters.

### Properties
- **AntiAliasing** (PDFtoImage.PdfAntiAliasing) - Gets or initializes the anti-aliasing mode for rendering.
- **BackgroundColor** (SkiaSharp.SKColor?) - Gets or initializes the background color of the PDF page.
- **Bounds** (System.Drawing.RectangleF?) - Gets or initializes the rectangular bounds for the conversion.
- **Dpi** (int) - Gets or initializes the dots per inch (DPI) for the conversion.
- **DpiRelativeToBounds** (bool) - Gets or initializes a value indicating whether DPI is relative to the bounds.
- **Grayscale** (bool) - Gets or initializes a value indicating whether to convert the image to grayscale.
- **Height** (int?) - Gets or initializes the desired height of the output image.
- **Rotation** (PDFtoImage.PdfRotation) - Gets or initializes the rotation applied to the PDF page.
- **UseTiling** (bool) - Gets or initializes a value indicating whether tiling is used for rendering.
- **Width** (int?) - Gets or initializes the desired width of the output image.
- **WithAnnotations** (bool) - Gets or initializes a value indicating whether to include annotations.
- **WithAspectRatio** (bool) - Gets or initializes a value indicating whether to maintain the aspect ratio.
- **WithFormFill** (bool) - Gets or initializes a value indicating whether to fill form fields.

### Methods
- **Deconstruct(out int Dpi, out int? Width, out int? Height, out bool WithAnnotations, out bool WithFormFill, out bool WithAspectRatio, out PDFtoImage.PdfRotation Rotation, out PDFtoImage.PdfAntiAliasing AntiAliasing, out SkiaSharp.SKColor? BackgroundColor, out System.Drawing.RectangleF? Bounds, out bool UseTiling, out bool DpiRelativeToBounds, out bool Grayscale)**: Deconstructs the PdfOptions object into its constituent properties.
- **Equals(PDFtoZPL.PdfOptions other)**: Compares this PdfOptions object with another for equality.
- **Equals(object obj)**: Overrides the base Equals method to compare with an object.
- **GetHashCode()**: Overrides the base GetHashCode method.
- **ToString()**: Overrides the base ToString method to provide a string representation.
```

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

### PDF Options

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/net471/PublicAPI.Shipped.txt

Configuration options for converting PDF input.

```APIDOC
## PDF Options

### Description
Configures the conversion of PDF documents, including resolution, dimensions, and appearance settings.

### Constructors
- **PdfOptions()**: Initializes a new instance of the `PdfOptions` class with default values.
- **PdfOptions(int Dpi = 203, int? Width = null, int? Height = null, bool WithAnnotations = false, bool WithFormFill = false, bool WithAspectRatio = false, PDFtoImage.PdfRotation Rotation = PDFtoImage.PdfRotation.Rotate0, PDFtoImage.PdfAntiAliasing AntiAliasing = PDFtoImage.PdfAntiAliasing.All, SkiaSharp.SKColor? BackgroundColor = null, System.Drawing.RectangleF? Bounds = null, bool UseTiling = false, bool DpiRelativeToBounds = false, bool Grayscale = false)**: Initializes a new instance with specified settings.

### Properties
- **AntiAliasing** (PDFtoImage.PdfAntiAliasing): Gets or sets the anti-aliasing mode for rendering.
- **BackgroundColor** (SkiaSharp.SKColor?): Gets or sets the background color of the PDF page.
- **Bounds** (System.Drawing.RectangleF?): Gets or sets the bounding rectangle for the conversion area.
- **Dpi** (int): Gets or sets the dots per inch (DPI) for the conversion.
- **DpiRelativeToBounds** (bool): Gets or sets a value indicating whether DPI is relative to the bounds.
- **Grayscale** (bool): Gets or sets a value indicating whether to convert the PDF to grayscale.
- **Height** (int?): Gets or sets the desired height of the output image.
- **Rotation** (PDFtoImage.PdfRotation): Gets or sets the rotation applied to the PDF page.
- **UseTiling** (bool): Gets or sets a value indicating whether to use tiling for large pages.
- **Width** (int?): Gets or sets the desired width of the output image.
- **WithAnnotations** (bool): Gets or sets a value indicating whether to include annotations.
- **WithAspectRatio** (bool): Gets or sets a value indicating whether to maintain the aspect ratio.
- **WithFormFill** (bool): Gets or sets a value indicating whether to include form fill data.

### Methods
- **Deconstruct(...)**: Deconstructs the `PdfOptions` object into its constituent properties.
- **Equals(PDFtoZPL.PdfOptions other)**: Compares this instance with another `PdfOptions` object for equality.
- **GetHashCode()**: Returns the hash code for this instance.
- **ToString()**: Returns a string representation of the object.

### Operators
- **!= (left, right)**: Compares two `PdfOptions` objects for inequality.
- **== (left, right)**: Compares two `PdfOptions` objects for equality.
```

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

### PDFtoZPL.ZplOptions Class

Source: https://github.com/sungaila/pdftozpl/blob/master/PDFtoZPL/PublicAPI/netstandard2.1/PublicAPI.Shipped.txt

Configuration options specific to ZPL generation.

```APIDOC
## PDFtoZPL.ZplOptions Class

### Description
Provides options specific to ZPL generation.

### Constructors
- **ZplOptions()**

### Properties
- **DitheringKind** (PDFtoZPL.DitheringKind) - Gets or initializes the dithering kind.
- **EncodingKind** (PDFtoZPL.BitmapEncodingKind) - Gets or initializes the bitmap encoding kind.
- **GraphicFieldOnly** (bool) - Gets or initializes a value indicating whether to include only graphic fields.
- **LabelShift** (short) - Gets or initializes the label shift value.
- **LabelTop** (sbyte) - Gets or initializes the label top value.
- **PrintQuantity** (uint) - Gets or initializes the print quantity.
- **SetLabelLength** (bool) - Gets or initializes a value indicating whether to set the label length.
- **SetPrintWidth** (bool) - Gets or initializes a value indicating whether to set the print width.
- **Threshold** (byte) - Gets or initializes the threshold value.
```

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

### Manual Theme Toggling Function

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/index.html

Provides a global function `toggleTheme` to manually switch between 'dark' and 'light' themes by toggling the 'data-bs-theme' attribute on the document element.

```javascript
window.toggleTheme = () => { if (document.documentElement.getAttribute('data-bs-theme') == 'dark') { document.documentElement.setAttribute('data-bs-theme', 'light') } else { document.documentElement.setAttribute('data-bs-theme', 'dark') } }
```

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

### Set .NET Helper and Handle Service Worker Messages

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/index.html

Establishes a connection with a .NET backend via a service worker. It sets a global `dotNetHelper` object and listens for messages from the service worker, specifically handling 'receive-webshare' events to invoke a .NET method.

```javascript
window.setDotNetHelper = dotNetHelper => { window.dotNetHelper = dotNetHelper; navigator.serviceWorker.onmessage = async event => { if (event.data?.type === 'receive-webshare') { await window.dotNetHelper.invokeMethodAsync('ReceiveWebShareTargetAsync', JSON.stringify(event.data.payload)); } }; navigator.serviceWorker.ready .then(registration => { if (registration.active) { registration.active.postMessage('receive-webshare'); } }); };
```

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

### ConvertBitmap - Convert Images to ZPL

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Converts bitmap images (PNG, JPG, BMP, etc.) directly into ZPL code. Accepts file paths, streams, byte arrays, or SkiaSharp SKBitmap objects.

```APIDOC
## ConvertBitmap - Convert Images to ZPL

### Description
Converts bitmap images (PNG, JPG, BMP, etc.) directly into ZPL code. Accepts file paths, streams, byte arrays, or SkiaSharp SKBitmap objects.

### Method
`Conversion.ConvertBitmap`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```csharp
// Convert from file path
string zplCode = Conversion.ConvertBitmap("logo.png");

// Convert from stream
using var imageStream = new FileStream("label.png", FileMode.Open, FileAccess.Read);
string zplCode = Conversion.ConvertBitmap(imageStream, leaveOpen: false);

// Convert from byte array
byte[] imageBytes = File.ReadAllBytes("barcode.png");
string zplCode = Conversion.ConvertBitmap(imageBytes);

// Convert from SKBitmap (SkiaSharp)
using var bitmap = SKBitmap.Decode("image.png");
string zplCode = Conversion.ConvertBitmap(bitmap);

// With custom ZPL options
var options = new ZplOptions(
    Threshold: 100,                                    // Darker threshold
    DitheringKind: DitheringKind.FloydSteinberg,      // Apply dithering
    EncodingKind: BitmapEncodingKind.Base64Compressed // Z64 encoding
);
string zplCode = Conversion.ConvertBitmap("photo.jpg", options);
```

### Response
#### Success Response (200)
- **zplCode** (string) - The generated ZPL code for the image.
```

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

### Using Open Iconic with Bootstrap

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/css/open-iconic/README.md

Include the Bootstrap-specific stylesheet and use the icon span class.

```html
<link href="/open-iconic/font/css/open-iconic-bootstrap.css" rel="stylesheet">
```

```html
<span class="oi oi-icon-name" title="icon name" aria-hidden="true"></span>
```

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

### Set Image from Stream

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/index.html

Loads an image into an HTML element using a stream of image data. It converts the stream to an ArrayBuffer, creates a Blob, generates a URL, and sets the image source. The URL is revoked once the image has loaded.

```javascript
window.setImage = async (imageElementId, imageMime, imageStream) => { const arrayBuffer = await imageStream.arrayBuffer(); const blob = new Blob([arrayBuffer], { type: imageMime }); const url = URL.createObjectURL(blob); const image = document.getElementById(imageElementId); image.onload = () => { URL.revokeObjectURL(url); } image.src = url; }
```

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

### Configure ZPL Output Options

Source: https://context7.com/sungaila/pdftozpl/llms.txt

Customizes the ZPL output format, including encoding, printer commands, and graphic field extraction.

```csharp
using PDFtoZPL;

// Default options - HexadecimalCompressed encoding, threshold 128
var defaultOptions = new ZplOptions();

// Full configuration
var options = new ZplOptions(
    EncodingKind: BitmapEncodingKind.Base64Compressed,  // Z64 - smallest output
    GraphicFieldOnly: false,      // Include ^XA and ^XZ wrapper commands
    SetLabelLength: true,         // Add ^LL command for continuous media
    SetPrintWidth: true,          // Add ^PW command for print width
    Threshold: 128,               // 0-255, pixels below this are black
    DitheringKind: DitheringKind.FloydSteinberg,  // Dithering algorithm
    PrintQuantity: 5,             // Print 5 copies (^PQ command)
    LabelTop: 10,                 // Shift label down 10 dots (^LT)
    LabelShift: -20               // Shift label right 20 dots (^LS)
);

string zplCode = Conversion.ConvertBitmap("label.png", options);
// Output includes: ^XA^LL<height>^PW<width>^LT10^LS-20^GFA,...^FS^PQ5^LS0^XZ

// Get only the ^GF graphic field (for embedding in existing ZPL templates)
var gfOnly = new ZplOptions(GraphicFieldOnly: true);
string graphicField = Conversion.ConvertBitmap("logo.png", gfOnly);
// Output: ^GFA,<byteCount>,<totalBytes>,<bytesPerRow>,<data>

// Custom ZPL template with embedded graphic
string customZpl = $@"^XA
^FO50,50{graphicField}^FS
^FO50,200^A0N,30,30^FDProduct Label^FS
^XZ";
```

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

### Displaying an SVG icon

Source: https://github.com/sungaila/pdftozpl/blob/master/WebConverter/wwwroot/css/open-iconic/README.md

Use standard image tags to display individual SVG files.

```html
<img src="/open-iconic/svg/icon-name.svg" alt="icon name">
```