stationery 0.1.0

data/lib/stationery/fonts/subset.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Builds a TrueType font holding only the given glyphs (plus the parts of
+    # composite glyphs and .notdef), renumbered compactly from zero.
+    module Subset
+      HINTING_TABLES = ["cvt ", "fpgm", "prep"].freeze
+      CHECKSUM_MAGIC = 0xB1B0AFBA
+
+      module_function
+
+      # Returns [font_bytes, { original_gid => subset_gid }].
+      def build(ttf, gids)
+        glyphs = closure(ttf, Set.new(gids) << 0).sort
+        mapping = glyphs.each_with_index.to_h
+        glyf, loca = glyph_tables(ttf, glyphs, mapping)
+
+        tables = {
+          "head" => head(ttf), "hhea" => patch(ttf, "hhea", 34, glyphs.size),
+          "maxp" => patch(ttf, "maxp", 4, glyphs.size), "hmtx" => hmtx(ttf, glyphs),
+          "loca" => loca.pack("N*"), "glyf" => glyf
+        }
+        HINTING_TABLES.each { |tag| tables[tag] = ttf.table_data(tag) if ttf.table?(tag) }
+        tables["post"] = post(ttf) if ttf.table?("post")
+
+        [assemble(tables), mapping]
+      end
+
+      def checksum(data)
+        (data + padding(data)).unpack("N*").sum & 0xFFFFFFFF
+      end
+
+      def closure(ttf, gids)
+        glyphs = Set.new
+        queue = gids.to_a
+        until queue.empty?
+          gid = queue.pop
+          next if gid >= ttf.num_glyphs || !glyphs.add?(gid)
+
+          each_component(ttf.glyph_data(gid)) { |_, component| queue << component }
+        end
+        glyphs
+      end
+
+      def glyph_tables(ttf, glyphs, mapping)
+        glyf = String.new(encoding: Encoding::BINARY)
+        loca = glyphs.map do |gid|
+          offset = glyf.bytesize
+          data = remap_components(ttf.glyph_data(gid), mapping)
+          glyf << data << padding(data)
+          offset
+        end
+        [glyf, loca << glyf.bytesize]
+      end
+
+      def head(ttf)
+        head = ttf.table_data("head").dup
+        head[8, 4] = [0].pack("N") # checkSumAdjustment, filled in by assemble
+        head[50, 2] = [1].pack("n") # indexToLocFormat: long offsets
+        head
+      end
+
+      def patch(ttf, tag, offset, count)
+        data = ttf.table_data(tag).dup
+        data[offset, 2] = [count].pack("n")
+        data
+      end
+
+      def hmtx(ttf, glyphs)
+        glyphs.flat_map { |gid| [ttf.advance(gid), ttf.left_side_bearing(gid)] }.pack("ns>" * glyphs.size)
+      end
+
+      # Version 3.0: metrics only, no glyph names.
+      def post(ttf)
+        post = ttf.table_data("post").byteslice(0, 32).dup
+        post[0, 4] = [0x00030000].pack("N")
+        post
+      end
+
+      def remap_components(data, mapping)
+        copy = nil
+        each_component(data) do |pos, component|
+          copy ||= data.dup
+          copy[pos, 2] = [mapping.fetch(component, 0)].pack("n")
+        end
+        copy || data
+      end
+
+      # Yields the byte offset of each component glyph id in a composite glyph.
+      def each_component(data)
+        return if data.bytesize < 10 || data.unpack1("s>") >= 0
+
+        pos = 10
+        loop do
+          flags, component = data.byteslice(pos, 4).unpack("nn")
+          yield pos + 2, component
+          pos += 4 + component_arguments_size(flags)
+          break if flags.nobits?(0x0020) # MORE_COMPONENTS
+        end
+      end
+
+      def component_arguments_size(flags)
+        size = flags.allbits?(0x0001) ? 4 : 2 # ARG_1_AND_2_ARE_WORDS
+        if flags.allbits?(0x0008) then size + 2 # WE_HAVE_A_SCALE
+        elsif flags.allbits?(0x0040) then size + 4 # WE_HAVE_AN_X_AND_Y_SCALE
+        elsif flags.allbits?(0x0080) then size + 8 # WE_HAVE_A_TWO_BY_TWO
+        else size
+        end
+      end
+
+      def assemble(tables)
+        tags = tables.keys.sort
+        entry_selector = Math.log2(tags.size).floor
+        search_range = (2**entry_selector) * 16
+        directory = [0x00010000, tags.size, search_range, entry_selector, (tags.size * 16) - search_range]
+                    .pack("Nnnnn")
+        body = String.new(encoding: Encoding::BINARY)
+        body_offset = 12 + (tags.size * 16)
+        head_offset = nil
+
+        tags.each do |tag|
+          data = tables[tag]
+          head_offset = body_offset + body.bytesize if tag == "head"
+          directory << [tag, checksum(data), body_offset + body.bytesize, data.bytesize].pack("a4NNN")
+          body << data << padding(data)
+        end
+
+        font = directory << body
+        font[head_offset + 8, 4] = [(CHECKSUM_MAGIC - checksum(font)) & 0xFFFFFFFF].pack("N")
+        font
+      end
+
+      def padding(data)
+        "\0".b * (-data.bytesize % 4)
+      end
+    end
+  end
+end

data/lib/stationery/fonts/true_type.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Reads the tables of a TrueType (.ttf) font needed to measure text and to
+    # embed a subset of it. Static TrueType outlines only: CFF (.otf), font
+    # collections and web font wrappers are rejected with a named reason.
+    class TrueType
+      REQUIRED_TABLES = %w[head hhea maxp hmtx loca glyf].freeze
+      SIGNATURES = {
+        "OTTO" => "OpenType fonts with CFF outlines (.otf) are not supported, use a TrueType (.ttf) font",
+        "ttcf" => "TrueType collections (.ttc) are not supported, use a single TrueType (.ttf) font",
+        "wOFF" => "WOFF web fonts are not supported, use the TrueType (.ttf) file",
+        "wOF2" => "WOFF2 web fonts are not supported, use the TrueType (.ttf) file"
+      }.freeze
+
+      attr_reader :data, :tables, :units_per_em, :bbox, :ascender, :descender, :line_gap, :num_glyphs,
+                  :number_of_hmetrics, :italic_angle, :underline_position, :underline_thickness,
+                  :strikeout_position, :strikeout_size, :cap_height, :x_height, :weight, :postscript_name
+
+      # A subset embedded in a PDF carries no cmap (the PDF maps glyphs itself),
+      # so reading one back passes `cmap: false`.
+      def initialize(data, cmap: true)
+        @data = data.b
+        check_signature
+        read_table_directory(cmap)
+        parse_head
+        parse_hhea
+        parse_maxp
+        parse_hmtx
+        parse_loca
+        @cmap = cmap ? Cmap.parse(self) : {}
+        parse_post
+        parse_os2
+        @postscript_name = NameTable.postscript_name(self)
+      end
+
+      def inspect = "#<#{self.class} #{@postscript_name} glyphs=#{@num_glyphs}>"
+
+      def glyph_id(codepoint)
+        @cmap.fetch(codepoint, 0)
+      end
+
+      def glyph?(char)
+        char.each_codepoint.all? { |codepoint| glyph_id(codepoint).positive? }
+      end
+
+      def advance(gid)
+        @advances[gid] || @advances.last
+      end
+
+      def left_side_bearing(gid)
+        if gid < @number_of_hmetrics
+          i16(@hmtx_offset + (gid * 4) + 2)
+        else
+          i16(@hmtx_offset + (@number_of_hmetrics * 4) + ((gid - @number_of_hmetrics) * 2))
+        end
+      end
+
+      def fixed_pitch?
+        @fixed_pitch
+      end
+
+      def table?(tag)
+        @tables.key?(tag)
+      end
+
+      def table_offset(tag)
+        @tables[tag]&.first
+      end
+
+      def table_data(tag)
+        offset, length = @tables.fetch(tag)
+        @data.byteslice(offset, length)
+      end
+
+      def glyph_data(gid)
+        return "".b if gid >= @num_glyphs
+
+        @data.byteslice(@glyf_offset + @loca[gid], @loca[gid + 1] - @loca[gid])
+      end
+
+      def u16(offset) = @data.byteslice(offset, 2).unpack1("n")
+      def i16(offset) = @data.byteslice(offset, 2).unpack1("s>")
+      def u32(offset) = @data.byteslice(offset, 4).unpack1("N")
+
+      private
+
+      def check_signature
+        signature = @data.byteslice(0, 4)
+        return if ["\x00\x01\x00\x00".b, "true"].include?(signature)
+
+        raise UnsupportedFont, SIGNATURES.fetch(signature, "not a TrueType font")
+      end
+
+      def read_table_directory(cmap)
+        @tables = {}
+        u16(4).times do |i|
+          record = 12 + (i * 16)
+          @tables[@data.byteslice(record, 4)] = [u32(record + 8), u32(record + 12)]
+        end
+        required = cmap ? REQUIRED_TABLES + ["cmap"] : REQUIRED_TABLES
+        missing = required.reject { |tag| @tables.key?(tag) }
+        raise UnsupportedFont, "font is missing the #{missing.join(", ")} table" if missing.any?
+      end
+
+      def parse_head
+        t = table_offset("head")
+        @units_per_em = u16(t + 18)
+        @bbox = [i16(t + 36), i16(t + 38), i16(t + 40), i16(t + 42)]
+        @index_to_loc_format = i16(t + 50)
+      end
+
+      def parse_hhea
+        t = table_offset("hhea")
+        @ascender = i16(t + 4)
+        @descender = i16(t + 6)
+        @line_gap = i16(t + 8)
+        @number_of_hmetrics = u16(t + 34)
+      end
+
+      def parse_maxp
+        @num_glyphs = u16(table_offset("maxp") + 4)
+      end
+
+      def parse_hmtx
+        @hmtx_offset = table_offset("hmtx")
+        @advances = @data.byteslice(@hmtx_offset, @number_of_hmetrics * 4).unpack("n*").each_slice(2).map(&:first)
+      end
+
+      def parse_loca
+        t = table_offset("loca")
+        @loca = if @index_to_loc_format.zero?
+                  @data.byteslice(t, (@num_glyphs + 1) * 2).unpack("n*").map { |offset| offset * 2 }
+                else
+                  @data.byteslice(t, (@num_glyphs + 1) * 4).unpack("N*")
+                end
+        @glyf_offset = table_offset("glyf")
+      end
+
+      def parse_post
+        if (t = table_offset("post"))
+          @italic_angle = i16(t + 4) + (u16(t + 6) / 65_536.0)
+          @underline_position = i16(t + 8)
+          @underline_thickness = i16(t + 10)
+          @fixed_pitch = u32(t + 12) != 0
+        else
+          @italic_angle = 0
+          @underline_position = -@units_per_em / 10
+          @underline_thickness = @units_per_em / 20
+          @fixed_pitch = false
+        end
+      end
+
+      def parse_os2
+        if (t = table_offset("OS/2"))
+          @weight = u16(t + 4)
+          @strikeout_size = i16(t + 26)
+          @strikeout_position = i16(t + 28)
+          if u16(t) >= 2
+            @x_height = i16(t + 86)
+            @cap_height = i16(t + 88)
+          end
+        end
+
+        @weight ||= 400
+        @strikeout_size ||= @underline_thickness
+        @strikeout_position ||= (@ascender * 0.25).round
+        @x_height ||= (@ascender * 0.5).round
+        @parse_os2 ||= (@ascender * 0.7).round
+      end
+    end
+  end
+end

data/lib/stationery/geometry.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Stationery
+  # A rectangle in top-left page coordinates, in points.
+  Rect = Data.define(:x, :y, :width, :height) do
+    def right = x + width
+    def bottom = y + height
+
+    def inset(top, right, bottom, left)
+      Rect.new(x + left, y + top, [width - left - right, 0].max, [height - top - bottom, 0].max)
+    end
+  end
+
+  module Geometry
+    SIDES = { top: 0, right: 1, bottom: 2, left: 3 }.freeze
+
+    module_function
+
+    # CSS-style shorthand to [top, right, bottom, left].
+    def box(value)
+      case value
+      when nil then [0, 0, 0, 0]
+      when Numeric then [value] * 4
+      when Hash then from_hash(value)
+      when Array then from_array(value)
+      else raise ArgumentError, "not a box: #{value.inspect}"
+      end
+    end
+
+    def from_array(value)
+      case value.size
+      when 1 then value * 4
+      when 2 then value * 2
+      when 3 then [value[0], value[1], value[2], value[1]]
+      when 4 then value.dup
+      else raise ArgumentError, "a box takes 1 to 4 values, got #{value.size}"
+      end
+    end
+
+    def from_hash(value)
+      sides = [0, 0, 0, 0]
+      sides[0] = sides[2] = value[:y] if value.key?(:y)
+      sides[1] = sides[3] = value[:x] if value.key?(:x)
+      SIDES.each { |name, index| sides[index] = value[name] if value.key?(name) }
+      sides
+    end
+
+    def align_offset(align, available, used)
+      case align
+      when :center then (available - used) / 2.0
+      when :right then available - used
+      else 0
+      end
+    end
+  end
+end

data/lib/stationery/images/cache.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module Images
+    # Process-wide cache of decoded images keyed by content digest, so a logo
+    # drawn on every invoice is parsed once. Decoded images are immutable after
+    # construction apart from memoized derived data, which is deterministic.
+    module Cache
+      SIZE = 16
+      @cache = {}
+      @mutex = Mutex.new
+
+      class << self
+        def fetch(data)
+          key = Digest::MD5.digest(data)
+          @mutex.synchronize do
+            image = @cache.delete(key) || yield
+            @cache[key] = image
+            @cache.shift while @cache.size > SIZE
+            image
+          end
+        end
+
+        def clear
+          @mutex.synchronize { @cache.clear }
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/images.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Stationery
+  # JPEG and PNG images, embedded as image XObjects.
+  module Images
+    PNG_SIGNATURE = "\x89PNG\r\n\x1A\n".b
+    JPEG_SIGNATURE = "\xFF\xD8".b
+    UNSUPPORTED = {
+      "GIF8" => "GIF", "RIFF" => "WebP", "II*\0" => "TIFF", "MM\0*" => "TIFF", "BM" => "BMP"
+    }.freeze
+
+    module_function
+
+    # Accepts a path, a Pathname or an IO-like object (read from its start).
+    def load(source)
+      data = read(source)
+      Cache.fetch(data) { parse(data) }
+    end
+
+    def read(source)
+      data = if source.respond_to?(:read)
+               source.binmode if source.respond_to?(:binmode)
+               source.rewind if source.respond_to?(:rewind)
+               source.read
+             else
+               File.binread(source.to_s)
+             end
+      data.b
+    end
+
+    def parse(data)
+      return JPEG.new(data) if data.start_with?(JPEG_SIGNATURE)
+      return PNG.new(data) if data.start_with?(PNG_SIGNATURE)
+
+      format = UNSUPPORTED.find { |magic, _| data.start_with?(magic.b) }&.last
+      raise UnsupportedImage, "#{format} images are not supported, convert to PNG or JPEG" if format
+
+      raise UnsupportedImage, "only PNG and JPEG images are supported"
+    end
+
+    def xobject(width, height, color_space, bits)
+      { Type: :XObject, Subtype: :Image, Width: width, Height: height, ColorSpace: color_space, BitsPerComponent: bits }
+    end
+  end
+end

data/lib/stationery/images/jpeg.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    # A JPEG passed through to the viewer as DCTDecode; only the frame header
+    # is read, for dimensions and colour components.
+    class JPEG
+      START_OF_FRAME = [0xC0..0xC3, 0xC5..0xC7, 0xC9..0xCB, 0xCD..0xCF].freeze
+      COLOR_SPACES = { 1 => :DeviceGray, 3 => :DeviceRGB, 4 => :DeviceCMYK }.freeze
+
+      attr_reader :width, :height
+
+      def initialize(data)
+        @data = data
+        read_frame_header
+        raise UnsupportedImage, "invalid JPEG image" unless @width
+        return if COLOR_SPACES.key?(@components)
+
+        raise UnsupportedImage,
+              "unsupported JPEG colour components: #{@components}"
+      end
+
+      def inspect = "#<#{self.class} #{@width}x#{@height}>"
+
+      def build(writer)
+        dictionary = Images.xobject(@width, @height, COLOR_SPACES.fetch(@components), @bits).merge(Filter: :DCTDecode)
+        # Adobe CMYK JPEGs store inverted values.
+        dictionary[:Decode] = [1, 0] * 4 if @components == 4 && @adobe
+        writer.add(PDF::Stream.new(@data, dictionary))
+      end
+
+      private
+
+      def read_frame_header
+        pos = 2
+        while pos + 4 <= @data.bytesize
+          raise UnsupportedImage, "invalid JPEG image" unless @data.getbyte(pos) == 0xFF
+
+          marker = @data.getbyte(pos + 1)
+          next pos += 1 if marker == 0xFF # fill byte
+
+          @adobe = true if marker == 0xEE && @data.byteslice(pos + 4, 5) == "Adobe"
+          if START_OF_FRAME.any? { |range| range.cover?(marker) }
+            @bits, @height, @width, @components = @data.byteslice(pos + 4, 6).unpack("CnnC")
+            return
+          end
+
+          pos += 2 + @data.byteslice(pos + 2, 2).unpack1("n")
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/png.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Stationery
+  module Images
+    # A PNG. Opaque images pass their compressed data straight through with a
+    # PNG predictor; transparency is split into a soft mask (or a colour-key
+    # mask for grey/RGB tRNS).
+    class PNG
+      CHANNELS = { 0 => 1, 2 => 3, 3 => 1, 4 => 2, 6 => 4 }.freeze
+
+      attr_reader :width, :height
+
+      def initialize(data)
+        @idat = String.new(encoding: Encoding::BINARY)
+        read_chunks(data)
+        raise UnsupportedImage, "invalid PNG image" unless @width && CHANNELS.key?(@color_type)
+        raise UnsupportedImage, "interlaced PNG images are not supported, save it non-interlaced" if @interlace == 1
+      end
+
+      def inspect = "#<#{self.class} #{@width}x#{@height}>"
+
+      def build(writer)
+        return build_with_alpha(writer) if alpha_channel?
+
+        dictionary = Images.xobject(@width, @height, color_space, @bit_depth).merge(
+          Filter: :FlateDecode,
+          DecodeParms: { Predictor: 15, Colors: CHANNELS[@color_type], BitsPerComponent: @bit_depth, Columns: @width }
+        )
+        if @transparency && @color_type == 3
+          dictionary[:SMask] = soft_mask(writer, palette_alpha)
+        elsif @transparency
+          dictionary[:Mask] = @transparency.unpack("n*").first(CHANNELS[@color_type]).flat_map { |v| [v, v] }
+        end
+        writer.add(PDF::Stream.new(@idat, dictionary))
+      end
+
+      private
+
+      def read_chunks(data)
+        pos = PNG_SIGNATURE.bytesize
+        while pos + 8 <= data.bytesize
+          length, type = data.byteslice(pos, 8).unpack("Na4")
+          chunk = data.byteslice(pos + 8, length)
+          break if type == "IEND"
+
+          read_chunk(type, chunk)
+          pos += 12 + length
+        end
+      end
+
+      def read_chunk(type, chunk)
+        case type
+        when "IHDR" then @width, @height, @bit_depth, @color_type, _, _, @interlace = chunk.unpack("NNCCCCC")
+        when "PLTE" then @palette = chunk
+        when "tRNS" then @transparency = chunk
+        when "IDAT" then @idat << chunk
+        end
+      end
+
+      def alpha_channel?
+        [4, 6].include?(@color_type)
+      end
+
+      def build_with_alpha(writer)
+        color, alpha = split_alpha
+        dictionary = Images.xobject(@width, @height, color_space, 8)
+                           .merge(Filter: :FlateDecode, SMask: soft_mask(writer, alpha))
+        writer.add(PDF::Stream.new(Zlib::Deflate.deflate(color), dictionary))
+      end
+
+      def color_space
+        case @color_type
+        when 0, 4 then :DeviceGray
+        when 2, 6 then :DeviceRGB
+        else [:Indexed, :DeviceRGB, (@palette.bytesize / 3) - 1, PDF::HexString.new(@palette)]
+        end
+      end
+
+      def soft_mask(writer, alpha)
+        dictionary = Images.xobject(@width, @height, :DeviceGray, 8).merge(Filter: :FlateDecode)
+        writer.add(PDF::Stream.new(Zlib::Deflate.deflate(alpha), dictionary))
+      end
+
+      def palette_alpha
+        alphas = @transparency.bytes
+        alpha = String.new(capacity: @width * @height, encoding: Encoding::BINARY)
+        Scanlines.each(@idat, @height, 1, ((@width * @bit_depth) + 7) / 8) do |row|
+          alpha << palette_indexes(row).map { |index| alphas[index] || 255 }.pack("C*")
+        end
+        alpha
+      end
+
+      def palette_indexes(row)
+        return row if @bit_depth == 8
+
+        row.pack("C*").unpack1("B*").scan(/.{#{@bit_depth}}/o).first(@width).map { |bits| bits.to_i(2) }
+      end
+
+      # Grey+alpha or RGBA pixels split into colour and alpha, 8 bits per sample.
+      def split_alpha
+        channels = CHANNELS[@color_type]
+        sample = @bit_depth / 8
+        step = channels * sample
+        color_bytes = Array.new(@width) { |x| Array.new(channels - 1) { |c| (x * step) + (c * sample) } }.flatten
+        alpha_bytes = Array.new(@width) { |x| (x * step) + ((channels - 1) * sample) }
+
+        color = String.new(encoding: Encoding::BINARY)
+        alpha = String.new(encoding: Encoding::BINARY)
+        Scanlines.each(@idat, @height, step, @width * step) do |row|
+          color << row.values_at(*color_bytes).pack("C*")
+          alpha << row.values_at(*alpha_bytes).pack("C*")
+        end
+        [color, alpha]
+      end
+    end
+  end
+end

data/lib/stationery/images/scanlines.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Stationery
+  module Images
+    # Inflates PNG image data and reverses the per-row filters, yielding each
+    # row as an Array of bytes.
+    module Scanlines
+      module_function
+
+      def each(idat, height, bpp, row_bytes)
+        data = Zlib::Inflate.inflate(idat)
+        previous = Array.new(row_bytes, 0)
+
+        height.times do |y|
+          pos = y * (row_bytes + 1)
+          row = unfilter(data.getbyte(pos), data.byteslice(pos + 1, row_bytes).bytes, previous, bpp)
+          yield row
+          previous = row
+        end
+      end
+
+      def unfilter(filter, row, previous, bpp)
+        case filter
+        when 0 then row
+        when 1 then row.each_index { |i| row[i] = (row[i] + (i >= bpp ? row[i - bpp] : 0)) & 0xFF }
+        when 2 then row.each_index { |i| row[i] = (row[i] + previous[i]) & 0xFF }
+        when 3 then row.each_index do |i|
+          row[i] = (row[i] + (((i >= bpp ? row[i - bpp] : 0) + previous[i]) >> 1)) & 0xFF
+        end
+        when 4 then paeth(row, previous, bpp)
+        else raise UnsupportedImage, "invalid PNG filter type: #{filter}"
+        end
+      end
+
+      def paeth(row, previous, bpp)
+        row.each_index do |i|
+          a = i >= bpp ? row[i - bpp] : 0
+          c = i >= bpp ? previous[i - bpp] : 0
+          row[i] = (row[i] + predictor(a, previous[i], c)) & 0xFF
+        end
+      end
+
+      def predictor(a, b, c)
+        p = a + b - c
+        pa = (p - a).abs
+        pb = (p - b).abs
+        pc = (p - c).abs
+        return a if pa <= pb && pa <= pc
+
+        pb <= pc ? b : c
+      end
+    end
+  end
+end