fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variable/instancer.rb

@@ -0,0 +1,344 @@
+# frozen_string_literal: true
+
+require_relative "delta_applicator"
+require_relative "static_font_builder"
+
+module Fontisan
+  module Variable
+    # Main entry point for variable font instancing
+    #
+    # This class orchestrates the complete process of generating a static
+    # font instance from a variable font at specified coordinates:
+    #
+    # 1. Validates the font is a variable font (has fvar table)
+    # 2. Normalizes user coordinates using AxisNormalizer
+    # 3. Calculates region scalars using RegionMatcher
+    # 4. Applies deltas using DeltaApplicator
+    # 5. Builds static font using StaticFontBuilder
+    #
+    # @example Generate instance at specific coordinates
+    #   instancer = Instancer.new(variable_font)
+    #   static_binary = instancer.instance({ "wght" => 700 })
+    #   File.binwrite("bold.ttf", static_binary)
+    #
+    # @example Generate instance for named instance
+    #   instancer = Instancer.new(variable_font)
+    #   static_binary = instancer.instance_named("Bold")
+    class Instancer
+      # @return [Object] The variable font object
+      attr_reader :font
+
+      # @return [DeltaApplicator] Delta applicator
+      attr_reader :delta_applicator
+
+      # @return [StaticFontBuilder] Static font builder
+      attr_reader :static_font_builder
+
+      # Initialize the instancer
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font object
+      # @raise [ArgumentError] If font is not a variable font
+      def initialize(font)
+        @font = font
+        validate_variable_font!
+
+        @delta_applicator = DeltaApplicator.new(font)
+        @static_font_builder = StaticFontBuilder.new(font)
+      end
+
+      # Generate static font instance at specified coordinates
+      #
+      # @param user_coords [Hash<String, Numeric>] User coordinates
+      #   { "wght" => 700, "wdth" => 100 }
+      # @param options [Hash] Instance options
+      # @option options [Boolean] :update_modified Update head modified timestamp
+      # @return [String] Complete static font binary
+      #
+      # @example
+      #   binary = instancer.instance({ "wght" => 700, "wdth" => 100 })
+      def instance(user_coords, options = {})
+        # Apply deltas to get all varied data
+        delta_result = @delta_applicator.apply(user_coords)
+
+        # Collect varied metrics for all glyphs
+        varied_metrics = collect_varied_glyph_metrics(
+          delta_result[:normalized_coords],
+          delta_result[:region_scalars],
+        )
+
+        # Extract font-level metrics
+        font_metrics = delta_result[:font_metrics]
+
+        # Build static font
+        @static_font_builder.build(varied_metrics, font_metrics, options)
+      end
+
+      # Generate static font instance and write to file
+      #
+      # @param output_path [String] Output file path
+      # @param user_coords [Hash<String, Numeric>] User coordinates
+      # @param options [Hash] Instance options
+      # @return [Integer] Number of bytes written
+      #
+      # @example
+      #   instancer.instance_to_file("bold.ttf", { "wght" => 700 })
+      def instance_to_file(output_path, user_coords, options = {})
+        binary = instance(user_coords, options)
+        File.binwrite(output_path, binary)
+      end
+
+      # Generate static font instance for a named instance
+      #
+      # @param instance_name [String] Named instance name (from fvar)
+      # @param options [Hash] Instance options
+      # @return [String] Complete static font binary
+      # @raise [ArgumentError] If named instance not found
+      #
+      # @example
+      #   binary = instancer.instance_named("Bold")
+      def instance_named(instance_name, options = {})
+        coords = find_named_instance_coords(instance_name)
+        instance(coords, options)
+      end
+
+      # Generate static font instance for a named instance and write to file
+      #
+      # @param output_path [String] Output file path
+      # @param instance_name [String] Named instance name
+      # @param options [Hash] Instance options
+      # @return [Integer] Number of bytes written
+      #
+      # @example
+      #   instancer.instance_named_to_file("bold.ttf", "Bold")
+      def instance_named_to_file(output_path, instance_name, options = {})
+        binary = instance_named(instance_name, options)
+        File.binwrite(output_path, binary)
+      end
+
+      # Get list of available named instances
+      #
+      # @return [Array<Hash>] Array of named instance information
+      #   [{ name: "Bold", coords: { "wght" => 700 } }, ...]
+      def named_instances
+        fvar = load_fvar_table
+        return [] unless fvar
+
+        # Get name table for instance names
+        name_table = load_name_table
+
+        fvar.instances.map do |instance|
+          coords = extract_instance_coords(instance, fvar)
+          name = if name_table
+                   get_instance_name(instance[:name_id],
+                                     name_table)
+                 end
+
+          {
+            name_id: instance[:name_id],
+            name: name || "Instance #{instance[:name_id]}",
+            coordinates: coords,
+          }
+        end
+      end
+
+      # Check if font is a variable font
+      #
+      # @return [Boolean] True if variable font
+      def variable_font?
+        @delta_applicator.variable_font?
+      end
+
+      # Get available axis information
+      #
+      # @return [Hash] Axis information
+      def axes
+        @delta_applicator.axes
+      end
+
+      # Get available axis tags
+      #
+      # @return [Array<String>] Array of axis tags
+      def axis_tags
+        @delta_applicator.axis_tags
+      end
+
+      private
+
+      # Validate that font is a variable font
+      #
+      # @raise [ArgumentError] If not a variable font
+      def validate_variable_font!
+        fvar_data = @font.table_data("fvar")
+        return unless fvar_data.nil? || fvar_data.empty?
+
+        raise ArgumentError, "Font is not a variable font (missing fvar table)"
+      end
+
+      # Collect varied metrics for all glyphs
+      #
+      # @param normalized_coords [Hash] Normalized coordinates
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Hash<Integer, Hash>] Varied metrics by glyph ID
+      def collect_varied_glyph_metrics(normalized_coords, _region_scalars)
+        varied_metrics = {}
+
+        # Get number of glyphs
+        maxp = load_maxp_table
+        return varied_metrics unless maxp
+
+        num_glyphs = maxp.num_glyphs
+
+        # Get original hmtx metrics
+        hmtx = load_hmtx_table
+        return varied_metrics unless hmtx
+
+        # For each glyph, calculate varied metrics
+        num_glyphs.times do |glyph_id|
+          original_metric = hmtx.metric_for(glyph_id)
+          next unless original_metric
+
+          # Get deltas from delta applicator
+          deltas = @delta_applicator.apply_glyph(glyph_id, normalized_coords)
+          metric_deltas = deltas[:metric_deltas]
+
+          # Calculate varied values
+          varied_metric = {
+            advance_width: original_metric[:advance_width],
+            lsb: original_metric[:lsb],
+          }
+
+          # Apply horizontal deltas if present
+          if metric_deltas[:horizontal]
+            if metric_deltas[:horizontal][:advance_width]
+              varied_metric[:advance_width] += metric_deltas[:horizontal][:advance_width]
+            end
+
+            if metric_deltas[:horizontal][:lsb]
+              varied_metric[:lsb] += metric_deltas[:horizontal][:lsb]
+            end
+          end
+
+          varied_metrics[glyph_id] = varied_metric
+        end
+
+        varied_metrics
+      end
+
+      # Find coordinates for a named instance
+      #
+      # @param instance_name [String] Instance name
+      # @return [Hash<String, Float>] Coordinates
+      # @raise [ArgumentError] If instance not found
+      def find_named_instance_coords(instance_name)
+        instances = named_instances
+        instance = instances.find { |inst| inst[:name] == instance_name }
+
+        unless instance
+          raise ArgumentError,
+                "Named instance '#{instance_name}' not found"
+        end
+
+        instance[:coordinates]
+      end
+
+      # Extract coordinates from instance record
+      #
+      # @param instance [Hash] Instance record
+      # @param fvar [Fvar] fvar table
+      # @return [Hash<String, Float>] Coordinates by axis tag
+      def extract_instance_coords(instance, fvar)
+        coords = {}
+        instance[:coordinates].each_with_index do |value, index|
+          axis = fvar.axes[index]
+          coords[axis.axis_tag.to_s] = value if axis
+        end
+        coords
+      end
+
+      # Get instance name from name table
+      #
+      # @param name_id [Integer] Name table ID
+      # @param name_table [Name] name table
+      # @return [String, nil] Instance name
+      def get_instance_name(name_id, name_table)
+        # Try to get English name
+        record = name_table.records.find do |r|
+          r.name_id == name_id && r.language_id == 0x0409 # English (US)
+        end
+
+        record ||= name_table.records.find { |r| r.name_id == name_id }
+        record&.value
+      rescue StandardError
+        nil
+      end
+
+      # Load fvar table
+      #
+      # @return [Fvar, nil] fvar table or nil
+      def load_fvar_table
+        data = @font.table_data("fvar")
+        return nil if data.nil? || data.empty?
+
+        Tables::Fvar.read(data)
+      rescue StandardError
+        nil
+      end
+
+      # Load name table
+      #
+      # @return [Name, nil] name table or nil
+      def load_name_table
+        data = @font.table_data("name")
+        return nil if data.nil? || data.empty?
+
+        Tables::Name.read(data)
+      rescue StandardError
+        nil
+      end
+
+      # Load maxp table
+      #
+      # @return [Maxp, nil] maxp table or nil
+      def load_maxp_table
+        data = @font.table_data("maxp")
+        return nil if data.nil? || data.empty?
+
+        Tables::Maxp.read(data)
+      rescue StandardError
+        nil
+      end
+
+      # Load hmtx table
+      #
+      # @return [Hmtx, nil] hmtx table or nil
+      def load_hmtx_table
+        data = @font.table_data("hmtx")
+        return nil if data.nil? || data.empty?
+
+        hmtx = Tables::Hmtx.read(data)
+
+        # Parse with context
+        hhea = load_hhea_table
+        maxp = load_maxp_table
+        return nil unless hhea && maxp
+
+        hmtx.parse_with_context(hhea.number_of_h_metrics, maxp.num_glyphs)
+        hmtx
+      rescue StandardError
+        nil
+      end
+
+      # Load hhea table
+      #
+      # @return [Hhea, nil] hhea table or nil
+      def load_hhea_table
+        data = @font.table_data("hhea")
+        return nil if data.nil? || data.empty?
+
+        Tables::Hhea.read(data)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/fontisan/variable/metric_delta_processor.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontisan
+  module Variable
+    # Applies metric deltas from HVAR, VVAR, and MVAR tables
+    #
+    # Processes variation data for font metrics including:
+    # - Horizontal metrics (advance widths, LSB, RSB) via HVAR
+    # - Vertical metrics (advance heights, TSB, BSB) via VVAR
+    # - Font-level metrics (ascent, descent, line gap, etc.) via MVAR
+    #
+    # Uses ItemVariationStore and region scalars to calculate accumulated
+    # deltas which are then applied to original metric values.
+    #
+    # @example Apply metric deltas
+    #   processor = MetricDeltaProcessor.new(hvar, vvar, mvar)
+    #   deltas = processor.apply_deltas(glyph_id, region_scalars)
+    #   # => { advance_width: 10, lsb: -2, ... }
+    class MetricDeltaProcessor
+      # @return [Hash] Configuration settings
+      attr_reader :config
+
+      # Initialize the processor
+      #
+      # @param hvar [Fontisan::Tables::Hvar, nil] Horizontal variations table
+      # @param vvar [Fontisan::Tables::Vvar, nil] Vertical variations table
+      # @param mvar [Fontisan::Tables::Mvar, nil] Metrics variations table
+      # @param config [Hash] Optional configuration overrides
+      def initialize(hvar: nil, vvar: nil, mvar: nil, config: {})
+        @hvar = hvar
+        @vvar = vvar
+        @mvar = mvar
+        @config = load_config.merge(config)
+      end
+
+      # Apply all metric deltas for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Scalar for each region
+      # @return [Hash] Metric deltas
+      def apply_deltas(glyph_id, region_scalars)
+        result = {}
+
+        # Apply horizontal metric deltas if HVAR present
+        if @hvar && @config.dig(:metric_deltas, :apply_hvar)
+          result[:horizontal] = apply_hvar_deltas(glyph_id, region_scalars)
+        end
+
+        # Apply vertical metric deltas if VVAR present
+        if @vvar && @config.dig(:metric_deltas, :apply_vvar)
+          result[:vertical] = apply_vvar_deltas(glyph_id, region_scalars)
+        end
+
+        result
+      end
+
+      # Apply font-level metric deltas
+      #
+      # @param region_scalars [Array<Float>] Scalar for each region
+      # @return [Hash] Font-level metric deltas
+      def apply_font_metrics(region_scalars)
+        return {} unless @mvar && @config.dig(:metric_deltas, :apply_mvar)
+
+        result = {}
+
+        # Process each metric tag in MVAR
+        @mvar.metric_tags.each do |tag|
+          delta_set = @mvar.metric_delta_set(tag)
+          next unless delta_set
+
+          # Calculate accumulated delta
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[tag] = apply_rounding(accumulated)
+        end
+
+        result
+      end
+
+      # Get advance width delta for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Integer] Advance width delta
+      def advance_width_delta(glyph_id, region_scalars)
+        return 0 unless @hvar
+
+        delta_set = @hvar.advance_width_delta_set(glyph_id)
+        return 0 unless delta_set
+
+        accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+        apply_rounding(accumulated)
+      end
+
+      # Get LSB delta for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Integer] LSB delta
+      def lsb_delta(glyph_id, region_scalars)
+        return 0 unless @hvar
+
+        delta_set = @hvar.lsb_delta_set(glyph_id)
+        return 0 unless delta_set
+
+        accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+        apply_rounding(accumulated)
+      end
+
+      # Get RSB delta for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Integer] RSB delta
+      def rsb_delta(glyph_id, region_scalars)
+        return 0 unless @hvar
+
+        delta_set = @hvar.rsb_delta_set(glyph_id)
+        return 0 unless delta_set
+
+        accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+        apply_rounding(accumulated)
+      end
+
+      # Check if horizontal variations are present
+      #
+      # @return [Boolean] True if HVAR present
+      def has_hvar?
+        !@hvar.nil?
+      end
+
+      # Check if vertical variations are present
+      #
+      # @return [Boolean] True if VVAR present
+      def has_vvar?
+        !@vvar.nil?
+      end
+
+      # Check if font metric variations are present
+      #
+      # @return [Boolean] True if MVAR present
+      def has_mvar?
+        !@mvar.nil?
+      end
+
+      private
+
+      # Load configuration from YAML file
+      #
+      # @return [Hash] Configuration hash
+      def load_config
+        config_path = File.join(__dir__, "..", "config",
+                                "variable_settings.yml")
+        loaded = YAML.load_file(config_path)
+        # Convert string keys to symbol keys for consistency
+        deep_symbolize_keys(loaded)
+      rescue StandardError
+        # Return default config
+        {
+          metric_deltas: {
+            apply_hvar: true,
+            apply_vvar: true,
+            apply_mvar: true,
+            update_dependent_metrics: true,
+          },
+          delta_application: {
+            rounding_mode: "round",
+          },
+        }
+      end
+
+      # Recursively convert hash keys to symbols
+      #
+      # @param hash [Hash] Hash with string keys
+      # @return [Hash] Hash with symbol keys
+      def deep_symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), result|
+          new_key = key.to_sym
+          new_value = value.is_a?(Hash) ? deep_symbolize_keys(value) : value
+          result[new_key] = new_value
+        end
+      end
+
+      # Apply HVAR deltas for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Hash] Horizontal metric deltas
+      def apply_hvar_deltas(glyph_id, region_scalars)
+        result = {}
+
+        # Advance width delta
+        if (delta_set = @hvar.advance_width_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:advance_width] = apply_rounding(accumulated)
+        end
+
+        # LSB delta
+        if (delta_set = @hvar.lsb_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:lsb] = apply_rounding(accumulated)
+        end
+
+        # RSB delta
+        if (delta_set = @hvar.rsb_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:rsb] = apply_rounding(accumulated)
+        end
+
+        result
+      end
+
+      # Apply VVAR deltas for a glyph
+      #
+      # @param glyph_id [Integer] Glyph ID
+      # @param region_scalars [Array<Float>] Region scalars
+      # @return [Hash] Vertical metric deltas
+      def apply_vvar_deltas(glyph_id, region_scalars)
+        result = {}
+
+        # Similar to HVAR but for vertical metrics
+        # VVAR has the same structure as HVAR
+        if @vvar.respond_to?(:advance_height_delta_set) && (delta_set = @vvar.advance_height_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:advance_height] = apply_rounding(accumulated)
+        end
+
+        if @vvar.respond_to?(:tsb_delta_set) && (delta_set = @vvar.tsb_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:tsb] = apply_rounding(accumulated)
+        end
+
+        if @vvar.respond_to?(:bsb_delta_set) && (delta_set = @vvar.bsb_delta_set(glyph_id))
+          accumulated = calculate_accumulated_delta(delta_set, region_scalars)
+          result[:bsb] = apply_rounding(accumulated)
+        end
+
+        result
+      end
+
+      # Calculate accumulated delta from delta set and region scalars
+      #
+      # @param delta_set [Array<Integer>] Delta values for each region
+      # @param region_scalars [Array<Float>] Scalar for each region
+      # @return [Float] Accumulated delta
+      def calculate_accumulated_delta(delta_set, region_scalars)
+        accumulated = 0.0
+
+        delta_set.each_with_index do |delta, index|
+          next if index >= region_scalars.length
+
+          scalar = region_scalars[index]
+          accumulated += delta * scalar
+        end
+
+        accumulated
+      end
+
+      # Apply rounding to delta value
+      #
+      # @param delta [Float] Delta value
+      # @return [Integer] Rounded delta
+      def apply_rounding(delta)
+        mode = @config.dig(:delta_application, :rounding_mode) || "round"
+
+        case mode
+        when "round"
+          delta.round
+        when "floor"
+          delta.floor
+        when "ceil"
+          delta.ceil
+        when "truncate"
+          delta.to_i
+        else
+          delta.round
+        end
+      end
+    end
+  end
+end