hexapdf 1.7.0 → 1.9.0

data/lib/hexapdf/layout/text_fragment.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -111,20 +111,24 @@ module HexaPDF
         font = style.font
         text.each_codepoint do |codepoint|
           glyph = font.decode_codepoint(codepoint)
-          if glyph.valid? || glyph.control_char?
+          if glyph.valid?
             items << glyph
           else
             unless items.empty?
-              result << shaper.shape_text(new(items, style))
+              result.append(*shaper.shape_text(new(items, style)))
               items = []
             end
-            fallback = yield(codepoint, glyph)
-            unless fallback.empty?
-              result << shaper.shape_text(new(fallback, styles[fallback.first.font_wrapper]))
+            if glyph.control_char?
+              result.append(new([glyph], style))
+            else
+              fallback = yield(codepoint, glyph)
+              unless fallback.empty?
+                result.append(*shaper.shape_text(new(fallback, styles[fallback.first.font_wrapper])))
+              end
             end
           end
         end
-        result << shaper.shape_text(new(items, style)) unless items.empty?
+        result.append(*shaper.shape_text(new(items, style))) unless items.empty?
         result
       end
 
@@ -251,7 +255,9 @@ module HexaPDF
         tx = x - tlm.e
         ty = y - tlm.f
         if tx.abs < PRECISION
-          if (ty + canvas.graphics_state.leading).abs < PRECISION
+          if ty.abs < PRECISION
+            # do nothing
+          elsif (ty + canvas.graphics_state.leading).abs < PRECISION
             canvas.move_text_cursor
           else
             canvas.move_text_cursor(offset: [0, ty], absolute: false)

data/lib/hexapdf/layout/text_layouter.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/layout/text_shaper.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -34,8 +34,71 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'hexapdf/error'
 require 'hexapdf/layout/numeric_refinements'
 
+HARFBUZZ_AVAILABLE = begin
+                       require 'harfbuzz'
+                       true
+                     rescue LoadError
+                     end
+
+if HARFBUZZ_AVAILABLE
+  class HarfBuzz::Buffer #:nodoc:
+
+    GLYPH_INFO_SIZE = HarfBuzz::C::HbGlyphInfoT.size
+    GLYPH_INFO_CODEPOINT_OFFSET = HarfBuzz::C::HbGlyphInfoT.offset_of(:codepoint)
+    GLYPH_INFO_CLUSTER_OFFSET = HarfBuzz::C::HbGlyphInfoT.offset_of(:cluster)
+    GLYPH_POS_SIZE  = HarfBuzz::C::HbGlyphPositionT.size
+    GLYPH_POS_XADVANCE_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:x_advance)
+    GLYPH_POS_YADVANCE_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:y_advance)
+    GLYPH_POS_XOFFSET_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:x_offset)
+    GLYPH_POS_YOFFSET_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:y_offset)
+
+    # Iterates efficiently over the shaping result without creating intermediary objects.
+    def each_result
+      return enum_for(__method__) unless block_given?
+
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      infos_ptr = HarfBuzz::C.hb_buffer_get_glyph_infos(@ptr, length_ptr)
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      positions_ptr = HarfBuzz::C.hb_buffer_get_glyph_positions(@ptr, length_ptr)
+      length = length_ptr.read_uint
+
+      return if infos_ptr.null? || positions_ptr.null? || length.zero?
+
+      last_info_cluster_offset = (length - 1) * GLYPH_INFO_SIZE + GLYPH_INFO_CLUSTER_OFFSET
+      i = 0
+      while i < length
+        info_offset = i * GLYPH_INFO_SIZE
+        pos_offset  = i * GLYPH_POS_SIZE
+
+        glyph_id = infos_ptr.get_uint32(info_offset + GLYPH_INFO_CODEPOINT_OFFSET)
+        cluster  = infos_ptr.get_uint32(info_offset + GLYPH_INFO_CLUSTER_OFFSET)
+
+        next_cluster = nil
+        tmp_offset = info_offset + GLYPH_INFO_CLUSTER_OFFSET + GLYPH_INFO_SIZE
+        while tmp_offset <= last_info_cluster_offset &&
+              (next_cluster = infos_ptr.get_uint32(tmp_offset)) == cluster
+          tmp_offset += GLYPH_INFO_SIZE
+          next_cluster = nil
+        end
+
+        x_advance = positions_ptr.get_int32(pos_offset + GLYPH_POS_XADVANCE_OFFSET)
+        y_advance = positions_ptr.get_int32(pos_offset + GLYPH_POS_YADVANCE_OFFSET)
+        x_offset = positions_ptr.get_int32(pos_offset + GLYPH_POS_XOFFSET_OFFSET)
+        y_offset = positions_ptr.get_int32(pos_offset + GLYPH_POS_YOFFSET_OFFSET)
+
+        yield(glyph_id, cluster, next_cluster, x_advance, y_advance, x_offset, y_offset)
+
+        i += 1
+      end
+
+      self
+    end
+  end
+end
+
 module HexaPDF
   module Layout
 
@@ -44,23 +107,33 @@ module HexaPDF
     # This class is used to perform text shaping, i.e. changing the position of glyphs (e.g. for
     # kerning) or substituting one or more glyphs for other glyphs (e.g. for ligatures).
     #
-    # Status of the implementation:
+    # The class contains two shaping engines: A very limited custom one and one based on
+    # HarfBuzz. Which one is used for shaping can be selected via the Style#shaping_engine property.
     #
-    # * All text shaping functionality possible for Type1 fonts is implemented, i.e. kerning and
-    #   ligature substitution.
+    # The custom implementation is always used for Type1 fonts and supports kerning and ligature
+    # substitution. It also supports the 'kern' table for TrueType fonts if HarfBuzz is not used.
     #
-    # * For TrueType fonts only kerning via the 'kern' table is implemented.
+    # For complex scripts or the need of special font features it is recommended to use the shaping
+    # engine based on HarfBuzz, even though it is slightly slower. For it to work the
+    # +harfbuzz-ruby+ gem needs to be installed. OpenType features can be activated and deactivated
+    # using Style#font_features.
     class TextShaper
 
-      # Shapes the given text fragment in-place.
+      # Shapes the given text fragment. Returns either the in-place modified fragment or, for
+      # complex shaping, an array of fragments.
       #
-      # The following shaping options, retrieved from the text fragment's Style#font_features, are
-      # supported:
-      #
-      # :kern:: Pair-wise kerning.
-      # :liga:: Ligature substitution.
+      # The style properties Style#shaping_engine, Style#font_features, Style#font_script,
+      # Style#language and Style#direction are used for shaping.
       def shape_text(text_fragment)
         font = text_fragment.style.font
+        if text_fragment.style.shaping_engine == :harfbuzz && font.font_type == :TrueType
+          unless HARFBUZZ_AVAILABLE
+            raise HexaPDF::Error, "Shaping engine harfbuzz required but the needed Rubygem " \
+              "harfbuzz-ruby is not available"
+          end
+          return harfbuzz_shape_text(text_fragment)
+        end
+
         if text_fragment.style.font_features[:liga] && font.wrapped_font.features.include?(:liga)
           if font.font_type == :Type1
             process_type1_ligatures(text_fragment)
@@ -76,11 +149,90 @@ module HexaPDF
           end
           text_fragment.clear_cache
         end
+
         text_fragment
       end
 
       private
 
+      # Shapes the text fragment with HarfBuzz.
+      def harfbuzz_shape_text(text_fragment, text = nil)
+        text ||= text_fragment.items.map(&:str).join
+        style = text_fragment.style
+
+        # Cache the used main Harfbuzz font objects
+        hb_font = style.font.pdf_object.document.cache('harfbuzz', style.font.filename) do
+          blob = HarfBuzz::Blob.from_file!(style.font.filename)
+          face = HarfBuzz::Face.new(blob, 0)
+          HarfBuzz::Font.new(face)
+        end
+
+        # Prepare the buffer and then shape the text. We are using cluster level 1 as this is the
+        # recommended level.
+        buffer = HarfBuzz::Buffer.new
+        buffer.add_utf8(text)
+        buffer.cluster_level = 1
+        buffer.direction = style.direction
+        buffer.script = style.font_script if style.font_script?
+        buffer.language = style.language if style.language?
+        buffer.guess_segment_properties
+        HarfBuzz.shape(hb_font, buffer, HarfBuzz::Feature.from_hash(style.font_features))
+
+        # Prepare the iteration over the shaping result. The final output will either be
+        # +text_fragment+ (no non-zero y_offsets) or +result+ containing at least two TextFragment
+        # instances.
+        result = nil
+        font = style.font
+        fragment = text_fragment
+        fragment.clear_cache
+        items = text_fragment.items.clear
+        last_cluster = nil
+        last_y_offset = 0
+        buffer.each_result do |glyph_id, cluster, next_cluster, x_advance, y_advance, x_offset, y_offset|
+          advance = (x_advance - x_offset) * font.scaling_factor
+
+          # 1. Determine the source characters for each glyph via their cluster numbers. If two or
+          # more glyphs have the same cluster number, the first gets the resulting string while the
+          # rest map to an empty string. Otherwise copying from the PDF would result in multiple
+          # copies of the resulting string.
+          str = (cluster == last_cluster ? '' : text.byteslice(cluster...(next_cluster || text.bytesize)))
+
+          # 2. Handle invalid glyphs with id=0 by mapping them to an InvalidGlyph instance
+          if glyph_id.zero?
+            glyph = font.decode_codepoint(str.ord)
+            advance = glyph.width
+          else
+            glyph = font.glyph(glyph_id, str)
+          end
+
+          # 3. Handle differing y_offsets by creating TextFragment instances with appropriate text
+          # rise properties.
+          if y_offset != last_y_offset
+            (result ||= []) << fragment
+            items = []
+            if y_offset.zero?
+              fragment = text_fragment.dup_attributes(items)
+            else
+              fragment = TextFragment.new(items, style.dup, properties: text_fragment.properties)
+              fragment.style.text_rise += y_offset * font.scaling_factor * fragment.style.font_size *
+                                          fragment.style.font.pdf_object.glyph_scaling_factor
+            end
+          end
+
+          # 4. Handle the correct x-positioning using x_offset. Also addjust the horizontal advance
+          # based on the glyph's fixed advance width as well as x_advance and x_offset (via
+          # +advance+).
+          items << -x_offset * font.scaling_factor unless x_offset.zero?
+          items << glyph
+          items << glyph.width - advance if glyph.width - advance != 0
+
+          last_cluster = cluster
+          last_y_offset = y_offset
+        end
+
+        result ? result.append(fragment) : text_fragment
+      end
+
       # Processes the text fragment and substitutes ligatures.
       def process_type1_ligatures(text_fragment)
         items = text_fragment.items

data/lib/hexapdf/layout/width_from_polygon.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/layout.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/name_tree_node.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/number_tree_node.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/object.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/parser.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/pdf_array.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/rectangle.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/reference.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/revision.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/revisions.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/serializer.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -270,7 +270,7 @@ module HexaPDF
       str << ">>"
     end
 
-    STRING_ESCAPE_MAP = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r"}.freeze # :nodoc:
+    STRING_ESCAPE_MAP = {"(" => "\\(", ")" => "\\)", "\\" => "\\\\", "\r" => "\\r", "\n" => "\\n"}.freeze # :nodoc:
 
     # Serializes a String object.
     #
@@ -287,7 +287,7 @@ module HexaPDF
             else
               obj.b
             end
-      obj.gsub!(/[()\\\r]/n, STRING_ESCAPE_MAP)
+      obj.gsub!(/[()\\\r\n]/n, STRING_ESCAPE_MAP)
       "(#{obj})"
     end
 

data/lib/hexapdf/stream.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/task/dereference.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/task/import_pages.rb

@@ -0,0 +1,185 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2026 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/serializer'
+require 'set'
+
+module HexaPDF
+  module Task
+
+    # Task for importing pages from another document that preserves the visual appearance.
+    #
+    # It takes care of
+    #
+    # * importing the specified pages with all associated objects,
+    # * handling optional content groups and their default state,
+    # * and merging form fields.
+    #
+    # Note that the /Order, /AS and /Locked fields of the default optional content configuration
+    # dictionary are not preserved.
+    #
+    # Example:
+    #
+    #   doc.task(:import_pages, source: source_doc, pages: [1..-2])
+    module ImportPages
+
+      # Performs the necessary steps to import the pages from the +source+ docment into the target
+      # document +doc+. Returns the imported pages.
+      #
+      # +source+::
+      #     Specifies the source PDF document from which the pages should be imported.
+      #
+      # +pages+::
+      #     Specifies the pages that should be imported. The argument has to be one of the
+      #     following:
+      #
+      #     +:all+:: Imports all pages from the +source+ document.
+      #     Integer value:: Imports the page with the given zero-based index.
+      #     Range value:: Imports the pages from the zero-based range.
+      #     Array of Integer or Range values:: Imports all specified pages or page ranges.
+      #     Array of source page objects:: Imports the given pages.
+      #
+      # +:append+::
+      #     Specifies whether the imported pages should be appended to the target document's page
+      #     tree.
+      #
+      # +ocgs+::
+      #     Specifies the handling of optional content groups:
+      #
+      #     +:preserve+:: Preserve the on/off state for all used OCGs.
+      #     +:ignore+:: Ignore the on/off state.
+      #
+      # +:acro_form+::
+      #     Specifies whether AcroForm fields should be merged into the target document.
+      #
+      #     +:merge+:: Merge AcroForm fields using the MergeAcroForm task.
+      #     +:ignore+:: Ignore AcroForm fields.
+      def self.call(doc, source:, pages: :all, append: true, ocgs: :preserve, acro_form: :merge)
+        # Retrieve all specified source pages
+        pages = if pages == :all
+                  source.pages.each.to_a
+                elsif pages.kind_of?(Integer)
+                  [source.pages[pages]]
+                elsif pages.kind_of?(Array) && pages[0].kind_of?(HexaPDF::Type::Page)
+                  pages
+                else
+                  result = Set.new
+                  all_pages = source.pages.each.to_a
+                  pages = [pages] unless pages.kind_of?(Array)
+                  pages.each {|selector| result.merge(Array(all_pages[selector])) }
+                  result
+                end
+
+        # Import the source pages and optionally append them to the target page tree
+        pages = pages.map do |page|
+          imported_page = doc.import(page)
+          doc.pages << imported_page if append
+          imported_page
+        end
+
+        doc.task(:merge_acro_form, source: source, pages: pages) if acro_form == :merge
+        preserve_ocgs(doc, source, pages) if ocgs == :preserve
+
+        pages
+      end
+
+      # Preserves the state of the OCGs found on +pages+ so that the visual appearance in the target
+      # document +doc+ is the same as in the +source+ document.
+      def self.preserve_ocgs(doc, source, pages)
+        # Find all OCGs used on all pages
+        ocgs = Set.new
+        process_ocg_or_ocmd = lambda do |obj|
+          if obj.type == :OCG
+            ocgs << obj
+          elsif obj.type == :OCMD
+            ocgs.merge(obj[:OCGs].to_ary)
+          end
+        end
+        seen_resources = {}
+        pages.each do |page|
+          unless seen_resources[page.resources] # handle case when pages share the resources dict
+            page.resources[:Properties]&.each do |name, obj|
+              next unless obj
+              process_ocg_or_ocmd.call(obj)
+            end
+
+            page.resources[:XObject]&.each do |name, obj|
+              process_ocg_or_ocmd.call(obj[:OC]) if obj.key?(:OC)
+            end
+          end
+
+          page.each_annotation do |annot|
+            process_ocg_or_ocmd.call(annot[:OC]) if annot.key?(:OC)
+          end
+
+          seen_resources[page.resources] = true
+        end
+
+        return if ocgs.empty?
+
+        # Add all found OCGs to the optional content properties dictionary
+        ocp = doc.optional_content
+        ocgs.each {|ocg| ocp.add_ocg(ocg) }
+
+        # Create a mapping from source OCGs to target OCGs and vice-versa
+        source_ocg = {}
+        target_ocg = {}
+        source.optional_content.ocgs.each do |ocg|
+          imported_ocg = doc.import(ocg)
+          next unless ocgs.include?(imported_ocg)
+          source_ocg[imported_ocg] = ocg
+          target_ocg[ocg] = imported_ocg
+        end
+
+        # Ensure the initial state of the OCGs is correct
+        source_config = source.optional_content.default_configuration
+        target_config = ocp.default_configuration
+        ocgs.each do |ocg|
+          target_config.ocg_state(ocg, source_config.ocg_state(source_ocg[ocg]))
+        end
+
+        # Copy radio button groups from the source document, removing unknown OCGs from them
+        source_config[:RBGroups]&.each do |array|
+          result = array.map {|ocg| target_ocg[ocg] }.compact
+          next if result.empty?
+          (target_config[:RBGroups] ||= []) << result
+        end
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/task/merge_acro_form.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/task/optimize.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/task/pdfa.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as

data/lib/hexapdf/task.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2025 Thomas Leitner
+# Copyright (C) 2014-2026 Thomas Leitner
 #
 # HexaPDF is free software: you can redistribute it and/or modify it
 # under the terms of the GNU Affero General Public License version 3 as
@@ -66,6 +66,7 @@ module HexaPDF
     autoload(:Dereference, 'hexapdf/task/dereference')
     autoload(:PDFA, 'hexapdf/task/pdfa')
     autoload(:MergeAcroForm, 'hexapdf/task/merge_acro_form')
+    autoload(:ImportPages, 'hexapdf/task/import_pages')
 
   end