### Install BinaryKits.Zpl NuGet Packages

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Use the dotnet CLI to add the necessary BinaryKits.Zpl packages to your project.

```bash
dotnet add package BinaryKits.Zpl.Label

# Local ZPL viewer / renderer
dotnet add package BinaryKits.Zpl.Viewer

# Labelary HTTP preview client
dotnet add package BinaryKits.Zpl.Labelary

# Raw Zebra protocol commands
dotnet add package BinaryKits.Zpl.Protocol
```

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

### Create Simple Layout with Graphic Boxes

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example shows how to create a simple layout by programmatically adding multiple graphic boxes. It uses ZplOrigin and Offset methods to position the boxes in a grid-like structure. The output is rendered using ZplEngine.

```cs
var elements = new List<ZplElementBase>();

var origin = new ZplOrigin(100, 100);
for (int i = 0; i < 3; i++)
{
    for (int j = 0; j < 3; j++)
    {
        elements.Add(new ZplGraphicBox(origin.PositionX, origin.PositionY, 50, 50));
        origin = origin.Offset(0, 100);
    }
    origin = origin.Offset(100, -300);
}

var options = new ZplRenderOptions();
var output = new ZplEngine(elements).ToZplString(options);

Console.WriteLine(output);
```

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

### Generate ZPL Graphic Box

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example shows how to create a ZPL graphic box element and convert it to its ZPL string representation. The dimensions are specified in dots.

```cs
var output = new ZplGraphicBox(100, 100, 100, 100).ToZplString();
Console.WriteLine(output);
```

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

### ZPL Font Mapping with SkiaSharp

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example demonstrates how to provide custom font mapping for ZPL font commands when using the viewer. The FontLoader delegate allows specifying system fonts for ZPL font names.

```cs
using SkiaSharp;

string zplString = @"^XA^FO20, 20^A1N,40, 30 ^FD西瓜^FS^FO20, 50^A0N,40, 30 ^FDABCDEFG^FS^XZ";

var drawOptions = new DrawerOptions()
{
    FontLoader = fontName =>
    {
        if (fontName == "0")
        {
            return SKTypeface.FromFamilyName("Arial", SKFontStyleWeight.Bold, SKFontStyleWidth.Normal, SKFontStyleSlant.Upright);
        }
        else if (fontName == "1")
        {
            return SKTypeface.FromFamilyName("SIMSUN");
        }

        return SKTypeface.Default;
    }
};

IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage, drawOptions);
var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze(zplString);

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    var imageData = drawer.Draw(labelInfo.ZplElements, 300, 300, 8);
    File.WriteAllBytes("test.png", imageData);
}
```

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

### Download and Print Image using ZplDownloadObjects

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example demonstrates transferring an image to the printer using the ZplDownloadObjects method, which utilizes ZPL commands ~DY and ^IM. The image is sent in its original format and converted by the printer. It includes options for rendering with specific DPI settings.

```cs
var elements = new List<ZplElementBase>();
elements.Add(new ZplDownloadObjects('R', "SAMPLE.BMP", System.IO.File.ReadAllBytes("sample.bmp")));
elements.Add(new ZplImageMove(100, 100, 'R', "SAMPLE", "BMP"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true, TargetPrintDpi = 300, SourcePrintDpi = 200 });

Console.WriteLine(output);
```

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

### Generate ZPL Barcode 128

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example demonstrates creating a Code 128 barcode with specified data and position, then converting it to its ZPL string format.

```cs
var output = new ZplBarcode128("123ABC", 10, 50).ToZplString();
Console.WriteLine(output);
```

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

### Vue.js App Initialization and Data Structure

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Viewer.WebApi/wwwroot/index.html

Initializes the Vue.js application and defines the data structure for the ZPL viewer, including state management for ZPL data, label dimensions, and API responses. This setup is essential for the viewer's frontend functionality.

```javascript
const App = { data() { return { loadingTestData: false, loadingPreview: false, zplData: null, testLabels: null, exampleLabels: null, pdfs: null, renderResponse: null, renderError: null, printDensityDpmm: 8, labelWidth: 101.6, labelHeight: 152.4, inch2mm: 25.4, printerIpAddress: null, selectedLabelFormatIndex: null, labelFormats: [ { width: 101.6, height: 152.4 }, { width: 54, height: 86 } ], showLabelaryOverlay: false, overlayResponse: null } }, computed: { labelWidthInch() { return (Math.round(this.labelWidth / this.inch2mm * 10) / 10).toFixed(1) }, labelHeightInch() { return (Math.round(this.labelHeight / this.inch2mm * 10) / 10).toFixed(1) }, dpi() { return (Math.round(this.printDensityDpmm * this.inch2mm)) } }, async created() { await this.loadLabelData() //await this.changeZplData(this.templateLabels[0].content) }, methods: { async labelFormatChange() { this.labelWidth = this.labelFormats[this.selectedLabelFormatIndex].width this.labelHeight = this.labelFormats[this.selectedLabelFormatIndex].height this.render(); }, async loadLabelData() { try { this.loadingTestData = true const response = await axios.get('api/v1/label') let labels = response.data.items; labels.sort((a, b) => a.name.localeCompare(b.name, 'en', { sensitivity: 'base', numeric: true })); this.testLabels = labels.filter(function(label){ return label.category === 'Test'; }); this.exampleLabels = labels.filter(function(label){ return label.category === 'Example'; }); } finally { this.loadingTestData = false } }, async changeZplData(zplData, formatData = '') { let formatParts = formatData.split("x"); if (formatParts.length === 2) { this.labelWidth = formatParts[0]; this.labelHeight = formatParts[1]; } this.zplData = zplData await this.render() }, async render() { this.renderError = null try { this.loadingPreview = true this.renderResponse = null this.overlayResponse = null this.renderOverlay() const payload = { zplData: this.zplData, printDensityDpmm: this.printDensityDpmm, labelWidth: this.labelWidth, labelHeight: this.labelHeight } const response = await axios.post('api/v1/viewer', payload) this.renderResponse = response.data } catch(err) { this.renderError = err.response.data console.error(this.renderError) } finally { this.loadingPreview = false } }, async downloadPDF() { this.renderError = null try { const payload = { zplData: this.zplData, printDensityDpmm: this.printDensityDpmm, labelWidth: this.labelWidth, labelHeight: this.labelHeight, type: 'PDF' } const response = await axios.post('api/v1/viewer', payload) response.data.pdfs.forEach(function (labelInfo, index) { var element = document.createElement('a'); element.setAttribute('href', 'data:application/pdf;base64,' + labelInfo.pdfBase64); element.setAttribute('download', 'label-'+ index +'.pdf'); element.style.display = 'none'; document.body.appendChild(element); element.click(); document.body.removeChild(element); }); } catch(error) { this.renderError = error.response.data console.error(this.renderError) } }, async downloadZpl() { var element = document.createElement('a'); element.setAttribute('href', 'data:text/plain;charset=utf-8,' + encodeURIComponent(this.zplData)); element.setAttribute('download', 'label.zpl'); element.style.display = 'none'; document.body.appendChild(element); element.click(); document.body.removeChild(element); }, async downloadPng() { try { this.renderResponse.labels.forEach(function (labelInfo, index) { var element = document.createElement('a'); element.setAttribute('href', 'data:image/png;base64,' + labelInfo.imageBase64); element.setAttribute('download', 'label-'+ index +'.png'); element.style.display = 'none'; document.body.appendChild(element); element.click(); document.body.removeChild(element); }); } catch(error) { console.error(error); } }, async renderOverlay() { if(this.showLabelaryOverlay) { try { const payload = { zplData: this.zplData, printDensityDpmm: this.printDensityDpmm, labelWidth: this.labelWidth, labelHeight: this.labelHeight } const response = await axios.post('api/v1/overlay', payload) this.overlayResponse = response.data } catch(err) { console.error(err) } } else { this.overlayResponse = null } }, async print() { const payload = { zplData: this.zplData, printerIpAddress: this.printerIpAddress } const response = await axios.post('api/v1/print', payload) if(response.status !== 200) { alert('Cannot print') } } } }; Vue.createApp(App).mount('#app');
```

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

### Generate Whole Label with Various Elements

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This snippet demonstrates creating a comprehensive label with text fields, graphic boxes, circles, diagonal lines, symbols, and raw ZPL commands. It utilizes ZplEngine to render the elements into ZPL string format with options for adding empty lines before element starts.

```cs
var sampleText = "[_~^"][LineBreak\n][The quick fox jumps over the lazy dog.]";
var font = new ZplFont(fontWidth: 50, fontHeight: 50);
var elements = new List<ZplElementBase>();
elements.Add(new ZplTextField(sampleText, 50, 100, font));
elements.Add(new ZplGraphicBox(400, 700, 100, 100, 5));
elements.Add(new ZplGraphicBox(450, 750, 100, 100, 50, LineColor.White));
elements.Add(new ZplGraphicCircle(400, 700, 100, 5));
elements.Add(new ZplGraphicDiagonalLine(400, 700, 100, 50, 5));
elements.Add(new ZplGraphicDiagonalLine(400, 700, 50, 100, 5));
elements.Add(new ZplGraphicSymbol(GraphicSymbolCharacter.Copyright, 600, 600, 50, 50));

// Add raw Zpl code
elements.Add(new ZplRaw("^FO200, 200^GB300, 200, 10 ^FS"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true });

Console.WriteLine(output);
```

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

### Render Text Field with Comments for Debugging

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This example demonstrates how to add comments to a ZplTextField for easier debugging. The Comments.Add method is used to attach a string comment, and the ZplRenderOptions.DisplayComments flag is set to true to include these comments in the output ZPL string.

```cs
var elements = new List<ZplElementBase>();

var textField = new ZplTextField("AAA", 50, 100, ZplConstants.Font.Default);
textField.Comments.Add("An important field");
elements.Add(textField);

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { DisplayComments = true });

Console.WriteLine(output);
```

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

### Build and Render a ZPL Label with ZplEngine

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Instantiate ZPL elements, add them to ZplEngine, and serialize to a ZPL string. Supports options for formatting and DPI scaling.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

var font = new ZplFont(fontWidth: 50, fontHeight: 50);
var elements = new List<ZplElementBase>
{
    new ZplTextField("SHIP TO: Warehouse 7", 50, 50, font),
    new ZplBarcode128("987654321012", 50, 150),
    new ZplGraphicBox(40, 130, 420, 2, borderThickness: 2),   // separator line
    new ZplQrCode("https://example.com/track/987654321012", 350, 200, magnificationFactor: 3),
};

// Add a raw ZPL fragment (e.g. for unsupported commands)
elements.Add(new ZplRaw("^FO200,400^GB300,1,2^FS"));

var options = new ZplRenderOptions
{
    AddStartEndFormat           = true,   // wraps output in ^XA … ^XZ
    AddDefaultLabelHome         = true,   // prepends ^LH0,0
    AddEmptyLineBeforeElementStart = true,
    DisplayComments             = false,
    SourcePrintDpi              = 203,
    TargetPrintDpi              = 300,    // auto-scales all coordinates
};

var engine = new ZplEngine(elements);
string zpl = engine.ToZplString(options);

Console.WriteLine(zpl);
// ^XA
// ^LH0,0
// ^A0N,74,74
// ^FO74,74
// ^FDShip to: Warehouse 7^FS
// … (scaled coordinates for 300 dpi)
// ^XZ
```

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

### Download and Print Image using ZplDownloadGraphics

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This snippet shows how to transfer an image using ZplDownloadGraphics, which employs ZPL commands ~DG and ^XG. The library converts the image to black and white before sending it to the printer. It includes rendering options with specified DPI values.

```cs
var elements = new List<ZplElementBase>();
elements.Add(new ZplDownloadGraphics('R', "SAMPLE", System.IO.File.ReadAllBytes("sample.bmp")));
elements.Add(new ZplRecallGraphic(100, 100, 'R', "SAMPLE"));

var renderEngine = new ZplEngine(elements);
var output = renderEngine.ToZplString(new ZplRenderOptions { AddEmptyLineBeforeElementStart = true, TargetPrintDpi = 600, SourcePrintDpi = 200 });

Console.WriteLine(output);
```

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

### ZPL Download Graphic with Z64 Encoding

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Label.UnitTest/ZplData/DownloadGraphicsZ64.txt

This ZPL code demonstrates downloading a graphic named 'SAMPLE.GRF' using Z64 encoding. The graphic data is provided directly within the command. The ^FS command terminates the field definition.

```zpl
^XA
^LH0,0

^FO0,0
^GB100,100,4,B,0^FS

~DGR:SAMPLE.GRF,1190,17,
:Z64:eNrV0z0OwyAMBeBHxMBWjuBUHTr2BuFoHK3H6hRq07T8DPaaRoI8fUv8ggD+5tlKKfmzvSoQr/yQjcIXHO4z3EZYcJ1hHcGD8gxpgACiGWKDrTwj6LL/AEgMYekgkwEOyQCOBngHAziPk1bo/geit0DeOnB7A7i9DtKeJ+XTHyAcnzva6yDtdZD2Okh7HdqQNfU1ajoPtMtU03mv/huIbE59:1804

^FO100,100
^XGR:SAMPLE.GRF,1,1^FS
^XZ
```

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

### Configure ZPL Rendering Behavior with ZplRenderOptions

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Control rendering options like DPI scaling, compression, and comment display. Useful for designing labels at one DPI and rendering for another.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

// Design the label at 203 dpi and output for a 600 dpi printer
var options = new ZplRenderOptions
{
    SourcePrintDpi = 203,
    TargetPrintDpi = 600,
    CompressedRendering = true,           // join all tokens on a single line per element
    AddEmptyLineBeforeElementStart = false,
    DisplayComments = true,
};

var tf = new ZplTextField("LOT#: AB-9921", 10, 10, new ZplFont(40, 40));
tf.Comments.Add("Lot number field");

var engine = new ZplEngine(new[] { tf });
string zpl = engine.ToZplString(options);
// ^XA
// ^LH0,0
// ^FX
// //Lot number field
// ^A0N,118,118^FO30,30^FDLOT#: AB-9921^FS    ← coordinates scaled ×2.96
// ^XZ

Console.WriteLine($"Scale factor: {options.ScaleFactor:F4}");  // 2.9557
Console.WriteLine($"Scaled value of 100: {options.Scale(100)}");  // 295
```

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

### Render ZPL Field Block with Word Wrap

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Creates a multi-line text block using the `^FB` command, supporting word wrapping, configurable line count, justification, and line spacing. Newlines in the source string are converted to ZPL `&` breaks.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

var font = new ZplFont(30, 30);
var longText = "The quick brown fox\njumps over the lazy dog near the river bank.";

var block = new ZplFieldBlock(
    longText,
    positionX: 10, positionY: 10,
    width: 400,
    font,
    maxLineCount: 3,
    lineSpace: 5,
    textJustification: TextJustification.Left,
    hangingIndent: 0);

Console.WriteLine(block.ToZplString());
// ^A0N,30,30
// ^FO10,10
// ^FB400,3,5,L,0
// ^FDThe quick brown fox\&jumps over the lazy dog near the river bank.^FS
```

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

### Render ZPL Elements to PNG

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Utilize ZplElementDrawer.Draw to render ZplElementBase objects into a PNG byte array. Specify label dimensions in millimeters and print density in dots-per-mm.

```csharp
using BinaryKits.Zpl.Viewer;
using System.IO;

IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage);
var analyzer = new ZplAnalyzer(printerStorage);

string zpl = @"^XA
^FT50,80^A0N,50,50^FDHello, ZPL!^FS
^FO50,100^GB500,3,3^FS
^FO50,120^BC N,80,Y,N^FDSN-2024-001^FS
^XZ";

var analyzeInfo = analyzer.Analyze(zpl);
foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    // labelWidth=101.6 mm, labelHeight=152.4 mm, density=8 dpmm (203 dpi)
    byte[] png = drawer.Draw(labelInfo.ZplElements, 101.6, 152.4, 8);
    File.WriteAllBytes("label_preview.png", png);
    Console.WriteLine($"PNG written: {png.Length} bytes");
}
```

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

### Import ZPL Label Elements

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

These using statements are required to utilize the ZPL label building blocks and elements within your C# project.

```cs
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;
```

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

### External ZPL Preview with Labelary API

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Utilize LabelaryClient to post ZPL data to the Labelary web API for a cloud-based PNG preview. Ensure no sensitive data is included when using this service.

```csharp
using BinaryKits.Zpl.Labelary;
using System;
using System.IO;
using System.Threading.Tasks;

async Task PreviewAsync()
{
    using var client = new LabelaryClient();

    string zpl = "^XA^FT100,100^A0N,60,60^FDLabelary Preview^FS^XZ";

    byte[] png = await client.GetPreviewAsync(
        zplData:      zpl,
        printDensity: PrintDensity.dpi203,
        labelSize:    new LabelSize(widthInInch: 4, heightInInch: 6));

    if (png.Length == 0)
    {
        Console.WriteLine("Preview request failed.");
        return;
    }

    File.WriteAllBytes("labelary_preview.png", png);
    Console.WriteLine($"Preview saved: {png.Length} bytes");
}

await PreviewAsync();
```

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

### Define and Recall ZPL Graphic

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Label.UnitTest/ZplData/DownloadGraphicsACS.txt

This snippet demonstrates defining a graphic using ~DGR and then recalling it using ^XGR. Ensure the graphic data is correctly formatted.

```zpl
^XA
^LH0,0

^FO0,0
^GB100,100,4,B,0^FS

~DGR:SAMPLE.GRF,1190,17,
,:::::::::H03MF803MF803HF8,H02M0803M0802H08,H02L01H028L0802H08,H02L01H024L0802H08,H02L02H0H2L0802H08,H02L02H021L0802H08,H02L04H0208K0802H08,H02L04H0204K0802H08,H02L08H0202K0802H08,H02L08H0201K0802H08,H03IFC01I02H0HFEH0802H08,L0401I02H0802H0802H08,L0802I02H0802H0802H08,:K01H04I02H0802H0802H08,:K02H08I02H0802H0802H08,:K0401J02H0802H0802H08,:K0802J02H0HFEH0802H08,K0802J02M0802H08,J01H04J02M0802H08,:J02H08J02M0802H08,:J0401K02M0802H08,:J0802K02M0802H08,:I01H04K02H0KF802H08,I01H04K02H08L02H08,I02H08K02H08L02H08,:I0401L02H08L02H08,:I0802L02H08L02H08,:H01H04L02H08L02H08,:H02H0KF802H08L02H0KF8,H02M0802H08L02M08,::::::::H03MF803HF8L03MF8,,::::::::

^FO100,100
^XGR:SAMPLE.GRF,1,1^FS
^XZ
```

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

### Auto Scale Graphic Box Based on DPI

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This snippet illustrates how to configure ZPL rendering to auto-scale elements based on source and target DPI. A graphic box is added, and ZplRenderOptions are used to specify SourcePrintDpi and TargetPrintDpi, allowing the library to handle scaling.

```cs
var elements = new List<ZplElementBase>();
elements.Add(new ZplGraphicBox(400, 700, 100, 100, 5));

var options = new ZplRenderOptions { SourcePrintDpi = 203, TargetPrintDpi = 300 };
var output = new ZplEngine(elements).ToZplString(options);

Console.WriteLine(output);
```

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

### Send ZPL Data to Printer via TCP

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

This snippet demonstrates how to connect to a printer via TCP and send ZPL data. Ensure the printer's IP address and port are correctly configured.

```cs
var zplData = @"^XA^MMP^PW300^LS0^LT0^FT10,60^APN,30,30^FH\^FDSAMPLE TEXT^FS^XZ";
// Open connection
var tcpClient = new System.Net.Sockets.TcpClient();
tcpClient.Connect("10.10.5.85", 9100);

// Send Zpl data to printer
var writer = new System.IO.StreamWriter(tcpClient.GetStream());
writer.Write(zplData);
writer.Flush();

// Close Connection
writer.Close();
tcpClient.Close();
```

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

### Download Base64 Encoded Graphic in ZPL

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Label.UnitTest/ZplData/DownloadGraphicsB64.txt

Use the ~DGR command with the :B64: prefix to download a Base64 encoded graphic. The graphic is then referenced using ^XGR.

```zpl
^XA
^LH0,0

^FO0,0
^GB100,100,4,B,0^FS

~DGR:SAMPLE.GRF,1190,17,
:B64:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAP////4A/////gD/4AAAAAAAgAAAAgDAAAACAIAgAAAAAACAAAAEAKAAAAIAgCAAAAAAAIAAAAQAkAAAAgCAIAAAAAAAgAAACACIAAACAIAgAAAAAACAAAAIAIQAAAIAgCAAAAAAAIAAABAAggAAAgCAIAAAAAAAIAAACAAgEAAAgCAIAAAAAAA//8AQACAP/gCAIAgAAAAAAAAAQBAAIAgCAIAgCAAAAAAAAACAIAAgCAIAgCAIAAAAAAAAAIAgACAIAgCAIAgAAAAAAAABAEAAIAgCAIAgCAAAAAAAAAEAQAAgCAIAgCAIAAAAAAAAAgCAACAIAgCAIAgAAAAAAAACAIAAIAgCAIAgCAAAAAAAAAQBAAAgCAIAgCAIAAAAAAAABAEAACAIAgCAIAgAAAAAAAAIAgAAIA/+AIAgCAAAAAAAAAgCAAAgAAAAgCAIAAAAAAAAEAQAACAAAACAIAgAAAAAAAAQBAAAIAAAAIAgCAAAAAAAACAIAAAgAAAAgCAIAAAAAAAAIAgAACAAAACAIAgAAAAAAABAEAAAIAAAAIAgCAAAAAAAAEAQAAAgAAAAgCAIAAAAAAAAgCAAACAAAACAIAgAAAAAAACAIAAAIAAAAIAgCAAAAAAAAQBAAAAgD///gCAIAAAAAAABAEAAACAIAAAAIAgAAAAAAAIAgAAAIAgAAAAgCAAAAAAAAgCAAAAgCAAAACAIAAAAAAAEAQAAACAIAAAAIAgAAAAAAAQBAAAAIAgAAAAgCAAAAAAACAIAAAAgCAAAACAIAAAAAAAIAgAAACAIAAAAIAgAAAAAABAEAAAAIAgAAAAgCAAAAAAAEAQAAAAgCAAAACAIAAAAAAAgD///gCAIAAAAIA///4AAACAAAACAIAgAAAAgAAAAgAAAIAAAAIAgCAAAACAAAACAAAAgAAAAgCAIAAAAIAAAAIAAACAAAACAIAgAAAAgAAAAgAAAIAAAAIAgCAAAACAAAACAAAAgAAAAgCAIAAAAIAAAAIAAACAAAACAIAgCAAAAAgAAAAgAAAIAAAAIAgCAAAACAAAACAAAAgAAAAgCAIAAAAIAAAAIAAAD////+AP/gAAAA/////gAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=:9723

^FO100,100
^XGR:SAMPLE.GRF,1,1^FS
^XZ
```

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

### Analyze and Draw ZPL Label

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/README.md

Use this snippet to analyze a ZPL string and draw the resulting label as a PNG image. Ensure ZPL syntax is correct.

```cs
IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage);

var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze("^XA^FT100,100^A0N,67,0^FDTestLabel^FS^XZ");

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    var imageData = drawer.Draw(labelInfo.ZplElements);
    File.WriteAllBytes("label.png", imageData);
}
```

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

### Render ZPL Elements to PDF

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Use ZplElementDrawer.DrawPdf to generate a PDF byte array from ZplElementBase objects. Enable PDF output by setting DrawerOptions.PdfOutput to true.

```csharp
using BinaryKits.Zpl.Viewer;
using System.IO;

IPrinterStorage printerStorage = new PrinterStorage();

var drawerOptions = new DrawerOptions { PdfOutput = true };
var drawer = new ZplElementDrawer(printerStorage, drawerOptions);
var analyzer = new ZplAnalyzer(printerStorage);

var analyzeInfo = analyzer.Analyze("^XA^FT10,50^A0N,40,40^FDPDF Label^FS^XZ");
foreach (var labelInfo in analyzeInfo.LabelInfos)
{
    byte[] pdf = drawer.DrawPdf(labelInfo.ZplElements, 101.6, 152.4, 8);
    File.WriteAllBytes("label.pdf", pdf);
    Console.WriteLine($"PDF written: {pdf.Length} bytes");
}
```

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

### ZplQrCode

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Generates a QR code with configurable model (1 or 2), magnification factor, and error correction level. Corresponds to `^BQ`.

```APIDOC
## ZplQrCode — QR code (`^BQ`)

Generates a QR code with configurable model (1 or 2), magnification factor, and error correction level (`HighDensity`, `Standard`, `HighReliability`, `UltraHighReliability`).

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

var qr = new ZplQrCode(
    content: "https://example.com/product/42",
    positionX: 300, positionY: 50,
    model: 2,
    magnificationFactor: 4,
    errorCorrectionLevel: ErrorCorrectionLevel.HighReliability);

Console.WriteLine(qr.ToZplString());
// ^FO300,50
// ^BQN,2,4,Q,7
// ^FDQA,https://example.com/product/42^FS
```
```

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

### ZplQrCode - Generate QR Code

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Generates a QR code with options for model (1 or 2), magnification factor, and error correction level. Ensure the `ErrorCorrectionLevel` enum is used for appropriate settings.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

var qr = new ZplQrCode(
    content: "https://example.com/product/42",
    positionX: 300, positionY: 50,
    model: 2,
    magnificationFactor: 4,
    errorCorrectionLevel: ErrorCorrectionLevel.HighReliability);

Console.WriteLine(qr.ToZplString());
```

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

### Analyze and Draw ZPL Data

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Viewer/README.md

This snippet demonstrates how to use the ZplAnalyzer to parse ZPL data and then use ZplElementDrawer to convert the parsed elements into PNG image data. It's useful for previewing ZPL labels.

```csharp
IPrinterStorage printerStorage = new PrinterStorage();
var drawer = new ZplElementDrawer(printerStorage);

var analyzer = new ZplAnalyzer(printerStorage);
var analyzeInfo = analyzer.Analyze(request.ZplData);

foreach (var labelInfo in analyzeInfo.LabelInfos)
{
	var imageData = drawer.Draw(labelInfo.ZplElements);
	//imageData is bytes of png image
}
```

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

### Embed and Recall Images using ~DG / ^XG

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Embed images (BMP, PNG, JPEG) using ZplDownloadGraphics with compression (ACS, Z64, B64) and recall them with ZplRecallGraphic. Configure render options for DPI conversion.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

byte[] imageBytes = File.ReadAllBytes("logo.png");

var elements = new List<ZplElementBase>
{
    // Download image to printer RAM device 'R', name 'LOGO'
    new ZplDownloadGraphics('R', "LOGO", imageBytes,
        compressionScheme: ZplCompressionScheme.ACS),

    // Place stored image at position (50, 50)
    new ZplRecallGraphic(50, 50, 'R', "LOGO",
        magnificationFactorX: 1,
        magnificationFactorY: 1),
};

var options = new ZplRenderOptions
{
    SourcePrintDpi = 200,
    TargetPrintDpi = 300,
};

string zpl = new ZplEngine(elements).ToZplString(options);
// ~DGR:LOGO.GRF,<byteCount>,<bytesPerRow>,
// <compressed hex data>
// ^FO0,0^XGR:LOGO.GRF,1,1^FS
```

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

### Native Image Transfer using ~DY / ^IM

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Transfer images in their original format using ZplDownloadObjects and recall them with ZplImageMove. Configure render options for adding empty lines before elements.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

byte[] bmpBytes = File.ReadAllBytes("icon.bmp");

var elements = new List<ZplElementBase>
{
    new ZplDownloadObjects('R', "ICON.BMP", bmpBytes),
    new ZplImageMove(100, 100, 'R', "ICON", "BMP"),
};

var options = new ZplRenderOptions { AddEmptyLineBeforeElementStart = true };
Console.WriteLine(new ZplEngine(elements).ToZplString(options));
// ~DYR:ICON.BMP,B,B,<size>,,<hex data>
// ^FO100,100^IMR:ICON.BMP^FS
```

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

### Utility Methods: AddRawZplCode and MapToHexadecimalValue

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Utilize ZplEngine.AddRawZplCode to append raw ZPL commands and ZplEngine.MapToHexadecimalValue to convert characters to their hex representation for manual field data encoding.

```csharp
using BinaryKits.Zpl.Label;

var engine = new ZplEngine();
engine.Add(new BinaryKits.Zpl.Label.Elements.ZplGraphicBox(10, 10, 100, 100));
engine.AddRawZplCode("^PR4,4");   // set print speed

// Hex-encode individual characters
string hexCaret = ZplEngine.MapToHexadecimalValue('^');  // "5E"
string hexTilde = ZplEngine.MapToHexadecimalValue('~');  // "7E"
Console.WriteLine($"^ = {hexCaret}, ~ = {hexTilde}");
```

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

### ZplGraphicBox

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Draws a rectangle with configurable dimensions, border thickness, line color, and corner rounding. Corresponds to `^GB`.

```APIDOC
## ZplGraphicBox — Filled or outlined rectangle (`^GB`)

Draws a rectangle with configurable dimensions, border thickness, line color (black or white), and corner rounding (0–8).

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

// Solid border box
var borderBox = new ZplGraphicBox(10, 10, 400, 200, borderThickness: 3);

// White-filled box (erase underlying content)
var eraser = new ZplGraphicBox(50, 50, 100, 100,
    borderThickness: 100,
    lineColor: LineColor.White);

// Rounded corners
var rounded = new ZplGraphicBox(200, 200, 150, 80,
    borderThickness: 2,
    cornerRounding: 4);

var engine = new ZplEngine(new[] { borderBox, eraser, rounded });
Console.WriteLine(engine.ToZplString(new ZplRenderOptions()));
// ^FO10,10^GB400,200,3,B,0^FS
// ^FO50,50^GB100,100,100,W,0^FS
// ^FO200,200^GB150,80,2,B,4^FS
```
```

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

### Inject Raw ZPL Fragments

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Use ZplRaw to inject arbitrary ZPL strings directly into the element tree, allowing for pass-through of unsupported commands. Combine with other ZPL elements.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

var elements = new List<ZplElementBase>
{
    new ZplTextField("Hello", 10, 10, new ZplFont(30, 30)),
    // Inject a raw printer media type command
    new ZplRaw("^MMP"),
    // Inject a raw print width command
    new ZplRaw("^PW609"),
};

string zpl = new ZplEngine(elements).ToZplString(new ZplRenderOptions());
Console.WriteLine(zpl);
```

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

### Parse ZPL String into Element Objects

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Use ZplAnalyzer to tokenize a raw ZPL string and map commands to ZplElementBase subclasses. The result is an AnalyzeInfo object containing label information, unknown commands, and errors.

```csharp
using BinaryKits.Zpl.Viewer;

IPrinterStorage printerStorage = new PrinterStorage();
var analyzer = new ZplAnalyzer(printerStorage);

string rawZpl = "^XA^FT100,100^A0N,40,40^FDInvoice #INV-2024-0051^FS^XZ";
var info = analyzer.Analyze(rawZpl);

Console.WriteLine($"Labels found : {info.LabelInfos.Length}");
Console.WriteLine($"Unknown cmds : {info.UnknownCommands.Length}");
Console.WriteLine($"Errors       : {info.Errors.Length}");

foreach (var labelInfo in info.LabelInfos)
{
    Console.WriteLine($"  Elements: {labelInfo.ZplElements.Length}");
    foreach (var element in labelInfo.ZplElements)
        Console.WriteLine($"    {element.GetType().Name}");
}
// Labels found : 1
// Unknown cmds : 0
// Errors       : 0
//   Elements: 1
//     ZplTextField
```

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

### Download Image to Printer Memory (ZPL)

Source: https://github.com/binarykits/binarykits.zpl/blob/develop/src/BinaryKits.Zpl.Label.UnitTest/ZplData/DownloadObject.txt

This command downloads an image file to the printer's memory. The image can then be referenced and printed on the label. Ensure the image format and dimensions are compatible with the printer.

```zpl
^XA
^LH0,0

^FO0,0
^GB150,150,6,B,0^FS

~DYR:SAMPLE.PNG,P,P,1315,,89504E470D0A1A0A0000000D49484452000000C3000000690803000000B026671000000057504C5445010101ACACAC3D3D3DEDEDED737373252525FEFEFECFCFCF5D5D5D0C0C0CDCDC838383B6B6B61515154C4C4C696969929292F4F4F4343434E4E4E47A7A7AD4D4D4565656636363C2C2C24444448B8B8B2D2D2DBDBDBDD3E099CC000000097048597300000EC400000EC401952B0E1B0000001974455874536F6674776172650041646F626520496D616765526561647971C9653C0000044D49444154789CED9B6193A2300C86ABCC06813BDD0A0CB3ABFFFF771EBA734E9BA62529ADD61DE2278490A67D78C976A382F7B72D87326CCBA10CDB7228C3B61CCAB02D8732EC57E6A0459F7CBE6B727843C339F4A3C05A7BBAFAB615F856A1B8E8AC28877EAF1AB6A9E6D3F46DF7CDA5E1BA235F14179D95E4A061546A384D2C3B7C4FEA080F7235B4CDECDC1D0E1CE7E1A826D3D78E6B9F95E5003036033FFFF16C5DDC5ED4D7C8F5AD9A53202E3ABB604E0E7CE7EFF315FB8E1F1DD3B96FA6405C7476C1304BCDC493C8F999FB52BDB1DE371EBEA1BBCCF3592DBA6BA81B9B253BAE75569603FCDC8B67FA74B6C9199BF9F1189A1DCB7BC4EB601C6AC93080CE813501E3F984AEFB09BC6BBAE53B6832076D1FB28D6289611A7A53944CDFEECC48C21EF4524A0B16CDD2F58215ECEE3B3F271D07A712581A2E57FCD5C37719A702589A831D2D51327D350BA7DC2C319C1D51327C3507A7FC2C2D15CAAE28A171DC71AABCF7C8CC12A3D67045090DEBB612FBF08D72B2A48E155540F7F665AE28D981F5ED6577D5B5BF9CCEC6D2BDF6242BE52F2B094294DC615D03E5744696E6DB7C4E4EE97D387D2A351A0BEF8A923BACF9590896D31959F2D8706ECDE112A204C45C86CAE98CBA445ABFB7548814256A1CFE723A2B4B84B056D0DA7FAF11A2141896A79C7E364B4885485182F05CEA203CF959422A448B92671CA29492B1840CA99047948039D3AF6209A9904794A06496900AF94409CA6509A9904F94A06C9698A214354ACF616A96B8A2043E96FE6FE5D42F62892D4AF4B0AC15D3B7D7F64B58628B12312CB38CAFF54EBD8825BE28B9C3B2CBF8BF7315CB9FF87439F045891A162EE307EB497A1E4B7C5192067E1A4B0251021100CF6249224A404E5E686FE4592C494409CA6449244A50224B225102F1E43D8925912841912CC94409CA6349284A50264B42519205D64F61492A4A00CBEF07F3536767492A4A209E3CAB14CFC492549488C081F69570299E8825B128810340B07DC52EC533B024172570266FB17DC52CC5B3B024172520E652D2BE929CA5085102E2D52BE87D49CD52842801C592B9AF11FE37650E96224409D6CD65729662440960D55CA665294A94C0C712CFD2B314254A50144B71A20405B114274A50184B71A20425B18445E9E30F4BE2213D4B9A1917E5E08AD2C46D084FCC92A04E719F07244A47B5AB6A5F094DB4912462C9D3FA427783A31CDAB35D3F5F94F257D0A82B3B214B6DB06F1C7783A3BE99DAEE0CA986A9F3D6CF4ECF763A96A8D6177F37787C8F2EDD4692822561DC5539F4043CE8309225515C4FBFB7F9D5C2DE441696047161CD3A24DDAB5B95F01A96C617B1340A5962074ECC123B2E6C2C6D2CB971B956324B917BE674BF77489C1F1FDFDEB5D564225C52CEA7C271A3FABD1F97E3BD6BB7C98479A3157181DDEFCDDABB0E3699846D4D5C66BF3763EF5A079B4CC2B6262E38EB102C7A837BD7B0D064B290C58AB8BFF2B7C7EF68597FC72EB115717FE53ABCA16D3994615B0E65D8964319B6E55086FD03FE4165CFE66895840000000049454E44AE426082

^FO150,150
^IMR:SAMPLE.PNG
^XZ
```

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

### ZplGraphicBox - Draw Rectangles

Source: https://context7.com/binarykits/binarykits.zpl/llms.txt

Draws rectangles with configurable dimensions, border thickness, line color (White for erasing), and corner rounding. Multiple boxes can be combined using a ZplEngine.

```csharp
using BinaryKits.Zpl.Label;
using BinaryKits.Zpl.Label.Elements;

// Solid border box
var borderBox = new ZplGraphicBox(10, 10, 400, 200, borderThickness: 3);

// White-filled box (erase underlying content)
var eraser = new ZplGraphicBox(50, 50, 100, 100,
    borderThickness: 100,
    lineColor: LineColor.White);

// Rounded corners
var rounded = new ZplGraphicBox(200, 200, 150, 80,
    borderThickness: 2,
    cornerRounding: 4);

var engine = new ZplEngine(new[] { borderBox, eraser, rounded });
Console.WriteLine(engine.ToZplString(new ZplRenderOptions()));
```