gamba 2.0.0

data/lib/gamba/graphic_state.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module PDF::Core
+  # What a PDF `q` saves and `Q` restores, as far as Gamba writes it.
+  class GraphicState
+    UNDASHED = {dash: nil, space: nil, phase: 0}.freeze
+    # The text state parameters Prawn sets, with their defaults, in the order a new page writes them back; each
+    # state records them as last written in it.
+    DEFAULT_TEXT_STATE = {text_rendering_mode: :fill, character_spacing: 0, word_spacing: 0, horizontal_text_scaling: 100, rise: 0}.freeze
+    TEXT_STATE_WRITERS = DEFAULT_TEXT_STATE.to_h { |setting, _default| [setting, :"#{setting}="] }.freeze
+
+    attr_accessor :color_space, :dash, :cap_style, :join_style, :line_width, :fill_color, :stroke_color,
+      *DEFAULT_TEXT_STATE.keys
+    # What Prawn's state leaves out: the pattern painting in place of each colour since a gradient was set, and the
+    # blend mode's ExtGState, {name:, reference:} each, nil for none and for Normal.
+    attr_accessor :fill_pattern, :stroke_pattern, :blend_mode
+    # The save that opened this state on its page, or that it was reopened for on a new page; a copy has none.
+    attr_accessor :save
+
+    def initialize(previous_state = nil)
+      if previous_state
+        @color_space = previous_state.color_space.dup
+        @fill_color = previous_state.fill_color.dup
+        @stroke_color = previous_state.stroke_color.dup
+        @dash = previous_state.dash.dup
+        @cap_style = previous_state.cap_style
+        @join_style = previous_state.join_style
+        @line_width = previous_state.line_width
+        @fill_pattern = previous_state.fill_pattern
+        @stroke_pattern = previous_state.stroke_pattern
+        @blend_mode = previous_state.blend_mode
+        copy_text_state(previous_state)
+      else
+        @color_space = {}
+        @fill_color = "000000"
+        @stroke_color = "000000"
+        @dash = UNDASHED.dup
+        @cap_style = :butt
+        @join_style = :miter
+        @line_width = 1
+        reset_text_state
+      end
+    end
+
+    # The text state recorded in another state, the default one for nil.
+    def copy_text_state(other)
+      return reset_text_state unless other
+
+      @text_rendering_mode = other.text_rendering_mode
+      @character_spacing = other.character_spacing
+      @word_spacing = other.word_spacing
+      @horizontal_text_scaling = other.horizontal_text_scaling
+      @rise = other.rise
+    end
+
+    def reset_text_state
+      @text_rendering_mode = :fill
+      @character_spacing = 0
+      @word_spacing = 0
+      @horizontal_text_scaling = 100
+      @rise = 0
+    end
+
+    # What fills or strokes: the pattern's name, else the colour.
+    def fill_paint
+      fill_pattern ? fill_pattern[:name] : fill_color
+    end
+
+    def stroke_paint
+      stroke_pattern ? stroke_pattern[:name] : stroke_color
+    end
+
+    def dup
+      GraphicState.new(self)
+    end
+
+    def dash_setting
+      return "[] 0 d" unless dash[:dash]
+
+      lengths = dash[:dash].is_a?(Array) ? dash[:dash] : [dash[:dash], dash[:space]]
+      "[#{PDF::Core.real_params(lengths)}] #{PDF::Core.real(dash[:phase])} d"
+    end
+  end
+end

data/lib/gamba/graphics/color.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+module Prawn
+  module Graphics
+    module Color
+      COLOR_SPACES = %i[DeviceRGB DeviceCMYK Pattern].freeze
+      OPERATOR_BY_TYPE = {fill: "scn", stroke: "SCN"}.freeze
+      COLOR_SPACE_OPERATOR_BY_TYPE = {fill: "cs", stroke: "CS"}.freeze
+      # A document uses a handful of colours; computed ones (gradients drawn by hand) must not grow it forever.
+      HEX_COLORS_CACHED = 256
+      PDF_OPERANDS_BY_HEX_COLOR = {}
+
+      def fill_color(*color)
+        return current_fill_color if color.empty?
+
+        self.current_fill_color = process_color(*color)
+        set_fill_color
+      end
+      alias_method :fill_color=, :fill_color
+
+      def stroke_color(*color)
+        return current_stroke_color if color.empty?
+
+        color = process_color(*color)
+        self.current_stroke_color = color
+        set_stroke_color(color)
+      end
+      alias_method :stroke_color=, :stroke_color
+
+      module_function
+
+      def rgb2hex(rgb)
+        rgb.map { format("%02x", _1) }.join
+      end
+
+      def hex2rgb(hex)
+        [hex[0..1], hex[2..3], hex[4..5]].map { _1.to_i(16) }
+      end
+
+      private
+
+      def process_color(*color)
+        case color.size
+        when 1 then color[0]
+        when 4 then color
+        else raise ArgumentError, "wrong number of arguments supplied"
+        end
+      end
+
+      def color_type(color)
+        case color
+        when String
+          return :RGB if /\A\h{6}\z/.match?(color)
+        when Array
+          return :RGB if color.length == 3
+          return :CMYK if color.length == 4
+        end
+        raise ArgumentError, "Unknown type of color: #{color.inspect}"
+      end
+
+      def normalize_color(color)
+        case color_type(color)
+        when :RGB
+          r, g, b = hex2rgb(color)
+          [r / 255.0, g / 255.0, b / 255.0]
+        when :CMYK
+          color.map { _1 / 100.0 }
+        end
+      end
+
+      def color_to_s(color)
+        return PDF::Core.real_params(normalize_color(color)) unless color.is_a?(String)
+
+        PDF_OPERANDS_BY_HEX_COLOR.fetch(color) do
+          operands = PDF::Core.real_params(normalize_color(color))
+          PDF_OPERANDS_BY_HEX_COLOR[color.dup.freeze] = operands if PDF_OPERANDS_BY_HEX_COLOR.size < HEX_COLORS_CACHED
+          operands
+        end
+      end
+
+      def color_space(color)
+        (color_type(color) == :RGB) ? :DeviceRGB : :DeviceCMYK
+      end
+
+      def set_color_space(type, color_space)
+        return if current_color_space(type) == color_space && !page.in_stamp_stream?
+
+        set_current_color_space(color_space, type)
+        raise ArgumentError, "unknown color space: '#{color_space}'" unless COLOR_SPACES.include?(color_space)
+
+        operator = COLOR_SPACE_OPERATOR_BY_TYPE.fetch(type) { raise ArgumentError, "unknown type '#{type}'" }
+        add_content("/#{color_space} #{operator}")
+      end
+
+      # A pattern paints until a colour of the same type replaces it. One the page's resources hold is recorded, to
+      # paint with on the next page.
+      def set_color(type, color, options = {})
+        operator = OPERATOR_BY_TYPE.fetch(type) { raise ArgumentError, "unknown type '#{type}'" }
+        if options[:pattern]
+          reference = page.dictionary.data[:Resources]&.dig(:Pattern, color)
+          set_color_space(type, :Pattern)
+          add_content("/#{color} #{operator}")
+          record_pattern(type, reference && {name: color, reference:})
+        else
+          set_color_space(type, color_space(color))
+          write_color(color_to_s(color), operator)
+          state = graphic_state
+          (type == :fill) ? state.fill_pattern &&= nil : state.stroke_pattern &&= nil
+        end
+      end
+
+      # A pattern, {name:, reference:}, on this page's resources too.
+      def write_pattern(type, pattern)
+        (page.resources[:Pattern] ||= {})[pattern[:name]] ||= pattern[:reference]
+        set_color_space(type, :Pattern)
+        add_content("/#{pattern[:name]} #{OPERATOR_BY_TYPE.fetch(type)}")
+        record_pattern(type, pattern)
+      end
+
+      def record_pattern(type, pattern)
+        (type == :fill) ? graphic_state.fill_pattern = pattern : graphic_state.stroke_pattern = pattern
+      end
+
+      def write_fill_paint
+        (pattern = graphic_state.fill_pattern) ? write_pattern(:fill, pattern) : set_fill_color
+      end
+
+      def write_stroke_paint
+        (pattern = graphic_state.stroke_pattern) ? write_pattern(:stroke, pattern) : set_stroke_color
+      end
+
+      def set_fill_color(color = nil)
+        set_color(:fill, color || current_fill_color)
+      end
+
+      def set_stroke_color(color = nil)
+        set_color(:stroke, color || current_stroke_color)
+      end
+
+      def update_colors
+        set_fill_color
+        set_stroke_color
+      end
+
+      def current_color_space(type)
+        graphic_state.color_space[type]
+      end
+
+      def set_current_color_space(color_space, type)
+        graphic_state.color_space[type] = color_space
+      end
+
+      def current_fill_color
+        graphic_state.fill_color
+      end
+
+      def current_fill_color=(color)
+        graphic_state.fill_color = color
+      end
+
+      def current_stroke_color
+        graphic_state.stroke_color
+      end
+
+      def current_stroke_color=(color)
+        graphic_state.stroke_color = color
+      end
+
+      def write_color(color, operator)
+        add_content("#{color} #{operator}")
+      end
+    end
+  end
+end

data/lib/gamba/graphics/patterns.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module Prawn
+  module Graphics
+    # Axial and radial gradients, as shading patterns (ISO 32000-1 §8.7.4.5).
+    module Patterns
+      GradientStop = Data.define(:position, :color)
+      Gradient = Data.define(:type, :apply_transformations, :stops, :from, :to, :r1, :r2)
+      IDENTITY_MATRIX = [1, 0, 0, 1, 0, 0].freeze
+
+      def fill_gradient(*, **)
+        set_gradient(:fill, *, **)
+      end
+
+      def stroke_gradient(*, **)
+        set_gradient(:stroke, *, **)
+      end
+
+      private
+
+      def set_gradient(type, *, **)
+        gradient = parse_gradient_arguments(*, **)
+        name = "SP#{gradient_registry_key(gradient)}"
+        reference = (@gradient_registry ||= {})[name] ||= create_gradient_pattern(gradient)
+        Color::OPERATOR_BY_TYPE.fetch(type) { raise ArgumentError, "unknown type '#{type}'" }
+        write_pattern(type, {name:, reference:})
+      end
+
+      def parse_gradient_arguments(*arguments, from: nil, to: nil, r1: nil, r2: nil, stops: nil, apply_transformations: nil)
+        case arguments.length
+        when 0 then apply_transformations = true if apply_transformations.nil?
+        when 4 then from, to, *stops = arguments
+        when 6 then from, r1, to, r2, *stops = arguments
+        else raise ArgumentError, "Unknown type of gradient: #{arguments.inspect}"
+        end
+        raise ArgumentError, "At least two stops must be specified" if stops.length < 2
+
+        stops = stops.each_with_index.map do |stop, index|
+          if stop.is_a?(Array) || stop.is_a?(Hash)
+            position, color = stop
+          else
+            position = index / (Float(stops.length) - 1)
+            color = stop
+          end
+          raise ArgumentError, "position must be between 0 and 1" unless (0..1).cover?(position)
+
+          GradientStop.new(position, normalize_color(color))
+        end
+        raise ArgumentError, "The first stop must have a position of 0" if stops.first.position != 0
+        raise ArgumentError, "The last stop must have a position of 1" if stops.last.position != 1
+        color_types = stops.map { color_type(_1.color) }
+        color_types.uniq!
+        raise ArgumentError, "All colors must be of the same color space" if color_types.length > 1
+
+        Gradient.new(r1 ? :radial : :axial, apply_transformations, stops, from, to, r1, r2)
+      end
+
+      def gradient_registry_key(gradient)
+        _x1, _y1, x2, y2, transformation = gradient_coordinates(gradient)
+        key = [gradient.type.to_s, transformation, x2, y2, gradient.r1 || -1, gradient.r2 || -1, gradient.stops.length,
+          gradient.stops.map { |stop| [stop.position, stop.color] }].flatten
+        Digest::SHA1.hexdigest(key.join(","))
+      end
+
+      def create_gradient_pattern(gradient)
+        if gradient.apply_transformations.nil? && current_transformation_matrix_with_translation(0, 0) != IDENTITY_MATRIX
+          warn "Gradients in Prawn 2.x and lower are not correctly positioned when a transformation has been made to the " \
+            "document. Pass 'apply_transformations: true' to correctly transform the gradient, or see " \
+            "https://github.com/prawnpdf/prawn/wiki/Gradient-Transformations for more information."
+        end
+
+        functions = gradient.stops.each_cons(2).map do |first, second|
+          ref!(FunctionType: 2, Domain: [0.0, 1.0], C0: first.color, C1: second.color, N: 1.0)
+        end
+        function =
+          if functions.length == 1
+            functions.first
+          else
+            ref!(FunctionType: 3, Domain: [0.0, 1.0], Functions: functions, Bounds: gradient.stops[1..-2].map(&:position),
+              Encode: [0.0, 1.0] * functions.length)
+          end
+
+        x1, y1, x2, y2, transformation = gradient_coordinates(gradient)
+        coordinates = (gradient.type == :axial) ? [0, 0, x2 - x1, y2 - y1] : [0, 0, gradient.r1, x2 - x1, y2 - y1, gradient.r2]
+        shading = ref!(ShadingType: (gradient.type == :axial) ? 2 : 3, ColorSpace: color_space(gradient.stops.first.color),
+          Coords: coordinates, Function: function, Extend: [true, true])
+        ref!(PatternType: 2, Shading: shading, Matrix: transformation)
+      end
+
+      def gradient_coordinates(gradient)
+        x1, y1 = map_to_absolute(gradient.from)
+        x2, y2 = map_to_absolute(gradient.to)
+        transformation = gradient.apply_transformations ? current_transformation_matrix_with_translation(x1, y1) : [1, 0, 0, 1, x1, y1]
+        [x1, y1, x2, y2, transformation]
+      end
+    end
+  end
+end

data/lib/gamba/graphics/style.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Prawn
+  module Graphics
+    module Dash
+      def dash(length = nil, options = {})
+        return current_dash_state if length.nil?
+
+        length = Array(length)
+        raise ArgumentError, "Zero length dashes are invalid. Call #undash to disable dashes." if length.all?(&:zero?)
+        raise ArgumentError, "Negative numbers are not allowed for dash lengths." if length.any?(&:negative?)
+
+        length = length.first if length.length == 1
+        self.current_dash_state = {dash: length, space: length.is_a?(Array) ? nil : options[:space] || length, phase: options[:phase] || 0}
+        write_stroke_dash
+      end
+      alias_method :dash=, :dash
+
+      def undash
+        self.current_dash_state = PDF::Core::GraphicState::UNDASHED.dup
+        write_stroke_dash
+      end
+
+      def dashed?
+        current_dash_state != PDF::Core::GraphicState::UNDASHED
+      end
+
+      private
+
+      def write_stroke_dash
+        add_content(graphic_state.dash_setting)
+      end
+
+      def current_dash_state=(dash_options)
+        graphic_state.dash = dash_options
+      end
+
+      def current_dash_state
+        graphic_state.dash
+      end
+    end
+
+    module CapStyle
+      CAP_STYLES = {butt: 0, round: 1, projecting_square: 2}.freeze
+
+      def cap_style(style = nil)
+        return graphic_state.cap_style || :butt if style.nil?
+
+        graphic_state.cap_style = style
+        write_stroke_cap_style
+      end
+      alias_method :cap_style=, :cap_style
+
+      private
+
+      def write_stroke_cap_style
+        add_content("#{CAP_STYLES[graphic_state.cap_style]} J")
+      end
+    end
+
+    module JoinStyle
+      JOIN_STYLES = {miter: 0, round: 1, bevel: 2}.freeze
+
+      def join_style(style = nil)
+        return graphic_state.join_style || :miter if style.nil?
+
+        graphic_state.join_style = style
+        unless JOIN_STYLES.key?(style)
+          raise Errors::InvalidJoinStyle, "#{style} is not a recognized join style. Valid styles are #{JOIN_STYLES.keys.join(", ")}"
+        end
+
+        write_stroke_join_style
+      end
+      alias_method :join_style=, :join_style
+
+      private
+
+      def write_stroke_join_style
+        add_content("#{JOIN_STYLES[graphic_state.join_style]} j")
+      end
+    end
+
+    module Transparency
+      def transparent(opacity, stroke_opacity = opacity)
+        min_version(1.4)
+        opacity = opacity.clamp(0.0, 1.0)
+        stroke_opacity = stroke_opacity.clamp(0.0, 1.0)
+        @opacity_dictionary_registry ||= {}
+        ext_gstate = @opacity_dictionary_registry["#{opacity}_#{stroke_opacity}"] ||=
+          {name: "Tr#{@opacity_dictionary_registry.length + 1}", reference: ref!(Type: :ExtGState, CA: stroke_opacity, ca: opacity)}
+        ext_gstate_block(ext_gstate) { yield }
+      end
+    end
+
+    module BlendMode
+      def blend_mode(blend_mode = :Normal)
+        min_version(1.4)
+        ext_gstate = blend_mode_ext_gstate(blend_mode)
+        return ext_gstate_block(ext_gstate) { yield } if block_given?
+
+        write_ext_gstate(ext_gstate)
+        nil
+      end
+
+      private
+
+      def blend_mode_ext_gstate(blend_mode)
+        @blend_mode_dictionary_registry ||= {}
+        name = "BM#{Array(blend_mode).join}"
+        @blend_mode_dictionary_registry[name] ||= {name:, reference: ref!(Type: :ExtGState, BM: blend_mode)}
+      end
+    end
+
+    module Transformation
+      def rotate(angle, options = {}, &block)
+        Prawn.verify_options(:origin, options)
+        radians = degree_to_rad(angle)
+        cos = Math.cos(radians)
+        sin = Math.sin(radians)
+        return transformation_matrix(cos, sin, -sin, cos, 0, 0, &block) if options[:origin].nil?
+        raise Errors::BlockRequired unless block
+
+        x = options[:origin][0] + bounds.absolute_left
+        y = options[:origin][1] + bounds.absolute_bottom
+        translate(x - ((x * cos) - (y * sin)), y - ((x * sin) + (y * cos))) do
+          transformation_matrix(cos, sin, -sin, cos, 0, 0, &block)
+        end
+      end
+
+      def translate(x, y, &)
+        transformation_matrix(1, 0, 0, 1, x, y, &)
+      end
+
+      def scale(factor, options = {}, &block)
+        Prawn.verify_options(:origin, options)
+        return transformation_matrix(factor, 0, 0, factor, 0, 0, &block) if options[:origin].nil?
+        raise Errors::BlockRequired unless block
+
+        x = options[:origin][0] + bounds.absolute_left
+        y = options[:origin][1] + bounds.absolute_bottom
+        translate(x - (factor * x), y - (factor * y)) do
+          transformation_matrix(factor, 0, 0, factor, 0, 0, &block)
+        end
+      end
+
+      def transformation_matrix(*matrix)
+        raise ArgumentError, "Transformation matrix must have exacty 6 elements" if matrix.length != 6
+
+        save_graphics_state if block_given?
+        add_to_transformation_stack(*matrix)
+        add_content("#{PDF::Core.real_params(matrix)} cm")
+        return unless block_given?
+
+        yield
+        restore_graphics_state
+      end
+    end
+  end
+end