pdfrb 0.3.0 → 0.7.1

data/lib/pdfrb/content/color_space.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module ColorSpace
+      REGISTRY = {} # rubocop:disable Style/MutableConstant
+
+      class << self
+        def register(name, klass)
+          REGISTRY[name.to_sym] = klass
+        end
+
+        def resolve(name, _document = nil)
+          REGISTRY[name.to_sym]
+        end
+
+        def families
+          REGISTRY.keys
+        end
+      end
+
+      class DeviceGray
+        def self.family; :DeviceGray; end
+        def self.components; 1; end
+        def self.default; [0.0]; end
+      end
+      register :DeviceGray, DeviceGray
+
+      class DeviceRGB
+        def self.family; :DeviceRGB; end
+        def self.components; 3; end
+        def self.default; [0.0, 0.0, 0.0]; end
+      end
+      register :DeviceRGB, DeviceRGB
+
+      class DeviceCMYK
+        def self.family; :DeviceCMYK; end
+        def self.components; 4; end
+        def self.default; [0.0, 0.0, 0.0, 1.0]; end
+      end
+      register :DeviceCMYK, DeviceCMYK
+
+      class CalGray
+        attr_reader :white_point, :gamma
+
+        def initialize(white_point:, gamma: 1.0)
+          @white_point = white_point
+          @gamma = gamma
+        end
+
+        def family; :CalGray; end
+        def components; 1; end
+      end
+      register :CalGray, CalGray
+
+      class CalRGB
+        attr_reader :white_point, :black_point, :gamma
+
+        def initialize(white_point:, black_point: [0, 0, 0], gamma: [1, 1, 1])
+          @white_point = white_point
+          @black_point = black_point
+          @gamma = gamma
+        end
+
+        def family; :CalRGB; end
+        def components; 3; end
+      end
+      register :CalRGB, CalRGB
+
+      class Lab
+        attr_reader :white_point, :black_point, :range
+
+        def initialize(white_point:, black_point: [0, 0, 0], range: [-100, 100, -100, 100])
+          @white_point = white_point
+          @black_point = black_point
+          @range = range
+        end
+
+        def family; :Lab; end
+        def components; 3; end
+      end
+      register :Lab, Lab
+
+      class ICCBased
+        attr_reader :stream_ref, :alternate, :range, :n
+
+        def initialize(stream_ref:, n:, alternate: nil, range: nil)
+          @stream_ref = stream_ref
+          @n = n
+          @alternate = alternate
+          @range = range
+        end
+
+        def family; :ICCBased; end
+        def components; @n; end
+      end
+      register :ICCBased, ICCBased
+
+      class Indexed
+        attr_reader :base, :hival, :lookup
+
+        def initialize(base:, hival:, lookup:)
+          @base = base
+          @hival = hival
+          @lookup = lookup
+        end
+
+        def family; :Indexed; end
+        def components; 1; end
+      end
+      register :Indexed, Indexed
+
+      class Separation
+        attr_reader :name, :alternate_space, :tint_transform
+
+        def initialize(name:, alternate_space:, tint_transform:)
+          @name = name
+          @alternate_space = alternate_space
+          @tint_transform = tint_transform
+        end
+
+        def family; :Separation; end
+        def components; 1; end
+      end
+      register :Separation, Separation
+
+      class DeviceN
+        attr_reader :names, :alternate_space, :tint_transform
+
+        def initialize(names:, alternate_space:, tint_transform:)
+          @names = names
+          @alternate_space = alternate_space
+          @tint_transform = tint_transform
+        end
+
+        def family; :DeviceN; end
+
+        def components
+          (@names || []).length
+        end
+      end
+      register :DeviceN, DeviceN
+
+      class Pattern
+        attr_reader :base_space
+
+        def initialize(base_space: nil)
+          @base_space = base_space
+        end
+
+        def family; :Pattern; end
+        def components; 0; end
+      end
+      register :Pattern, Pattern
+    end
+  end
+end

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/inline_image.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Content
+    module Operator
+      # Inline image operators (s8.9.7). Inline images embed raw image
+      # data directly in the content stream, framed by BI ... ID ...
+      # EI. They're an alternative to /XObject /Image for one-shot
+      # images: smaller overhead per image, no /Resources entry
+      # needed, but the bytes live in the content stream so they
+      # can't be reused.
+      #
+      # The serialise path emits the BI dict, ID marker, raw bytes,
+      # and EI marker. The invoke path is intentionally a no-op; the
+      # content Parser handles BI/ID/EI as a single bounded block
+      # rather than via the operator dispatch table.
+      class BeginInlineImage < Base
+        class << self
+          def name; "BI"; end
+
+          def serialize(serializer, **dict)
+            buf = +"BI\n"
+            dict.each do |k, v|
+              buf << serializer.serialize(k) << " " << serializer.serialize(v) << "\n"
+            end
+            buf << "ID\n"
+            buf
+          end
+
+          def invoke(_processor, *_operands); end
+          register
+        end
+      end
+
+      class EndInlineImage < Base
+        class << self
+          def name; "EI"; end
+
+          # The byte payload sits between ID and EI. The serializer
+          # for inline images writes the payload directly via
+          # Canvas#inline_image; this method is here so the registry
+          # knows about EI.
+          def serialize(_serializer, *_operands)
+            "EI\n"
+          end
+
+          def invoke(_processor, *_operands); end
+          register
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/content/operators.rb

@@ -0,0 +1,22 @@
+# 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"
+      autoload :InlineImage, "pdfrb/content/operators/inline_image"
+    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