prawnx 0.1.1

data/lib/prawnx/graphics/color.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module PrawnX
+  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 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 stroke_color= stroke_color
+
+      module_function
+
+      def rgb2hex(rgb)
+        rgb.map { format("%02x", it) }.join
+      end
+
+      def hex2rgb(hex)
+        [hex[0..1], hex[2..3], hex[4..5]].map { it.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 { it / 100.0 }
+        end
+      end
+
+      def color_to_s(color)
+        return PDF.real_params(normalize_color(color)) unless color.is_a?(String)
+
+        PDF_OPERANDS_BY_HEX_COLOR.fetch(color) do
+          operands = PDF.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
+
+      def set_color(type, color, options = {})
+        operator = OPERATOR_BY_TYPE.fetch(type) { raise ArgumentError, "unknown type '#{type}'" }
+        if options[:pattern]
+          set_color_space(type, :Pattern)
+          add_content("/#{color} #{operator}")
+        else
+          set_color_space(type, color_space(color))
+          write_color(color_to_s(color), operator)
+        end
+      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/prawnx/graphics/patterns.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "digest/sha1"
+
+module PrawnX
+  module Graphics
+    # Axial and radial gradients, as shading patterns (ISO 32000-1 §8.7.4.5).
+    module Patterns
+      GradientStop = Struct.new(:position, :color)
+      Gradient = Struct.new(:type, :apply_transformations, :stops, :from, :to, :r1, :r2)
+      IDENTITY_MATRIX = [1, 0, 0, 1, 0, 0].freeze
+
+      def fill_gradient(*arguments, **options)
+        set_gradient(:fill, *arguments, **options)
+      end
+
+      def stroke_gradient(*arguments, **options)
+        set_gradient(:stroke, *arguments, **options)
+      end
+
+      private
+
+      def set_gradient(type, *arguments, **options)
+        gradient = parse_gradient_arguments(*arguments, **options)
+        patterns = page.resources[:Pattern] ||= {}
+        name = "SP#{gradient_registry_key(gradient)}"
+        patterns[name] ||= (@gradient_registry ||= {})[name] ||= create_gradient_pattern(gradient)
+        operator = Color::OPERATOR_BY_TYPE.fetch(type) { raise ArgumentError, "unknown type '#{type}'" }
+        set_color_space(type, :Pattern)
+        add_content("/#{name} #{operator}")
+      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
+        raise ArgumentError, "All colors must be of the same color space" if stops.map { color_type(it.color) }.uniq.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 { [it.position, it.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/prawnx/graphics/style.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PrawnX
+  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 dash= dash
+
+      def undash
+        self.current_dash_state = GraphicState::UNDASHED.dup
+        write_stroke_dash
+      end
+
+      def dashed?
+        current_dash_state != 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 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 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)
+        save_graphics_state
+        add_content("/#{opacity_dictionary_name(opacity, stroke_opacity)} gs")
+        yield
+        restore_graphics_state
+      end
+
+      private
+
+      def opacity_dictionary_name(opacity, stroke_opacity)
+        @opacity_dictionary_registry ||= {}
+        entry = @opacity_dictionary_registry["#{opacity}_#{stroke_opacity}"] ||=
+          {name: "Tr#{@opacity_dictionary_registry.length + 1}", reference: ref!(Type: :ExtGState, CA: stroke_opacity, ca: opacity)}
+        page.ext_gstates[entry[:name]] = entry[:reference]
+        entry[:name]
+      end
+    end
+
+    module BlendMode
+      def blend_mode(blend_mode = :Normal)
+        min_version(1.4)
+        save_graphics_state if block_given?
+        add_content("/#{blend_mode_dictionary_name(blend_mode)} gs")
+        return unless block_given?
+
+        yield
+        restore_graphics_state
+      end
+
+      private
+
+      def blend_mode_dictionary_name(blend_mode)
+        @blend_mode_dictionary_registry ||= {}
+        name = "BM#{Array(blend_mode).join}"
+        page.ext_gstates[name] = @blend_mode_dictionary_registry[name] ||= ref!(Type: :ExtGState, BM: blend_mode)
+        name
+      end
+    end
+
+    module Transformation
+      def rotate(angle, options = {}, &block)
+        PrawnX.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)
+        PrawnX.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.real_params(matrix)} cm")
+        return unless block_given?
+
+        yield
+        restore_graphics_state
+      end
+    end
+  end
+end

data/lib/prawnx/graphics.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module PrawnX
+  module Graphics
+    include BlendMode
+    include Color
+    include Dash
+    include CapStyle
+    include JoinStyle
+    include Transparency
+    include Transformation
+    include Patterns
+
+    # Distance of a cubic Bézier control point approximating a quarter circle of radius 1.
+    KAPPA = 4.0 * ((Math.sqrt(2) - 1.0) / 3.0)
+
+    def move_to(*point)
+      add_content("#{PDF.real_params(map_to_absolute(point))} m")
+    end
+
+    def line_to(*point)
+      add_content("#{PDF.real_params(map_to_absolute(point))} l")
+    end
+
+    def curve_to(destination, options = {})
+      options[:bounds] || raise(Errors::InvalidGraphicsPath, "Bounding points for bezier curve must be specified as :bounds => [[x1,y1],[x2,y2]]")
+
+      add_content("#{PDF.real_params((options[:bounds] << destination).flat_map { map_to_absolute(it) })} c")
+    end
+
+    def rectangle(point, width, height)
+      x, y = map_to_absolute(point)
+      add_content("#{PDF.real_params([x, y - height, width, height])} re")
+    end
+
+    def rounded_rectangle(point, width, height, radius)
+      x, y = point
+      rounded_polygon(radius, point, [x + width, y], [x + width, y - height], [x, y - height])
+    end
+
+    def line_width=(width)
+      graphic_state.line_width = width
+      write_line_width
+    end
+
+    def line_width(width = nil)
+      return graphic_state.line_width unless width
+
+      self.line_width = width
+    end
+
+    def line(*points)
+      x0, y0, x1, y1 = points.flatten
+      move_to(x0, y0)
+      line_to(x1, y1)
+    end
+
+    def horizontal_line(x1, x2, options = {})
+      y1 = options[:at] || (y - bounds.absolute_bottom)
+      line(x1, y1, x2, y1)
+    end
+
+    def horizontal_rule
+      horizontal_line(bounds.left, bounds.right)
+    end
+
+    def vertical_line(y1, y2, params)
+      line(params[:at], y1, params[:at], y2)
+    end
+
+    def curve(origin, destination, options = {})
+      move_to(*origin)
+      curve_to(destination, options)
+    end
+
+    def circle(center, radius)
+      ellipse(center, radius, radius)
+    end
+
+    def ellipse(point, radius1, radius2 = radius1)
+      x, y = point
+      l1 = radius1 * KAPPA
+      l2 = radius2 * KAPPA
+      move_to(x + radius1, y)
+      curve_to([x, y + radius2], bounds: [[x + radius1, y + l2], [x + l1, y + radius2]])
+      curve_to([x - radius1, y], bounds: [[x - l1, y + radius2], [x - radius1, y + l2]])
+      curve_to([x, y - radius2], bounds: [[x - radius1, y - l2], [x - l1, y - radius2]])
+      curve_to([x + radius1, y], bounds: [[x + l1, y - radius2], [x + radius1, y - l2]])
+      move_to(x, y)
+    end
+
+    def polygon(*points)
+      move_to(points[0])
+      (points[1..] << points[0]).each { line_to(*it) }
+      add_content("h")
+    end
+
+    def rounded_polygon(radius, *points)
+      move_to(point_on_line(radius, points[1], points[0]))
+      sides = points.size
+      points << points[0] << points[1]
+      sides.times { rounded_vertex(radius, points[it], points[it + 1], points[it + 2]) }
+      add_content("h")
+    end
+
+    def rounded_vertex(radius, *points)
+      radial_point1 = point_on_line(radius, points[0], points[1])
+      bezier_point1 = point_on_line(radius - (radius * KAPPA), points[0], points[1])
+      radial_point2 = point_on_line(radius, points[2], points[1])
+      bezier_point2 = point_on_line(radius - (radius * KAPPA), points[2], points[1])
+      line_to(radial_point1)
+      curve_to(radial_point2, bounds: [bezier_point1, bezier_point2])
+    end
+
+    def stroke
+      yield if block_given?
+      add_content("S")
+    end
+
+    def close_and_stroke
+      yield if block_given?
+      add_content("s")
+    end
+
+    def stroke_bounds
+      stroke_rectangle(bounds.top_left, bounds.width, bounds.height)
+    end
+
+    def stroke_axis(options = {})
+      origin = options[:at] || [0, 0]
+      options = {
+        at: [0, 0], height: bounds.height - origin[1], width: bounds.width - origin[0],
+        step_length: 100, negative_axes_length: 20, color: "000000",
+      }.merge(options)
+      PrawnX.verify_options(%i[at width height step_length negative_axes_length color], options)
+      x, y = options[:at]
+
+      save_graphics_state do
+        fill_color(options[:color])
+        stroke_color(options[:color])
+        dash(1, space: 4)
+        stroke_horizontal_line(x - options[:negative_axes_length], x + options[:width], at: y)
+        stroke_vertical_line(y - options[:negative_axes_length], y + options[:height], at: x)
+        undash
+        fill_circle(options[:at], 1)
+        (options[:step_length]..options[:width]).step(options[:step_length]) do |point|
+          fill_circle([x + point, y], 1)
+          draw_text(point, at: [x + point - 5, y - 10], size: 7)
+        end
+        (options[:step_length]..options[:height]).step(options[:step_length]) do |point|
+          fill_circle([x, y + point], 1)
+          draw_text(point, at: [x - 17, y + point - 2], size: 7)
+        end
+      end
+    end
+
+    def fill(options = {})
+      yield if block_given?
+      add_content(options[:fill_rule] == :even_odd ? "f*" : "f")
+    end
+
+    def fill_and_stroke(options = {})
+      yield if block_given?
+      add_content(options[:fill_rule] == :even_odd ? "b*" : "b")
+    end
+
+    def close_path
+      add_content("h")
+    end
+
+    SHAPES = %i[
+      line_to curve_to rectangle rounded_rectangle line horizontal_line horizontal_rule vertical_line curve circle_at circle
+      ellipse_at ellipse polygon rounded_polygon rounded_vertex
+    ].freeze
+
+    %i[fill stroke fill_and_stroke].product(SHAPES).each do |operation, shape|
+      define_method(:"#{operation}_#{shape}") do |*arguments|
+        public_send(operation) { public_send(shape, *arguments) }
+      end
+    end
+
+    private
+
+    def write_line_width
+      add_content("#{graphic_state.line_width} w")
+    end
+
+    def map_to_absolute(*point)
+      x, y = point.flatten
+      [@bounding_box.absolute_left + x, @bounding_box.absolute_bottom + y]
+    end
+
+    def map_to_absolute!(point)
+      point.replace(map_to_absolute(point))
+    end
+
+    def degree_to_rad(angle)
+      angle * Math::PI / 180
+    end
+
+    def point_on_line(distance_from_end, *points)
+      x0, y0, x1, y1 = points.flatten
+      length = Math.sqrt(((x1 - x0)**2) + ((y1 - y0)**2))
+      ratio = (length - distance_from_end) / length
+      [x0 + (ratio * (x1 - x0)), y0 + (ratio * (y1 - y0))]
+    end
+  end
+end