fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variation/instance_generator.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require_relative "interpolator"
+require_relative "region_matcher"
+require_relative "metrics_adjuster"
+require_relative "variation_context"
+require_relative "table_accessor"
+
+module Fontisan
+  module Variation
+    # Generates static font instances from variable fonts
+    #
+    # This class creates static font instances by applying variation deltas
+    # at specific design space coordinates. It supports both TrueType (gvar)
+    # and PostScript (CFF2) variable fonts.
+    #
+    # Process:
+    # 1. Extract variation data (axes, deltas, regions)
+    # 2. Calculate interpolation scalars for given coordinates
+    # 3. Apply deltas to outlines (gvar or CFF2)
+    # 4. Apply deltas to metrics (HVAR, VVAR, MVAR)
+    # 5. Remove variation tables to create static font
+    #
+    # @example Generating an instance at specific coordinates
+    #   generator = Fontisan::Variation::InstanceGenerator.new(font, { "wght" => 700.0 })
+    #   instance_tables = generator.generate
+    #
+    # @example Generating a named instance
+    #   generator = Fontisan::Variation::InstanceGenerator.new(font)
+    #   instance_tables = generator.generate_named_instance(0)
+    class InstanceGenerator
+      include TableAccessor
+
+      # @return [TrueTypeFont, OpenTypeFont] Variable font
+      attr_reader :font
+
+      # @return [Hash<String, Float>] Design space coordinates
+      attr_reader :coordinates
+
+      # @return [VariationContext] Variation context
+      attr_reader :context
+
+      # Initialize generator with font and optional coordinates
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font
+      # @param coordinates [Hash<String, Float>] Design space coordinates (axis tag => value)
+      # @param options [Hash] Options
+      # @option options [Boolean] :skip_validation Skip context validation (default: false)
+      def initialize(font, coordinates = {}, options = {})
+        @font = font
+        @coordinates = coordinates
+
+        # Initialize variation context
+        @context = VariationContext.new(@font)
+        @context.validate! unless options[:skip_validation]
+
+        # Initialize table cache for lazy loading
+        @variation_tables = {}
+      end
+
+      # Generate static font instance
+      #
+      # Applies variation deltas and returns static font tables.
+      #
+      # @return [Hash<String, String>] Map of table tags to binary data
+      def generate
+        # Start with base font tables
+        tables = @font.table_data.dup
+
+        # Determine variation type
+        if has_variation_table?("gvar")
+          # TrueType outlines with gvar
+          apply_gvar_deltas(tables)
+        elsif has_variation_table?("CFF2")
+          # PostScript outlines with CFF2 blend
+          apply_cff2_blend(tables)
+        end
+
+        # Apply metrics variations if present
+        apply_metrics_deltas(tables) if @context.has_metrics_variations?
+
+        # Remove variation-specific tables to create static font
+        remove_variation_tables(tables)
+
+        tables
+      end
+
+      # Generate a named instance
+      #
+      # @param instance_index [Integer] Index of named instance in fvar table
+      # @return [Hash<String, String>] Map of table tags to binary data
+      def generate_named_instance(instance_index)
+        # Extract instance coordinates from fvar
+        return generate if instance_index.nil? || !@context.fvar
+
+        instances = @context.fvar.instances
+        return generate if instance_index >= instances.length
+
+        instance = instances[instance_index]
+        @coordinates = build_coordinates_from_instance(instance, @context.axes)
+
+        generate
+      end
+
+      # Apply gvar deltas to TrueType outlines
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_gvar_deltas(_tables)
+        gvar = variation_table("gvar")
+        glyf = @font.table("glyf")
+        return unless gvar && glyf
+
+        # Get glyph count
+        maxp = @font.table("maxp")
+        glyph_count = maxp ? maxp.num_glyphs : gvar.glyph_count
+
+        # Process each glyph
+        glyph_count.times do |glyph_id|
+          apply_glyph_deltas(glyph_id, gvar, glyf)
+        end
+
+        # Rebuild glyf and loca tables with adjusted outlines
+        # This is a placeholder - full implementation would reconstruct tables
+      end
+
+      # Apply deltas to a specific glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param gvar [Gvar] Gvar table
+      # @param glyf [Glyf] Glyf table
+      def apply_glyph_deltas(glyph_id, gvar, _glyf)
+        # Get tuple variations for this glyph
+        tuple_data = gvar.glyph_tuple_variations(glyph_id)
+        return unless tuple_data
+
+        # Match tuples to current coordinates
+        matches = @context.region_matcher.match_tuples(
+          coordinates: @coordinates,
+          tuples: tuple_data[:tuples],
+        )
+
+        nil if matches.empty?
+
+        # Get base glyph outline
+        # Apply matched deltas with their scalars
+        # This is a placeholder - full implementation would:
+        # 1. Parse glyph outline points
+        # 2. Parse delta data for each tuple
+        # 3. Apply: new_point = base_point + Σ(delta * scalar)
+        # 4. Update glyph outline
+      end
+
+      # Apply CFF2 blend operators
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_cff2_blend(_tables)
+        cff2 = variation_table("CFF2")
+        return unless cff2
+
+        # Set number of axes for CFF2
+        cff2.num_axes = @context.axis_count
+
+        # Process each glyph's CharString
+        glyph_count = cff2.glyph_count
+        return if glyph_count.zero?
+
+        # Calculate variation scalars once
+        calculate_variation_scalars
+
+        # Apply blend to each glyph
+        # This is a placeholder - full implementation would:
+        # 1. Parse CharString with blend operators
+        # 2. Apply scalars to blend operands
+        # 3. Rebuild CharStrings without blend operators
+        # 4. Update CFF2 table
+      end
+
+      # Calculate variation scalars for current coordinates
+      #
+      # @return [Array<Float>] Scalars for each axis
+      def calculate_variation_scalars
+        @context.axes.map do |axis|
+          coord = @coordinates[axis.axis_tag] || axis.default_value
+          @context.interpolator.normalize_coordinate(coord, axis.axis_tag)
+        end
+      end
+
+      # Apply metrics variations
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_metrics_deltas(tables)
+        # Apply HVAR (horizontal metrics)
+        apply_hvar_deltas(tables) if has_variation_table?("HVAR")
+
+        # Apply VVAR (vertical metrics)
+        apply_vvar_deltas(tables) if has_variation_table?("VVAR")
+
+        # Apply MVAR (font-wide metrics)
+        apply_mvar_deltas(tables) if has_variation_table?("MVAR")
+      end
+
+      # Apply HVAR deltas to horizontal metrics
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_hvar_deltas(_tables)
+        adjuster = MetricsAdjuster.new(@font, @context.interpolator)
+        adjuster.apply_hvar_deltas(@coordinates)
+      end
+
+      # Apply VVAR deltas to vertical metrics
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_vvar_deltas(_tables)
+        adjuster = MetricsAdjuster.new(@font, @context.interpolator)
+        adjuster.apply_vvar_deltas(@coordinates)
+      end
+
+      # Apply MVAR deltas to font-wide metrics
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def apply_mvar_deltas(_tables)
+        adjuster = MetricsAdjuster.new(@font, @context.interpolator)
+        adjuster.apply_mvar_deltas(@coordinates)
+      end
+
+      # Remove variation tables from static font
+      #
+      # @param tables [Hash<String, String>] Font tables
+      def remove_variation_tables(tables)
+        variation_tables = %w[fvar gvar cvar HVAR VVAR MVAR avar STAT]
+        variation_tables.each { |tag| tables.delete(tag) }
+      end
+
+      # Interpolate a single value
+      #
+      # @param base_value [Numeric] Base value
+      # @param deltas [Array<Numeric>] Delta values
+      # @param scalars [Array<Float>] Region scalars
+      # @return [Float] Interpolated value
+      def interpolate_value(base_value, deltas, scalars)
+        @context.interpolator.interpolate_value(base_value, deltas, scalars)
+      end
+
+      # Interpolate a point
+      #
+      # @param base_point [Hash] Base point with :x and :y
+      # @param delta_points [Array<Hash>] Delta points
+      # @param scalars [Array<Float>] Region scalars
+      # @return [Hash] Interpolated point
+      def interpolate_point(base_point, delta_points, scalars)
+        @context.interpolator.interpolate_point(base_point, delta_points, scalars)
+      end
+
+      private
+
+      # Build coordinates hash from instance
+      #
+      # @param instance [Hash] Instance data from fvar
+      # @param axes [Array<VariationAxisRecord>] Variation axes
+      # @return [Hash<String, Float>] Coordinates hash
+      def build_coordinates_from_instance(instance, axes)
+        coordinates = {}
+        instance[:coordinates].each_with_index do |value, index|
+          next if index >= axes.length
+
+          axis = axes[index]
+          coordinates[axis.axis_tag] = value
+        end
+        coordinates
+      end
+    end
+  end
+end

data/lib/fontisan/variation/interpolator.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Variation
+    # Coordinate interpolator for variable fonts
+    #
+    # This class interpolates values in the variation design space by
+    # calculating scalars based on the current coordinates and variation
+    # regions/tuples.
+    #
+    # Interpolation Process:
+    # 1. Normalize user coordinates to [-1, 1] range based on axis min/default/max
+    # 2. For each variation region, calculate a scalar that represents how much
+    #    that region contributes at the current coordinates
+    # 3. Apply the scalars to deltas to get the final interpolated value
+    #
+    # Region Scalar Calculation:
+    # For each axis, given a region [start, peak, end] and coordinate c:
+    # - If c < start or c > end: scalar = 0 (outside region)
+    # - If c in [start, peak]: scalar = (c - start) / (peak - start)
+    # - If c in [peak, end]: scalar = (end - c) / (end - peak)
+    # - If c == peak: scalar = 1 (at peak)
+    #
+    # For multi-axis regions, multiply the per-axis scalars together.
+    #
+    # Reference: OpenType Font Variations specification
+    #
+    # @example Interpolating a coordinate
+    #   interpolator = Interpolator.new(axes)
+    #   scalar = interpolator.calculate_scalar(
+    #     coordinates: { "wght" => 600.0 },
+    #     region: { "wght" => { start: 400, peak: 700, end: 900 } }
+    #   )
+    #   # => 0.666... (normalized position between 400 and 700)
+    class Interpolator
+      # @return [Array<VariationAxisRecord>] Variation axes
+      attr_reader :axes
+
+      # Initialize interpolator
+      #
+      # @param axes [Array<VariationAxisRecord>] Variation axes from fvar table
+      def initialize(axes)
+        @axes = axes || []
+      end
+
+      # Normalize a coordinate value to [-1, 1] range
+      #
+      # @param value [Float] User-space coordinate value
+      # @param axis_tag [String] Axis tag (e.g., "wght", "wdth")
+      # @return [Float] Normalized coordinate in [-1, 1]
+      def normalize_coordinate(value, axis_tag)
+        axis = find_axis(axis_tag)
+        return 0.0 unless axis
+
+        # Clamp to axis range
+        value = [[value, axis.min_value].max, axis.max_value].min
+
+        # Normalize to [-1, 1]
+        if value < axis.default_value
+          # Normalize between min and default (maps to -1..0)
+          range = axis.default_value - axis.min_value
+          return -1.0 if range.zero?
+
+          (value - axis.default_value) / range
+        elsif value > axis.default_value
+          # Normalize between default and max (maps to 0..1)
+          range = axis.max_value - axis.default_value
+          return 1.0 if range.zero?
+
+          (value - axis.default_value) / range
+        else
+          # At default value
+          0.0
+        end
+      end
+
+      # Normalize all coordinates
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @return [Hash<String, Float>] Normalized coordinates
+      def normalize_coordinates(coordinates)
+        result = {}
+        @axes.each do |axis|
+          tag = axis.axis_tag
+          value = coordinates[tag] || axis.default_value
+          result[tag] = normalize_coordinate(value, tag)
+        end
+        result
+      end
+
+      # Calculate scalar for a single axis region
+      #
+      # @param coord [Float] Normalized coordinate value [-1, 1]
+      # @param region [Hash] Region definition with :start, :peak, :end
+      # @return [Float] Scalar value [0, 1]
+      def calculate_axis_scalar(coord, region)
+        start_val = region[:start] || -1.0
+        peak = region[:peak] || 0.0
+        end_val = region[:end] || 1.0
+
+        # Outside region
+        return 0.0 if coord < start_val || coord > end_val
+
+        # At or beyond peak
+        return 1.0 if coord == peak
+
+        # Between start and peak
+        if coord < peak
+          range = peak - start_val
+          return 1.0 if range.zero?
+
+          (coord - start_val) / range
+        else
+          # Between peak and end
+          range = end_val - peak
+          return 1.0 if range.zero?
+
+          (end_val - coord) / range
+        end
+      end
+
+      # Calculate scalar for a multi-axis region
+      #
+      # For multi-axis regions, the final scalar is the product of per-axis scalars.
+      #
+      # @param coordinates [Hash<String, Float>] Normalized coordinates
+      # @param region [Hash<String, Hash>] Region definition per axis
+      # @return [Float] Combined scalar [0, 1]
+      def calculate_region_scalar(coordinates, region)
+        scalar = 1.0
+
+        region.each do |axis_tag, axis_region|
+          coord = coordinates[axis_tag] || 0.0
+          axis_scalar = calculate_axis_scalar(coord, axis_region)
+
+          # If any axis has zero scalar, entire region has zero contribution
+          return 0.0 if axis_scalar.zero?
+
+          scalar *= axis_scalar
+        end
+
+        scalar
+      end
+
+      # Calculate scalars for all regions
+      #
+      # @param coordinates [Hash<String, Float>] User-space coordinates
+      # @param regions [Array<Hash>] Array of region definitions
+      # @return [Array<Float>] Scalars for each region
+      def calculate_scalars(coordinates, regions)
+        # Normalize coordinates first
+        normalized = normalize_coordinates(coordinates)
+
+        # Calculate scalar for each region
+        regions.map do |region|
+          calculate_region_scalar(normalized, region)
+        end
+      end
+
+      # Interpolate a value using deltas
+      #
+      # @param base_value [Numeric] Base value
+      # @param deltas [Array<Numeric>] Delta values (one per region)
+      # @param scalars [Array<Float>] Region scalars (one per region)
+      # @return [Float] Interpolated value
+      def interpolate_value(base_value, deltas, scalars)
+        result = base_value.to_f
+
+        deltas.each_with_index do |delta, index|
+          scalar = scalars[index] || 0.0
+          result += delta.to_f * scalar
+        end
+
+        result
+      end
+
+      # Interpolate a point (x, y coordinates)
+      #
+      # @param base_point [Hash] Base point with :x and :y
+      # @param delta_points [Array<Hash>] Delta points (one per region)
+      # @param scalars [Array<Float>] Region scalars
+      # @return [Hash] Interpolated point with :x and :y
+      def interpolate_point(base_point, delta_points, scalars)
+        x = base_point[:x].to_f
+        y = base_point[:y].to_f
+
+        delta_points.each_with_index do |delta_point, index|
+          scalar = scalars[index] || 0.0
+          x += delta_point[:x].to_f * scalar
+          y += delta_point[:y].to_f * scalar
+        end
+
+        { x: x, y: y }
+      end
+
+      # Build region from tuple variation data
+      #
+      # Converts gvar tuple data to the region format used by interpolator
+      #
+      # @param tuple [Hash] Tuple variation data with :peak, :start, :end
+      # @return [Hash<String, Hash>] Region definition per axis
+      def build_region_from_tuple(tuple)
+        region = {}
+
+        @axes.each_with_index do |axis, axis_index|
+          peak = tuple[:peak] ? tuple[:peak][axis_index] : 0.0
+          start_val = tuple[:start] ? tuple[:start][axis_index] : -1.0
+          end_val = tuple[:end] ? tuple[:end][axis_index] : 1.0
+
+          region[axis.axis_tag] = {
+            start: start_val,
+            peak: peak,
+            end: end_val,
+          }
+        end
+
+        region
+      end
+
+      private
+
+      # Find axis by tag
+      #
+      # @param axis_tag [String] Axis tag
+      # @return [VariationAxisRecord, nil] Axis or nil
+      def find_axis(axis_tag)
+        @axes.find { |axis| axis.axis_tag == axis_tag }
+      end
+    end
+  end
+end