prawnx 0.1.1

data/lib/prawnx/grid.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module PrawnX
+  class Document
+    def define_grid(options = {})
+      @boxes = nil
+      @grid = Grid.new(self, options)
+    end
+
+    def grid(*arguments)
+      @boxes ||= {}
+      @boxes[arguments] ||=
+        if arguments.empty?
+          @grid
+        else
+          first, second = arguments
+          if first.is_a?(Array) && second.is_a?(Array) && first.length == 2 && second.length == 2
+            MultiBox.new(self, GridBox.new(self, *first), GridBox.new(self, *second))
+          else
+            GridBox.new(self, first, second)
+          end
+        end
+    end
+
+    # Rows and columns of equal size dividing the current bounds, separated by gutters.
+    class Grid
+      attr_reader :pdf, :columns, :rows, :gutter, :row_gutter, :column_gutter
+
+      def initialize(pdf, options = {})
+        PrawnX.verify_options(%i[columns rows gutter row_gutter column_gutter], options)
+        @pdf = pdf
+        @columns = options[:columns]
+        @rows = options[:rows]
+        if options.key?(:gutter)
+          @gutter = Float(options[:gutter])
+          @row_gutter = @gutter
+          @column_gutter = @gutter
+        else
+          @row_gutter = Float(options[:row_gutter])
+          @column_gutter = Float(options[:column_gutter])
+          @gutter = 0
+        end
+      end
+
+      def column_width
+        @column_width ||= subdivide(pdf.bounds.width, columns, column_gutter)
+      end
+
+      def row_height
+        @row_height ||= subdivide(pdf.bounds.height, rows, row_gutter)
+      end
+
+      def show_all(color = "CCCCCC")
+        rows.times { |row| columns.times { |column| pdf.grid(row, column).show(color) } }
+      end
+
+      private
+
+      def subdivide(total, count, gutter)
+        (Float(total) - (gutter * Float(count - 1))) / Float(count)
+      end
+    end
+
+    # What a grid cell and a span of cells share: corners, a bounding box, and a way to show themselves.
+    module GridArea
+      def top_left
+        [left, top]
+      end
+
+      def top_right
+        [right, top]
+      end
+
+      def bottom_left
+        [left, bottom]
+      end
+
+      def bottom_right
+        [right, bottom]
+      end
+
+      def bounding_box(&)
+        pdf.bounding_box(top_left, width:, height:, &)
+      end
+
+      def show(grid_color = "CCCCCC")
+        bounding_box do
+          original_stroke_color = pdf.stroke_color
+          pdf.stroke_color = grid_color
+          pdf.text(name)
+          pdf.stroke_bounds
+          pdf.stroke_color = original_stroke_color
+        end
+      end
+    end
+
+    class GridBox
+      include GridArea
+
+      attr_reader :pdf
+
+      def initialize(pdf, rows, columns)
+        @pdf = pdf
+        @rows = rows
+        @columns = columns
+      end
+
+      def name
+        "#{@rows},#{@columns}"
+      end
+
+      def total_height
+        Float(pdf.bounds.height)
+      end
+
+      def width
+        Float(grid.column_width)
+      end
+
+      def height
+        Float(grid.row_height)
+      end
+
+      def gutter
+        Float(grid.gutter)
+      end
+
+      def left
+        @left ||= (width + grid.column_gutter) * Float(@columns)
+      end
+
+      def right
+        @right ||= left + width
+      end
+
+      def top
+        @top ||= total_height - ((height + grid.row_gutter) * Float(@rows))
+      end
+
+      def bottom
+        @bottom ||= top - height
+      end
+
+      private
+
+      def grid
+        pdf.grid
+      end
+    end
+
+    class MultiBox
+      include GridArea
+
+      attr_reader :pdf
+
+      def initialize(pdf, box1, box2)
+        @pdf = pdf
+        @boxes = [box1, box2]
+      end
+
+      def name
+        @boxes.map(&:name).join(":")
+      end
+
+      def total_height
+        @boxes[0].total_height
+      end
+
+      def width
+        right_box.right - left_box.left
+      end
+
+      def height
+        top_box.top - bottom_box.bottom
+      end
+
+      def gutter
+        @boxes[0].gutter
+      end
+
+      def left
+        left_box.left
+      end
+
+      def right
+        right_box.right
+      end
+
+      def top
+        top_box.top
+      end
+
+      def bottom
+        bottom_box.bottom
+      end
+
+      private
+
+      def left_box
+        @left_box ||= @boxes.min_by(&:left)
+      end
+
+      def right_box
+        @right_box ||= @boxes.max_by(&:right)
+      end
+
+      def top_box
+        @top_box ||= @boxes.max_by(&:top)
+      end
+
+      def bottom_box
+        @bottom_box ||= @boxes.min_by(&:bottom)
+      end
+    end
+  end
+end

data/lib/prawnx/images/image.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module Images
+    class Image
+      attr_accessor :scaled_width, :scaled_height
+
+      def calc_image_dimensions(options)
+        w = options[:width] || width
+        h = options[:height] || height
+        if options[:width] && !options[:height]
+          ratio = w / Float(width)
+          w = width * ratio
+          h = height * ratio
+        elsif options[:height] && !options[:width]
+          ratio = h / Float(height)
+          w = width * ratio
+          h = height * ratio
+        elsif options[:scale]
+          w = width * options[:scale]
+          h = height * options[:scale]
+        elsif options[:fit]
+          box_width, box_height = options[:fit]
+          if width / Float(height) > box_width / Float(box_height)
+            w = box_width
+            h = box_width / (width / Float(height))
+          else
+            h = box_height
+            w = box_height * (width / Float(height))
+          end
+        end
+        self.scaled_width = w
+        self.scaled_height = h
+        [w, h]
+      end
+    end
+
+    class JPG < Image
+      class FormatError < StandardError
+      end
+
+      START_OF_FRAME_MARKERS = [0xC0, 0xC1, 0xC2, 0xC3, 0xC5, 0xC6, 0xC7, 0xC9, 0xCA, 0xCB, 0xCD, 0xCE, 0xCF].freeze
+      MARKER_PREFIX = 0xFF
+      COLOR_SPACE_BY_CHANNELS = {1 => :DeviceGray, 3 => :DeviceRGB, 4 => :DeviceCMYK}.freeze
+      # Adobe's CMYK JPEGs store inverted values.
+      INVERTED_CMYK_DECODE = [1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0].freeze
+
+      attr_reader :width, :height, :bits, :channels
+
+      def self.can_render?(image_blob)
+        image_blob.byteslice(0, 3).bytes == [255, 216, 255]
+      end
+
+      def initialize(data)
+        super()
+        @data = data
+        position = 2
+        loop do
+          marker, code, length = data.byteslice(position, 4)&.unpack("CCn")
+          raise FormatError, "JPEG marker not found!" if marker != MARKER_PREFIX
+
+          if START_OF_FRAME_MARKERS.include?(code)
+            @bits, @height, @width, @channels = data.unpack("@#{position + 4} CnnC")
+            break
+          end
+          position += 2 + length
+        end
+      end
+
+      def build_pdf_object(document)
+        color_space = COLOR_SPACE_BY_CHANNELS.fetch(channels) { raise ArgumentError, "JPG uses an unsupported number of channels" }
+        dictionary = {Type: :XObject, Subtype: :Image, ColorSpace: color_space, BitsPerComponent: bits, Width: width, Height: height, Filter: :DCTDecode}
+        dictionary[:Decode] = INVERTED_CMYK_DECODE if color_space == :DeviceCMYK
+        document.ref!(dictionary, @data)
+      end
+    end
+
+    class PNG < Image
+      SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10].freeze
+      GRAYSCALE = 0
+      TRUE_COLOR = 2
+      INDEXED = 3
+      GRAYSCALE_ALPHA = 4
+      TRUE_COLOR_ALPHA = 6
+      PNG_PREDICTORS = 15
+      # Compressed input fed at a time: at zlib's highest ratio, 4 KB inflate to about 4 MB before the size check.
+      INFLATE_CHUNK_BYTES = 4096
+      MAXIMUM_IMAGE_BYTES = 1 << 30
+
+      attr_reader :palette, :img_data, :transparency, :width, :height, :bits, :color_type, :compression_method,
+        :filter_method, :interlace_method, :alpha_channel
+
+      def self.can_render?(image_blob)
+        image_blob.byteslice(0, 8).bytes == SIGNATURE
+      end
+
+      def initialize(data)
+        super()
+        @palette = +"".b
+        compressed = +"".b
+        @transparency = {}
+        position = 8
+        loop do
+          raise Errors::UnsupportedImageType, "Truncated PNG" if position + 8 > data.bytesize
+
+          length, section = data.unpack("@#{position} N a4")
+          raise Errors::UnsupportedImageType, "Truncated PNG #{section} chunk" if position + 8 + length > data.bytesize
+
+          chunk = data.byteslice(position + 8, length)
+          case section
+          when "IHDR"
+            @width, @height, @bits, @color_type, @compression_method, @filter_method, @interlace_method = chunk.unpack("NNCCCCC")
+          when "PLTE" then @palette << chunk
+          when "IDAT" then compressed << chunk
+          when "tRNS"
+            @transparency =
+              case @color_type
+              when INDEXED then {palette: chunk.unpack("C*")}
+              when GRAYSCALE then {grayscale: chunk.unpack1("n")}
+              when TRUE_COLOR then {rgb: chunk.unpack("nnn")}
+              else {}
+              end
+          when "IEND" then break
+          end
+          position += 12 + length
+        end
+        raise Errors::UnsupportedImageType, "PNG without a valid IHDR chunk" unless @width.to_i.positive? && @height.to_i.positive? && @bits.to_i.positive?
+
+        @compressed_data = compressed
+      end
+
+      # Inflated up to the size the header announces, never more: a few kilobytes of crafted data could otherwise
+      # inflate into gigabytes.
+      def img_data
+        @img_data ||= begin
+          samples = (colors || 1) + (alpha_channel? && color_type != INDEXED ? 1 : 0)
+          expected_bytes = height * (1 + (((width * bits * samples) + 7) / 8))
+          raise Errors::UnsupportedImageType, "PNG of #{width}x#{height} pixels is too large" if expected_bytes > MAXIMUM_IMAGE_BYTES
+
+          inflater = Zlib::Inflate.new
+          inflated = +"".b
+          (0...@compressed_data.bytesize).step(INFLATE_CHUNK_BYTES) do |offset|
+            inflated << inflater.inflate(@compressed_data.byteslice(offset, INFLATE_CHUNK_BYTES))
+            raise Errors::UnsupportedImageType, "PNG data inflates beyond its #{width}x#{height} size" if inflated.bytesize > expected_bytes
+          end
+          inflated << inflater.finish
+          inflated
+        rescue Zlib::Error => exception
+          raise Errors::UnsupportedImageType, "Corrupt PNG data: #{exception.message}"
+        ensure
+          inflater&.close
+        end
+      end
+
+      def colors
+        case color_type
+        when GRAYSCALE, INDEXED, GRAYSCALE_ALPHA then 1
+        when TRUE_COLOR, TRUE_COLOR_ALPHA then 3
+        end
+      end
+
+      def alpha_channel?
+        return true if color_type == GRAYSCALE_ALPHA || color_type == TRUE_COLOR_ALPHA
+        return @transparency.any? if color_type == INDEXED
+
+        false
+      end
+
+      def min_pdf_version
+        if bits > 8 then 1.5
+        elsif alpha_channel? then 1.4
+        else 1.0
+        end
+      end
+
+      def build_pdf_object(document)
+        raise Errors::UnsupportedImageType, "PNG uses an unsupported compression method" if compression_method != 0
+        raise Errors::UnsupportedImageType, "PNG uses an unsupported filter method" if filter_method != 0
+        raise Errors::UnsupportedImageType, "PNG uses unsupported interlace method" if interlace_method != 0
+
+        dictionary = {Type: :XObject, Subtype: :Image, Height: height, Width: width, BitsPerComponent: bits}
+        if color_type == INDEXED && alpha_channel?
+          index_samples, alpha_samples = split_palette_transparency
+          image = document.ref!(dictionary, index_samples)
+          image.data[:SMask] = document.ref!(alpha_dictionary(8), alpha_samples)
+        elsif alpha_channel?
+          color_rows, alpha_rows = split_alpha_channel
+          image = document.ref!(dictionary.merge(DecodeParms: predictors(colors)), color_rows)
+          image.data[:SMask] = document.ref!(alpha_dictionary(bits).merge(DecodeParms: predictors(1)), alpha_rows)
+        else
+          image = document.ref!(dictionary.merge(DecodeParms: predictors(colors)), img_data)
+        end
+        image.data[:ColorSpace] = palette.empty? ? (colors == 1 ? :DeviceGray : :DeviceRGB) : [:Indexed, :DeviceRGB, (palette.bytesize / 3) - 1, document.ref!({}, palette)]
+        if transparency[:grayscale]
+          image.data[:Mask] = [transparency[:grayscale]] * 2
+        elsif transparency[:rgb]
+          image.data[:Mask] = transparency[:rgb].flat_map { [it, it] }
+        end
+        image
+      end
+
+      private
+
+      # The reader undoes the PNG filters itself; the stream gets compressed again when the document is written.
+      def predictors(color_count)
+        {Predictor: PNG_PREDICTORS, Colors: color_count, BitsPerComponent: bits, Columns: width}
+      end
+
+      def alpha_dictionary(bits_per_component)
+        {Type: :XObject, Subtype: :Image, Height: height, Width: width, BitsPerComponent: bits_per_component, ColorSpace: :DeviceGray, Decode: [0, 1]}
+      end
+
+      # Color and alpha rows, each keeping its filter byte: PNG filters predict a byte from the same channel of
+      # the neighbouring pixels, which stays at the same relative place once the channels are apart.
+      def split_alpha_channel
+        sample_bytes = bits / 8
+        color_bytes = colors * sample_bytes
+        row_bytes = (width * (color_bytes + sample_bytes)) + 1
+        pixel_layout = "a#{color_bytes}a#{sample_bytes}" * width
+        color = +"".b
+        alpha = +"".b
+        (img_data.bytesize / row_bytes).times do |row_index|
+          start = row_index * row_bytes
+          filter = img_data.byteslice(start, 1)
+          samples = img_data.byteslice(start + 1, row_bytes - 1).unpack(pixel_layout)
+          color << filter << samples.each_slice(2).map(&:first).join
+          alpha << filter << samples.each_slice(2).map(&:last).join
+        end
+        [color, alpha]
+      end
+
+      # Palette indices and their opacity: indices only mean something once the rows are unfiltered.
+      def split_palette_transparency
+        rows = PngDecoder.unfilter(img_data, ((width * bits) + 7) / 8, 1)
+        alpha_by_index = Array.new(256) { transparency[:palette][it] || 0xFF }
+        alpha = rows.map do |row|
+          indices = bits == 8 ? row.bytes : row.unpack1("B*").scan(/.{#{bits}}/).first(width).map { it.to_i(2) }
+          indices.map { alpha_by_index[it] }.pack("C*")
+        end
+        [rows.join, alpha.join]
+      end
+    end
+  end
+end

data/lib/prawnx/images/png_decoder.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module Images
+    # Undoes PNG's per-row filters (PNG specification §9), giving back raw samples: needed to split an alpha
+    # channel or a palette's transparency into a separate soft mask.
+    module PngDecoder
+      NONE = 0
+      SUB = 1
+      UP = 2
+      AVERAGE = 3
+      PAETH = 4
+
+      module_function
+
+      # Rows of unfiltered bytes, from the inflated data of a non-interlaced image.
+      def unfilter(data, row_bytes, bytes_per_pixel)
+        previous = ("\x00" * row_bytes).b
+        row_count = data.bytesize / (row_bytes + 1)
+        Array.new(row_count) do |row_index|
+          start = row_index * (row_bytes + 1)
+          filter = data.getbyte(start)
+          row = data.byteslice(start + 1, row_bytes).b
+          unfilter_row!(row, previous, filter, bytes_per_pixel)
+          previous = row
+        end
+      end
+
+      def unfilter_row!(row, previous, filter, bytes_per_pixel)
+        case filter
+        when NONE then nil
+        when SUB
+          (bytes_per_pixel...row.bytesize).each { row.setbyte(it, (row.getbyte(it) + row.getbyte(it - bytes_per_pixel)) & 0xFF) }
+        when UP
+          row.bytesize.times { row.setbyte(it, (row.getbyte(it) + previous.getbyte(it)) & 0xFF) }
+        when AVERAGE
+          row.bytesize.times do |index|
+            left = index >= bytes_per_pixel ? row.getbyte(index - bytes_per_pixel) : 0
+            row.setbyte(index, (row.getbyte(index) + ((left + previous.getbyte(index)) >> 1)) & 0xFF)
+          end
+        when PAETH
+          row.bytesize.times do |index|
+            left = index >= bytes_per_pixel ? row.getbyte(index - bytes_per_pixel) : 0
+            up = previous.getbyte(index)
+            up_left = index >= bytes_per_pixel ? previous.getbyte(index - bytes_per_pixel) : 0
+            row.setbyte(index, (row.getbyte(index) + paeth(left, up, up_left)) & 0xFF)
+          end
+        else raise Errors::UnsupportedImageType, "PNG uses an unknown filter type #{filter}"
+        end
+        row
+      end
+
+      def paeth(left, up, up_left)
+        estimate = left + up - up_left
+        distance_left = (estimate - left).abs
+        distance_up = (estimate - up).abs
+        distance_up_left = (estimate - up_left).abs
+        if distance_left <= distance_up && distance_left <= distance_up_left then left
+        elsif distance_up <= distance_up_left then up
+        else up_left
+        end
+      end
+    end
+  end
+end

data/lib/prawnx/images.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+require "pathname"
+
+module PrawnX
+  def self.image_handler
+    @image_handler ||= ImageHandler.new
+  end
+
+  # The image formats PrawnX knows, tried in order on an image's first bytes.
+  class ImageHandler
+    def initialize
+      @handlers = []
+    end
+
+    def register(handler)
+      @handlers.delete(handler)
+      @handlers.push(handler)
+    end
+
+    def register!(handler)
+      @handlers.delete(handler)
+      @handlers.unshift(handler)
+    end
+
+    def unregister(handler)
+      @handlers.delete(handler)
+    end
+
+    def find(image_blob)
+      @handlers.find { it.can_render?(image_blob) } || raise(Errors::UnsupportedImageType, "image file is an unrecognised format")
+    end
+  end
+
+  module Images
+    def image(file, options = {})
+      PrawnX.verify_options(%i[at position vposition height width scale fit], options)
+      pdf_object, info = build_image_object(file)
+      embed_image(pdf_object, info, options)
+      info
+    end
+
+    # The same image bytes are embedded once per document, however many times they are placed.
+    def build_image_object(file)
+      image_content = verify_and_read_image(file)
+      entry = image_registry[Digest::SHA1.hexdigest(image_content)] ||= begin
+        info = PrawnX.image_handler.find(image_content).new(image_content)
+        min_version(info.min_pdf_version) if info.respond_to?(:min_pdf_version)
+        {obj: info.build_pdf_object(self), info:}
+      end
+      [entry[:obj], entry[:info]]
+    end
+
+    def embed_image(pdf_object, info, options)
+      width, height = info.calc_image_dimensions(options)
+      if options[:at]
+        x, y = map_to_absolute(options[:at])
+      else
+        x, y = image_position(width, height, options)
+        move_text_position(height)
+      end
+      label = "I#{@image_counter = (@image_counter || 0) + 1}"
+      page.xobjects[label] = pdf_object
+      add_content("\nq\n#{PDF.real_params([width, 0, 0, height, x, y - height])} cm\n/#{label} Do\nQ")
+    end
+
+    private
+
+    def verify_and_read_image(io_or_path)
+      if io_or_path.respond_to?(:rewind)
+        io_or_path.rewind
+        io_or_path.binmode if io_or_path.respond_to?(:binmode)
+        return io_or_path.read
+      end
+      path = Pathname.new(io_or_path)
+      raise ArgumentError, "#{path} not found" unless path.file?
+
+      path.binread
+    end
+
+    def image_position(width, height, options)
+      options[:position] ||= :left
+      y =
+        case options[:vposition]
+        when :top then bounds.absolute_top
+        when :center then bounds.absolute_top - ((bounds.height - height) / 2.0)
+        when :bottom then bounds.absolute_bottom + height
+        when Numeric then bounds.absolute_top - options[:vposition]
+        else determine_y_with_page_flow(height)
+        end
+      x =
+        case options[:position]
+        when :left then bounds.left_side
+        when :center then bounds.left_side + ((bounds.width - width) / 2.0)
+        when :right then bounds.right_side - width
+        when Numeric then options[:position] + bounds.left_side
+        end
+      [x, y]
+    end
+
+    def determine_y_with_page_flow(height)
+      bounds.move_past_bottom if overruns_page?(height)
+      y
+    end
+
+    def overruns_page?(height)
+      (y - height) < reference_bounds.absolute_bottom
+    end
+
+    def image_registry
+      @image_registry ||= {}
+    end
+  end
+end

data/lib/prawnx/measurement_extensions.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "measurements"
+
+# 10.mm, 2.cm, 1.in…: lengths in PDF points.
+class Numeric
+  include PrawnX::Measurements
+
+  def mm
+    mm2pt(self)
+  end
+
+  def cm
+    cm2pt(self)
+  end
+
+  def dm
+    dm2pt(self)
+  end
+
+  def m
+    m2pt(self)
+  end
+
+  def in
+    in2pt(self)
+  end
+
+  def yd
+    yd2pt(self)
+  end
+
+  def ft
+    ft2pt(self)
+  end
+
+  def pt
+    pt2pt(self)
+  end
+end