fontisan 0.2.0 → 0.2.2

data/lib/fontisan/tables/cff2/table_reader.rb

@@ -0,0 +1,421 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "../../binary/base_record"
+
+module Fontisan
+  module Tables
+    class Cff2
+      # Table reader for CFF2 with Variable Store support
+      #
+      # CFF2TableReader parses CFF2 tables and extracts variation data
+      # from the Variable Store, which is essential for applying hints
+      # to variable fonts with CFF2 outlines.
+      #
+      # Variable Store Structure:
+      # - RegionList: Defines variation regions (min/peak/max per axis)
+      # - ItemVariationData: Contains delta arrays per region
+      #
+      # Reference: Adobe Technical Note #5177 (CFF2)
+      # Reference: OpenType spec - Item Variation Store
+      #
+      # @example Reading CFF2 with Variable Store
+      #   reader = CFF2TableReader.new(cff2_data)
+      #   store = reader.read_variable_store
+      #   regions = store[:regions]
+      #   deltas = store[:deltas]
+      class TableReader
+        # @return [String] Binary CFF2 data
+        attr_reader :data
+
+        # @return [Hash] CFF2 header information
+        attr_reader :header
+
+        # @return [Hash] Top DICT data
+        attr_reader :top_dict
+
+        # @return [Hash, nil] Variable Store data
+        attr_reader :variable_store
+
+        # CFF2-specific operators
+        VSTORE_OPERATOR = 24
+
+        # Initialize reader with CFF2 data
+        #
+        # @param data [String] Binary CFF2 table data
+        def initialize(data)
+          @data = data
+          @io = StringIO.new(data)
+          @io.set_encoding(Encoding::BINARY)
+          @header = nil
+          @top_dict = nil
+          @variable_store = nil
+        end
+
+        # Read CFF2 header
+        #
+        # @return [Hash] Header information
+        def read_header
+          @io.rewind
+          @header = {
+            major_version: read_uint8,
+            minor_version: read_uint8,
+            header_size: read_uint8,
+            top_dict_length: read_uint16,
+          }
+
+          # Validate CFF2 version
+          unless @header[:major_version] == 2 && @header[:minor_version].zero?
+            raise CorruptedTableError,
+                  "Invalid CFF2 version: #{@header[:major_version]}.#{@header[:minor_version]}"
+          end
+
+          @header
+        end
+
+        # Read Top DICT
+        #
+        # @return [Hash] Top DICT operators and values
+        def read_top_dict
+          read_header unless @header
+
+          # Seek to Top DICT (after header)
+          @io.seek(@header[:header_size])
+
+          top_dict_data = @io.read(@header[:top_dict_length])
+          @top_dict = parse_dict(top_dict_data)
+        end
+
+        # Read Variable Store from Top DICT
+        #
+        # The Variable Store is referenced by the vstore operator (24)
+        # in the Top DICT. It contains regions and deltas for variation.
+        #
+        # @return [Hash, nil] Variable Store data with :regions and :deltas
+        def read_variable_store
+          read_top_dict unless @top_dict
+
+          # Check if Variable Store is present (operator 24)
+          vstore_offset = @top_dict[VSTORE_OPERATOR]
+          return nil unless vstore_offset
+
+          # Seek to Variable Store
+          @io.seek(vstore_offset)
+
+          # Parse Variable Store structure
+          @variable_store = {
+            regions: read_region_list,
+            item_variation_data: read_item_variation_data,
+          }
+
+          @variable_store
+        end
+
+        # Read Region List from Variable Store
+        #
+        # Region List defines variation regions, where each region
+        # specifies min/peak/max values per axis.
+        #
+        # @return [Array<Hash>] Array of region definitions
+        def read_region_list
+          region_count = read_uint16
+          regions = []
+
+          region_count.times do
+            region = read_region
+            regions << region
+          end
+
+          regions
+        end
+
+        # Read a single region
+        #
+        # @return [Hash] Region with axis coordinates
+        def read_region
+          axis_count = read_uint16
+          axes = []
+
+          axis_count.times do
+            axes << {
+              start_coord: read_f2dot14,
+              peak_coord: read_f2dot14,
+              end_coord: read_f2dot14,
+            }
+          end
+
+          { axis_count: axis_count, axes: axes }
+        end
+
+        # Read Item Variation Data
+        #
+        # Contains delta arrays per region for varying values
+        #
+        # @return [Array<Hash>] Array of item variation data
+        def read_item_variation_data
+          data_count = read_uint16
+          return [] if data_count.zero?
+
+          item_variation_data = []
+
+          data_count.times do |_idx|
+            item_data = read_single_item_variation_data
+            item_variation_data << item_data
+          rescue EOFError
+            # break
+          end
+
+          item_variation_data
+        end
+
+        # Read a single Item Variation Data entry
+        #
+        # @return [Hash] Item variation data with region indices and deltas
+        def read_single_item_variation_data
+          item_count = read_uint16
+          short_delta_count = read_uint16
+          region_index_count = read_uint16
+
+          # Read region indices
+          region_indices = []
+          region_index_count.times do
+            region_indices << read_uint16
+          end
+
+          # Read delta sets
+          delta_sets = []
+          item_count.times do |_item_idx|
+            deltas = []
+
+            # Short deltas (16-bit)
+            short_delta_count.times do
+              break if @io.eof?
+
+              deltas << read_int16
+            end
+
+            # Long deltas (8-bit) for remaining regions
+            (region_index_count - short_delta_count).times do
+              break if @io.eof?
+
+              deltas << read_int8
+            end
+
+            delta_sets << deltas
+          rescue EOFError
+            # break
+          end
+
+          {
+            item_count: item_count,
+            region_indices: region_indices,
+            delta_sets: delta_sets,
+          }
+        end
+
+        # Read Private DICT with blend support
+        #
+        # Private DICT in CFF2 can contain blend operators for
+        # variable hint parameters.
+        #
+        # @param size [Integer] Private DICT size
+        # @param offset [Integer] Private DICT offset
+        # @return [Hash] Private DICT data
+        def read_private_dict(size, offset)
+          @io.seek(offset)
+          private_dict_data = @io.read(size)
+          parse_dict(private_dict_data)
+        end
+
+        # Read CharStrings INDEX
+        #
+        # @param offset [Integer] CharStrings offset from Top DICT
+        # @return [Cff::Index] CharStrings INDEX
+        def read_charstrings(offset)
+          @io.seek(offset)
+          require_relative "../cff/index"
+          Cff::Index.new(@io, start_offset: offset)
+        end
+
+        private
+
+        # Read bytes safely with EOF checking
+        #
+        # @param bytes [Integer] Number of bytes to read
+        # @param description [String] Description for error messages
+        # @return [String] Binary data
+        # @raise [EOFError] If not enough bytes available
+        def read_safely(bytes, description)
+          data = @io.read(bytes)
+          if data.nil? || data.bytesize < bytes
+            raise EOFError,
+                  "Unexpected EOF while reading #{description}"
+          end
+
+          data
+        end
+
+        # Parse DICT structure
+        #
+        # @param data [String] DICT binary data
+        # @return [Hash] Parsed operators and values
+        def parse_dict(data)
+          dict = {}
+          io = StringIO.new(data)
+          io.set_encoding(Encoding::BINARY)
+          operands = []
+
+          until io.eof?
+            byte = io.getbyte
+
+            if operator_byte?(byte)
+              operator = read_dict_operator(io, byte)
+              dict[operator] =
+                operands.size == 1 ? operands.first : operands.dup
+              operands.clear
+            else
+              # Operand (number)
+              io.pos -= 1
+              operands << read_dict_number(io)
+            end
+          end
+
+          dict
+        end
+
+        # Check if byte is an operator
+        #
+        # CFF2 extends the operator range to include operator 24 (vstore)
+        #
+        # @param byte [Integer] Byte value
+        # @return [Boolean] True if operator
+        def operator_byte?(byte)
+          # Standard DICT operators (0-21, excluding number markers)
+          return true if byte <= 21 && ![12, 28, 29, 30, 31].include?(byte)
+
+          # CFF2-specific operators
+          return true if byte == VSTORE_OPERATOR
+
+          false
+        end
+
+        # Read DICT operator
+        #
+        # @param io [StringIO] Input stream
+        # @param first_byte [Integer] First operator byte
+        # @return [Integer, Array<Integer>] Operator code
+        def read_dict_operator(io, first_byte)
+          if first_byte == 12
+            # Two-byte operator
+            second_byte = io.getbyte
+            [12, second_byte]
+          else
+            first_byte
+          end
+        end
+
+        # Read number from DICT
+        #
+        # @param io [StringIO] Input stream
+        # @return [Integer, Float] Number value
+        def read_dict_number(io)
+          byte = io.getbyte
+
+          case byte
+          when 28
+            # 3-byte signed integer
+            b1 = io.getbyte
+            b2 = io.getbyte
+            value = (b1 << 8) | b2
+            value > 0x7FFF ? value - 0x10000 : value
+          when 29
+            # 5-byte signed integer
+            io.read(4).unpack1("l>")
+          when 30
+            # Real number
+            read_real_number(io)
+          when 32..246
+            byte - 139
+          when 247..250
+            b2 = io.getbyte
+            (byte - 247) * 256 + b2 + 108
+          when 251..254
+            b2 = io.getbyte
+            -(byte - 251) * 256 - b2 - 108
+          else
+            0
+          end
+        end
+
+        # Read real number from DICT
+        #
+        # @param io [StringIO] Input stream
+        # @return [Float] Real number
+        def read_real_number(io)
+          nibbles = []
+          loop do
+            byte = io.getbyte
+            nibbles << ((byte >> 4) & 0x0F)
+            nibbles << (byte & 0x0F)
+            break if (byte & 0x0F) == 0x0F
+          end
+
+          str = ""
+          nibbles.each do |nibble|
+            case nibble
+            when 0..9 then str << nibble.to_s
+            when 0x0A then str << "."
+            when 0x0B then str << "E"
+            when 0x0C then str << "E-"
+            when 0x0E then str << "-"
+            when 0x0F then break
+            end
+          end
+
+          str.to_f
+        end
+
+        # Read unsigned 8-bit integer
+        #
+        # @return [Integer] Value
+        def read_uint8
+          read_safely(1, "uint8").unpack1("C")
+        end
+
+        # Read unsigned 16-bit integer (big-endian)
+        #
+        # @return [Integer] Value
+        def read_uint16
+          read_safely(2, "uint16").unpack1("n")
+        end
+
+        # Read signed 16-bit integer (big-endian)
+        #
+        # @return [Integer] Value
+        def read_int16
+          read_safely(2, "int16").unpack1("s>")
+        end
+
+        # Read signed 8-bit integer
+        #
+        # @return [Integer] Value
+        def read_int8
+          value = read_safely(1, "int8").unpack1("C")
+          value > 0x7F ? value - 0x100 : value
+        end
+
+        # Read F2DOT14 format (signed 16-bit fixed-point)
+        #
+        # F2DOT14 represents a number in 2.14 format:
+        # - 2 bits for integer part
+        # - 14 bits for fractional part
+        #
+        # @return [Float] Value
+        def read_f2dot14
+          value = read_int16
+          value / 16384.0
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff2/variation_data_extractor.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff2
+      # Variation data extractor for CFF2 Variable Store
+      #
+      # Extracts regions and deltas from the Variable Store and provides
+      # utilities for working with variation data.
+      #
+      # Reference: OpenType spec - Item Variation Store
+      # Reference: Adobe Technical Note #5177 (CFF2)
+      #
+      # @example Extracting variation data
+      #   extractor = VariationDataExtractor.new(variable_store)
+      #   regions = extractor.regions
+      #   deltas = extractor.deltas_for_item(item_index)
+      class VariationDataExtractor
+        # @return [Hash] Variable Store data
+        attr_reader :variable_store
+
+        # @return [Array<Hash>] Extracted regions
+        attr_reader :regions
+
+        # @return [Array<Hash>] Item variation data
+        attr_reader :item_variation_data
+
+        # Initialize extractor with Variable Store data
+        #
+        # @param variable_store [Hash] Variable Store from CFF2TableReader
+        def initialize(variable_store)
+          @variable_store = variable_store
+          @regions = variable_store[:regions] || []
+          @item_variation_data = variable_store[:item_variation_data] || []
+        end
+
+        # Get deltas for a specific item
+        #
+        # @param item_index [Integer] Item index
+        # @param data_index [Integer] Item variation data index (default 0)
+        # @return [Array<Integer>, nil] Deltas for the item, or nil if not found
+        def deltas_for_item(item_index, data_index: 0)
+          return nil if data_index >= @item_variation_data.size
+
+          item_data = @item_variation_data[data_index]
+          return nil if item_index >= item_data[:delta_sets].size
+
+          item_data[:delta_sets][item_index]
+        end
+
+        # Get region indices for item variation data
+        #
+        # @param data_index [Integer] Item variation data index (default 0)
+        # @return [Array<Integer>] Region indices
+        def region_indices(data_index: 0)
+          return [] if data_index >= @item_variation_data.size
+
+          @item_variation_data[data_index][:region_indices] || []
+        end
+
+        # Get number of items in item variation data
+        #
+        # @param data_index [Integer] Item variation data index (default 0)
+        # @return [Integer] Number of items
+        def item_count(data_index: 0)
+          return 0 if data_index >= @item_variation_data.size
+
+          @item_variation_data[data_index][:item_count] || 0
+        end
+
+        # Get all deltas for all items
+        #
+        # @param data_index [Integer] Item variation data index (default 0)
+        # @return [Array<Array<Integer>>] Array of delta sets
+        def all_deltas(data_index: 0)
+          return [] if data_index >= @item_variation_data.size
+
+          @item_variation_data[data_index][:delta_sets] || []
+        end
+
+        # Calculate blended value for an item at specific coordinates
+        #
+        # @param item_index [Integer] Item index
+        # @param base_value [Numeric] Base value to blend
+        # @param scalars [Array<Float>] Region scalars for each region
+        # @param data_index [Integer] Item variation data index (default 0)
+        # @return [Float] Blended value
+        def blend_value(item_index, base_value, scalars, data_index: 0)
+          deltas = deltas_for_item(item_index, data_index: data_index)
+          return base_value.to_f unless deltas
+
+          indices = region_indices(data_index: data_index)
+
+          # Apply blend: result = base + Σ(delta[i] * scalar[region_index[i]])
+          result = base_value.to_f
+          deltas.each_with_index do |delta, i|
+            region_index = indices[i]
+            next unless region_index
+
+            scalar = scalars[region_index] || 0.0
+            result += delta.to_f * scalar
+          end
+
+          result
+        end
+
+        # Get region by index
+        #
+        # @param region_index [Integer] Region index
+        # @return [Hash, nil] Region data or nil if not found
+        def region(region_index)
+          return nil if region_index >= @regions.size
+
+          @regions[region_index]
+        end
+
+        # Get number of regions
+        #
+        # @return [Integer] Total number of regions
+        def region_count
+          @regions.size
+        end
+
+        # Get number of axes from first region
+        #
+        # @return [Integer] Number of axes
+        def axis_count
+          return 0 if @regions.empty?
+
+          @regions.first[:axis_count] || 0
+        end
+
+        # Check if Variable Store has data
+        #
+        # @return [Boolean] True if Variable Store contains data
+        def has_data?
+          !@regions.empty? && !@item_variation_data.empty?
+        end
+
+        # Extract all region coordinates as arrays
+        #
+        # Useful for debugging and validation
+        #
+        # @return [Array<Array<Hash>>] Array of regions with axis coordinates
+        def region_coordinates
+          @regions.map do |region|
+            region[:axes].map do |axis|
+              {
+                start: axis[:start_coord],
+                peak: axis[:peak_coord],
+                end: axis[:end_coord],
+              }
+            end
+          end
+        end
+
+        # Validate Variable Store structure
+        #
+        # @return [Array<String>] Array of validation errors (empty if valid)
+        def validate
+          errors = []
+
+          # Check regions consistency
+          if @regions.any?
+            expected_axes = @regions.first[:axis_count]
+            @regions.each_with_index do |region, i|
+              unless region[:axis_count] == expected_axes
+                errors << "Region #{i} has inconsistent axis_count: " \
+                          "#{region[:axis_count]} vs #{expected_axes}"
+              end
+
+              unless region[:axes].size == expected_axes
+                errors << "Region #{i} has #{region[:axes].size} axes, " \
+                          "expected #{expected_axes}"
+              end
+            end
+          end
+
+          # Check item variation data
+          @item_variation_data.each_with_index do |item_data, i|
+            item_count = item_data[:item_count]
+            delta_sets = item_data[:delta_sets]
+            region_indices = item_data[:region_indices]
+
+            unless delta_sets.size == item_count
+              errors << "Item variation data #{i} has #{delta_sets.size} " \
+                        "delta sets, expected #{item_count}"
+            end
+
+            # Check each delta set has correct number of deltas
+            delta_sets.each_with_index do |deltas, j|
+              unless deltas.size == region_indices.size
+                errors << "Delta set #{j} in data #{i} has #{deltas.size} " \
+                          "deltas, expected #{region_indices.size}"
+              end
+            end
+
+            # Check region indices are valid
+            region_indices.each_with_index do |idx, j|
+              if idx >= @regions.size
+                errors << "Region index #{idx} at position #{j} in data #{i} " \
+                          "exceeds region count #{@regions.size}"
+              end
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/tables/cff2.rb

@@ -22,7 +22,7 @@ module Fontisan
     #   num_glyphs = cff2.glyph_count
     class Cff2 < Binary::BaseRecord
       # CFF2 header structure
-      class Header < Binary::BaseRecord
+      class Cff2Header < Binary::BaseRecord
         uint8 :major_version
         uint8 :minor_version
         uint8 :header_size
@@ -53,7 +53,7 @@ module Fontisan
 
       # Get the CFF2 header
       #
-      # @return [Header] Header structure
+      # @return [Cff2Header] Header structure
       def header
         parse unless @parsed
         @header
@@ -111,7 +111,7 @@ module Fontisan
           @num_axes,
           @global_subr_index,
           nil, # local subrs (CFF2 may not have them)
-          0    # vsindex
+          0, # vsindex
         ).parse
       end
 
@@ -137,12 +137,12 @@ module Fontisan
 
       # Parse CFF2 header
       #
-      # @return [Header] Parsed header
+      # @return [Cff2Header] Parsed header
       def parse_header
         data = raw_data
         return nil if data.nil? || data.bytesize < 5
 
-        Header.read(data.byteslice(0, 5))
+        Cff2Header.read(data.byteslice(0, 5))
       end
 
       # Parse Global Subr INDEX
@@ -339,3 +339,8 @@ end
 require_relative "cff2/charstring_parser"
 require_relative "cff2/blend_operator"
 require_relative "cff2/operand_stack"
+require_relative "cff2/table_reader"
+require_relative "cff2/variation_data_extractor"
+require_relative "cff2/region_matcher"
+require_relative "cff2/private_dict_blend_handler"
+require_relative "cff2/table_builder"