zpl_render 0.1.0

data/lib/zpl_render/renderer.rb

@@ -0,0 +1,627 @@
+# frozen_string_literal: true
+
+module ZplRender
+  # Executes a parsed ZPL command stream and paints labels onto Canvases.
+  # One Canvas is produced per ^XA...^XZ format.
+  class Renderer
+    DEFAULT_MODULE_WIDTH = 2
+    DEFAULT_RATIO = 3.0
+    DEFAULT_BARCODE_HEIGHT = 10
+
+    attr_reader :warnings
+
+    # strict: false (default) records recoverable problems in #warnings and
+    # keeps rendering; true raises ZplRender::Error on the first problem
+    # (bad field data, unsupported command).
+    def initialize(dpmm: 8, width_in: 4.0, height_in: 6.0, strict: false)
+      raise Error, "dpmm must be a positive number (got #{dpmm.inspect})" unless dpmm.is_a?(Numeric) && dpmm.positive?
+      unless width_in.is_a?(Numeric) && width_in.positive? && height_in.is_a?(Numeric) && height_in.positive?
+        raise Error, "label dimensions must be positive numbers (got #{width_in.inspect} x #{height_in.inspect})"
+      end
+
+      @dpmm = dpmm
+      @strict = strict
+      dpi = (25.4 * dpmm).round # printers advertise 203/300/600 dpi nominal
+      @default_width = (width_in * dpi).floor
+      @default_height = (height_in * dpi).floor
+      @warnings = []
+      @images = {} # ~DG store, keyed by "R:NAME.GRF"
+    end
+
+    def render(zpl)
+      commands = Parser.parse(zpl)
+      labels = []
+      reset_label_state
+
+      commands.each do |cmd|
+        case cmd.name
+        when "XA"
+          reset_label_state
+        when "XZ"
+          flush_field
+          labels << @canvas if @canvas
+          @canvas = nil
+        else
+          execute(cmd)
+        end
+      end
+      labels << @canvas if @canvas && dirty? # tolerate missing ^XZ
+      labels
+    end
+
+    private
+
+    def reset_label_state
+      @canvas = Canvas.new(@default_width, @default_height)
+      @lh = [0, 0]
+      @fw = :n
+      @default_font = { name: "0", h: nil, w: nil }
+      @by = { module: DEFAULT_MODULE_WIDTH, ratio: DEFAULT_RATIO, height: DEFAULT_BARCODE_HEIGHT }
+      @encoding = 0
+      @pw = nil
+      @dirty = false
+      reset_field
+    end
+
+    def print_width_offset
+      return 0 unless @pw && @pw < @canvas.width
+
+      (@canvas.width - @pw) / 2
+    end
+
+    def reset_field
+      @field = {
+        x: 0, y: 0, typeset: false, origin_set: false,
+        font: nil, barcode: nil, graphic: nil,
+        reverse: false, block: nil, hex: false, hex_char: "_",
+        data: nil, orientation: nil
+      }
+    end
+
+    def dirty?
+      @dirty
+    end
+
+    def execute(cmd)
+      p = cmd.args
+      case cmd.name
+      when "FO", "FT"
+        flush_field
+        @field[:x] = int(p[0], 0) + @lh[0] + print_width_offset
+        @field[:y] = int(p[1], 0) + @lh[1]
+        @field[:typeset] = cmd.name == "FT"
+        @field[:origin_set] = true
+      when "FS"
+        flush_field
+      when "FD", "FV"
+        @field[:data] = cmd.params
+      when "SN"
+        @field[:data] = cmd.args[0].to_s
+      when "FH"
+        @field[:hex] = true
+        @field[:hex_char] = p[0].to_s.empty? ? "_" : p[0][0]
+      when "FR"
+        @field[:reverse] = true
+      when "FB"
+        @field[:block] = {
+          width: int(p[0], 0), lines: int(p[1], 1),
+          line_gap: int(p[2], 0), just: (p[3] || "L").upcase
+        }
+      when "A"
+        @field[:font] = font_from_params(p)
+        @field[:orientation] = @field[:font][:orientation]
+      when "A@"
+        # downloaded scalable font: fall back to default font metrics
+        @field[:font] = { name: "0", h: int(p[1], nil), w: int(p[2], nil) }
+        @field[:orientation] = orient(p[0])
+      when "CF"
+        @default_font = { name: (p[0].to_s.empty? ? @default_font[:name] : p[0]),
+                          h: int(p[1], @default_font[:h]), w: int(p[2], @default_font[:w]) }
+      when "CI"
+        @encoding = int(p[0], 0)
+      when "FW"
+        @fw = orient(p[0])
+        # ^FW between ^A and ^FD overrides the field's orientation,
+        # matching printer behavior (last orientation wins).
+        @field[:orientation] = @fw if @field[:origin_set]
+      when "BY"
+        @by[:module] = int(p[0], @by[:module]).clamp(1, 10)
+        @by[:ratio] = (p[1].to_s.empty? ? @by[:ratio] : p[1].to_f).clamp(2.0, 3.0)
+        @by[:height] = int(p[2], @by[:height])
+      when "BC"
+        @field[:barcode] = {
+          type: :code128, orientation: orient(p[0]),
+          height: int(p[1], nil), interp: yn(p[2], true), above: yn(p[3], false),
+          check: yn(p[4], false), mode: (p[5].to_s.empty? ? "N" : p[5].upcase)
+        }
+        @field[:orientation] = @field[:barcode][:orientation]
+      when "B3"
+        @field[:barcode] = {
+          type: :code39, orientation: orient(p[0]), check: yn(p[1], false),
+          height: int(p[2], nil), interp: yn(p[3], true), above: yn(p[4], false)
+        }
+        @field[:orientation] = @field[:barcode][:orientation]
+      when "B2"
+        @field[:barcode] = {
+          type: :i2of5, orientation: orient(p[0]), height: int(p[1], nil),
+          interp: yn(p[2], true), above: yn(p[3], false), check: yn(p[4], false)
+        }
+        @field[:orientation] = @field[:barcode][:orientation]
+      when "B7"
+        @field[:barcode] = {
+          type: :pdf417, orientation: orient(p[0]), row_height: int(p[1], nil),
+          security: int(p[2], nil), columns: int(p[3], 0), rows: int(p[4], 0),
+          truncate: yn(p[5], false)
+        }
+        @field[:orientation] = @field[:barcode][:orientation]
+      when "BQ"
+        @field[:barcode] = {
+          type: :qr, orientation: orient(p[0]), model: int(p[1], 2),
+          magnification: int(p[2], default_qr_magnification),
+          ecc: (p[3].to_s.empty? ? "Q" : p[3].upcase), mask: int(p[4], 7)
+        }
+        @field[:orientation] = @field[:barcode][:orientation]
+      when "GB"
+        @field[:graphic] = { type: :box, w: int(p[0], 1), h: int(p[1], 1),
+                             t: int(p[2], 1), color: color(p[3]), round: int(p[4], 0) }
+      when "GC"
+        @field[:graphic] = { type: :circle, d: int(p[0], 3), t: int(p[1], 1), color: color(p[2]) }
+      when "GD"
+        @field[:graphic] = { type: :diagonal, w: int(p[0], 3), h: int(p[1], 3),
+                             t: int(p[2], 1), color: color(p[3]), dir: (p[4] || "R").upcase }
+      when "GF"
+        @field[:graphic] = parse_gf(cmd.params)
+      when "XG"
+        name = normalize_image_name(p[0])
+        mx = int(p[1], 1).clamp(1, 10)
+        my = int(p[2], 1).clamp(1, 10)
+        @field[:graphic] = { type: :image, name: name, mx: mx, my: my }
+      when "DG"
+        store_dg(cmd.params)
+      when "PW"
+        # ^PW sets the printable width; the label canvas never shrinks and
+        # a narrower print area is centered on the label, like the printer.
+        @pw = int(p[0], nil)
+        resize_canvas(width: [@pw || 0, @canvas.width].max)
+      when "LL"
+        resize_canvas(height: [int(p[0], @canvas.height), @canvas.height].max)
+      when "LH"
+        @lh = [int(p[0], 0), int(p[1], 0)]
+      when "FX", "PQ", "MC", "MD", "MM", "MN", "MT", "PR", "PO", "LR", "LS",
+           "CW", "JM", "PM", "SD", "SZ", "XB", "DF", "EG", "ID", "TA", "JU",
+           "PF", "PH", "SL", "SO", "ST", "SX", "SQ", "WD", "HH", "HS", "JS"
+        # no visual effect at render time; ignored
+      else
+        problem("unsupported command: #{cmd.prefix == :tilde ? '~' : '^'}#{cmd.name}")
+      end
+    end
+
+    # ---- field flushing -----------------------------------------------------
+
+    def flush_field
+      f = @field
+      begin
+        if f[:graphic] && f[:origin_set]
+          draw_graphic(f)
+        elsif f[:data]
+          if f[:barcode]
+            draw_barcode(f)
+          else
+            draw_text(f)
+          end
+        end
+      rescue StandardError => e
+        problem("#{field_label(f)} at (#{f[:x]},#{f[:y]}) failed: #{e.message}")
+      end
+      reset_field
+    end
+
+    def field_label(f)
+      if f[:barcode]
+        "#{f[:barcode][:type]} barcode field"
+      elsif f[:graphic]
+        "#{f[:graphic][:type]} graphic field"
+      else
+        "text field"
+      end
+    end
+
+    # Record a recoverable problem, or raise it in strict mode. When called
+    # from a rescue block, Ruby chains the original exception as #cause.
+    def problem(message)
+      raise Error, message if @strict
+
+      @warnings << message
+    end
+
+    def field_data(f)
+      data = f[:data].to_s
+      if f[:hex]
+        hx = Regexp.escape(f[:hex_char])
+        data = data.gsub(/#{hx}([0-9A-Fa-f]{2})/) { [$1].pack("H2") }
+        data.force_encoding(@encoding.to_i >= 28 ? Encoding::UTF_8 : Encoding::ISO_8859_1)
+        data = data.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "?")
+      end
+      data
+    end
+
+    # ---- text ---------------------------------------------------------------
+
+    def draw_text(f)
+      font = f[:font] || @default_font
+      face = Font.face_for(font[:name], font[:h], font[:w])
+      rotation = f[:orientation] || font[:orientation] || @fw
+      text = field_data(f)
+      return if text.empty?
+
+      lines = if f[:block]
+                wrap_block(text, f[:block], face)
+              else
+                [text.gsub("\\&", " ")]
+              end
+
+      line_h = Font.line_height(face) + (f[:block] ? f[:block][:line_gap] : 0)
+      max_w = lines.map { |l| Font.measure(l, face) }.max || 0
+      block_w = f[:block] ? [f[:block][:width], max_w].max : max_w
+      bitmap = Canvas.new([block_w, 1].max, [lines.length * line_h, 1].max)
+      lines.each_with_index do |line, li|
+        line_w = Font.measure(line, face)
+        x = case f[:block] && f[:block][:just]
+            when "C" then (block_w - line_w) / 2
+            when "R" then block_w - line_w
+            else 0
+            end
+        Font.draw_line(bitmap, [x, 0].max, li * line_h, line, face)
+      end
+
+      x = f[:x]
+      y = f[:y]
+      if f[:typeset]
+        rw, rh = Canvas.rotated_size(bitmap.width, bitmap.height, rotation)
+        y -= rh
+        rw # unused; kept for clarity
+      end
+      @canvas.blit(bitmap, x, y, rotation: rotation, mode: f[:reverse] ? :xor : :paint)
+      @dirty = true
+    end
+
+    def wrap_block(text, block, face)
+      max_w = block[:width].positive? ? block[:width] : Font.measure(text, face)
+      lines = []
+      text.split("\\&").each do |paragraph|
+        words = paragraph.split(/ +/)
+        current = +""
+        words.each do |word|
+          candidate = current.empty? ? word : "#{current} #{word}"
+          if Font.measure(candidate, face) <= max_w
+            current = candidate
+          else
+            lines << current unless current.empty?
+            # hard-break words wider than the block
+            while Font.measure(word, face) > max_w && word.length > 1
+              head = word.length
+              head -= 1 while head > 1 && Font.measure(word[0, head], face) > max_w
+              lines << word[0, head]
+              word = word[head..]
+            end
+            current = word
+          end
+        end
+        lines << current
+      end
+      lines.take(block[:lines])
+    end
+
+    # ---- barcodes -----------------------------------------------------------
+
+    def draw_barcode(f)
+      bc = f[:barcode]
+      rotation = f[:orientation] || bc[:orientation] || @fw
+      data = field_data(f)
+      return if data.empty?
+
+      bitmap = case bc[:type]
+               when :code128 then linear_bitmap(code128_widths(data, bc), bc, data)
+               when :code39  then two_width_bitmap(Barcode::Code39.encode(data, check_digit: bc[:check]), bc)
+               when :i2of5   then two_width_bitmap(Barcode::Interleaved2of5.encode(data, check_digit: bc[:check]), bc)
+               when :pdf417  then pdf417_bitmap(data, bc)
+               when :qr      then qr_bitmap(data, bc)
+               end
+      return unless bitmap
+
+      x = f[:x]
+      y = f[:y]
+      if f[:typeset]
+        _, rh = Canvas.rotated_size(bitmap.width, bitmap.height, rotation)
+        y -= rh
+      end
+      @canvas.blit(bitmap, x, y, rotation: rotation, mode: f[:reverse] ? :xor : :paint)
+      @dirty = true
+    end
+
+    def code128_widths(data, bc)
+      result = Barcode::Code128.encode(data, mode: bc[:mode], ucc_check: bc[:check])
+      modules = Barcode::Code128.modules(result.values)
+      widths = modules.each_char.map.with_index { |c, i| [c.to_i * @by[:module], i.even?] }
+      [widths, result.interpretation]
+    end
+
+    def linear_bitmap((widths, interp), bc, _data)
+      height = bc[:height] || @by[:height]
+      height = @by[:height] if height <= 0
+      total_w = widths.sum { |w, _| w }
+      compose_linear(widths, total_w, height, bc, interp)
+    end
+
+    def two_width_bitmap(result, bc)
+      narrow = @by[:module]
+      wide = (@by[:ratio] * narrow).round
+      widths = result.elements.map { |kind, bar| [kind == :wide ? wide : narrow, bar] }
+      height = bc[:height] || @by[:height]
+      height = @by[:height] if height <= 0
+      total_w = widths.sum { |w, _| w }
+      compose_linear(widths, total_w, height, bc, result.interpretation)
+    end
+
+    def compose_linear(widths, total_w, height, bc, interp)
+      show_interp = bc[:interp] && !interp.to_s.empty?
+      face = interpretation_face(interp, total_w)
+      interp_h = Font.line_height(face) + 3
+      full_h = height + (show_interp ? interp_h : 0)
+      bitmap = Canvas.new([total_w, 1].max, full_h)
+
+      bars_y = show_interp && bc[:above] ? interp_h : 0
+      x = 0
+      widths.each do |w, bar|
+        bitmap.fill_rect(x, bars_y, w, height) if bar
+        x += w
+      end
+
+      if show_interp
+        text_y = bc[:above] ? 0 : height + 1
+        text_x = [(total_w - Font.measure(interp, face)) / 2, 0].max
+        Font.draw_line(bitmap, text_x, text_y, interp, face)
+      end
+      bitmap
+    end
+
+    def interpretation_face(interp, total_w)
+      size = [@dpmm * 2, 10].max # ~2 mm tall interpretation line
+      face = Font.face_for("0", size, size)
+      while Font.measure(interp, face) > total_w && size > 5
+        size -= 1
+        face = Font.face_for("0", size, size)
+      end
+      face
+    end
+
+    def pdf417_bitmap(data, bc)
+      symbol = Barcode::Pdf417.encode(
+        data.b, security: bc[:security], columns: bc[:columns],
+        rows: bc[:rows], truncated: bc[:truncate]
+      )
+      mod_w = @by[:module]
+      row_h = bc[:row_height]
+      row_h = [mod_w * 3, 4].max if row_h.nil? || row_h < 1
+      width = symbol.patterns.first.sum { |_, count| count } * mod_w
+      bitmap = Canvas.new(width, symbol.rows * row_h)
+      symbol.patterns.each_with_index do |row, row_no|
+        x = 0
+        y = row_no * row_h
+        row.each do |pattern, count|
+          (count - 1).downto(0) do |bit|
+            bitmap.fill_rect(x, y, mod_w, row_h) if (pattern >> bit) & 1 == 1
+            x += mod_w
+          end
+        end
+      end
+      bitmap
+    end
+
+    def qr_bitmap(data, bc)
+      result = Barcode::Qr.encode(data, default_ecc: bc[:ecc])
+      mag = bc[:magnification].clamp(1, 10)
+      size = result.modules.length
+      bitmap = Canvas.new(size * mag, size * mag)
+      result.modules.each_with_index do |row, ry|
+        row.each_with_index do |mod, rx|
+          bitmap.fill_rect(rx * mag, ry * mag, mag, mag) if mod
+        end
+      end
+      bitmap
+    end
+
+    def default_qr_magnification
+      case @dpmm
+      when 0..6 then 1
+      when 7..8 then 2
+      when 9..14 then 3
+      else 6
+      end
+    end
+
+    # ---- graphics -----------------------------------------------------------
+
+    def draw_graphic(f)
+      g = f[:graphic]
+      mode = if f[:reverse]
+               :xor
+             else
+               g[:color] == :white ? :erase : :paint
+             end
+
+      bitmap = case g[:type]
+               when :box      then box_bitmap(g)
+               when :circle   then circle_bitmap(g)
+               when :diagonal then diagonal_bitmap(g)
+               when :gf       then g[:canvas]
+               when :image    then image_bitmap(g)
+               end
+      return unless bitmap
+
+      y = f[:y]
+      y -= bitmap.height if f[:typeset]
+      @canvas.blit(bitmap, f[:x], y, rotation: :n, mode: mode)
+      @dirty = true
+    end
+
+    def box_bitmap(g)
+      t = [g[:t], 1].max
+      w = [g[:w], t].max
+      h = [g[:h], t].max
+      bitmap = Canvas.new(w, h)
+      if g[:round].to_i.positive?
+        rounded_box(bitmap, w, h, t, g[:round].to_i.clamp(0, 8))
+      else
+        bitmap.fill_rect(0, 0, w, t)
+        bitmap.fill_rect(0, h - t, w, t)
+        bitmap.fill_rect(0, 0, t, h)
+        bitmap.fill_rect(w - t, 0, t, h)
+      end
+      bitmap
+    end
+
+    def rounded_box(bitmap, w, h, t, rounding)
+      radius = (rounding * [w, h].min) / 16
+      (0...h).each do |y|
+        (0...w).each do |x|
+          bitmap.set(x, y) if rounded_border?(x, y, w, h, t, radius)
+        end
+      end
+    end
+
+    def rounded_border?(x, y, w, h, t, r)
+      inside_rounded?(x, y, w, h, r) && !inside_rounded?(x - t, y - t, w - 2 * t, h - 2 * t, [r - t, 0].max)
+    end
+
+    def inside_rounded?(x, y, w, h, r)
+      return false if x.negative? || y.negative? || x >= w || y >= h
+      return true if r <= 0
+
+      cx = x < r ? r : (x >= w - r ? w - r - 1 : nil)
+      cy = y < r ? r : (y >= h - r ? h - r - 1 : nil)
+      return true if cx.nil? || cy.nil?
+
+      (x - cx)**2 + (y - cy)**2 <= r * r
+    end
+
+    def circle_bitmap(g)
+      d = [g[:d], 3].max
+      t = g[:t].clamp(1, d / 2 + 1)
+      bitmap = Canvas.new(d, d)
+      r_out = d / 2.0
+      r_in = r_out - t
+      cx = cy = (d - 1) / 2.0
+      (0...d).each do |y|
+        (0...d).each do |x|
+          dist2 = (x - cx)**2 + (y - cy)**2
+          bitmap.set(x, y) if dist2 <= r_out**2 && dist2 >= r_in**2 * (r_in.positive? ? 1 : 0)
+        end
+      end
+      bitmap
+    end
+
+    def diagonal_bitmap(g)
+      w = [g[:w], 3].max
+      h = [g[:h], 3].max
+      t = [g[:t], 1].max
+      bitmap = Canvas.new(w, h)
+      (0...w).each do |x|
+        y = g[:dir] == "L" ? (x * (h - 1) / [w - 1, 1].max) : (h - 1 - x * (h - 1) / [w - 1, 1].max)
+        (0...t).each do |dy|
+          bitmap.set(x, y + dy - t / 2)
+          bitmap.set(x + 1, y + dy - t / 2) if x + 1 < w # thicken against aliasing gaps
+        end
+      end
+      bitmap
+    end
+
+    def parse_gf(params)
+      # ^GFa,b,c,d,data - data may itself contain commas only for binary,
+      # so split just the first four fields.
+      parts = params.split(",", 5)
+      _format = (parts[0] || "A").strip.upcase
+      total = parts[2].to_i
+      per_row = parts[3].to_i
+      data = parts[4].to_s
+      { type: :gf, canvas: GraphicField.decode(data, per_row, total) }
+    end
+
+    def store_dg(params)
+      parts = params.split(",", 4)
+      name = normalize_image_name(parts[0])
+      total = parts[1].to_i
+      per_row = parts[2].to_i
+      data = parts[3].to_s
+      @images[name] = GraphicField.decode(data, per_row, total)
+    end
+
+    def image_bitmap(g)
+      src = @images[g[:name]]
+      unless src
+        problem("^XG references missing image #{g[:name]}")
+        return nil
+      end
+      return src if g[:mx] == 1 && g[:my] == 1
+
+      scaled = Canvas.new(src.width * g[:mx], src.height * g[:my])
+      (0...src.height).each do |y|
+        (0...src.width).each do |x|
+          scaled.fill_rect(x * g[:mx], y * g[:my], g[:mx], g[:my]) if src.get(x, y)
+        end
+      end
+      scaled
+    end
+
+    def normalize_image_name(raw)
+      name = raw.to_s.strip.upcase
+      name = "R:#{name}" unless name.include?(":")
+      name += ".GRF" unless name.include?(".")
+      name
+    end
+
+    # ---- misc ---------------------------------------------------------------
+
+    def resize_canvas(width: nil, height: nil)
+      w = width || @canvas.width
+      h = height || @canvas.height
+      return if w == @canvas.width && h == @canvas.height
+
+      fresh = Canvas.new(w, h)
+      fresh.blit(@canvas, 0, 0) if dirty?
+      @canvas = fresh
+    end
+
+    def font_from_params(p)
+      name = p[0].to_s[0] || "0"
+      { name: name, orientation: orient(p[0].to_s[1]), h: int(p[1], nil), w: int(p[2], nil) }
+    end
+
+    def orient(val)
+      case val.to_s.upcase
+      when "R" then :r
+      when "I" then :i
+      when "B" then :b
+      when "N" then :n
+      end
+    end
+
+    def color(val)
+      val.to_s.upcase == "W" ? :white : :black
+    end
+
+    def yn(val, default)
+      return default if val.nil? || val.to_s.empty?
+
+      val.to_s.upcase == "Y"
+    end
+
+    def int(val, default)
+      return default if val.nil? || val.to_s.strip.empty?
+
+      Integer(val.to_s.strip, 10)
+    rescue ArgumentError
+      default
+    end
+  end
+end