zebra-zpl 1.0.2 → 1.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 4601d04149c76a88c86a00b57b76b004ff603183
-  data.tar.gz: 75b6773cd9f63a0d9ca27e5b799949d076dfb150
+SHA256:
+  metadata.gz: dc4d0325bb49923c0936ec1a9945e0abd7ff840be83a761135b841ede695fadf
+  data.tar.gz: 8e085aeccc1055499e96c43c3585ecbe5e024d761618014583db6ca338941d24
 SHA512:
-  metadata.gz: 3883a043edbe74c0d9e8847f3ca3c48ef9c16605d703cc5efcd400623ab833cdb11706249412c5828d32bc2b3139dce1efd34c3e70ac503769ad0265fde5b25d
-  data.tar.gz: eb2baa12fff0b2b6eddc69692fea622ec2d7474947965ec9a6792196a3aa23f210671436e86783e44a09b08df32c261812f78668430bb0d5e05d988ce3eccb76
+  metadata.gz: 982e20fa56bc1deef5c9421e83c60da9c377e0d3acb68c4d3ec5ed33c309c86ef2ca48d51a2f62b6599ec8ac79db708b32db904620e72c2c3c252d7dcb600c28
+  data.tar.gz: 45fa3614e53bdc7b8ea1c95f75311768b1727cb1621776af195578c9781c96d0d5b023af151ad32b2a3ac48141e76c5faaa1b9e738b55e753c3fd7fc031da28f

data/CHANGELOG.md

@@ -0,0 +1,71 @@
+### 1.1.3 (10/05/2020)
+
+* [#70](https://github.com/bbulpett/zebra-zpl/pull/70): Update max print speed from 6 to 14 - [@eke-bb](https://github.com/eke-bb)
+
+### 1.1.2 (02/25/2019)
+
+* [#63](https://github.com/bbulpett/zebra-zpl/pull/63): Un-restrict font size - [@mtking2](https://github.com/mtking2)
+* [#62](https://github.com/bbulpett/zebra-zpl/pull/62): Add print service option for print jobs (`lp`/`rlpr`) - [@LagTag](https://github.com/LagTag)
+
+### 1.1.1 (12/19/2019)
+
+* [#58](https://github.com/bbulpett/zebra-zpl/pull/58): Add access to source `Img2Zpl::Image` object - [@mtking2](https://github.com/mtking2)
+
+### 1.1.0 (11/04/2019)
+
+* [#54](https://github.com/bbulpett/zebra-zpl/pull/54): Fix height bug with ^B commands - [@mtking2](https://github.com/mtking2)
+* [#53](https://github.com/bbulpett/zebra-zpl/pull/53): Added support for symbol types, fixed other bugs with the `Graphic` class, updated specs - [@mtking2](https://github.com/mtking2)
+* [#50](https://github.com/bbulpett/zebra-zpl/pull/50): Add support for image elements by incorporating the [img2zpl](https://github.com/mtking2/img2zpl) gem - [@mtking2](https://github.com/mtking2)
+* [#49](https://github.com/bbulpett/zebra-zpl/pull/49): Fixed bug with `Barcode`'s `^BY` command. Added UPCA, UPCE, & EAN13 types - [@mtking2](https://github.com/mtking2)
+* [#48](https://github.com/bbulpett/zebra-zpl/pull/48): Fixed bug breaking `Text` elements. Added rspecs for `Datamatrix` - [@mtking2](https://github.com/mtking2)
+* [#45](https://github.com/bbulpett/zebra-zpl/pull/45): Add CHANGELOG & update README - [@mtking2](https://github.com/mtking2)
+* [#44](https://github.com/bbulpett/zebra-zpl/pull/44): Update README & add more docs - [@mtking2](https://github.com/mtking2)
+* [#43](https://github.com/bbulpett/zebra-zpl/pull/43): Add ZPL comment element - [@LagTag](https://github.com/LagTag)
+* [#42](https://github.com/bbulpett/zebra-zpl/pull/42): Consolidate Graphic Elements to One Class. Deprecate `Box` class - [@LagTag](https://github.com/LagTag)
+* [#41](https://github.com/bbulpett/zebra-zpl/pull/41): Ability to pass ZPL string to PrintJob - [@LagTag](https://github.com/LagTag)
+* [#40](https://github.com/bbulpett/zebra-zpl/pull/40): Bold Text - [@LagTag](https://github.com/LagTag)
+* [#39](https://github.com/bbulpett/zebra-zpl/pull/39): Fix specs + minor maintenance - [@mtking2](https://github.com/mtking2)
+* [#36](https://github.com/bbulpett/zebra-zpl/pull/36): Add Datamatrix - [@rafaelmf3](https://github.com/rafaelmf3)
+* [#33](https://github.com/bbulpett/zebra-zpl/pull/33): Remove the hardcoded attributes for the box element - [@LagTag](https://github.com/LagTag)
+* [#32](https://github.com/bbulpett/zebra-zpl/pull/32): Added diagonal line graphic (^GD) - [@LagTag](https://github.com/LagTag)
+* [#31](https://github.com/bbulpett/zebra-zpl/pull/31): Added Circle Graphic (^GC) - [@LagTag](https://github.com/LagTag)
+* [#29](https://github.com/bbulpett/zebra-zpl/pull/29): Removed hard coded attributes in Text Element - [@LagTag](https://github.com/LagTag)
+* [#27](https://github.com/bbulpett/zebra-zpl/pull/27): Added pdf417 support - [@LagTag](https://github.com/LagTag)
+* [#25](https://github.com/bbulpett/zebra-zpl/pull/25): Don't Overwrite Element Widths - [@LagTag](https://github.com/LagTag)
+
+### 1.0.5 (2018/10/25)
+
+* [#22](https://github.com/bbulpett/zebra-zpl/pull/22): update label print density range from 0-6 to 0-15 - [@steve-abrams](https://github.com/steve-abrams)
+* [#21](https://github.com/bbulpett/zebra-zpl/pull/21): Support QR codes (fixed) - [@mtking2](https://github.com/mtking2)
+* [#20](https://github.com/bbulpett/zebra-zpl/pull/20): Fix incorrect raw flag - [@mtking2](https://github.com/mtking2)
+
+### 1.0.4 (2017/10/27)
+
+* [#15](https://github.com/bbulpett/zebra-zpl/pull/15): Raw ZPL support - [@bbulpett](https://github.com/bbulpett)
+
+### 1.0.3 (2017/06/12)
+
+* [#14](https://github.com/bbulpett/zebra-zpl/pull/14): Version bump to 1.0.3 - [@bbulpett](https://github.com/bbulpett)
+* [#13](https://github.com/bbulpett/zebra-zpl/pull/13): Windows Printing Support - [@mtking2](https://github.com/mtking2)
+
+### 1.0.2 (2017/04/27)
+
+* [ead84a4](https://github.com/bbulpett/zebra-zpl/commit/ead84a4170f291e9a121263ac0ce577b9b5b21ba): Revert to Unix-only `lp` - [@bbulpett](https://github.com/bbulpett)
+
+### 1.0.1 (2017/04/26)
+
+* [b5e3f3e](https://github.com/bbulpett/zebra-zpl/commit/b5e3f3ea41960ce953073dcf1b09c28047a17b0d): Attempt `lpr` for Windows if Unix `lp` fails - [@bbulpett](https://github.com/bbulpett)
+* [3858b33](https://github.com/bbulpett/zebra-zpl/commit/3858b332491d7afe34277d43530e0da7462da2b1): Use SSL for homepage in gemspec - [@bbulpett](https://github.com/bbulpett)
+
+### 1.0.0 (2017/04/26)
+
+* [#10](https://github.com/bbulpett/zebra-zpl/pull/10): Add side margins - [@bbulpett](https://github.com/bbulpett)
+* [#9](https://github.com/bbulpett/zebra-zpl/pull/9): Add padding to sides for text blocks - [@bbulpett](https://github.com/bbulpett)
+* [#8](https://github.com/bbulpett/zebra-zpl/pull/8): Add rotation to zpl builders - [@bbulpett](https://github.com/bbulpett)
+* [#7](https://github.com/bbulpett/zebra-zpl/pull/7): Add international text support and apply label width to zpl builder methods - [@bbulpett](https://github.com/bbulpett)
+* [#6](https://github.com/bbulpett/zebra-zpl/pull/6): Font modifications - [@bbulpett](https://github.com/bbulpett)
+* [#5](https://github.com/bbulpett/zebra-zpl/pull/5): Restore barcode functionality - [@bbulpett](https://github.com/bbulpett)
+* [#4](https://github.com/bbulpett/zebra-zpl/pull/4): Orientation module - [@bbulpett](https://github.com/bbulpett)
+* [#3](https://github.com/bbulpett/zebra-zpl/pull/3): Restore zpl barcode logic - [@bbulpett](https://github.com/bbulpett)
+* [#2](https://github.com/bbulpett/zebra-zpl/pull/2): ZPL barcodes tested and working - [@bbulpett](https://github.com/bbulpett)
+* [#1](https://github.com/bbulpett/zebra-zpl/pull/1): Convert zpl method, class, and file namings - [@bbulpett](https://github.com/bbulpett)

data/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+## Contributing
+
+Check [open issues](https://github.com/bbulpett/zebra-zpl/issues) for things that need work.  
+Also check any [open pull requests](https://github.com/bbulpett/zebra-zpl/pulls) to make sure any changes you want to make haven't already been made by someone else.
+
+### Fork & clone the repository
+
+```
+git clone git@github.com:<your-username>/zebra-zpl.git
+cd zebra-zpl
+git remote add upstream git@github.com:bbulpett/zebra-zpl.git
+bundle install
+```
+
+Then check out a working branch:
+
+```
+git checkout -b <my-working-branch>
+```
+
+### Write tests
+
+This project uses `rspec`. After writing your tests, you can run tests with the following command:
+
+`bundle exec rspec`
+
+
+### Write code
+
+Write your code to make your tests pass.
+
+### Update the CHANGELOG with a description and your name
+
+Update `CHANGELOG.md` with the description of your code changes and your name on the line after `"* Your contribution here"`.
+
+### Commit & Push your changes
+
+Commit and push your changes to your working branch.
+
+```
+git commit -am 'Add some feature'
+git push origin <my-working-branch>
+```
+
+### Open a pull request
+
+Open a pull request against upstream master and your working branch. Give a brief description of what your PR does and explain what the code changes do.
+
+Thank you!

data/Gemfile

@@ -1,4 +1,10 @@
 source 'https://rubygems.org'
 
+group :development, :test do
+  gem 'byebug'
+  gem 'pry'
+  gem 'pry-nav'
+end
+
 # Specify your gem's dependencies in zebra-zpl.gemspec
 gemspec

data/README.md

@@ -1,10 +1,30 @@
-#### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, my needs require many of the new Zebra (ZPL) functions. 
-
 # Zebra::Zpl
 
-### ToDo: Update documentation with instructions for new features such as font sizing, margins, and text alignment
+[![gem](https://img.shields.io/gem/v/zebra-zpl?color=orange)](https://rubygems.org/gems/zebra-zpl)
+[![downloads](https://img.shields.io/gem/dt/zebra-zpl?color=brightgreen)](https://rubygems.org/gems/zebra-zpl)
+
+Zebra::Zpl offers a Ruby DSL to design and print labels using the ZPL programming language.
+
+## Contents
+
+  - [Installation](#installation)
+  - [Usage](#usage)
+    - [Building Labels](#building-labels)
+    - [Printing Labels](#printing-the-labels)
+  - [Elements](#available-elements)
+    - [Text](#text)
+    - [Raw ZPL](#raw-zpl)
+    - [Barcodes](#barcodes)
+    - [QR Codes](#qr-codes)
+    - [Data Matrix](#data-matrix)      
+    - ~[Boxes](#boxes)~ - deprecated. See [Graphics](#graphics)
+    - [Images](#images)
+  - [Options](#options)
+    - [Rotation](#elements-rotation)
+    - [Justification](#elements-justification)
+  - [Contributing](#contributing)
+  - [References](#references)
 
-Zebra::Zpl offers a Ruby DSL to design and print labels using the ZPL programming language. 
 
 ## Installation
 
@@ -14,11 +34,11 @@ Add this line to your application's Gemfile:
 
 And then execute:
 
-    $ bundle
+    bundle install
 
 Or install it yourself as:
 
-    $ gem install zebra-zpl
+    gem install zebra-zpl
 
 ## Usage
 
@@ -29,81 +49,97 @@ You create new labels with an instance of the `Zebra::Zpl::Label` class. It acce
 * `copies`: The number of copies to print. This option defaults to 1.
 * `width`: The label's width, in dots.
 * `length`: The label's length, is dots.
-* `gap`: The gap between labels, in dots.
 * `print_speed`: The print speed to be used. You can use values between 0 and 6. This option is required.
-* `print_density`: The print density to be used. You can use values between 0 and 15. This option is required.
 
 With a label, you can start adding elements to it:
 
-	label = Zebra::Zpl::Label.new :print_density => 8, :print_speed => 3
-	text  = Zebra::Zpl::Text.new :data => "Hello, printer!", :position => [100, 100], :font_size => Zebra::Zpl::FontSize::SIZE_2
-	label << text
-	
+```ruby
+label = Zebra::Zpl::Label.new print_speed: 3
+text  = Zebra::Zpl::Text.new(
+  data:       "Hello, printer!",
+  position:   [100, 100],
+  font_size:  Zebra::Zpl::FontSize::SIZE_2
+)
+label << text
+```
+
 You can add as many elements as you want.
 
 ### Printing the labels
 
-You need to have your printer visible to CUPS. Once your printer is configured and you know its name on CUPS, you can send the labels to the printer using a `Zebra::PrintJob` instance.
-
-	label = Zebra::Zpl::Label.new(
-	  :width         => 200,
-	  :length        => 200,
-	  :print_speed   => 3,
-	  :print_density => 6
-	)
-	
-	
-	barcode = Zebra::Zpl::Barcode.new(
-	  :data                      => "12345678",
-	  :position                  => [50, 50],
-	  :height                    => 50,
-	  :print_human_readable_code => true,
-	  :narrow_bar_width          => 4,
-	  :wide_bar_width            => 8,
-	  :type                      => Zebra::Zpl::BarcodeType::CODE_128_AUTO
-	)
-	
-	label << barcode
-	
-	print_job = Zebra::PrintJob.new "your-printer-name-on-cups"
-	
-	print_job.print label
-
-This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `lpr -P <your-printer-name-on-cups> -o raw <path-to-the-temp-file>` (if you're on Mac OSX) or `lp -d <your-printer-name-on-cups> -o raw <path-to-the-tempfile>` (if you're on Linux). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class. 
-
-### Printing QR codes
-
-    label = Zebra::Zpl::Label.new(
-      :width=>350,
-      :length=>250,
-      :print_speed=>3,
-      :print_density=>6
-    )
-
-    qrcode = Zebra::Zpl::Qrcode.new(
-      :data=>"www.github.com",
-      :position=>[50,10],
-      :scale_factor=>3,
-      :correction_level=>"H"
-    )
-
-    label << qrcode
-
-    print_job = Zebra::PrintJob.new "your-qr-printer-name-on-cups"
-
-    print_job.print label
-	
-### Available elements
-
-#### Text
+You need to have your printer visible to CUPS (or shared on the network in Windows). Once your printer is configured and you know its name on CUPS (or the Windows shared printer name), you can send the labels to the printer using a `Zebra::PrintJob` instance.
+
+```ruby
+label = Zebra::Zpl::Label.new(
+  width:        200,
+  length:       200,
+  print_speed:  3
+)
+
+
+barcode = Zebra::Zpl::Barcode.new(
+  data:                       '12345678',
+  position:                   [50, 50],
+  height:                     50,
+  print_human_readable_code:  true,
+  narrow_bar_width:           4,
+  wide_bar_width:             8,
+  type:                       Zebra::Zpl::BarcodeType::CODE_128_AUTO
+)
+
+label << barcode
+
+print_job = Zebra::PrintJob.new '<your-printer-name-on-cups/windows-shared-printer-name>'
+
+ip = '<IP/Host where the print queue lives>'  # can use 'localhost', '127.0.0.1', or '0.0.0.0' for local machine
+
+print_job.print label, ip
+```
+
+This will persist the label contents to a tempfile (using Ruby's tempfile core library) and copy the file to the printer using either `rlpr -H <hostname/ip> -P <your-printer-name-on-windows> -o <path-to-the-temp-file>` (for Windows systems, see [section](#printing-directly-to-windows-lpd) below) or `lp -h <hostname/ip> -d <your-printer-name-on-cups> -o raw <path-to-the-tempfile>` (for Unix systems). All the tempfile creation/path resolution, as well as which command has to be used, are handled by the `PrintJob` class.
+
+##### Print Service
+
+You can specify what print service command you want to be used when calling the `print` method by setting the `:print_service` option parameter. If left unspecified, it will attempt to send the print job first via `rlpr` - if the `rlpr` command fails in anyway then it will fall back to the `lp` command.
+
+```ruby
+print_job.print label, ip, print_service: 'lp'  # attempt only via the lp command
+
+print_job.print label, ip, print_service: 'rlpr'  # attempt only via the rlpr command
+
+print_job.print label, ip  # attempt via rlpr first, fallback to lp
+```
+
+#### Printing directly to Windows LPD
+This gem also supports printing directly to shared printer on Windows using LPD.
+In order to print directly to a LPD on a Windows machine you need two things:
+- [rlpr](http://manpages.ubuntu.com/manpages/xenial/man1/rlpr.1.html) installed on the (UNIX) system running your app that uses this gem.<sup>[1](#fn1)</sup>
+- LPD Print Service and LPR Port Monitor features enabled on the Windows machine.<sup>[2](#fn2)</sup>
+
+<p align="center">
+<img align="center" src="http://i.imgur.com/3CWkEWU.png" height="300px"/>
+<p/>
+
+<hr/>
+
+<sup><a name="fn1">1</a>. On a distro such as Ubuntu simply do: `sudo apt-get install rlpr`  
+If using OSX then you will have to manually build it from source and add it to your `$PATH` environment variable.<sup/>
+
+<sup><a name="fn2">2</a>. The printer name that you pass in must correspond with the **shared printer name** on the Windows machine.</sup>
+
+## Available elements
+
+### Text
+
+<p align="center">
+  <img src="docs/images/text.png" width="400">
+</p>
 
 You create text elements to print using instances of the `Zebra::Zpl::Text` class. It accepts the following options:
 
-* `position`: An array with the coordinates to place the text, in dots. 
-* `rotation`: The rotation for the text. More about the possible values below.
+* `position`: An array with the coordinates to place the text, in dots.
+* `rotation`: The rotation for the text. More about the possible values below (see [Rotation](#elements-rotation) section).
 * `data`: The text to be printed.
-* `v_multiplier`: The vertical multiplier to use. 
-* `h_multiplier`: The horizontal multipler to use.
 * `print_mode`: The print mode. Can be normal ("N") or reverse ("R").
 * `font_size`: The font size to use. You can use values between 1 and 5.
 
@@ -112,14 +148,38 @@ For the print modes, you can also use the constants:
 * `Zebra::Zpl::PrintMode::NORMAL`
 * `Zebra::Zpl::PrintMode::REVERSE`
 
+### Raw ZPL
+
+The `Zebra::Zpl::Raw` class allows you to supply a raw string of ZPL to include on a label. This can be useful for small images, sections of static ZPL that never change, or if you have previously generated ZPL.
+
+* `data`: The ZPL string to be printed.
+* `position`: An array with the coordinates to place the text, in dots.
+* `rotation`: The rotation for the text. More about the possible values below (see [Rotation](#elements-rotation) section).
+
+```ruby
+label = Zebra::Zpl::Label.new width: 600, length: 305, print_speed: 6
+
+zpl_string = "^GFA,1300,1300,13,,::::::O01IFE,N01KFE,N0MFC,M03NF,M0OFC,L03PF,L0QF8,K01QFE,K03RF,K07RF8,J01SFC,J03F9OFE7E,J07F01MFE03F,J07E007LF803F8,J0FE003KFE001FC,I01FEI0FC00FC001FE,I03FCI04M01FF,I07FCQ01FF,I07FCQ01FF8,I0FFCQ01FFC,I0FFEQ01FFC,001FFEQ01FFE,:003FFEQ03IF,003FFEQ01IF,007FFCR0IF,007FFCR0IF8,007FF8R07FF8,00IFS03FF8,00IFS03FFC,:00FFES01FFC,01FFES01FFC,01FFES01FFE,:01FFCS01FFE,:::::01FFES01FFE,::01FFES03FFE,01IFS03FFE,01IFS03FFC,01IF8R07FFC,00IF8R0IFC,00IFCR0IFC,00IFEQ01IFC,00JFQ03IF8,007IF8P07IF8,007IFCP0JF8,007JFO03JF,003F87FCN0KF,003F81FFM03JFE,001F80FFEK01KFE,001FC07FFCJ0LFC,I0FF03FF8J0LFC,I0FF03FF8J07KF8,I07F81FF8J07KF8,I03F807F8J07KF,I03FC004K07JFE,I01FCN07JFE,J0FEN07JFC,J07FN07JF8,J03F8M07JF,J01FCM07IFE,K0FFM07IFC,K07IF8J07IF8,K03IF8J07IF,L0IF8J07FFC,L07FF8J07FF8,L01FF8J07FE,M0FF8J07F8,M01F8J07E,N07K038,,::::::::::::::^FS"
+
+raw_zpl = Zebra::Zpl::Raw.new(
+  data:       zpl_string,
+  position:   [50, 50],
+)
 
-#### Barcodes
+label << raw_zpl
+```
+
+### Barcodes
+
+<p align="center">
+  <img src="docs/images/barcode.png" width="400">
+</p>
 
 You create barcode elements to print using instances of the `Zebra::Zpl::Barcode` class. It accepts the following options:
 
-* `position`: An array with the coordinates to place the text, in dots. 
+* `position`: An array with the coordinates to place the barcode, in dots.
 * `height`: The barcode's height, in dots.
-* `rotation`: The rotation for the text. More about the possible values below.
+* `rotation`: The rotation for the text. More about the possible values below (see [Rotation](#elements-rotation) section).
 * `data`: The text to be printed.
 * `type`: The type os barcode to use. More on the available types below.
 * `narrow_bar_width`: The barcode's narrow bar width, in dots.
@@ -137,21 +197,211 @@ The available barcode types are:
 * `Zebra::Zpl::BarcodeType::CODE_UPS_MAXICODE`
 * `Zebra::Zpl::BarcodeType::CODE_QR`
 
-#### QR Codes
+### QR Codes
+
+<p align="center">
+  <img src="docs/images/qrcode.png" width="400">
+</p>
 
 You can create QR Codes elements to print using instances of the `Zebra::Zpl::Qrcode` class. It accepts the following options:
 
 * `position`: An array with the coordinates to place the QR code, in dots.
-* `scale factor`: Crucial variable of the QR codes's size. Accepted values: 1-99.
-* `error correction level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored.
-
-#### Boxes
-
-You can draw boxes in your labels:
-
-	box = Zebra::Zpl::Box.new :position => [20, 20], :end_position => [100, 100], :line_thickness => 39
-	
-#### Elements Rotation
+* `scale_factor`: Crucial variable of the QR codes's size. Accepted values: 1-99.
+* `correction_level`: Algorithm enables reading damaged QR codes. There are four error correction levels: L - 7% of codewords can be restored, M - 15% can be restored, Q - 25% can be restored, H - 30% can be restored.
+
+#### Printing QR codes
+
+```ruby
+label = Zebra::Zpl::Label.new(
+  width:        350,
+  length:       250,
+  print_speed:  3
+)
+
+qrcode = Zebra::Zpl::Qrcode.new(
+  data:             'www.github.com',
+  position:         [50,10],
+  scale_factor:     3,
+  correction_level: 'H'
+)
+
+label << qrcode
+
+print_job = Zebra::PrintJob.new '<your-qr-printer-name-on-cups>'
+
+print_job.print label, '<hostname>'
+```
+
+### Data Matrix
+
+<p align="center">
+  <img src="docs/images/datamatrix.png" width="400">
+</p>
+
+You can create Data Matrix elements to print using instances of the `Zebra::Zpl::Datamatrix` class. It accepts the following options:
+
+* `position`: An array with the coordinates to place the data matrix, in dots.
+* `symbol_height`: Crucial variable of the size size of the data matrix. Accepted values: 1 - label width.
+* `aspect_ratio`: 1 for square, 2 for rectangular.
+
+```ruby
+datamatrix = Zebra::Zpl::Datamatrix.new(
+  data:             'www.github.com',
+  position:         [50,50],
+  symbol_height:     5
+)
+```
+
+### Boxes
+
+**&ast;&ast;&ast; The `Zebra::Zpl::Box` class is deprecated and will be removed in future versions. Please switch to the `Zebra::Zpl::Graphic` class (see [Graphics](#graphics) below). &ast;&ast;&ast;**  
+
+### Graphics
+
+<p align="center">
+  <img src="docs/images/graphics.png" width="400">
+</p>
+
+You can create graphics elements using the `Zebra::Zpl::Graphic` class:
+
+* `position`: An array with the coordinates to place the graphic, in dots.
+* `graphic_type`: Sets the type of graphic:
+  * `B`: Box
+  * `C`: Circle
+  * `D`: Diagonal
+  * `E`: Ellipse
+  * `S`: Symbol, _see symbol types below._
+* `graphic_width`: Width of the element in dots. (use as the diameter for circles, `C`)
+* `graphic_height`: Height of the element in dots. (does not apply to circles, `C`)
+* `line_thickness`: The thickness of the border in dots.
+* `color`: The color if the lines. B for black, W for white.
+* `orientation`: Only applies to diagonals (graphic type `D`). `R` for right-leaning. `L` for left-leaning.
+* `rounding_degree`: Only applies to boxes (graphic type `B`). Determines what degree to round the corners of the box. Valid values are 0 - 8.
+* `symbol_type`: Only applies to symbols (graphic type `S`). Possible values are:
+  * `A`: ® - Registered Trade Mark
+  * `B`: © - Copyright
+  * `C`: ™ - Trade Mark
+  * `D`: (UL) - Underwriters Laboratories approval
+  * `E`: (SA) - Canadian Standards Association approval
+
+```ruby
+label = Zebra::Zpl::Label.new width: 600, length: 305, print_speed: 6
+
+box = Zebra::Zpl::Graphic.new(
+  graphic_type:     'B',
+  position:         [20,25],
+  graphic_width:    50,
+  graphic_height:   50,
+  line_thickness:   2,
+  rounding_degree:  2
+)
+
+circle = Zebra::Zpl::Graphic.new(
+  graphic_type:   'C',
+  position:       [80,25],
+  graphic_width:  50,
+  line_thickness: 3
+)
+
+diagonal1 = Zebra::Zpl::Graphic.new(
+  graphic_type:   'D',
+  position:       [140,25],
+  graphic_width:  50,
+  graphic_height: 50,
+  line_thickness: 3,
+  orientation:    'R'
+)
+diagonal2 = diagonal1.dup
+diagonal2.orientation = 'L'
+
+ellipse = Zebra::Zpl::Graphic.new(
+  graphic_type:   'E',
+  position:       [200,25],
+  graphic_width:  25,
+  graphic_height: 50,
+  line_thickness: 3
+)
+
+symbol = Zebra::Zpl::Graphic.new(
+  graphic_type:   'S',
+  symbol_type:    'B',
+  position:       [235,25],
+  graphic_width:  50,
+  graphic_height: 50
+)
+
+label << box
+label << circle
+label << diagonal1
+label << diagonal2
+label << ellipse
+label << symbol
+
+print_job = Zebra::PrintJob.new '<your-qr-printer-name-on-cups>'
+print_job.print label, '<hostname>'
+```
+
+### Images
+
+<p align="center">
+  <img src="docs/images/images.png" width="700">
+</p>  
+
+You can also create graphics elements from an image using the `Zebra::Zpl::Image` class. Images are converted and encoded into an `^GF` (_Graphics Field_) command using the [img2zpl](https://github.com/mtking2/img2zpl) gem. Accepted parameters are:
+
+* `path` (required): The file path or URL of an image.
+* `position`: An array with the coordinates to place the image, in dots.
+* `width`: The width (in pixels) that the image should be printed.
+* `height`: The height (in pixels) that the image should be printed.
+* `rotation`: The number of degrees the image should be rotated
+  * unlike the other elements with strict 90° rotations, image elements can be rotated any number of degrees since the image is rotated with imagemagick before conversion to ZPL.
+* `black_threshold`: A value between 0 and 1 that sets the darkness threshold which determines how dark a pixel should be in order to become black in the resulting b/w image. Use larger value for a more saturated image and smaller value for a less saturated one. Default: `0.5`
+* `invert`: set to `true` to invert which pixels are set to black and which are set to white. Default is, depending on the `black_threshold`, dark pixels become black and light pixels become white.
+
+#### Usage
+```ruby
+label = Zebra::Zpl::Label.new width: 600, length: 305, print_speed: 6
+
+image = Zebra::Zpl::Image.new(
+  path: '/path/to/my/image.jpg',
+  position: [100, 50],
+  width: 200,
+  height: 180,
+  rotation: -90,
+  black_threshold: 0.35
+)
+
+label << image
+```
+**Modifying Images**
+
+<p align="center">
+  <img src="docs/images/image_manipulation.png" width="500">
+</p>  
+
+Image elements can also be modified in many ways before being added to the label by calling ImageMagick commands (provided by the [minimagick](https://github.com/minimagick/minimagick) & [img2zpl](https://github.com/mtking2/img2zpl) gems) on the source `Img2Zpl::Image < MiniMagick::Image` object.
+
+**Example:** Flattening an image's layers, so it is properly converted, and then trimming out unnecessary white space around the edges:
+
+```ruby
+label = Zebra::Zpl::Label.new width: 600, length: 305, print_speed: 6
+image = Zebra::Zpl::Image.new path: 'path/to/image.png', position: [0, 0]
+
+img_src = image.source #=> instance of Img2Zpl::Image < MiniMagick::Image
+
+img_src.flatten
+img_src.trim
+
+label << image
+```
+
+## Options
+
+### Elements Rotation
+
+<p align="center">
+  <img src="docs/images/rotation.png" width="400">
+</p>  
 
 All printable elements can be rotated on the label, using the `:Rotation` option. The accepted rotation values are:
 
@@ -160,7 +410,11 @@ All printable elements can be rotated on the label, using the `:Rotation` option
 * `Zebra::Zpl::Rotation::DEGREES_180`: will rotate the element 180 degrees.
 * `Zebra::Zpl::Rotation::DEGREES_270`: will rotate the element 270 degrees.
 
-#### Elements Justification
+### Elements Justification
+
+<p align="center">
+  <img src="docs/images/justification.png" width="400">
+</p>  
 
 There are four ZPL-supported `:Justification` parameters. "LEFT" (left-justified) is the default.
 
@@ -169,12 +423,17 @@ There are four ZPL-supported `:Justification` parameters. "LEFT" (left-justified
 * `Zebra::Zpl::Justification::CENTER` ~ centered
 * `Zebra::Zpl::Justification::JUSTIFIED` ~ full-width-justifed _(YMMV)_
 
+## Examples
 
+See [docs/example.rb](docs/example.rb) for code samples of most elements.
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+See [CONTRIBUTING.md](CONTRIBUTING.md) on how to contribute to this project.
+
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes by version as well as all the awesome people who have contributed to the project.
+
+## References
+
+###### This is a gem based on a terrific older gem by Cassio Marques. Although the new printers are mostly compatible with old Eltron (Epl) code, our needs require many of the new Zebra (ZPL) functions.
+* [Zebra Technologies Corporation, _"ZPL II Programming Guide."_ 2019 PDF](https://www.zebra.com/content/dam/zebra/manuals/printers/common/programming/zpl-zbi2-pm-en.pdf)