fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variation/blend_applier.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require_relative "interpolator"
+
+module Fontisan
+  module Variation
+    # Applies CFF2 blend operators during CharString execution
+    #
+    # The blend operator in CFF2 CharStrings provides variation support by
+    # blending base values with deltas based on design space coordinates.
+    #
+    # Blend Format:
+    #   v1 Δv1_axis1 Δv1_axis2 ... v2 Δv2_axis1 ... K N blend
+    #
+    # Where:
+    # - K = number of values to blend
+    # - N = number of axes
+    # - Each value has N deltas (one per axis)
+    #
+    # The applier calculates blended values:
+    #   result = base + Σ(delta_i × scalar_i)
+    #
+    # Reference: Adobe Technical Note #5177 (CFF2 specification)
+    #
+    # @example Applying blend operators
+    #   applier = Fontisan::Variation::BlendApplier.new(interpolator)
+    #   blended = applier.apply_blend(base: 100, deltas: [10, 5], scalars: [0.8, 0.5])
+    #   # => 110.5 (100 + 10*0.8 + 5*0.5)
+    class BlendApplier
+      # @return [Interpolator] Coordinate interpolator
+      attr_reader :interpolator
+
+      # @return [Array<Float>] Current variation scalars
+      attr_reader :scalars
+
+      # Initialize blend applier
+      #
+      # @param interpolator [Interpolator] Coordinate interpolator
+      # @param coordinates [Hash<String, Float>] Design space coordinates
+      def initialize(interpolator, coordinates = {})
+        @interpolator = interpolator
+        @coordinates = coordinates
+        @scalars = []
+      end
+
+      # Set design space coordinates
+      #
+      # Updates the variation scalars based on new coordinates.
+      #
+      # @param coordinates [Hash<String, Float>] Axis tag => value
+      # @param axes [Array] Variation axes from fvar
+      def set_coordinates(coordinates, axes)
+        @coordinates = coordinates
+        @scalars = calculate_scalars(axes)
+      end
+
+      # Apply blend operation
+      #
+      # Blends base value with deltas using variation scalars.
+      #
+      # @param base [Numeric] Base value
+      # @param deltas [Array<Numeric>] Delta values (one per axis)
+      # @param num_axes [Integer] Number of axes (for validation)
+      # @return [Float] Blended value
+      # @raise [InvalidVariationDataError] If delta count doesn't match axis count
+      def apply_blend(base:, deltas:, num_axes: nil)
+        # Validate delta count matches axes
+        if num_axes && deltas.length != num_axes
+          raise InvalidVariationDataError.new(
+            message: "Blend delta count (#{deltas.length}) doesn't match axes (#{num_axes})",
+            details: {
+              delta_count: deltas.length,
+              expected_axes: num_axes,
+              base_value: base,
+            },
+          )
+        end
+
+        # Start with base value
+        result = base.to_f
+
+        # Apply each delta with its scalar
+        deltas.each_with_index do |delta, index|
+          scalar = @scalars[index] || 0.0
+          result += delta.to_f * scalar
+        end
+
+        result
+      end
+
+      # Apply multiple blend operations
+      #
+      # Processes multiple values with their deltas.
+      #
+      # @param blends [Array<Hash>] Array of { base:, deltas: } hashes
+      # @param num_axes [Integer] Number of axes
+      # @return [Array<Float>] Blended values
+      def apply_blends(blends, num_axes)
+        blends.map do |blend|
+          apply_blend(
+            base: blend[:base],
+            deltas: blend[:deltas],
+            num_axes: num_axes,
+          )
+        end
+      end
+
+      # Apply blend operator from CharString stack
+      #
+      # Processes blend operator arguments from CharString execution.
+      #
+      # @param operands [Array<Numeric>] Blend operands from stack
+      # @param num_values [Integer] K (number of values to blend)
+      # @param num_axes [Integer] N (number of axes)
+      # @return [Array<Float>] Blended values
+      # @raise [InvalidVariationDataError] If operand count doesn't match expected format
+      def apply_blend_operands(operands, num_values, num_axes)
+        # Expected operands: K * (N + 1)
+        expected_count = num_values * (num_axes + 1)
+
+        if operands.length != expected_count
+          raise InvalidVariationDataError.new(
+            message: "Blend operand count mismatch: expected #{expected_count}, got #{operands.length}",
+            details: {
+              operand_count: operands.length,
+              expected_count: expected_count,
+              num_values: num_values,
+              num_axes: num_axes,
+            },
+          )
+        end
+
+        blended_values = []
+
+        num_values.times do |i|
+          offset = i * (num_axes + 1)
+          base = operands[offset]
+          deltas = operands[offset + 1, num_axes] || []
+
+          blended_values << apply_blend(
+            base: base,
+            deltas: deltas,
+            num_axes: num_axes,
+          )
+        end
+
+        blended_values
+      end
+
+      # Calculate scalars for current coordinates
+      #
+      # Converts design space coordinates to normalized scalars [-1, 1].
+      #
+      # @param axes [Array] Variation axes
+      # @return [Array<Float>] Scalar for each axis
+      def calculate_scalars(axes)
+        axes.map do |axis|
+          coord = @coordinates[axis.axis_tag] || axis.default_value
+          @interpolator.normalize_coordinate(coord, axis.axis_tag)
+        end
+      end
+
+      # Check if coordinates are at default
+      #
+      # @return [Boolean] True if all scalars are zero
+      def at_default?
+        @scalars.all?(&:zero?)
+      end
+
+      # Get blended point coordinates
+      #
+      # Applies blend to X and Y coordinates simultaneously.
+      #
+      # @param base_x [Numeric] Base X coordinate
+      # @param base_y [Numeric] Base Y coordinate
+      # @param deltas_x [Array<Numeric>] X deltas
+      # @param deltas_y [Array<Numeric>] Y deltas
+      # @return [Array<Float>] [blended_x, blended_y]
+      def blend_point(base_x, base_y, deltas_x, deltas_y)
+        [
+          apply_blend(base: base_x, deltas: deltas_x),
+          apply_blend(base: base_y, deltas: deltas_y),
+        ]
+      end
+
+      # Convert blend data to static values
+      #
+      # For instance generation, replaces blend operators with static values.
+      #
+      # @param blend_data [Array<Hash>] Blend operations data
+      # @return [Array<Float>] Static blended values
+      def blend_to_static(blend_data)
+        blend_data.flat_map do |blend_op|
+          apply_blends(blend_op[:blends], blend_op[:num_axes])
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/variation/cache.rb

@@ -0,0 +1,298 @@
+# frozen_string_literal: true
+
+require_relative "cache_key_builder"
+
+module Fontisan
+  module Variation
+    # Caches variation calculations for performance
+    #
+    # This class implements a caching layer for expensive variation calculations
+    # to significantly improve instance generation performance. It caches:
+    # - Normalized scalars per coordinate set
+    # - Interpolated values
+    # - Instance generation results
+    # - Region matches
+    #
+    # Cache strategies:
+    # 1. LRU (Least Recently Used) for memory management
+    # 2. Coordinate-based keys for scalar caching
+    # 3. Invalidation on font modification
+    # 4. Optional persistent caching across sessions
+    #
+    # @example Using the cache with instance generation
+    #   cache = Fontisan::Variation::Cache.new(max_size: 100)
+    #   scalars = cache.fetch_scalars(coordinates, axes) do
+    #     calculate_scalars(coordinates, axes)
+    #   end
+    #
+    # @example Cache statistics
+    #   cache.statistics
+    #   # => { hits: 150, misses: 50, hit_rate: 0.75 }
+    class Cache
+      # @return [Integer] Maximum cache size
+      attr_reader :max_size
+
+      # @return [Hash] Cache statistics
+      attr_reader :stats
+
+      # Initialize cache
+      #
+      # @param max_size [Integer] Maximum number of entries (default: 1000)
+      # @param ttl [Integer, nil] Time-to-live in seconds (nil for no expiration)
+      def initialize(max_size: 1000, ttl: nil)
+        @max_size = max_size
+        @ttl = ttl
+        @cache = {}
+        @access_times = {}
+        @stats = {
+          hits: 0,
+          misses: 0,
+          evictions: 0,
+          invalidations: 0,
+        }
+      end
+
+      # Fetch or compute scalars for coordinates
+      #
+      # @param coordinates [Hash<String, Float>] Design space coordinates
+      # @param axes [Array] Variation axes
+      # @yield Block to calculate scalars if not cached
+      # @return [Array<Float>] Cached or computed scalars
+      def fetch_scalars(coordinates, axes, &)
+        key = CacheKeyBuilder.scalars_key(coordinates, axes)
+        fetch(key, &)
+      end
+
+      # Fetch or compute interpolated value
+      #
+      # @param base_value [Numeric] Base value
+      # @param deltas [Array<Numeric>] Delta values
+      # @param scalars [Array<Float>] Region scalars
+      # @yield Block to calculate value if not cached
+      # @return [Float] Cached or computed value
+      def fetch_interpolated(base_value, deltas, scalars, &)
+        key = CacheKeyBuilder.interpolation_key(base_value, deltas, scalars)
+        fetch(key, &)
+      end
+
+      # Fetch or compute instance generation result
+      #
+      # @param font_checksum [String] Font identifier
+      # @param coordinates [Hash<String, Float>] Instance coordinates
+      # @yield Block to generate instance if not cached
+      # @return [Hash] Cached or generated instance tables
+      def fetch_instance(font_checksum, coordinates, &)
+        key = CacheKeyBuilder.instance_key(font_checksum, coordinates)
+        fetch(key, &)
+      end
+
+      # Fetch or compute region matches
+      #
+      # @param coordinates [Hash<String, Float>] Design space coordinates
+      # @param regions [Array] Variation regions
+      # @yield Block to calculate matches if not cached
+      # @return [Array] Cached or computed region matches
+      def fetch_region_matches(coordinates, regions, &)
+        key = CacheKeyBuilder.region_matches_key(coordinates, regions)
+        fetch(key, &)
+      end
+
+      # Generic fetch with caching
+      #
+      # @param key [String] Cache key
+      # @yield Block to compute value if not cached
+      # @return [Object] Cached or computed value
+      def fetch(key)
+        if cached?(key)
+          @stats[:hits] += 1
+          touch(key)
+          return @cache[key][:value]
+        end
+
+        @stats[:misses] += 1
+        value = yield
+        store(key, value)
+        value
+      end
+
+      # Check if key is cached and valid
+      #
+      # @param key [String] Cache key
+      # @return [Boolean] True if cached and valid
+      def cached?(key)
+        return false unless @cache.key?(key)
+        return false if expired?(key)
+
+        true
+      end
+
+      # Store value in cache
+      #
+      # @param key [String] Cache key
+      # @param value [Object] Value to store
+      def store(key, value)
+        evict_if_needed
+
+        @cache[key] = {
+          value: value,
+          created_at: Time.now,
+        }
+        touch(key)
+      end
+
+      # Clear entire cache
+      def clear
+        @cache.clear
+        @access_times.clear
+        @stats[:invalidations] += 1
+      end
+
+      # Invalidate specific key
+      #
+      # @param key [String] Cache key to invalidate
+      def invalidate(key)
+        @cache.delete(key)
+        @access_times.delete(key)
+        @stats[:invalidations] += 1
+      end
+
+      # Invalidate keys matching pattern
+      #
+      # @param pattern [Regexp] Pattern to match keys
+      def invalidate_matching(pattern)
+        keys = @cache.keys.select { |k| k.match?(pattern) }
+        keys.each { |k| invalidate(k) }
+      end
+
+      # Get cache statistics
+      #
+      # @return [Hash] Statistics including hit rate
+      def statistics
+        total = @stats[:hits] + @stats[:misses]
+        hit_rate = total.zero? ? 0.0 : @stats[:hits].to_f / total
+
+        @stats.merge(
+          total_requests: total,
+          hit_rate: hit_rate,
+          size: @cache.size,
+          max_size: @max_size,
+        )
+      end
+
+      # Get cache size
+      #
+      # @return [Integer] Number of cached entries
+      def size
+        @cache.size
+      end
+
+      # Check if cache is empty
+      #
+      # @return [Boolean] True if empty
+      def empty?
+        @cache.empty?
+      end
+
+      # Check if cache is full
+      #
+      # @return [Boolean] True if at capacity
+      def full?
+        @cache.size >= @max_size
+      end
+
+      private
+
+      # Check if entry has expired
+      #
+      # @param key [String] Cache key
+      # @return [Boolean] True if expired
+      def expired?(key)
+        return false unless @ttl
+
+        entry = @cache[key]
+        return true unless entry
+
+        Time.now - entry[:created_at] > @ttl
+      end
+
+      # Update access time for LRU
+      #
+      # @param key [String] Cache key
+      def touch(key)
+        @access_times[key] = Time.now
+      end
+
+      # Evict entries if cache is full
+      def evict_if_needed
+        return unless full?
+
+        # Remove least recently used entry
+        lru_key = @access_times.min_by { |_k, v| v }&.first
+        return unless lru_key
+
+        @cache.delete(lru_key)
+        @access_times.delete(lru_key)
+        @stats[:evictions] += 1
+      end
+    end
+
+    # Thread-safe cache wrapper
+    #
+    # Wraps Cache with Mutex for thread-safe operations.
+    class ThreadSafeCache < Cache
+      def initialize(max_size: 1000, ttl: nil)
+        super
+        @mutex = Mutex.new
+      end
+
+      def fetch(key)
+        # Check cache without entering critical section for computation
+        @mutex.synchronize do
+          if cached?(key)
+            @stats[:hits] += 1
+            touch(key)
+            return @cache[key][:value]
+          end
+        end
+
+        # Compute value outside of mutex
+        value = yield
+
+        # Store result
+        @mutex.synchronize do
+          evict_if_needed
+          @cache[key] = {
+            value: value,
+            created_at: Time.now,
+          }
+          touch(key)
+        end
+
+        value
+      end
+
+      def store(key, value)
+        @mutex.synchronize do
+          evict_if_needed
+          @cache[key] = {
+            value: value,
+            created_at: Time.now,
+          }
+          touch(key)
+        end
+      end
+
+      def clear
+        @mutex.synchronize { super }
+      end
+
+      def invalidate(key)
+        @mutex.synchronize { super }
+      end
+
+      def statistics
+        @mutex.synchronize { super }
+      end
+    end
+  end
+end

data/lib/fontisan/variation/cache_key_builder.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Variation
+    # Builds cache keys for variation calculations
+    #
+    # This class centralizes cache key generation with consistent formatting
+    # and efficient string construction. All variation caches should use
+    # this builder to ensure key compatibility.
+    #
+    # @example Building cache keys
+    #   builder = CacheKeyBuilder
+    #
+    #   # Scalars key
+    #   key = builder.scalars_key(coordinates, axes)
+    #
+    #   # Instance key
+    #   key = builder.instance_key(font_checksum, coordinates)
+    class CacheKeyBuilder
+      class << self
+        # Build cache key for scalars
+        #
+        # Generates a deterministic key based on axis tags and coordinate values.
+        # Axes are sorted to ensure consistent keys regardless of hash order.
+        #
+        # @param coordinates [Hash<String, Float>] Design space coordinates
+        # @param axes [Array<VariationAxisRecord>] Variation axes
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.scalars_key(
+        #     { "wght" => 700, "wdth" => 100 },
+        #     axes
+        #   )
+        #   # => "scalars:wdth,wght:100.0,700.0"
+        def scalars_key(coordinates, axes)
+          axis_tags = axes.map(&:axis_tag).sort
+          coord_values = axis_tags.map { |tag| coordinates[tag] || 0.0 }
+          "scalars:#{axis_tags.join(',')}:#{coord_values.join(',')}"
+        end
+
+        # Build cache key for interpolated value
+        #
+        # Generates key based on base value, deltas, and scalars.
+        # Useful for caching individual interpolation results.
+        #
+        # @param base_value [Numeric] Base value
+        # @param deltas [Array<Numeric>] Delta values
+        # @param scalars [Array<Float>] Region scalars
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.interpolation_key(100, [10, 5], [0.8, 0.5])
+        #   # => "interp:100:10,5:0.8,0.5"
+        def interpolation_key(base_value, deltas, scalars)
+          "interp:#{base_value}:#{deltas.join(',')}:#{scalars.join(',')}"
+        end
+
+        # Build cache key for font instance
+        #
+        # Generates key for entire instance generation result.
+        # Coordinates are sorted to ensure consistency.
+        #
+        # @param font_checksum [String] Font identifier
+        # @param coordinates [Hash<String, Float>] Instance coordinates
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.instance_key("font_123", { "wght" => 700 })
+        #   # => "instance:font_123:{\"wght\"=>700.0}"
+        def instance_key(font_checksum, coordinates)
+          sorted_coords = coordinates.sort.to_h
+          "instance:#{font_checksum}:#{sorted_coords}"
+        end
+
+        # Build cache key for region matches
+        #
+        # Generates key based on coordinates and region hash.
+        # Region hash is used to quickly identify region set without
+        # serializing entire region data.
+        #
+        # @param coordinates [Hash<String, Float>] Design space coordinates
+        # @param regions [Array<Hash>] Variation regions
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.region_matches_key(coords, regions)
+        #   # => "regions:{\"wght\"=>700.0}:12345678"
+        def region_matches_key(coordinates, regions)
+          sorted_coords = coordinates.sort.to_h
+          region_hash = regions.hash
+          "regions:#{sorted_coords}:#{region_hash}"
+        end
+
+        # Build cache key for glyph deltas
+        #
+        # Generates key for cached glyph delta application results.
+        #
+        # @param glyph_id [Integer] Glyph ID
+        # @param coordinates [Hash<String, Float>] Design space coordinates
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.glyph_deltas_key(42, { "wght" => 700 })
+        #   # => "glyph:42:{\"wght\"=>700.0}"
+        def glyph_deltas_key(glyph_id, coordinates)
+          sorted_coords = coordinates.sort.to_h
+          "glyph:#{glyph_id}:#{sorted_coords}"
+        end
+
+        # Build cache key for metrics deltas
+        #
+        # Generates key for cached metrics variation results.
+        #
+        # @param metrics_type [String] Metrics table tag (HVAR, VVAR, MVAR)
+        # @param glyph_id [Integer, nil] Glyph ID (nil for font-wide metrics)
+        # @param coordinates [Hash<String, Float>] Design space coordinates
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.metrics_deltas_key("HVAR", 42, coords)
+        #   # => "metrics:HVAR:42:{\"wght\"=>700.0}"
+        def metrics_deltas_key(metrics_type, glyph_id, coordinates)
+          sorted_coords = coordinates.sort.to_h
+          glyph_part = glyph_id ? ":#{glyph_id}" : ""
+          "metrics:#{metrics_type}#{glyph_part}:#{sorted_coords}"
+        end
+
+        # Build cache key for blend operations
+        #
+        # Generates key for CFF2 blend operator results.
+        #
+        # @param blend_index [Integer] Blend operation index
+        # @param scalars [Array<Float>] Variation scalars
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.blend_key(0, [0.8, 0.5])
+        #   # => "blend:0:0.8,0.5"
+        def blend_key(blend_index, scalars)
+          "blend:#{blend_index}:#{scalars.join(',')}"
+        end
+
+        # Build custom cache key
+        #
+        # Generates key with custom prefix and components.
+        # Use for specialized caching needs.
+        #
+        # @param prefix [String] Key prefix
+        # @param components [Array] Key components (will be joined with :)
+        # @return [String] Cache key
+        #
+        # @example
+        #   key = CacheKeyBuilder.custom_key("mydata", [font_id, value1, value2])
+        #   # => "mydata:font_123:100:200"
+        def custom_key(prefix, *components)
+          "#{prefix}:#{components.join(':')}"
+        end
+      end
+    end
+  end
+end