pdfrb 0.1.0

data/lib/pdfrb/content/canvas.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # High-level drawing API on a Stream (page /Contents or Form
+    # XObject). The Canvas emits operators via the +Serializer+ and
+    # appends the bytes to the Stream's raw payload.
+    #
+    # Methods mirror HexaPDF::Content::Canvas where the names are
+    # intuitive; PDF-specific concepts (q/Q, marked content) are
+    # exposed via Ruby-block syntax.
+    class Canvas
+      attr_reader :stream, :document, :serializer
+
+      def initialize(stream, document: nil)
+        @stream = stream
+        @document = document || stream.document
+        @serializer = Pdfrb::Serializer.new
+        ensure_stream_payload
+      end
+
+      # ---- State stack ----
+
+      def save_graphics_state(&block)
+        emit_op Pdfrb::Content::Operator::SaveGraphicsState
+        if block_given?
+          begin
+            yield self
+          ensure
+            emit_op Pdfrb::Content::Operator::RestoreGraphicsState
+          end
+        end
+        self
+      end
+      alias with_graphics_state save_graphics_state
+
+      # ---- Transforms ----
+
+      def translate(tx, ty, &block)
+        concat(1, 0, 0, 1, tx, ty, &block)
+      end
+
+      def scale(sx, sy = sx, &block)
+        concat(sx, 0, 0, sy, 0, 0, &block)
+      end
+
+      def rotate(angle_in_radians, &block)
+        c = Math.cos(angle_in_radians)
+        s = Math.sin(angle_in_radians)
+        concat(c, s, -s, c, 0, 0, &block)
+      end
+
+      def concat(a, b, c, d, e, f, &block)
+        emit_op Pdfrb::Content::Operator::ConcatMatrix, a, b, c, d, e, f
+        return self unless block_given?
+
+        begin
+          yield self
+        ensure
+          # Reverse by save/restore so the caller's matrix is unchanged.
+          emit_op Pdfrb::Content::Operator::SaveGraphicsState
+        end
+        self
+      end
+
+      # ---- Path construction ----
+
+      def move_to(x, y)
+        emit_op Pdfrb::Content::Operator::MoveTo, x, y
+        self
+      end
+
+      def line_to(x, y)
+        emit_op Pdfrb::Content::Operator::LineTo, x, y
+        self
+      end
+
+      def line(x1, y1, x2, y2)
+        move_to(x1, y1).line_to(x2, y2)
+      end
+
+      def curve_to(c1x, c1y, c2x, c2y, x, y)
+        emit_op Pdfrb::Content::Operator::CurveTo, c1x, c1y, c2x, c2y, x, y
+        self
+      end
+
+      def rectangle(x, y, width, height)
+        emit_op Pdfrb::Content::Operator::Rectangle, x, y, width, height
+        self
+      end
+
+      def close_path
+        emit_op Pdfrb::Content::Operator::ClosePath
+        self
+      end
+
+      # ---- Painting ----
+
+      def stroke
+        emit_op Pdfrb::Content::Operator::Stroke
+        self
+      end
+
+      def fill(rule: :nonzero)
+        op = rule == :even_odd ?
+               Pdfrb::Content::Operator::FillEvenOdd :
+               Pdfrb::Content::Operator::FillNonZero
+        emit_op op
+        self
+      end
+
+      def fill_stroke(rule: :nonzero)
+        op = rule == :even_odd ?
+               Pdfrb::Content::Operator::FillStrokeEvenOdd :
+               Pdfrb::Content::Operator::FillStrokeNonZero
+        emit_op op
+        self
+      end
+
+      def end_path
+        emit_op Pdfrb::Content::Operator::EndPath
+        self
+      end
+
+      # ---- Color ----
+
+      def fill_color(color)
+        case color
+        in [Symbol | String => family, *rest]
+          emit_color_op(true, family.to_sym, rest)
+        else
+          emit_color_op(true, :gray, [color])
+        end
+        self
+      end
+
+      def stroke_color(color)
+        case color
+        in [Symbol | String => family, *rest]
+          emit_color_op(false, family.to_sym, rest)
+        else
+          emit_color_op(false, :gray, [color])
+        end
+        self
+      end
+
+      # ---- Text ----
+
+      # Show +text+ at (+x+, +y+) in the named font. Caller is
+      # responsible for registering the font in the page resources
+      # under +font_name+ before this call.
+      def text(str, at:, font:, size:, char_spacing: nil, word_spacing: nil)
+        emit_op Pdfrb::Content::Operator::BeginText
+        emit_op Pdfrb::Content::Operator::SetTextMatrix,
+                1, 0, 0, 1, at[0], at[1]
+        emit_op Pdfrb::Content::Operator::Font, font, size
+        emit_op Pdfrb::Content::Operator::CharSpacing, char_spacing if char_spacing
+        emit_op Pdfrb::Content::Operator::WordSpacing, word_spacing if word_spacing
+        emit_op Pdfrb::Content::Operator::ShowText, str.to_s
+        emit_op Pdfrb::Content::Operator::EndText
+        self
+      end
+
+      # ---- Graphics-state params ----
+
+      def line_width=(n)
+        emit_op Pdfrb::Content::Operator::LineWidth, n
+      end
+
+      def line_cap=(n)
+        emit_op Pdfrb::Content::Operator::LineCap, n
+      end
+
+      def line_join=(n)
+        emit_op Pdfrb::Content::Operator::LineJoin, n
+      end
+
+      def miter_limit=(n)
+        emit_op Pdfrb::Content::Operator::MiterLimit, n
+      end
+
+      def dash_pattern=(spec)
+        if spec.is_a?(::Array)
+          array, phase = spec
+        else
+          array, phase = spec, 0
+        end
+        emit_op Pdfrb::Content::Operator::DashPattern, array, phase
+      end
+
+      # ---- Marked content ----
+
+      def marked_content(tag, properties = nil, &block)
+        if properties
+          emit_op Pdfrb::Content::Operator::BeginMarkedContentWithProperties, tag, properties
+        else
+          emit_op Pdfrb::Content::Operator::BeginMarkedContent, tag
+        end
+        return self unless block_given?
+
+        begin
+          yield self
+        ensure
+          emit_op Pdfrb::Content::Operator::EndMarkedContent
+        end
+        self
+      end
+
+      # ---- Internal ----
+
+      def emit_op(op_class, *operands)
+        bytes = op_class.serialize(@serializer, *operands)
+        append(bytes)
+      end
+
+      private
+
+      def ensure_stream_payload
+        return if @stream.stream.is_a?(::String)
+
+        @stream.stream = ""
+      end
+
+      def append(bytes)
+        new_payload = (@stream.stream || +"") + bytes.to_s
+        @stream.stream = new_payload
+      end
+
+      def emit_color_op(fill, family, rest)
+        klass = color_op_class(family, fill)
+        emit_op(klass, *rest)
+      end
+
+      def color_op_class(family, fill)
+        case [family, fill]
+        in [:gray, true] then Pdfrb::Content::Operator::FillGray
+        in [:gray, false] then Pdfrb::Content::Operator::StrokeGray
+        in [:rgb, true] then Pdfrb::Content::Operator::FillRGB
+        in [:rgb, false] then Pdfrb::Content::Operator::StrokeRGB
+        in [:cmyk, true] then Pdfrb::Content::Operator::FillCMYK
+        in [:cmyk, false] then Pdfrb::Content::Operator::StrokeCMYK
+        else
+          raise ArgumentError, "unknown color family #{family.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/graphic_object/arc.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module GraphicObject
+      # Circular or elliptical arc, approximated with cubic Beziers
+      # (s8.3.8.3 in PDF reference). One segment per 90 degrees.
+      class Arc
+        KAPPA = 0.5522847498.freeze
+        private_constant :KAPPA
+
+        attr_reader :cx, :cy, :radius_x, :radius_y,
+                    :start_angle, :end_angle
+
+        def initialize(cx:, cy:, radius:, radius_y: nil,
+                       start_angle: 0, end_angle: 360)
+          @cx = cx.to_f
+          @cy = cy.to_f
+          @radius_x = radius.to_f
+          @radius_y = (radius_y || radius).to_f
+          @start_angle = start_angle.to_f
+          @end_angle = end_angle.to_f
+        end
+
+        # Emit the path operators onto +canvas+ starting with a moveto.
+        def draw(canvas)
+          steps = tessellate
+          return if steps.empty?
+
+          first = steps.first
+          canvas.move_to(first[:p0][0], first[:p0][1])
+          steps.each do |seg|
+            canvas.curve_to(seg[:c1][0], seg[:c1][1],
+                            seg[:c2][0], seg[:c2][1],
+                            seg[:p3][0], seg[:p3][1])
+          end
+          canvas
+        end
+
+        private
+
+        # One Bezier per 90 degrees (the canonical approximation).
+        def tessellate
+          segments = []
+          return segments if @radius_x.zero? || @radius_y.zero?
+
+          angle = @start_angle
+          step = 90.0
+          while angle < @end_angle
+            seg_end = [angle + step, @end_angle].min
+            segments << bezier_segment(angle, seg_end)
+            angle = seg_end
+            break if angle >= @end_angle
+          end
+          segments
+        end
+
+        def bezier_segment(a0, a1)
+          r0 = a0 * Math::PI / 180
+          r1 = a1 * Math::PI / 180
+          {
+            p0: point_at(r0),
+            c1: control_at(r0, r1, true),
+            c2: control_at(r1, r0, false),
+            p3: point_at(r1)
+          }
+        end
+
+        def point_at(rad)
+          [@cx + @radius_x * Math.cos(rad), @cy + @radius_y * Math.sin(rad)]
+        end
+
+        def control_at(from, to, forward)
+          # Tangent direction at +from+; scale by KAPPA * (angle delta).
+          delta = (to - from).abs
+          k = KAPPA * (delta / 90.0)
+          dx = -@radius_x * Math.sin(from) * k
+          dy =  @radius_y * Math.cos(from) * k
+          pt = point_at(from)
+          forward ? [pt[0] + dx, pt[1] + dy] : [pt[0] - dx, pt[1] - dy]
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/graphic_object/curve.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module GraphicObject
+      # Cubic Bezier curve through one start point, two control
+      # points, and one end point. Convenience wrapper around
+      # +canvas.curve_to+ for users that prefer object form.
+      class Curve
+        attr_reader :start, :c1, :c2, :endpoint
+
+        def initialize(start:, c1:, c2:, endpoint:)
+          @start = [start[0].to_f, start[1].to_f]
+          @c1 = [c1[0].to_f, c1[1].to_f]
+          @c2 = [c2[0].to_f, c2[1].to_f]
+          @endpoint = [endpoint[0].to_f, endpoint[1].to_f]
+        end
+
+        def draw(canvas)
+          canvas.move_to(@start[0], @start[1])
+          canvas.curve_to(@c1[0], @c1[1], @c2[0], @c2[1],
+                          @endpoint[0], @endpoint[1])
+          canvas
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/graphic_object/polyline.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module GraphicObject
+      # Open polyline through a list of points.
+      class Polyline
+        attr_reader :points, :closed
+
+        def initialize(points, closed: false)
+          @points = points.map { |p| [p[0].to_f, p[1].to_f] }
+          @closed = closed
+        end
+
+        def draw(canvas)
+          return canvas if @points.empty?
+
+          first = @points.first
+          canvas.move_to(first[0], first[1])
+          @points.drop(1).each { |x, y| canvas.line_to(x, y) }
+          canvas.close_path if @closed
+          canvas
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/graphic_object/rectangle.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module GraphicObject
+      # Rectangle with optional rounded corners, drawn as four Bezier
+      # curves when radii are non-zero.
+      class Rectangle
+        KAPPA = 0.5522847498.freeze
+        private_constant :KAPPA
+
+        attr_reader :x, :y, :width, :height, :radius
+
+        def initialize(x:, y:, width:, height:, radius: 0)
+          @x = x.to_f
+          @y = y.to_f
+          @width = width.to_f
+          @height = height.to_f
+          @radius = radius.to_f
+        end
+
+        def draw(canvas)
+          if @radius.zero?
+            canvas.rectangle(@x, @y, @width, @height)
+          else
+            draw_rounded(canvas)
+          end
+          canvas
+        end
+
+        private
+
+        def draw_rounded(canvas)
+          r = @radius
+          rx2 = @x + @width
+          ry2 = @y + @height
+          rx = @x
+          ry = @y
+          k = r * KAPPA
+          canvas.move_to(rx + r, ry)
+          canvas.line_to(rx2 - r, ry)
+          canvas.curve_to(rx2 - k, ry, rx2, ry + r - k, rx2, ry + r)
+          canvas.line_to(rx2, ry2 - r)
+          canvas.curve_to(rx2, ry2 - r + k, rx2 - r + k, ry2, rx2 - r, ry2)
+          canvas.line_to(rx + r, ry2)
+          canvas.curve_to(rx + r - k, ry2, rx, ry2 - r + k, rx, ry2 - r)
+          canvas.line_to(rx, ry + r)
+          canvas.curve_to(rx, ry + r - k, rx + r - k, ry, rx + r, ry)
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/graphic_object.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # High-level shape primitives. Each is a small value object with
+    # a +draw(canvas)+ method that emits the right path operators.
+    # Adding a new shape = adding one class + (optionally) registering
+    # it for the Canvas DSL.
+    module GraphicObject
+      autoload :Arc, "pdfrb/content/graphic_object/arc"
+      autoload :Polyline, "pdfrb/content/graphic_object/polyline"
+      autoload :Rectangle, "pdfrb/content/graphic_object/rectangle"
+      autoload :Curve, "pdfrb/content/graphic_object/curve"
+    end
+  end
+end

data/lib/pdfrb/content/graphics_state.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Immutable snapshot of the PDF graphics state (s8.4). The
+    # +Processor+ holds a stack of these for `q` (push) / `Q` (pop).
+    # Subclasses (TextState for the text sub-state) compose rather
+    # than inherit.
+    class GraphicsState
+      attr_reader :ctm, :text_state, :fill_color, :stroke_color,
+                  :line_width, :line_cap, :line_join, :miter_limit,
+                  :dash_pattern, :flatness, :alpha_is_shape,
+                  :stroke_alpha, :fill_alpha, :blend_mode, :soft_mask,
+                  :overprint, :overprint_mode
+
+      def initialize(ctm: Pdfrb::Model::Matrix.identity,
+                     text_state: TextState.new,
+                     fill_color: nil, stroke_color: nil,
+                     line_width: 1.0, line_cap: 0, line_join: 0,
+                     miter_limit: 10.0, dash_pattern: [].freeze,
+                     flatness: 0, alpha_is_shape: false,
+                     stroke_alpha: 1.0, fill_alpha: 1.0,
+                     blend_mode: :Normal, soft_mask: nil,
+                     overprint: false, overprint_mode: 0)
+        @ctm = ctm
+        @text_state = text_state
+        @fill_color = fill_color
+        @stroke_color = stroke_color
+        @line_width = line_width.to_f
+        @line_cap = line_cap.to_i
+        @line_join = line_join.to_i
+        @miter_limit = miter_limit.to_f
+        @dash_pattern = dash_pattern
+        @flatness = flatness.to_i
+        @alpha_is_shape = alpha_is_shape
+        @stroke_alpha = stroke_alpha.to_f
+        @fill_alpha = fill_alpha.to_f
+        @blend_mode = blend_mode
+        @soft_mask = soft_mask
+        @overprint = overprint
+        @overprint_mode = overprint_mode.to_i
+      end
+
+      # Returns a new GraphicsState with the given overrides (the
+      # original is frozen).
+      def with(**overrides)
+        GraphicsState.new(**to_h.merge(overrides))
+      end
+
+      def to_h
+        {
+          ctm: @ctm, text_state: @text_state,
+          fill_color: @fill_color, stroke_color: @stroke_color,
+          line_width: @line_width, line_cap: @line_cap,
+          line_join: @line_join, miter_limit: @miter_limit,
+          dash_pattern: @dash_pattern, flatness: @flatness,
+          alpha_is_shape: @alpha_is_shape, stroke_alpha: @stroke_alpha,
+          fill_alpha: @fill_alpha, blend_mode: @blend_mode,
+          soft_mask: @soft_mask, overprint: @overprint,
+          overprint_mode: @overprint_mode
+        }
+      end
+
+      # Text-specific sub-state (s9.3). Composed in GraphicsState.
+      class TextState
+        attr_reader :char_spacing, :word_spacing, :horizontal_scaling,
+                    :leading, :font_name, :font_size,
+                    :rendering_mode, :rise, :text_matrix, :line_matrix
+
+        def initialize(char_spacing: 0.0, word_spacing: 0.0,
+                       horizontal_scaling: 100.0, leading: 0.0,
+                       font_name: nil, font_size: 0.0,
+                       rendering_mode: 0, rise: 0.0,
+                       text_matrix: Pdfrb::Model::Matrix.identity,
+                       line_matrix: Pdfrb::Model::Matrix.identity)
+          @char_spacing = char_spacing.to_f
+          @word_spacing = word_spacing.to_f
+          @horizontal_scaling = horizontal_scaling.to_f
+          @leading = leading.to_f
+          @font_name = font_name
+          @font_size = font_size.to_f
+          @rendering_mode = rendering_mode.to_i
+          @rise = rise.to_f
+          @text_matrix = text_matrix
+          @line_matrix = line_matrix
+        end
+
+        def with(**overrides)
+          TextState.new(**to_h.merge(overrides))
+        end
+
+        def to_h
+          {
+            char_spacing: @char_spacing, word_spacing: @word_spacing,
+            horizontal_scaling: @horizontal_scaling, leading: @leading,
+            font_name: @font_name, font_size: @font_size,
+            rendering_mode: @rendering_mode, rise: @rise,
+            text_matrix: @text_matrix, line_matrix: @line_matrix
+          }
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/operator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Operator catalogue. Each PDF content operator (`q`, `m`, `Tj`,
+    # ...) is implemented by a subclass of +Operator::Base+ that
+    # registers itself in +REGISTRY+ at file load.
+    #
+    # Adding a new operator = adding one subclass + `register`. No
+    # switch edits (open/closed). Mirrors the postscript gem's
+    # Model::Operators pattern.
+    module Operator
+      @registry = {}
+
+      class << self
+        attr_reader :registry
+
+        def register(name, klass)
+          @registry[name.to_s] = klass
+        end
+
+        def [](name)
+          @registry[name.to_s]
+        end
+
+        def names
+          @registry.keys
+        end
+      end
+
+      # Base class. Subclasses override +name+ and optionally
+      # +invoke+ (read-side effect on the Processor) and +serialize+
+      # (write-side emit).
+      class Base
+        class << self
+          def name
+            raise NotImplementedError, "#{self} must define self.name"
+          end
+
+          def register
+            Operator.register(self.name, self)
+          end
+
+          # Default serialize: join operands with spaces and append
+          # the operator keyword.
+          def serialize(serializer, *operands)
+            prefix = operands.empty? ? +"#{name}\n" : +""
+            unless operands.empty?
+              prefix << operands.map { |o| serializer.serialize(o) }.join(" ")
+              prefix << " #{name}\n"
+            end
+            prefix
+          end
+
+          # Read-side: default no-op. Subclasses override to mutate
+          # processor.graphics_state (or do painting / text / etc.).
+          def invoke(_processor, *_operands); end
+        end
+      end
+
+      # Convenience subclass for operators that take no operands and
+      # have a fixed serialization.
+      class NoArg < Base
+        class << self
+          def serialize(_serializer, *_operands)
+            "#{name}\n"
+          end
+        end
+      end
+    end
+  end
+end