zpl_render 0.1.0

data/lib/zpl_render/truetype.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module ZplRender
+  # Minimal pure-Ruby TrueType font loader and glyph rasterizer.
+  #
+  # Parses just enough of a .ttf (head, maxp, cmap format 4, loca, glyf,
+  # hhea, hmtx, OS/2) to rasterize glyph outlines: quadratic contours are
+  # flattened to polygons and filled scanline-wise with the non-zero
+  # winding rule, sampling at pixel centers. Output is 1-bit, matching a
+  # thermal print head.
+  class TrueType
+    ON_CURVE = 0x01
+    X_SHORT = 0x02
+    Y_SHORT = 0x04
+    REPEAT = 0x08
+    X_SAME_OR_POS = 0x10
+    Y_SAME_OR_POS = 0x20
+
+    CURVE_SEGMENTS = 8 # polyline segments per quadratic bezier
+
+    Glyph = Struct.new(:canvas, :left, :top, keyword_init: true)
+
+    attr_reader :units_per_em, :cap_height
+
+    def self.default
+      @default ||= new(File.expand_path("fonts/LiberationSans-Bold.ttf", __dir__))
+    end
+
+    def self.mono
+      @mono ||= new(File.expand_path("fonts/LiberationMono-Regular.ttf", __dir__))
+    end
+
+    def initialize(path)
+      @data = File.binread(path)
+      @tables = parse_table_directory
+      parse_head
+      parse_maxp
+      parse_hhea_hmtx
+      parse_cmap
+      parse_os2
+      @glyph_cache = {}
+      @contour_cache = {}
+    end
+
+    # Advance width in font units for a unicode codepoint.
+    def advance(code)
+      gid = glyph_id(code)
+      @advances[gid] || @advances.last || @units_per_em / 2
+    end
+
+    def glyph_id(code)
+      @cmap_cache[code] ||= lookup_cmap(code)
+    end
+
+    # Rasterize a glyph at the given x/y scales (pixels per font unit).
+    # Returns a Glyph whose canvas is stamped at
+    # (pen_x + left, baseline_y - top). Returns nil for blank glyphs.
+    def glyph_bitmap(code, scale_x, scale_y)
+      key = [code, (scale_x * 10_000).round, (scale_y * 10_000).round]
+      return @glyph_cache[key] if @glyph_cache.key?(key)
+
+      @glyph_cache[key] = rasterize(glyph_id(code), scale_x, scale_y)
+    end
+
+    private
+
+    # ---- table directory and fixed-layout tables ----------------------------
+
+    def u8(o) = @data.getbyte(o)
+    def u16(o) = (@data.getbyte(o) << 8) | @data.getbyte(o + 1)
+    def i16(o)
+      v = u16(o)
+      v >= 0x8000 ? v - 0x10000 : v
+    end
+    def u32(o) = (u16(o) << 16) | u16(o + 2)
+
+    def parse_table_directory
+      count = u16(4)
+      tables = {}
+      count.times do |i|
+        rec = 12 + i * 16
+        tag = @data[rec, 4]
+        tables[tag] = [u32(rec + 8), u32(rec + 12)] # offset, length
+      end
+      tables
+    end
+
+    def table(tag)
+      @tables[tag] or raise Error, "font missing #{tag} table"
+    end
+
+    def parse_head
+      off, = table("head")
+      @units_per_em = u16(off + 18)
+      @loca_long = i16(off + 50) == 1
+    end
+
+    def parse_maxp
+      off, = table("maxp")
+      @num_glyphs = u16(off + 4)
+    end
+
+    def parse_hhea_hmtx
+      hhea, = table("hhea")
+      num_hmetrics = u16(hhea + 34)
+      hmtx, = table("hmtx")
+      @advances = Array.new(@num_glyphs) do |gid|
+        gid < num_hmetrics ? u16(hmtx + gid * 4) : u16(hmtx + (num_hmetrics - 1) * 4)
+      end
+    end
+
+    def parse_os2
+      if @tables["OS/2"]
+        off, len = table("OS/2")
+        version = u16(off)
+        @cap_height = i16(off + 88) if version >= 2 && len >= 90
+      end
+      @cap_height = nil if @cap_height && @cap_height <= 0
+      @cap_height ||= measure_cap_height
+    end
+
+    def measure_cap_height
+      gid = lookup_cmap("H".ord)
+      offset = glyph_offset(gid)
+      offset ? i16(glyf_base + offset + 8) : (@units_per_em * 0.7).round # yMax of 'H'
+    end
+
+    # ---- cmap format 4 -------------------------------------------------------
+
+    def parse_cmap
+      off, = table("cmap")
+      count = u16(off + 2)
+      best = nil
+      count.times do |i|
+        rec = off + 4 + i * 8
+        platform = u16(rec)
+        encoding = u16(rec + 2)
+        sub = off + u32(rec + 4)
+        next unless u16(sub) == 4
+
+        score = { [3, 1] => 3, [0, 3] => 2, [0, 4] => 2 }.fetch([platform, encoding], 1)
+        best = [score, sub] if best.nil? || score > best[0]
+      end
+      raise Error, "font has no format-4 cmap subtable" unless best
+
+      @cmap4 = best[1]
+      @cmap_cache = {}
+    end
+
+    def lookup_cmap(code)
+      sub = @cmap4
+      seg_count = u16(sub + 6) / 2
+      end_codes = sub + 14
+      start_codes = end_codes + seg_count * 2 + 2
+      id_deltas = start_codes + seg_count * 2
+      id_range_offsets = id_deltas + seg_count * 2
+
+      seg = (0...seg_count).bsearch { |i| u16(end_codes + i * 2) >= code }
+      return 0 unless seg
+
+      start = u16(start_codes + seg * 2)
+      return 0 if code < start
+
+      range_offset = u16(id_range_offsets + seg * 2)
+      delta = i16(id_deltas + seg * 2)
+      if range_offset.zero?
+        (code + delta) & 0xFFFF
+      else
+        addr = id_range_offsets + seg * 2 + range_offset + (code - start) * 2
+        gid = u16(addr)
+        gid.zero? ? 0 : (gid + delta) & 0xFFFF
+      end
+    end
+
+    # ---- glyf access ---------------------------------------------------------
+
+    def glyf_base
+      @glyf_base ||= table("glyf")[0]
+    end
+
+    def glyph_offset(gid)
+      return nil if gid >= @num_glyphs
+
+      loca, = table("loca")
+      if @loca_long
+        start = u32(loca + gid * 4)
+        fin = u32(loca + gid * 4 + 4)
+      else
+        start = u16(loca + gid * 2) * 2
+        fin = u16(loca + gid * 2 + 2) * 2
+      end
+      fin > start ? start : nil # empty glyph (e.g. space)
+    end
+
+    # Returns an array of contours, each an array of [x, y, on_curve] in
+    # font units, with composite glyphs resolved.
+    def contours(gid, depth = 0)
+      return [] if depth > 4
+
+      @contour_cache[gid] ||= begin
+        offset = glyph_offset(gid)
+        if offset.nil?
+          []
+        else
+          o = glyf_base + offset
+          n = i16(o)
+          n >= 0 ? simple_contours(o, n) : composite_contours(o, depth)
+        end
+      end
+    end
+
+    def simple_contours(o, contour_count)
+      end_pts = Array.new(contour_count) { |i| u16(o + 10 + i * 2) }
+      point_count = end_pts.last + 1
+      p = o + 10 + contour_count * 2
+      p += 2 + u16(p) # instructions
+
+      flags = []
+      while flags.length < point_count
+        flag = u8(p)
+        p += 1
+        flags << flag
+        if flag & REPEAT != 0
+          u8(p).times { flags << flag }
+          p += 1
+        end
+      end
+
+      xs = read_coords(flags, p, X_SHORT, X_SAME_OR_POS) { |bytes| p += bytes }
+      ys = read_coords(flags, p, Y_SHORT, Y_SAME_OR_POS) { |bytes| p += bytes }
+
+      result = []
+      start = 0
+      end_pts.each do |last|
+        result << (start..last).map { |i| [xs[i], ys[i], flags[i] & ON_CURVE != 0] }
+        start = last + 1
+      end
+      result
+    end
+
+    def read_coords(flags, start, short_bit, same_bit)
+      p = start
+      value = 0
+      coords = flags.map do |flag|
+        if flag & short_bit != 0
+          d = u8(p)
+          p += 1
+          value += (flag & same_bit != 0 ? d : -d)
+        elsif flag & same_bit == 0
+          value += i16(p)
+          p += 2
+        end
+        value
+      end
+      yield(p - start)
+      coords
+    end
+
+    ARGS_ARE_WORDS = 0x0001
+    ARGS_ARE_XY = 0x0002
+    HAVE_SCALE = 0x0008
+    MORE_COMPONENTS = 0x0020
+    HAVE_XY_SCALE = 0x0040
+    HAVE_2X2 = 0x0080
+
+    def composite_contours(o, depth)
+      p = o + 10
+      result = []
+      loop do
+        flags = u16(p)
+        component_gid = u16(p + 2)
+        p += 4
+        if flags & ARGS_ARE_WORDS != 0
+          dx = i16(p)
+          dy = i16(p + 2)
+          p += 4
+        else
+          dx = u8(p)
+          dy = u8(p + 1)
+          dx -= 256 if dx > 127
+          dy -= 256 if dy > 127
+          p += 2
+        end
+        a = d = 1.0
+        b = c = 0.0
+        if flags & HAVE_SCALE != 0
+          a = d = f2dot14(p)
+          p += 2
+        elsif flags & HAVE_XY_SCALE != 0
+          a = f2dot14(p)
+          d = f2dot14(p + 2)
+          p += 4
+        elsif flags & HAVE_2X2 != 0
+          a = f2dot14(p)
+          b = f2dot14(p + 2)
+          c = f2dot14(p + 4)
+          d = f2dot14(p + 6)
+          p += 8
+        end
+        dx = dy = 0 unless flags & ARGS_ARE_XY != 0
+        contours(component_gid, depth + 1).each do |contour|
+          result << contour.map do |x, y, on|
+            [a * x + c * y + dx, b * x + d * y + dy, on]
+          end
+        end
+        break if flags & MORE_COMPONENTS == 0
+      end
+      result
+    end
+
+    def f2dot14(o)
+      i16(o) / 16_384.0
+    end
+
+    # ---- rasterization -------------------------------------------------------
+
+    def rasterize(gid, scale_x, scale_y)
+      polys = contours(gid).map { |c| flatten_contour(c, scale_x, scale_y) }
+      polys.reject! { |pts| pts.length < 3 }
+      return nil if polys.empty?
+
+      min_x = polys.flat_map { |pts| pts.map(&:first) }.min
+      max_x = polys.flat_map { |pts| pts.map(&:first) }.max
+      min_y = polys.flat_map { |pts| pts.map(&:last) }.min
+      max_y = polys.flat_map { |pts| pts.map(&:last) }.max
+
+      left = min_x.floor
+      top = max_y.ceil # distance above baseline (y grows up in font space)
+      width = max_x.ceil - left + 1
+      height = top - min_y.floor + 1
+      return nil if width < 1 || height < 1
+
+      canvas = Canvas.new(width, height)
+      edges = []
+      polys.each do |pts|
+        pts.each_with_index do |(x0, y0), i|
+          x1, y1 = pts[(i + 1) % pts.length]
+          edges << [x0, y0, x1, y1] unless y0 == y1
+        end
+      end
+
+      (0...height).each do |row|
+        yc = top - row - 0.5 # sample at pixel center, font-space y
+        crossings = []
+        edges.each do |x0, y0, x1, y1|
+          next unless (y0 <= yc && y1 > yc) || (y1 <= yc && y0 > yc)
+
+          crossings << [x0 + (yc - y0) * (x1 - x0) / (y1 - y0), y1 > y0 ? 1 : -1]
+        end
+        next if crossings.empty?
+
+        crossings.sort_by!(&:first)
+        winding = 0
+        span_start = nil
+        crossings.each do |x, dir|
+          was_inside = winding != 0
+          winding += dir
+          if !was_inside && winding != 0
+            span_start = x
+          elsif was_inside && winding.zero? && span_start
+            px0 = (span_start - left - 0.5).ceil
+            px1 = (x - left - 0.5).floor
+            canvas.fill_rect(px0, row, px1 - px0 + 1, 1) if px1 >= px0
+            span_start = nil
+          end
+        end
+      end
+
+      Glyph.new(canvas: canvas, left: left, top: top)
+    end
+
+    # Flatten a contour of [x, y, on_curve] font-unit points into a scaled
+    # polygon. Consecutive off-curve points imply an on-curve midpoint.
+    def flatten_contour(contour, scale_x, scale_y)
+      points = normalize_contour(contour)
+      out = []
+      i = 0
+      while i < points.length
+        x, y, on = points[i]
+        if on
+          out << [x * scale_x, y * scale_y]
+          i += 1
+        else
+          x0, y0 = out.last || begin
+            px, py, = points[i - 1]
+            [px * scale_x, py * scale_y]
+          end
+          nx, ny, = points[(i + 1) % points.length]
+          cx = x * scale_x
+          cy = y * scale_y
+          ex = nx * scale_x
+          ey = ny * scale_y
+          (1..CURVE_SEGMENTS).each do |s|
+            t = s.to_f / CURVE_SEGMENTS
+            mt = 1 - t
+            out << [mt * mt * x0 + 2 * mt * t * cx + t * t * ex,
+                    mt * mt * y0 + 2 * mt * t * cy + t * t * ey]
+          end
+          i += 2 # consumed the following on-curve point as curve end
+        end
+      end
+      out
+    end
+
+    # Ensure the contour starts with an on-curve point and has explicit
+    # on-curve midpoints between consecutive off-curve points.
+    def normalize_contour(contour)
+      points = []
+      contour.each_with_index do |(x, y, on), i|
+        if !on && !contour[i - 1][2]
+          px, py, = contour[i - 1]
+          points << [(px + x) / 2.0, (py + y) / 2.0, true]
+        end
+        points << [x, y, on]
+      end
+      unless points.first[2]
+        if points.last[2]
+          points.rotate!(-1)
+        else
+          first = points.first
+          last = points.last
+          points.unshift([(first[0] + last[0]) / 2.0, (first[1] + last[1]) / 2.0, true])
+        end
+      end
+      points
+    end
+  end
+end

data/lib/zpl_render/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ZplRender
+  VERSION = "0.1.0"
+end

data/lib/zpl_render.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "zpl_render/version"
+require_relative "zpl_render/canvas"
+require_relative "zpl_render/truetype"
+require_relative "zpl_render/font"
+require_relative "zpl_render/parser"
+require_relative "zpl_render/graphic_field"
+require_relative "zpl_render/barcode/code128"
+require_relative "zpl_render/barcode/code39"
+require_relative "zpl_render/barcode/interleaved2of5"
+require_relative "zpl_render/barcode/pdf417"
+require_relative "zpl_render/barcode/qr"
+require_relative "zpl_render/renderer"
+require_relative "zpl_render/output/png"
+require_relative "zpl_render/output/pdf"
+
+# Render ZPL II label programs to PNG or PDF.
+#
+#   png = ZplRender.to_png(zpl, dpmm: 8, width_in: 4, height_in: 6)
+#   pdf = ZplRender.to_pdf(zpl, dpmm: 8, width_in: 4, height_in: 6)
+#
+# dpmm is the printer density in dots per millimeter:
+#   6 = 152 dpi, 8 = 203 dpi (most common), 12 = 300 dpi, 24 = 600 dpi
+#
+# Error handling: every failure the library raises intentionally is a
+# ZplRender::Error. By default rendering is lenient: recoverable problems
+# (a field that fails to render, an unsupported command) are recorded in
+# the optional +warnings+ array and rendering continues, like a printer.
+# Pass strict: true to raise ZplRender::Error on the first problem
+# instead, for pipelines that must not silently drop label content.
+module ZplRender
+  class Error < StandardError; end
+
+  module_function
+
+  # Render every ^XA..^XZ format to a Canvas (dot matrix).
+  def render(zpl, dpmm: 8, width_in: 4.0, height_in: 6.0, strict: false, warnings: nil)
+    raise Error, "zpl must be a String (got #{zpl.class})" unless zpl.respond_to?(:to_str)
+
+    renderer = Renderer.new(dpmm: dpmm, width_in: width_in, height_in: height_in, strict: strict)
+    labels = renderer.render(zpl.to_str)
+    warnings.concat(renderer.warnings) if warnings
+    labels
+  end
+
+  # PNG bytes for the first label.
+  def to_png(zpl, dpmm: 8, width_in: 4.0, height_in: 6.0, scale: 1, strict: false, warnings: nil)
+    labels = render(zpl, dpmm: dpmm, width_in: width_in, height_in: height_in,
+                         strict: strict, warnings: warnings)
+    raise Error, "no ^XA..^XZ label formats found" if labels.empty?
+
+    Output::Png.encode(labels.first, scale: scale)
+  end
+
+  # PNG bytes for every label.
+  def to_pngs(zpl, dpmm: 8, width_in: 4.0, height_in: 6.0, scale: 1, strict: false, warnings: nil)
+    render(zpl, dpmm: dpmm, width_in: width_in, height_in: height_in,
+                strict: strict, warnings: warnings)
+      .map { |canvas| Output::Png.encode(canvas, scale: scale) }
+  end
+
+  # PDF bytes, one page per label, at exact physical size.
+  def to_pdf(zpl, dpmm: 8, width_in: 4.0, height_in: 6.0, strict: false, warnings: nil)
+    labels = render(zpl, dpmm: dpmm, width_in: width_in, height_in: height_in,
+                         strict: strict, warnings: warnings)
+    raise Error, "no ^XA..^XZ label formats found" if labels.empty?
+
+    Output::Pdf.encode(labels, dpmm: dpmm)
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification
+name: zpl_render
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Waqas Ali
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-07-31 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: chunky_png
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: prawn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rqrcode_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: A pure-Ruby ZPL II renderer. Parses ^XA..^XZ label formats and rasterizes
+  them at true printer resolution (dots), producing PNG images and print-size PDF
+  documents. Code 128 (^BC, incl. Zebra subset invocation codes and GS1 modes), QR
+  (^BQ), Code 39 (^B3) and Interleaved 2 of 5 (^B2) are generated module-exact so
+  scanners read them reliably. Also supports text fields, field blocks, graphic boxes/circles/diagonals,
+  ^GF images (ASCII hex, Zebra RLE, B64/Z64) and ~DG/^XG stored graphics.
+email:
+- wqsaali@gmail.com
+executables:
+- zpl_render
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- exe/zpl_render
+- lib/zpl_render.rb
+- lib/zpl_render/barcode/code128.rb
+- lib/zpl_render/barcode/code39.rb
+- lib/zpl_render/barcode/interleaved2of5.rb
+- lib/zpl_render/barcode/pdf417.rb
+- lib/zpl_render/barcode/pdf417_tables.rb
+- lib/zpl_render/barcode/qr.rb
+- lib/zpl_render/canvas.rb
+- lib/zpl_render/font.rb
+- lib/zpl_render/font_data.rb
+- lib/zpl_render/fonts/LICENSE-LiberationSans.txt
+- lib/zpl_render/fonts/LiberationMono-Regular.ttf
+- lib/zpl_render/fonts/LiberationSans-Bold.ttf
+- lib/zpl_render/graphic_field.rb
+- lib/zpl_render/helvetica_metrics.rb
+- lib/zpl_render/output/pdf.rb
+- lib/zpl_render/output/png.rb
+- lib/zpl_render/parser.rb
+- lib/zpl_render/renderer.rb
+- lib/zpl_render/truetype.rb
+- lib/zpl_render/version.rb
+homepage: https://github.com/wqsaali/zpl_render
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  homepage_uri: https://github.com/wqsaali/zpl_render
+  source_code_uri: https://github.com/wqsaali/zpl_render
+  bug_tracker_uri: https://github.com/wqsaali/zpl_render/issues
+  changelog_uri: https://github.com/wqsaali/zpl_render/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: Render ZPL II label programs to PNG and PDF, with scanner-accurate barcodes.
+test_files: []