fontisan 0.1.0 → 0.2.1

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

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff2
+      # Operand stack manager for CFF2 CharStrings
+      #
+      # This class manages the operand stack for CFF2 CharStrings, with special
+      # handling for blend operations that mix base values and deltas.
+      #
+      # In CFF2, the blend operator takes operands in the format:
+      #   [base1, delta1_axis1, delta1_axis2, ..., base2, delta2_axis1, ..., K, N]
+      #
+      # Where:
+      #   - K = number of values to blend
+      #   - N = number of variation axes
+      #
+      # The stack manager separates base values from deltas and applies blend
+      # operations to produce final values based on variation coordinates.
+      #
+      # @example Managing a blend operation
+      #   stack = OperandStack.new(num_axes: 2)
+      #   stack.push(100, 10, 5)  # base=100, deltas=[10, 5]
+      #   stack.push(200, 20, 10) # base=200, deltas=[20, 10]
+      #   blended = stack.apply_blend(k: 2, coordinates: { "wght" => 0.5, "wdth" => 0.3 })
+      #   # => [105.0, 206.0]  # base + (delta * scalar)
+      class OperandStack
+        # @return [Array<Numeric>] The operand stack
+        attr_reader :stack
+
+        # @return [Integer] Number of variation axes
+        attr_reader :num_axes
+
+        # @return [Array<Hash>] Blend values (base + deltas)
+        attr_reader :blend_values
+
+        # Initialize operand stack
+        #
+        # @param num_axes [Integer] Number of variation axes (default 0)
+        def initialize(num_axes: 0)
+          @stack = []
+          @num_axes = num_axes
+          @blend_values = []
+        end
+
+        # Push a value onto the stack
+        #
+        # @param values [Numeric] Values to push
+        def push(*values)
+          @stack.concat(values)
+        end
+
+        # Pop a value from the stack
+        #
+        # @return [Numeric, nil] Popped value or nil if empty
+        def pop
+          @stack.pop
+        end
+
+        # Pop multiple values from the stack
+        #
+        # @param count [Integer] Number of values to pop
+        # @return [Array<Numeric>] Popped values
+        def pop_many(count)
+          return [] if count <= 0 || @stack.empty?
+
+          @stack.pop(count)
+        end
+
+        # Shift a value from the front of the stack
+        #
+        # @return [Numeric, nil] Shifted value or nil if empty
+        def shift
+          @stack.shift
+        end
+
+        # Get the top value without popping
+        #
+        # @return [Numeric, nil] Top value or nil if empty
+        def peek
+          @stack.last
+        end
+
+        # Get stack size
+        #
+        # @return [Integer] Number of values on stack
+        def size
+          @stack.size
+        end
+
+        # Check if stack is empty
+        #
+        # @return [Boolean] True if empty
+        def empty?
+          @stack.empty?
+        end
+
+        # Clear the stack
+        def clear
+          @stack.clear
+          @blend_values.clear
+        end
+
+        # Apply blend operation
+        #
+        # This pops K * (N + 1) + 2 operands from the stack, where:
+        #   - K = number of values to blend
+        #   - N = number of axes
+        #   - Last 2 values are K and N themselves
+        #
+        # @param scalars [Array<Float>] Variation scalars for each axis
+        # @return [Array<Float>] Blended values
+        def apply_blend(scalars = [])
+          # Pop N and K
+          n = pop.to_i
+          k = pop.to_i
+
+          # Validate
+          required_operands = k * (n + 1)
+          if size < required_operands
+            warn "Blend requires #{required_operands} operands, got #{size}"
+            clear
+            return []
+          end
+
+          # Extract operands (base + deltas for each value)
+          blend_operands = pop_many(required_operands).reverse
+
+          # Process each value to blend
+          blended_values = []
+          k.times do |i|
+            offset = i * (n + 1)
+            base = blend_operands[offset]
+            deltas = blend_operands[offset + 1, n] || []
+
+            # Apply blend: result = base + sum(delta[i] * scalar[i])
+            blended = base.to_f
+            deltas.each_with_index do |delta, axis_index|
+              scalar = scalars[axis_index] || 0.0
+              blended += delta.to_f * scalar
+            end
+
+            # Store blend info for debugging/inspection
+            @blend_values << {
+              base: base,
+              deltas: deltas,
+              blended: blended,
+            }
+
+            blended_values << blended
+          end
+
+          # Push blended values back onto stack
+          push(*blended_values)
+
+          blended_values
+        end
+
+        # Extract blend data without applying
+        #
+        # This is used when we need to store blend operations for later
+        # application with specific coordinates.
+        #
+        # @return [Hash] Blend operation data
+        def extract_blend_data
+          # Pop N and K
+          n = pop.to_i
+          k = pop.to_i
+
+          # Validate
+          required_operands = k * (n + 1)
+          if size < required_operands
+            warn "Blend requires #{required_operands} operands, got #{size}"
+            clear
+            return nil
+          end
+
+          # Extract operands
+          blend_operands = pop_many(required_operands).reverse
+
+          # Parse into base + deltas structure
+          blends = []
+          k.times do |i|
+            offset = i * (n + 1)
+            base = blend_operands[offset]
+            deltas = blend_operands[offset + 1, n] || []
+
+            blends << {
+              base: base,
+              deltas: deltas,
+            }
+
+            # Push base value back (will be blended later)
+            push(base)
+          end
+
+          {
+            num_values: k,
+            num_axes: n,
+            blends: blends,
+          }
+        end
+
+        # Get all values on the stack
+        #
+        # @return [Array<Numeric>] Stack contents
+        def to_a
+          @stack.dup
+        end
+
+        # Get string representation for debugging
+        #
+        # @return [String] Stack contents as string
+        def inspect
+          "#<OperandStack size=#{size} values=#{@stack.inspect}>"
+        end
+
+        # Get blend value history
+        #
+        # @return [Array<Hash>] Blend values that have been calculated
+        def blend_history
+          @blend_values.dup
+        end
+
+        # Reset blend history
+        def reset_blend_history
+          @blend_values.clear
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff2
+      # Private DICT blend handler for CFF2
+      #
+      # Handles blend operators in Private DICT which allow hint parameters
+      # to vary across the design space in variable fonts.
+      #
+      # Blend in Private DICT format:
+      #   base_value delta1 delta2 ... deltaN num_axes blend
+      #
+      # Example for BlueValues with 2 axes:
+      #   -10 2 1   0 1 0   500 10 5   510 12 6   2 blend
+      #   This creates BlueValues that vary across the design space.
+      #
+      # Reference: Adobe Technical Note #5177 (CFF2)
+      #
+      # @example Parsing blend in Private DICT
+      #   handler = PrivateDictBlendHandler.new(private_dict)
+      #   blue_values = handler.parse_blend_array(:blue_values, num_axes: 2)
+      class PrivateDictBlendHandler
+        # @return [Hash] Private DICT data
+        attr_reader :private_dict
+
+        # Initialize handler with Private DICT data
+        #
+        # @param private_dict [Hash] Parsed Private DICT
+        def initialize(private_dict)
+          @private_dict = private_dict
+        end
+
+        # Check if Private DICT contains blend data
+        #
+        # @return [Boolean] True if blend operators are present
+        def has_blend?
+          # In a DICT with blend, values are arrays with blend data
+          @private_dict.values.any? { |v| blend_value?(v) }
+        end
+
+        # Parse blended array (like BlueValues)
+        #
+        # @param key [Symbol, Integer] DICT operator key
+        # @param num_axes [Integer] Number of variation axes
+        # @return [Hash, nil] Parsed blend data or nil if not present
+        def parse_blend_array(key, num_axes:)
+          value = @private_dict[key]
+          return nil unless value.is_a?(Array)
+
+          # Check if this is blend data
+          # Format: base1 delta1_1 ... delta1_N base2 delta2_1 ... delta2_N ...
+          # The array must be divisible by (num_axes + 1)
+          return nil unless value.size % (num_axes + 1) == 0
+
+          num_values = value.size / (num_axes + 1)
+          blends = []
+
+          num_values.times do |i|
+            offset = i * (num_axes + 1)
+            base = value[offset]
+            deltas = value[offset + 1, num_axes] || []
+
+            blends << {
+              base: base,
+              deltas: deltas
+            }
+          end
+
+          {
+            num_values: num_values,
+            num_axes: num_axes,
+            blends: blends
+          }
+        end
+
+        # Parse single blended value
+        #
+        # @param key [Symbol, Integer] DICT operator key
+        # @param num_axes [Integer] Number of variation axes
+        # @return [Hash, nil] Parsed blend data or nil if not present
+        def parse_blend_value(key, num_axes:)
+          value = @private_dict[key]
+          return nil unless value.is_a?(Array)
+
+          # Single value format: base delta1 delta2 ... deltaN
+          expected_size = num_axes + 1
+          return nil unless value.size == expected_size
+
+          {
+            base: value[0],
+            deltas: value[1..num_axes],
+            num_axes: num_axes
+          }
+        end
+
+        # Apply blend at specific coordinates
+        #
+        # @param blend_data [Hash] Parsed blend data
+        # @param scalars [Array<Float>] Region scalars for each axis
+        # @return [Array<Float>, Float] Blended values
+        def apply_blend(blend_data, scalars)
+          return nil unless blend_data
+
+          if blend_data.key?(:blends)
+            # Array of blended values
+            blend_data[:blends].map do |blend|
+              apply_single_blend(blend, scalars)
+            end
+          else
+            # Single blended value
+            apply_single_blend(blend_data, scalars)
+          end
+        end
+
+        # Apply blend to a single value
+        #
+        # @param blend [Hash] Single blend with :base and :deltas
+        # @param scalars [Array<Float>] Region scalars
+        # @return [Float] Blended value
+        def apply_single_blend(blend, scalars)
+          base = blend[:base].to_f
+          deltas = blend[:deltas]
+
+          # Apply formula: result = base + Σ(delta[i] * scalar[i])
+          result = base
+          deltas.each_with_index do |delta, i|
+            scalar = scalars[i] || 0.0
+            result += delta.to_f * scalar
+          end
+
+          result
+        end
+
+        # Get blended Private DICT values at coordinates
+        #
+        # @param num_axes [Integer] Number of variation axes
+        # @param scalars [Array<Float>] Region scalars
+        # @return [Hash] Private DICT with blended values
+        def blended_dict(num_axes:, scalars:)
+          result = {}
+
+          @private_dict.each do |key, value|
+            if value.is_a?(Array) && blend_value?(value)
+              # Try parsing as blend array
+              blend_data = parse_blend_array(key, num_axes: num_axes)
+              if blend_data
+                result[key] = apply_blend(blend_data, scalars)
+              else
+                # Try as single blend value
+                blend_data = parse_blend_value(key, num_axes: num_axes)
+                result[key] = blend_data ? apply_blend(blend_data, scalars) : value
+              end
+            else
+              # Non-blend value, copy as-is
+              result[key] = value
+            end
+          end
+
+          result
+        end
+
+        # Check if value looks like blend data
+        #
+        # @param value [Object] Value to check
+        # @return [Boolean] True if value could be blend data
+        def blend_value?(value)
+          # Blend values are arrays with multiple elements
+          value.is_a?(Array) && value.size > 1
+        end
+
+        # Rebuild Private DICT with hints injected
+        #
+        # This method prepares Private DICT for rebuilding, preserving
+        # blend operators while incorporating new hint values.
+        #
+        # @param hints [Hash] Hint values to inject
+        # @param num_axes [Integer] Number of variation axes
+        # @return [Hash] Modified Private DICT
+        def rebuild_with_hints(hints, num_axes:)
+          result = @private_dict.dup
+
+          # Inject hint values
+          hints.each do |key, value|
+            if value.is_a?(Hash) && (value.key?(:base) || value.key?("base")) && (value.key?(:deltas) || value.key?("deltas"))
+              # Hint with blend data - normalize and flatten for DICT storage
+              normalized_value = {
+                base: value[:base] || value["base"],
+                deltas: value[:deltas] || value["deltas"]
+              }
+              result[key] = flatten_blend(normalized_value, num_axes: num_axes)
+            else
+              # Simple hint value
+              result[key] = value
+            end
+          end
+
+          result
+        end
+
+        # Flatten blend data to array format
+        #
+        # @param blend_data [Hash] Blend data with :base and :deltas
+        # @param num_axes [Integer] Number of variation axes
+        # @return [Array] Flattened array
+        def flatten_blend(blend_data, num_axes:)
+          if blend_data.key?(:blends)
+            # Array of blends
+            blend_data[:blends].flat_map do |blend|
+              [blend[:base]] + blend[:deltas]
+            end
+          else
+            # Single blend
+            [blend_data[:base]] + blend_data[:deltas]
+          end
+        end
+
+        # Validate blend data structure
+        #
+        # @param num_axes [Integer] Expected number of axes
+        # @return [Array<String>] Validation errors (empty if valid)
+        def validate(num_axes:)
+          errors = []
+
+          @private_dict.each do |key, value|
+            next unless value.is_a?(Array)
+            next unless blend_value?(value)
+
+            # Try parsing as blend array
+            blend_data = parse_blend_array(key, num_axes: num_axes)
+            unless blend_data
+              # Try as single blend value
+              blend_data = parse_blend_value(key, num_axes: num_axes)
+              unless blend_data
+                errors << "Key #{key} has array value that doesn't match " \
+                          "blend format for #{num_axes} axes"
+              end
+            end
+          end
+
+          errors
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Tables
+    class Cff2
+      # Region matcher for calculating variation scalars
+      #
+      # Maps design space coordinates to region scalars based on
+      # the Variable Store region definitions. Each region defines
+      # a range (start, peak, end) for each variation axis.
+      #
+      # Scalar Calculation:
+      # - If coordinate is at peak: scalar = 1.0
+      # - If coordinate is between start and peak: linear interpolation
+      # - If coordinate is between peak and end: linear interpolation
+      # - If coordinate is outside [start, end]: scalar = 0.0
+      #
+      # Reference: OpenType Font Variations Overview
+      # Reference: Adobe Technical Note #5177 (CFF2)
+      #
+      # @example Calculating scalars
+      #   matcher = RegionMatcher.new(regions)
+      #   scalars = matcher.calculate_scalars({ "wght" => 0.5, "wdth" => 0.3 })
+      class RegionMatcher
+        # @return [Array<Hash>] Regions from Variable Store
+        attr_reader :regions
+
+        # Initialize matcher with regions
+        #
+        # @param regions [Array<Hash>] Region definitions from Variable Store
+        def initialize(regions)
+          @regions = regions
+        end
+
+        # Calculate scalars for all regions at given coordinates
+        #
+        # Coordinates are normalized values in the range [-1.0, 1.0]
+        # where 0.0 represents the default/regular style.
+        #
+        # @param coordinates [Array<Float>] Normalized coordinates per axis
+        # @return [Array<Float>] Scalars for each region
+        def calculate_scalars(coordinates)
+          @regions.map do |region|
+            calculate_region_scalar(region, coordinates)
+          end
+        end
+
+        # Calculate scalar for a single region
+        #
+        # The scalar is the product of scalars for all axes in the region.
+        # If any axis has scalar 0.0, the entire region scalar is 0.0.
+        #
+        # @param region [Hash] Region definition
+        # @param coordinates [Array<Float>] Normalized coordinates per axis
+        # @return [Float] Scalar for the region (0.0 to 1.0)
+        def calculate_region_scalar(region, coordinates)
+          axes = region[:axes]
+
+          # Multiply scalars for all axes
+          scalar = 1.0
+          axes.each_with_index do |axis, i|
+            coord = coordinates[i] || 0.0
+            axis_scalar = calculate_axis_scalar(axis, coord)
+            scalar *= axis_scalar
+
+            # Early exit if any axis is out of range
+            return 0.0 if axis_scalar.zero?
+          end
+
+          scalar
+        end
+
+        # Calculate scalar for a single axis
+        #
+        # @param axis [Hash] Axis definition with :start_coord, :peak_coord, :end_coord
+        # @param coordinate [Float] Normalized coordinate for this axis
+        # @return [Float] Scalar for this axis (0.0 to 1.0)
+        def calculate_axis_scalar(axis, coordinate)
+          start_coord = axis[:start_coord]
+          peak_coord = axis[:peak_coord]
+          end_coord = axis[:end_coord]
+
+          # Outside the region
+          return 0.0 if coordinate < start_coord || coordinate > end_coord
+
+          # At or beyond peak
+          return 1.0 if coordinate == peak_coord
+
+          # Between start and peak
+          if coordinate < peak_coord
+            # Linear interpolation: (coord - start) / (peak - start)
+            range = peak_coord - start_coord
+            return 1.0 if range.zero? # Avoid division by zero
+
+            (coordinate - start_coord) / range
+          else
+            # Between peak and end
+            # Linear interpolation: (end - coord) / (end - peak)
+            range = end_coord - peak_coord
+            return 1.0 if range.zero? # Avoid division by zero
+
+            (end_coord - coordinate) / range
+          end
+        end
+
+        # Check if coordinates are within any region
+        #
+        # @param coordinates [Array<Float>] Normalized coordinates
+        # @return [Boolean] True if coordinates activate any region
+        def coordinates_active?(coordinates)
+          scalars = calculate_scalars(coordinates)
+          scalars.any?(&:positive?)
+        end
+
+        # Get active regions for coordinates
+        #
+        # Returns indices of regions that have non-zero scalars
+        #
+        # @param coordinates [Array<Float>] Normalized coordinates
+        # @return [Array<Integer>] Indices of active regions
+        def active_regions(coordinates)
+          scalars = calculate_scalars(coordinates)
+          scalars.each_with_index.select { |scalar, _| scalar.positive? }
+                 .map(&:last)
+        end
+
+        # Get scalar for specific region index
+        #
+        # @param region_index [Integer] Region index
+        # @param coordinates [Array<Float>] Normalized coordinates
+        # @return [Float, nil] Scalar for the region, or nil if index invalid
+        def scalar_for_region(region_index, coordinates)
+          return nil if region_index >= @regions.size
+
+          region = @regions[region_index]
+          calculate_region_scalar(region, coordinates)
+        end
+
+        # Validate region structure
+        #
+        # @return [Array<String>] Array of validation errors (empty if valid)
+        def validate
+          errors = []
+
+          @regions.each_with_index do |region, i|
+            axes = region[:axes]
+            unless axes.is_a?(Array)
+              errors << "Region #{i} has invalid axes (not an array)"
+              next
+            end
+
+            axes.each_with_index do |axis, j|
+              unless axis.is_a?(Hash)
+                errors << "Region #{i}, axis #{j} is not a hash"
+                next
+              end
+
+              # Check required keys
+              %i[start_coord peak_coord end_coord].each do |key|
+                unless axis.key?(key)
+                  errors << "Region #{i}, axis #{j} missing #{key}"
+                end
+              end
+
+              # Validate coordinate ordering
+              if axis[:start_coord] && axis[:peak_coord] && axis[:end_coord]
+                start = axis[:start_coord]
+                peak = axis[:peak_coord]
+                ending = axis[:end_coord]
+
+                unless start <= peak && peak <= ending
+                  errors << "Region #{i}, axis #{j} has invalid ordering: " \
+                            "#{start} > #{peak} > #{ending}"
+                end
+              end
+            end
+          end
+
+          errors
+        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] || @regions.first[:axes]&.size || 0
+        end
+
+        # Check if matcher has regions
+        #
+        # @return [Boolean] True if regions are present
+        def has_regions?
+          !@regions.empty?
+        end
+      end
+    end
+  end
+end