pdfrb 0.2.1 → 0.6.0

data/lib/pdfrb/content/hidden_text_detector.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Pdfrb
+  module Content
+    # Detects hidden / transparent text in content streams. Hidden text
+    # is text rendered with Tr=3 (invisible) or with alpha=0 (fully
+    # transparent). PDF/A and PDF/UA require such text to be tagged as
+    # /Artifact or wrapped in a structure element.
+    #
+    # Inspired by mn2pdf's PDFHiddenTextStripper. Walks content streams
+    # via the Content::Parser, tracking graphics state changes.
+    class HiddenTextDetector
+      HiddenItem = Struct.new(:text, :reason, :page, keyword_init: true) do
+        def hidden?
+          !reason.nil?
+        end
+      end
+
+      attr_reader :document
+
+      def initialize(document)
+        @document = document
+      end
+
+      # Walk all content streams. Returns HiddenItem objects for each
+      # text-showing operation. Items with a nil reason are visible.
+      def detect
+        items = []
+        @document.each_indirect_object do |obj|
+          next unless content_stream?(obj)
+
+          page = find_page(obj)
+          detect_in_stream(obj, page) { |item| items << item }
+        end
+        items
+      end
+
+      # Returns only the hidden text items (rendering_mode_3 or alpha=0).
+      def hidden_only
+        detect.select(&:hidden?)
+      end
+
+      private
+
+      def content_stream?(obj)
+        return false unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+        return true if obj.value[:Type] == :Page
+
+        subtype = obj.value[:Subtype]
+        return false if subtype == :Image
+
+        true
+      end
+
+      def find_page(stream_obj)
+        @document.each_indirect_object do |obj|
+          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+          next unless obj[:Type] == :Page
+
+          contents = obj[:Contents]
+          next unless contents
+
+          list = if contents.is_a?(Pdfrb::Model::PdfArray)
+                   contents.value
+                 else
+                   contents.is_a?(::Array) ? contents : [contents]
+                 end
+
+          return obj if list.any? do |c|
+            c_obj = c.is_a?(Pdfrb::Model::Reference) ? @document.object(c) : c
+            c_obj == stream_obj
+          end
+        end
+        nil
+      end
+
+      def detect_in_stream(stream_obj, page, &)
+        bytes = stream_obj.stream
+        return unless bytes && !bytes.empty?
+
+        io = StringIO.new(bytes.b)
+        tokenizer = Pdfrb::Source::Tokenizer.new(io)
+        parser = Content::Parser.new(tokenizer)
+        collector = Collector.new(page)
+
+        parser.each_invocation do |op_class, operands|
+          op_name = op_class.name
+          case op_name
+          when "Tr"
+            collector.text_rendering_mode = operands.first.to_i if operands.first
+          when "ca"
+            collector.stroke_alpha = operands.first.to_f if operands.first
+          when "CA"
+            collector.non_stroke_alpha = operands.first.to_f if operands.first
+          when "Tj"
+            collector.show_text(operands.first)
+          when "TJ"
+            collector.show_text_array(operands.first)
+          when "'", "\""
+            collector.move_to_next_line
+            collector.show_text(operands.first) if operands.first
+          end
+        end
+
+        collector.items.each(&)
+      rescue StandardError
+        nil
+      end
+
+      # Internal: collects text-show operations with their visibility state.
+      class Collector
+        attr_reader :items
+
+        def initialize(page)
+          @items = []
+          @page = page
+          @text_rendering_mode = 0
+          @non_stroke_alpha = 1.0
+          @stroke_alpha = 1.0
+        end
+
+        def text_rendering_mode=(value)
+          @text_rendering_mode = value
+        end
+
+        def non_stroke_alpha=(value)
+          @non_stroke_alpha = value
+        end
+
+        def stroke_alpha=(value)
+          @stroke_alpha = value
+        end
+
+        def show_text(text)
+          return if text.nil?
+
+          reason = current_reason
+          @items << HiddenItem.new(text: text.to_s, reason: reason, page: @page)
+        end
+
+        def show_text_array(items)
+          return unless items.is_a?(::Array)
+
+          items.each do |item|
+            if item.is_a?(::String)
+              show_text(item)
+            end
+            # Numeric items are positioning values; ignore them
+          end
+        end
+
+        def move_to_next_line; end
+
+        private
+
+        def current_reason
+          return :rendering_mode_invisible if @text_rendering_mode == 3
+          return :alpha_zero_hidden if @non_stroke_alpha.to_f == 0.0 || @stroke_alpha.to_f == 0.0
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/operator.rb

@@ -20,12 +20,32 @@ module Pdfrb
         end
 
         def [](name)
-          @registry[name.to_s]
+          key = name.to_s
+          result = @registry[key]
+          return result if result
+
+          # Lazy-load on miss: trigger eager_load! which populates
+          # the registry, then retry.
+          eager_load! unless @eager_loaded
+          @registry[key]
         end
 
         def names
           @registry.keys
         end
+
+        # Force-load all operator implementations so register calls
+        # fire and populate the registry. Idempotent.
+        def eager_load!
+          return if @eager_loaded
+
+          Pdfrb::Content::Operators.constants.each do |c|
+            Pdfrb::Content::Operators.const_get(c)
+          rescue NameError
+            # Skip modules that don't resolve.
+          end
+          @eager_loaded = true
+        end
       end
 
       # Base class. Subclasses override +name+ and optionally

data/lib/pdfrb/content/operators/clipping.rb

@@ -0,0 +1,36 @@
+# frozen_string literal: true
+
+module Pdfrb
+  module Content
+    module Operator
+      # Clipping path operators (s8.5.4). W and W* modify the current
+      # clipping path by intersecting it with the current path. The
+      # clipping path takes effect when the next painting operator or
+      # `n` (end path) is executed.
+
+      # `W` — modify clipping path using nonzero winding rule.
+      class ClipNonZero < NoArg
+        def self.name; "W"; end
+        register
+      end
+
+      # `W*` — modify clipping path using even-odd rule.
+      class ClipEvenOdd < NoArg
+        def self.name; "W*"; end
+        register
+      end
+
+      # `Do` — invoke an XObject (Image or Form) by resource name.
+      class InvokeXObject < Base
+        class << self
+          def name; "Do"; end
+
+          def serialize(_serializer, name)
+            "/#{name} Do\n"
+          end
+        end
+        register
+      end
+    end
+  end
+end

data/lib/pdfrb/content/operators/graphics_state_params.rb

@@ -73,6 +73,21 @@ module Pdfrb
         end
         register
       end
+      class NonStrokeAlpha < Base
+        def self.name; "ca"; end
+        def self.invoke(processor, alpha)
+          processor.update_graphics_state(non_stroke_alpha: alpha.to_f)
+        end
+        register
+      end
+
+      class StrokeAlpha < Base
+        def self.name; "CA"; end
+        def self.invoke(processor, alpha)
+          processor.update_graphics_state(stroke_alpha: alpha.to_f)
+        end
+        register
+      end
     end
   end
 end

data/lib/pdfrb/content/operators.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Operator implementation files. Each file defines one or more
+    # Operator::Base subclasses that register themselves on load.
+    # Eager loading is triggered by Operator.eager_load!.
+    module Operators
+      autoload :General, "pdfrb/content/operators/general"
+      autoload :Path, "pdfrb/content/operators/path"
+      autoload :Painting, "pdfrb/content/operators/painting"
+      autoload :TextState, "pdfrb/content/operators/text_state"
+      autoload :TextPositioning, "pdfrb/content/operators/text_positioning"
+      autoload :TextShowing, "pdfrb/content/operators/text_showing"
+      autoload :Color, "pdfrb/content/operators/color"
+      autoload :GraphicsStateParams, "pdfrb/content/operators/graphics_state_params"
+      autoload :MarkedContent, "pdfrb/content/operators/marked_content"
+      autoload :Clipping, "pdfrb/content/operators/clipping"
+    end
+  end
+end

data/lib/pdfrb/content/shading/base.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module Shading
+      # Base shading builder. Subclasses set +shading_type+ and
+      # +shading_fields+. Creates a shading dict and registers it
+      # in the page's /Resources /Shading sub-dict.
+      class Base
+        attr_reader :color_space
+
+        class << self
+          def shading_type
+            raise NotImplementedError
+          end
+        end
+
+        def initialize(color_space: :DeviceGray)
+          @color_space = color_space
+        end
+
+        # Build the shading dictionary value (a Hash).
+        def to_dict
+          { ShadingType: self.class.shading_type,
+            ColorSpace: @color_space }.merge!(shading_fields)
+        end
+
+        # Register this shading on a page and return the resource name.
+        # @param document [Pdfrb::Document]
+        # @param page [Pdfrb::Model::Cos::Dictionary] target page.
+        # @return [Symbol] resource name (e.g. :Sh1)
+        def register_on(document, page)
+          shading_obj = document.add(to_dict, type: Pdfrb::Model::Cos::Dictionary)
+          ref = Pdfrb::Model::Reference.new(shading_obj.oid, shading_obj.gen)
+          resources = ensure_resources(document, page)
+          shading_dict = resources.value[:Shading]
+          if shading_dict.nil?
+            shading_dict = {}
+            resources.value[:Shading] = shading_dict
+          end
+          name = next_shading_name(shading_dict)
+          shading_dict[name] = ref
+          name
+        end
+
+        protected
+
+        def shading_fields
+          {}
+        end
+
+        private
+
+        def ensure_resources(document, page)
+          resources = page.value[:Resources]
+          return resources if resources.is_a?(Pdfrb::Model::Cos::Dictionary)
+
+          resources_hash = if resources.is_a?(Pdfrb::Model::Reference)
+                             document.object(resources)&.value
+                           else
+                             resources
+                           end
+          resources_hash ||= {}
+          wrapped = Pdfrb::Model::Cos::Dictionary.new(resources_hash)
+          page.value[:Resources] = wrapped
+          wrapped
+        end
+
+        def next_shading_name(shading_dict)
+          existing = shading_dict.keys.map(&:to_s).grep(/\ASh\d+\z/).map { |k| k[2..].to_i }
+          num = (existing.max || 0) + 1
+          :"Sh#{num}"
+        end
+      end
+
+      # Axial (linear) gradient. ShadingType 2.
+      # ISO 32000-2 §8.7.4.5.4.
+      class Axial < Base
+        attr_reader :start_point, :end_point, :function, :extend
+
+        def initialize(color_space:, start_point:, end_point:,
+                       function:, extend: nil)
+          super(color_space: color_space)
+          @start_point = start_point
+          @end_point = end_point
+          @function = function
+          @extend = extend
+        end
+
+        class << self
+          def shading_type; 2; end
+        end
+
+        protected
+
+        def shading_fields
+          fields = {
+            Coords: Pdfrb::Model::PdfArray.new([*@start_point, *@end_point]),
+            Function: @function,
+          }
+          fields[:Extend] = Pdfrb::Model::PdfArray.new(@extend) if @extend
+          fields
+        end
+      end
+
+      # Radial gradient. ShadingType 3.
+      # ISO 32000-2 §8.7.4.5.3.
+      class Radial < Base
+        attr_reader :center1, :radius1, :center2, :radius2, :function, :extend
+
+        def initialize(color_space:, center1:, radius1:, center2:, radius2:,
+                       function:, extend: nil)
+          super(color_space: color_space)
+          @center1 = center1
+          @radius1 = radius1
+          @center2 = center2
+          @radius2 = radius2
+          @function = function
+          @extend = extend
+        end
+
+        class << self
+          def shading_type; 3; end
+        end
+
+        protected
+
+        def shading_fields
+          fields = {
+            Coords: Pdfrb::Model::PdfArray.new([*@center1, @radius1, *@center2, @radius2]),
+            Function: @function,
+          }
+          fields[:Extend] = Pdfrb::Model::PdfArray.new(@extend) if @extend
+          fields
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/shading.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Shading patterns (ISO 32000-2 §8.7.4). Shadings define smooth
+    # color transitions: axial (linear) gradients, radial gradients,
+    # and free-form Gouraud-triangle meshes.
+    #
+    # Each shading is a dictionary with /ShadingType and type-specific
+    # parameters. Registered in page Resources under /Shading.
+    module Shading
+      autoload :Base, "pdfrb/content/shading/base"
+      autoload :Axial, "pdfrb/content/shading/base"
+      autoload :Radial, "pdfrb/content/shading/base"
+    end
+  end
+end

data/lib/pdfrb/content/smart_text_extractor.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module SmartTextExtractor
+      module_function
+
+      def extract(document)
+        results = []
+        document.pages.each do |page|
+          text = extract_page_text(document, page)
+          results << { page: page, text: text }
+        end
+
+        block_given? ? yield(results) : results
+      end
+
+      def extract_page_text(document, page)
+        contents = page.value[:Contents]
+        return "" unless contents
+
+        ref = contents.is_a?(Pdfrb::Model::Reference) ? contents : nil
+        return "" unless ref
+
+        stream = document.object(ref)
+        return "" unless stream.is_a?(Pdfrb::Model::Cos::Stream)
+
+        data = stream.decoded_stream
+        return "" unless data && !data.empty?
+
+        collector = TextCollector.new(document, page)
+        begin
+          collector.process(data)
+        rescue StandardError
+          # Best effort extraction
+        end
+        collector.text
+      end
+
+      class TextCollector < Pdfrb::Content::Processor
+        attr_reader :text
+
+        def initialize(document, page)
+          super()
+          @document = document
+          @page = page
+          @text = +""
+          @last_y = nil
+        end
+
+        def show_text(str)
+          insert_line_break_if_needed
+          @text << decode_text(str)
+        end
+
+        def show_text_array(arr)
+          insert_line_break_if_needed
+          arr.each do |e|
+            @text << decode_text(e) if e.is_a?(String)
+          end
+        end
+
+        def move_text(tx, ty, **)
+          super
+          insert_line_break_if_needed
+        end
+
+        private
+
+        def insert_line_break_if_needed
+          cur_y = graphics_state.text_state.text_matrix.f
+          if @last_y && (cur_y - @last_y).abs > 0.001
+            @text << "\n"
+          end
+          @last_y = cur_y
+        end
+
+        def decode_text(bytes)
+          bytes.to_s.dup.force_encoding("UTF-8")
+        end
+      end
+      private_constant :TextCollector
+    end
+  end
+end

data/lib/pdfrb/content/tiling_pattern.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    # Tiling patterns (ISO 32000-2 §8.7.3). A tiling pattern is a
+    # repeating cell that fills an area. Type 1 (constant spacing) and
+    # Type 2 (no distortion) are supported.
+    #
+    # The pattern cell is drawn via a block using the Canvas API.
+    # Registered in page Resources under /Pattern.
+    class TilingPattern
+      PATTERN_TYPE = 1
+
+      attr_reader :paint_type, :tiling_type, :bbox, :x_step, :y_step
+
+      # @param paint_type [Integer] 1 = colored, 2 = uncolored.
+      # @param tiling_type [Integer] 1 = constant, 2 = no distortion, 3 = constant spacing + no distortion.
+      # @param bbox [Array] bounding box of the pattern cell.
+      # @param x_step [Numeric] horizontal repeat distance.
+      # @param y_step [Numeric] vertical repeat distance.
+      def initialize(paint_type: 1, tiling_type: 1, bbox: [0, 0, 16, 16],
+                     x_step: 16, y_step: 16)
+        @paint_type = paint_type
+        @tiling_type = tiling_type
+        @bbox = bbox
+        @x_step = x_step
+        @y_step = y_step
+      end
+
+      # Build the pattern stream and register it in the page's Resources.
+      # @param document [Pdfrb::Document]
+      # @param page [Pdfrb::Model::Cos::Dictionary] target page.
+      # @yield [canvas] block that draws the pattern cell.
+      # @return [Symbol] the resource name (e.g. :P1)
+      def register_on(document, page)
+        pattern_stream = document.add(
+          {
+            Type: :Pattern,
+            PatternType: PATTERN_TYPE,
+            PaintType: @paint_type,
+            TilingType: @tiling_type,
+            BBox: @bbox,
+            XStep: @x_step,
+            YStep: @y_step,
+          },
+          type: Pdfrb::Model::Cos::Stream
+        )
+
+        if block_given?
+          canvas = Pdfrb::Content::Canvas.new(pattern_stream, document: document)
+          yield canvas
+        end
+
+        ref = Pdfrb::Model::Reference.new(pattern_stream.oid, pattern_stream.gen)
+        register_in_resources(document, page, ref)
+      end
+
+      private
+
+      def register_in_resources(_document, page, ref)
+        resources = page.value[:Resources]
+        resources = {} unless resources.is_a?(::Hash)
+        pattern_dict = resources[:Pattern] || {}
+        name = next_pattern_name(pattern_dict)
+        pattern_dict[name] = ref
+        resources[:Pattern] = pattern_dict
+        page.value[:Resources] = resources
+        name
+      end
+
+      def next_pattern_name(pattern_dict)
+        existing = pattern_dict.keys.map(&:to_s).grep(/\AP\d+\z/).map { |k| k[1..].to_i }
+        num = (existing.max || 0) + 1
+        :"P#{num}"
+      end
+    end
+  end
+end

data/lib/pdfrb/content/transformation_matrix.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    class TransformationMatrix
+      attr_reader :a, :b, :c, :d, :e, :f
+
+      def initialize(a = 1, b = 0, c = 0, d = 1, e = 0, f = 0)
+        @a = a.to_f
+        @b = b.to_f
+        @c = c.to_f
+        @d = d.to_f
+        @e = e.to_f
+        @f = f.to_f
+        freeze
+      end
+
+      def identity?
+        @a == 1 && @b.zero? && @c.zero? && @d == 1 && @e.zero? && @f.zero?
+      end
+
+      def multiply(other)
+        self.class.new(
+          (@a * other.a) + (@c * other.b),
+          (@b * other.a) + (@d * other.b),
+          (@a * other.c) + (@c * other.d),
+          (@b * other.c) + (@d * other.d),
+          (@a * other.e) + (@c * other.f) + @e,
+          (@b * other.e) + (@d * other.f) + @f,
+        )
+      end
+
+      def translate(tx, ty)
+        multiply(self.class.new(1, 0, 0, 1, tx, ty))
+      end
+
+      def scale(sx, sy = sx)
+        multiply(self.class.new(sx, 0, 0, sy, 0, 0))
+      end
+
+      def rotate(angle_radians)
+        cos = Math.cos(angle_radians)
+        sin = Math.sin(angle_radians)
+        multiply(self.class.new(cos, sin, -sin, cos, 0, 0))
+      end
+
+      def skew(fa, fb)
+        multiply(self.class.new(1, Math.tan(fa), Math.tan(fb), 1, 0, 0))
+      end
+
+      def to_a
+        [@a, @b, @c, @d, @e, @f]
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && to_a == other.to_a
+      end
+      alias eql? ==
+    end
+  end
+end