ruby-zint

This gem is a Ruby FFI binding for the libzint barcode generation library.

See the documentation for a full API description.

Install via RubyGems:

gem install ruby-zint

This installs the binary gem, specific to the running platform by default.

The binary gems don't depend on the libzint package on the running system or on CMake or libpng. They have libzint builtin and should just work.

If for some reason the binary gem doesn't work for you, the source gem can be installed alternatively. It can be forced by:

gem uninstall ruby-zint --all
gem install ruby-zint --platform ruby

By default ruby-zint first tries to use libzint installed on the system. If libzint can't be found or if it isn't a supported version, then the zint version, bundled into the gem, is compiled and used instead. Both install methods can be enforced by using --enable-system-libzint or --disable-system-libzint options, see below.

First install CMake with your package manager (e. g. apt install cmake). Please also install libpng (e. g. apt install libpng-dev) before installing the gem if you want to use the PNG format. Afterwards install the gem and force builtin libzint:

$ gem install ruby-zint -- --disable-system-libzint

Install the libzint binary with your package manager (e. g. apt install zint or perhaps brew install zint). Other platforms require building from source.

NOTE: It is assumed that you are using libzint with the version 2.15.

Then install this gem and enforce system libzint:

$ gem install ruby-zint -- --enable-system-libzint

Include gem "ruby-zint" in your Gemfile. To make sure, the necessary platforms and the source gem are fetched by bundler, they can be added like so

bundle lock --add-platform x86_64-linux-gnu
bundle lock --add-platform arm64-darwin
bundle lock --add-platform x64-mingw-ucrt
bundle lock --add-platform ruby
bundle package --all-platforms

A re-run of bundle package is also necessary after bundle update, in order to retrieve the new specific gems of all platforms.

If the binary gems don't work for some reason, it's easy to force the usage of the source gem in the Gemfile:

gem "ruby-zint", force_ruby_platform: true

Optionally set the install option by running bundler like so:

bundle config build.ruby-zint --enable-system-libzint

require "zint"

barcode = Zint::Barcode.new(value: "Test", symbology: Zint::BARCODE_CODE128)

# Export to file
barcode.to_file(path: "out.png")

# Export file to memory
barcode.to_memory_file(extension: ".png")

# Write from Bitmap to own canvas
require "chunky_png"
png = ChunkyPNG::Image.new(bitmap.width, bitmap.height, ChunkyPNG::Color::TRANSPARENT)
white = ChunkyPNG::Color("white")
black = ChunkyPNG::Color("black")

bitmap = barcode.to_bitmap
bitmap.pixels.each do |pixel|
  png.compose_pixel(pixel.x, pixel.y, (pixel.colour == "1") ? black : white)
end

png.save("out.png")

# Use vector export
vec = Zint::Qr.new(value: "Test").to_vector
png = ChunkyPNG::Image.new(vec.width.to_i, vec.height.to_i, ChunkyPNG::Color::WHITE)
vec.each_rectangle do |rec|
  png.rect(rec.x.to_i, rec.y.to_i,
      rec.x.to_i+rec.width.to_i-1, rec.y.to_i+rec.height.to_i-1,
      ChunkyPNG::Color::BLACK, ChunkyPNG::Color::BLACK)
end
png.save("out.png")

# See also manual: https://zint.org.uk/manual/chapter/5#buffering-symbols-in-memory-vector

# Use file as input
barcode = Zint::Barcode.new(input_file: "/tmp/test.txt")
barcode.to_file(path: "out.png")

# Use of comfort classes

# EAN
ean_barcode = Zint::Eanx.new(value: "012345678912")
ean_barcode.to_file(path: "ean.png")

# Code128
code_128_barcode = Zint::Code128.new(value: "012345678912")
code_128_barcode.to_file(path: "code_128.png")

Bug reports and pull requests are welcome on GitHub at https://github.com/api-walker/ruby-zint.

The gem is available as open source under the terms of the MIT License.

The project is based on the work and ideas of Angel Pizarro's zint. I would also like to say a big thank you to Lars Kanis for his great contributions.