fontisan 0.1.0 → 0.2.0

data/lib/fontisan/variable/region_matcher.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Fontisan
+  module Variable
+    # Calculates region scalars for variation regions
+    #
+    # Given normalized coordinates and variation regions, computes scalar values
+    # (0.0 to 1.0) that determine how much each region contributes to the final
+    # delta values. The algorithm follows the OpenType specification for region
+    # matching.
+    #
+    # A region is defined by start, peak, and end coordinates for each axis:
+    # - If coordinate is outside [start, end], scalar is 0.0
+    # - If coordinate is at peak, scalar contribution for that axis is 1.0
+    # - Otherwise, scalar is linearly interpolated
+    # - Final scalar is the product of all axis contributions
+    #
+    # @example Calculate region scalars
+    #   matcher = RegionMatcher.new(variation_region_list)
+    #   scalars = matcher.match({ "wght" => 0.5 })
+    #   # => [0.5, 1.0, 0.0, ...]
+    class RegionMatcher
+      # @return [Hash] Configuration settings
+      attr_reader :config
+
+      # @return [Array<Array<Hash>>] Variation regions
+      attr_reader :regions
+
+      # Initialize the region matcher
+      #
+      # @param variation_region_list [VariationCommon::VariationRegionList] Region list
+      # @param axis_tags [Array<String>] Axis tags in order
+      # @param config [Hash] Optional configuration overrides
+      def initialize(variation_region_list, axis_tags, config = {})
+        @variation_region_list = variation_region_list
+        @axis_tags = axis_tags
+        @config = load_config.merge(config)
+        @regions = build_regions
+        @scalar_cache = {} if @config.dig(:region_matching, :cache_scalars)
+      end
+
+      # Calculate scalars for all regions
+      #
+      # @param normalized_coords [Hash<String, Float>] Normalized coordinates
+      # @return [Array<Float>] Scalar for each region (0.0 to 1.0)
+      def match(normalized_coords)
+        # Check cache if enabled
+        if @config.dig(:region_matching, :cache_scalars)
+          cache_key = cache_key_for(normalized_coords)
+          return @scalar_cache[cache_key] if @scalar_cache.key?(cache_key)
+        end
+
+        scalars = @regions.map do |region|
+          calculate_region_scalar(region, normalized_coords)
+        end
+
+        # Cache result if enabled
+        if @config.dig(:region_matching, :cache_scalars)
+          @scalar_cache[cache_key_for(normalized_coords)] = scalars
+        end
+
+        scalars
+      end
+
+      # Calculate scalar for a specific region
+      #
+      # @param region_index [Integer] Region index
+      # @param normalized_coords [Hash<String, Float>] Normalized coordinates
+      # @return [Float] Region scalar (0.0 to 1.0)
+      def match_region(region_index, normalized_coords)
+        return 0.0 if region_index >= @regions.length
+
+        region = @regions[region_index]
+        calculate_region_scalar(region, normalized_coords)
+      end
+
+      # Get number of regions
+      #
+      # @return [Integer] Region count
+      def region_count
+        @regions.length
+      end
+
+      # Clear scalar cache
+      def clear_cache
+        @scalar_cache&.clear
+      end
+
+      private
+
+      # Load configuration from YAML file
+      #
+      # @return [Hash] Configuration hash
+      def load_config
+        config_path = File.join(__dir__, "..", "config",
+                                "variable_settings.yml")
+        YAML.load_file(config_path)
+      rescue StandardError
+        # Return default config
+        {
+          region_matching: {
+            algorithm: "standard",
+            multi_axis: true,
+            cache_scalars: true,
+          },
+          delta_application: {
+            min_scalar_threshold: 0.0001,
+          },
+        }
+      end
+
+      # Build region information from variation region list
+      #
+      # @return [Array<Array<Hash>>] Array of regions with axis coordinates
+      def build_regions
+        return [] unless @variation_region_list
+
+        @variation_region_list.regions.map do |region_coords|
+          # Map axis coordinates to hash
+          region_coords.each_with_index.map do |coord, axis_index|
+            {
+              axis_tag: @axis_tags[axis_index],
+              start: coord.start,
+              peak: coord.peak,
+              end: coord.end_value,
+            }
+          end
+        end
+      end
+
+      # Calculate scalar for a region
+      #
+      # @param region [Array<Hash>] Region axis coordinates
+      # @param normalized_coords [Hash<String, Float>] Normalized coordinates
+      # @return [Float] Region scalar (0.0 to 1.0)
+      def calculate_region_scalar(region, normalized_coords)
+        # Start with scalar of 1.0
+        scalar = 1.0
+
+        # Process each axis in the region
+        region.each do |axis_coord|
+          axis_tag = axis_coord[:axis_tag]
+          coord = normalized_coords[axis_tag] || normalized_coords[axis_tag.to_sym] || 0.0
+
+          # Calculate contribution for this axis
+          axis_scalar = calculate_axis_scalar(
+            coord,
+            axis_coord[:start],
+            axis_coord[:peak],
+            axis_coord[:end],
+          )
+
+          # Multiply into total scalar
+          scalar *= axis_scalar
+
+          # Early exit if scalar becomes 0
+          break if scalar.zero?
+        end
+
+        # Apply minimum threshold if configured
+        threshold = @config.dig(:delta_application,
+                                :min_scalar_threshold) || 0.0
+        scalar < threshold ? 0.0 : scalar
+      end
+
+      # Calculate scalar contribution for a single axis
+      #
+      # @param coord [Float] Normalized coordinate
+      # @param start [Float] Region start
+      # @param peak [Float] Region peak
+      # @param end_coord [Float] Region end
+      # @return [Float] Axis scalar (0.0 to 1.0)
+      def calculate_axis_scalar(coord, start, peak, end_coord)
+        # Outside region range: no contribution
+        return 0.0 if coord < start || coord > end_coord
+
+        # At peak: full contribution
+        return 1.0 if (coord - peak).abs < Float::EPSILON
+
+        # Between start and peak
+        if coord < peak
+          range = peak - start
+          return 1.0 if range.abs < Float::EPSILON
+
+          return (coord - start) / range
+        end
+
+        # Between peak and end
+        range = end_coord - peak
+        return 1.0 if range.abs < Float::EPSILON
+
+        (end_coord - coord) / range
+      end
+
+      # Generate cache key for coordinates
+      #
+      # @param normalized_coords [Hash] Normalized coordinates
+      # @return [String] Cache key
+      def cache_key_for(normalized_coords)
+        # Sort by axis tag for consistent keys
+        sorted_coords = normalized_coords.sort_by { |tag, _| tag.to_s }
+        sorted_coords.map { |tag, value| "#{tag}:#{value}" }.join("|")
+      end
+    end
+  end
+end

data/lib/fontisan/variable/static_font_builder.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require_relative "table_updater"
+require_relative "../font_writer"
+
+module Fontisan
+  module Variable
+    # Builds static font instances from variable font data
+    #
+    # This class takes a variable font and applied variation data,
+    # then constructs a complete static font by:
+    # 1. Copying all non-variation tables unchanged
+    # 2. Removing variation-specific tables (fvar, gvar, HVAR, etc.)
+    # 3. Updating metric tables (hmtx, hhea) with varied values
+    # 4. Updating head table's modified timestamp
+    # 5. Writing the complete static font binary
+    #
+    # The result is a valid static font at the specified instance point.
+    #
+    # @example Build static font
+    #   builder = StaticFontBuilder.new(font)
+    #   static_binary = builder.build(varied_metrics, font_metrics)
+    class StaticFontBuilder
+      # Tables to remove from static font (variation-specific)
+      VARIATION_TABLES = %w[fvar avar gvar cvar HVAR VVAR MVAR STAT].freeze
+
+      # @return [TableUpdater] Table updater instance
+      attr_reader :table_updater
+
+      # Initialize the builder
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Variable font object
+      def initialize(font)
+        @font = font
+        @table_updater = TableUpdater.new
+      end
+
+      # Build static font from varied data
+      #
+      # @param varied_metrics [Hash<Integer, Hash>] Varied metrics by glyph ID
+      #   { glyph_id => { advance_width: 500, lsb: 50 } }
+      # @param font_metrics [Hash] Varied font-level metrics
+      #   { ascent: 2048, descent: -512, line_gap: 0 }
+      # @param options [Hash] Build options
+      # @option options [Boolean] :update_modified Update head modified timestamp
+      # @return [String] Complete static font binary
+      def build(varied_metrics = {}, font_metrics = {}, options = {})
+        # Collect tables for static font
+        tables = collect_tables(varied_metrics, font_metrics, options)
+
+        # Detect sfnt version
+        sfnt_version = detect_sfnt_version(tables)
+
+        # Write font using FontWriter
+        FontWriter.write_font(tables, sfnt_version: sfnt_version)
+      end
+
+      # Build static font and write to file
+      #
+      # @param output_path [String] Output file path
+      # @param varied_metrics [Hash<Integer, Hash>] Varied metrics by glyph ID
+      # @param font_metrics [Hash] Varied font-level metrics
+      # @param options [Hash] Build options
+      # @return [Integer] Number of bytes written
+      def build_to_file(output_path, varied_metrics = {}, font_metrics = {},
+options = {})
+        binary = build(varied_metrics, font_metrics, options)
+        File.binwrite(output_path, binary)
+      end
+
+      private
+
+      # Collect all tables for static font
+      #
+      # @param varied_metrics [Hash] Varied glyph metrics
+      # @param font_metrics [Hash] Varied font metrics
+      # @param options [Hash] Build options
+      # @return [Hash<String, String>] Map of table tag to binary data
+      def collect_tables(varied_metrics, font_metrics, options)
+        tables = {}
+
+        # Get all table tags from font
+        table_tags = @font.respond_to?(:tables) ? @font.tables.keys : []
+
+        table_tags.each do |tag|
+          # Skip variation tables
+          next if VARIATION_TABLES.include?(tag)
+
+          # Get original table data
+          original_data = @font.table_data(tag)
+          next if original_data.nil? || original_data.empty?
+
+          # Update specific tables with varied data
+          tables[tag] = case tag
+                        when "hmtx"
+                          update_hmtx_table(original_data, varied_metrics)
+                        when "hhea"
+                          update_hhea_table(original_data, font_metrics)
+                        when "OS/2"
+                          update_os2_table(original_data, font_metrics)
+                        when "head"
+                          update_head_table(original_data, options)
+                        else
+                          # Copy unchanged
+                          original_data
+                        end
+        end
+
+        tables
+      end
+
+      # Update hmtx table with varied metrics
+      #
+      # @param original_data [String] Original table data
+      # @param varied_metrics [Hash] Varied glyph metrics
+      # @return [String] Updated table data
+      def update_hmtx_table(original_data, varied_metrics)
+        return original_data if varied_metrics.empty?
+
+        # Get required context from other tables
+        hhea = load_table("hhea")
+        maxp = load_table("maxp")
+
+        return original_data unless hhea && maxp
+
+        num_h_metrics = hhea.number_of_h_metrics
+        num_glyphs = maxp.num_glyphs
+
+        @table_updater.update_hmtx(
+          original_data,
+          varied_metrics,
+          num_h_metrics,
+          num_glyphs,
+        )
+      end
+
+      # Update hhea table with varied metrics
+      #
+      # @param original_data [String] Original table data
+      # @param font_metrics [Hash] Varied font metrics
+      # @return [String] Updated table data
+      def update_hhea_table(original_data, font_metrics)
+        return original_data if font_metrics.empty?
+
+        # Extract hhea-specific metrics
+        hhea_metrics = {}
+        hhea_metrics[:ascent] = font_metrics["hasc"] if font_metrics["hasc"]
+        hhea_metrics[:descent] = font_metrics["hdsc"] if font_metrics["hdsc"]
+        hhea_metrics[:line_gap] = font_metrics["hlgp"] if font_metrics["hlgp"]
+
+        return original_data if hhea_metrics.empty?
+
+        @table_updater.update_hhea(original_data, hhea_metrics)
+      end
+
+      # Update OS/2 table with varied metrics
+      #
+      # @param original_data [String] Original table data
+      # @param font_metrics [Hash] Varied font metrics
+      # @return [String] Updated table data
+      def update_os2_table(original_data, font_metrics)
+        return original_data if font_metrics.empty?
+
+        @table_updater.update_os2(original_data, font_metrics)
+      end
+
+      # Update head table
+      #
+      # @param original_data [String] Original table data
+      # @param options [Hash] Build options
+      # @return [String] Updated table data
+      def update_head_table(original_data, options)
+        if options[:update_modified] == false
+          original_data
+        else
+          @table_updater.update_head_modified(original_data)
+        end
+      end
+
+      # Load a table from the font
+      #
+      # @param tag [String] Table tag
+      # @return [Object, nil] Parsed table or nil
+      def load_table(tag)
+        data = @font.table_data(tag)
+        return nil if data.nil? || data.empty?
+
+        table_class = case tag
+                      when "hhea" then Tables::Hhea
+                      when "maxp" then Tables::Maxp
+                      when "head" then Tables::Head
+                      else return nil
+                      end
+
+        table_class.read(data)
+      rescue StandardError
+        nil
+      end
+
+      # Detect sfnt version from tables
+      #
+      # @param tables [Hash] Map of table tag to data
+      # @return [Integer] sfnt version
+      def detect_sfnt_version(tables)
+        if tables.key?("CFF ") || tables.key?("CFF2")
+          0x4F54544F # 'OTTO' for OpenType/CFF
+        else
+          0x00010000 # 1.0 for TrueType
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/variable/table_updater.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Fontisan
+  module Variable
+    # Updates font tables with applied variation deltas
+    #
+    # This class is responsible for taking original table data and applying
+    # calculated deltas to create updated tables for static font instances.
+    # It handles:
+    # - Updating hmtx with varied advance widths and sidebearings
+    # - Updating hhea with varied ascent/descent/line gap
+    # - Updating OS/2 with varied metrics
+    # - Updating head table's modified timestamp
+    #
+    # Each update method takes the original table and delta values,
+    # then reconstructs the table binary with updated values.
+    #
+    # @example Update hmtx table
+    #   updater = TableUpdater.new
+    #   new_hmtx = updater.update_hmtx(
+    #     original_hmtx_data,
+    #     varied_metrics,
+    #     num_h_metrics,
+    #     num_glyphs
+    #   )
+    class TableUpdater
+      # Update hmtx table with varied metrics
+      #
+      # @param original_data [String] Original hmtx table binary
+      # @param varied_metrics [Hash<Integer, Hash>] Varied metrics by glyph ID
+      #   { glyph_id => { advance_width: 500, lsb: 50 } }
+      # @param num_h_metrics [Integer] Number of hMetrics from hhea
+      # @param num_glyphs [Integer] Total glyphs from maxp
+      # @return [String] Updated hmtx table binary
+      def update_hmtx(original_data, varied_metrics, num_h_metrics, num_glyphs)
+        io = StringIO.new(original_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Parse original hMetrics
+        h_metrics = []
+        num_h_metrics.times do
+          advance_width = io.read(2)&.unpack1("n") || 0
+          lsb = io.read(2)&.unpack1("n") || 0
+          lsb = lsb >= 0x8000 ? lsb - 0x10000 : lsb # Convert to signed
+          h_metrics << { advance_width: advance_width, lsb: lsb }
+        end
+
+        # Parse additional LSBs
+        lsb_count = num_glyphs - num_h_metrics
+        left_side_bearings = []
+        lsb_count.times do
+          lsb = io.read(2)&.unpack1("n") || 0
+          lsb = lsb >= 0x8000 ? lsb - 0x10000 : lsb
+          left_side_bearings << lsb
+        end
+
+        # Apply varied metrics
+        varied_metrics.each do |glyph_id, metrics|
+          if glyph_id < num_h_metrics
+            if metrics[:advance_width]
+              h_metrics[glyph_id][:advance_width] =
+                metrics[:advance_width]
+            end
+            h_metrics[glyph_id][:lsb] = metrics[:lsb] if metrics[:lsb]
+          else
+            lsb_index = glyph_id - num_h_metrics
+            left_side_bearings[lsb_index] = metrics[:lsb] if metrics[:lsb]
+          end
+        end
+
+        # Build updated hmtx binary
+        output = String.new(encoding: Encoding::BINARY)
+
+        # Write hMetrics
+        h_metrics.each do |metric|
+          output << [metric[:advance_width]].pack("n")
+          # Convert signed LSB to unsigned for packing
+          lsb_unsigned = metric[:lsb].negative? ? metric[:lsb] + 0x10000 : metric[:lsb]
+          output << [lsb_unsigned].pack("n")
+        end
+
+        # Write additional LSBs
+        left_side_bearings.each do |lsb|
+          lsb_unsigned = lsb.negative? ? lsb + 0x10000 : lsb
+          output << [lsb_unsigned].pack("n")
+        end
+
+        output
+      end
+
+      # Update hhea table with varied metrics
+      #
+      # @param original_data [String] Original hhea table binary
+      # @param varied_metrics [Hash] Varied font metrics
+      #   { ascent: 2048, descent: -512, line_gap: 0 }
+      # @return [String] Updated hhea table binary
+      def update_hhea(original_data, varied_metrics)
+        io = StringIO.new(original_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Read all fields
+        version = io.read(4)
+        ascent = io.read(2)&.unpack1("n") || 0
+        ascent = ascent >= 0x8000 ? ascent - 0x10000 : ascent
+        descent = io.read(2)&.unpack1("n") || 0
+        descent = descent >= 0x8000 ? descent - 0x10000 : descent
+        line_gap = io.read(2)&.unpack1("n") || 0
+        line_gap = line_gap >= 0x8000 ? line_gap - 0x10000 : line_gap
+
+        # Read remaining fields
+        rest = io.read
+
+        # Apply varied metrics
+        ascent = varied_metrics[:ascent] if varied_metrics[:ascent]
+        descent = varied_metrics[:descent] if varied_metrics[:descent]
+        line_gap = varied_metrics[:line_gap] if varied_metrics[:line_gap]
+
+        # Build updated hhea binary
+        output = String.new(encoding: Encoding::BINARY)
+        output << version
+
+        # Convert signed values to unsigned for packing
+        ascent_unsigned = ascent.negative? ? ascent + 0x10000 : ascent
+        descent_unsigned = descent.negative? ? descent + 0x10000 : descent
+        line_gap_unsigned = line_gap.negative? ? line_gap + 0x10000 : line_gap
+
+        output << [ascent_unsigned].pack("n")
+        output << [descent_unsigned].pack("n")
+        output << [line_gap_unsigned].pack("n")
+        output << rest
+
+        output
+      end
+
+      # Update OS/2 table with varied metrics
+      #
+      # @param original_data [String] Original OS/2 table binary
+      # @param varied_metrics [Hash] Varied font metrics from MVAR
+      # @return [String] Updated OS/2 table binary
+      def update_os2(original_data, varied_metrics)
+        return original_data if varied_metrics.empty?
+
+        io = StringIO.new(original_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Read version to determine table size
+        io.read(2)&.unpack1("n") || 0
+        io.rewind
+
+        # For simplicity, return original if no specific OS/2 metrics to update
+        # This would need to be expanded based on MVAR tags present
+        original_data
+      end
+
+      # Update head table's modified timestamp
+      #
+      # @param original_data [String] Original head table binary
+      # @param timestamp [Time] New modification time
+      # @return [String] Updated head table binary
+      def update_head_modified(original_data, timestamp = Time.now)
+        io = StringIO.new(original_data)
+        io.set_encoding(Encoding::BINARY)
+
+        # Read up to modified timestamp
+        header = io.read(28) # version through created timestamp
+        _old_modified = io.read(8) # Skip old modified timestamp
+        rest = io.read # Remaining data
+
+        # Convert Time to LONGDATETIME (seconds since 1904-01-01)
+        # Difference between 1904 and 1970 (Unix epoch) is 2082844800 seconds
+        longdatetime = timestamp.to_i + 2_082_844_800
+
+        # Build updated head binary
+        output = String.new(encoding: Encoding::BINARY)
+        output << header
+        output << [longdatetime].pack("q>") # 64-bit big-endian signed integer
+        output << rest
+
+        output
+      end
+
+      # Build updated table with varied values
+      #
+      # This is a generic helper for building updated table binaries
+      #
+      # @param original_data [String] Original table binary
+      # @param updates [Hash] Hash of offset => new_value pairs
+      # @return [String] Updated table binary
+      def apply_updates(original_data, updates)
+        data = original_data.dup
+
+        updates.each do |offset, value|
+          # Handle different value types
+          packed_value = case value
+                         when Integer
+                           if value >= -32768 && value <= 32767
+                             # int16
+                             unsigned = value.negative? ? value + 0x10000 : value
+                             [unsigned].pack("n")
+                           else
+                             # int32
+                             [value].pack("N")
+                           end
+                         when String
+                           value
+                         else
+                           value.to_s
+                         end
+
+          data[offset, packed_value.bytesize] = packed_value
+        end
+
+        data
+      end
+    end
+  end
+end