fontisan 0.1.0 → 0.2.1

data/lib/fontisan/variation/instance_writer.rb

@@ -0,0 +1,341 @@
+# frozen_string_literal: true
+
+require_relative "../font_writer"
+require_relative "../converters/outline_converter"
+require_relative "../converters/woff_writer"
+require_relative "../error"
+
+module Fontisan
+  module Variation
+    # Writes generated static font instances to files in various formats
+    #
+    # [`InstanceWriter`](lib/fontisan/variation/instance_writer.rb) takes
+    # instance tables generated by
+    # [`InstanceGenerator`](lib/fontisan/variation/instance_generator.rb) and
+    # writes them to files in the desired output format. It handles:
+    # - Format detection from file extension
+    # - Format conversion when needed (e.g., glyf → CFF for OTF)
+    # - SFNT version selection based on output format
+    # - Integration with FontWriter for binary output
+    # - Integration with OutlineConverter for format conversion
+    # - Integration with WoffWriter for WOFF packaging
+    #
+    # **Supported Output Formats:**
+    # - TTF (TrueType with glyf outlines)
+    # - OTF (OpenType with CFF outlines)
+    # - WOFF (Web Open Font Format)
+    # - WOFF2 (Web Open Font Format 2.0, future)
+    #
+    # @example Write instance to TTF
+    #   tables = generator.generate
+    #   InstanceWriter.write(tables, 'bold.ttf')
+    #
+    # @example Write instance to OTF with format conversion
+    #   tables = generator.generate  # from variable TTF
+    #   InstanceWriter.write(tables, 'bold.otf', source_format: :ttf)
+    #
+    # @example Write instance to WOFF
+    #   tables = generator.generate
+    #   InstanceWriter.write(tables, 'bold.woff')
+    class InstanceWriter
+      # Supported output formats
+      SUPPORTED_FORMATS = %i[ttf otf woff woff2].freeze
+
+      # SFNT version constants
+      SFNT_VERSION_TRUETYPE = 0x00010000  # TrueType with glyf
+      SFNT_VERSION_CFF = 0x4F54544F       # 'OTTO' for CFF
+
+      # Write instance tables to file
+      #
+      # @param tables [Hash<String, String>] Instance tables from
+      #   InstanceGenerator
+      # @param output_path [String] Output file path
+      # @param options [Hash] Options
+      # @option options [Symbol] :format Output format (:ttf, :otf, :woff,
+      #   :woff2)
+      # @option options [Symbol] :source_format Source format before instancing
+      #   (:ttf or :otf)
+      # @option options [Boolean] :optimize Enable CFF optimization for OTF
+      #   (default: false)
+      # @option options [Integer] :sfnt_version Override SFNT version
+      # @return [Integer] Number of bytes written
+      # @raise [ArgumentError] If parameters are invalid
+      # @raise [Error] If format conversion fails
+      def self.write(tables, output_path, options = {})
+        new(tables, options).write(output_path)
+      end
+
+      # @return [Hash<String, String>] Instance tables
+      attr_reader :tables
+
+      # @return [Hash] Writer options
+      attr_reader :options
+
+      # Initialize writer with instance tables
+      #
+      # @param tables [Hash<String, String>] Instance tables from
+      #   InstanceGenerator
+      # @param options [Hash] Writer options
+      # @option options [Symbol] :source_format Source format before instancing
+      # @option options [Boolean] :optimize Enable CFF optimization
+      def initialize(tables, options = {})
+        @tables = tables
+        @options = options
+        validate_tables!
+      end
+
+      # Write instance to file
+      #
+      # @param output_path [String] Output file path
+      # @return [Integer] Number of bytes written
+      def write(output_path)
+        # Detect output format
+        format = detect_output_format(output_path)
+        validate_format!(format)
+
+        # Detect source format from tables
+        source_format = detect_source_format(@tables)
+
+        # Convert format if needed
+        output_tables = if format_conversion_needed?(source_format, format)
+                          convert_format(source_format, format)
+                        else
+                          @tables
+                        end
+
+        # Write to file based on format
+        case format
+        when :ttf, :otf
+          write_sfnt(output_tables, output_path, format)
+        when :woff
+          write_woff(output_tables, output_path, source_format)
+        when :woff2
+          raise Fontisan::Error,
+                "WOFF2 output not yet implemented (planned for Phase 6)"
+        end
+      end
+
+      private
+
+      # Validate instance tables
+      #
+      # @raise [ArgumentError] If tables are invalid
+      def validate_tables!
+        raise ArgumentError, "Tables cannot be nil" if @tables.nil?
+
+        unless @tables.is_a?(Hash)
+          raise ArgumentError,
+                "Tables must be a Hash, got: #{@tables.class}"
+        end
+
+        if @tables.empty?
+          raise ArgumentError, "Tables cannot be empty"
+        end
+
+        # Check for required tables
+        required_tables = %w[head hhea maxp]
+        required_tables.each do |tag|
+          unless @tables.key?(tag)
+            raise ArgumentError, "Missing required table: #{tag}"
+          end
+        end
+      end
+
+      # Detect output format from file path
+      #
+      # @param path [String] Output file path
+      # @return [Symbol] Format (:ttf, :otf, :woff, :woff2)
+      def detect_output_format(path)
+        return @options[:format] if @options[:format]
+
+        ext = File.extname(path).downcase
+        case ext
+        when ".ttf" then :ttf
+        when ".otf" then :otf
+        when ".woff" then :woff
+        when ".woff2" then :woff2
+        else
+          raise ArgumentError,
+                "Cannot determine format from extension: #{ext}. " \
+                "Supported: .ttf, .otf, .woff, .woff2"
+        end
+      end
+
+      # Validate output format
+      #
+      # @param format [Symbol] Format to validate
+      # @raise [ArgumentError] If format is not supported
+      def validate_format!(format)
+        unless SUPPORTED_FORMATS.include?(format)
+          raise ArgumentError,
+                "Unsupported format: #{format}. " \
+                "Supported: #{SUPPORTED_FORMATS.join(', ')}"
+        end
+      end
+
+      # Detect source format from instance tables
+      #
+      # @param tables [Hash<String, String>] Instance tables
+      # @return [Symbol] Source format (:ttf or :otf)
+      def detect_source_format(tables)
+        # Check for outline tables
+        if tables.key?("CFF ") || tables.key?("CFF2")
+          :otf
+        elsif tables.key?("glyf")
+          :ttf
+        else
+          # If no outline tables, use option or default to TTF
+          @options[:source_format] || :ttf
+        end
+      end
+
+      # Check if format conversion is needed
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @return [Boolean] True if conversion needed
+      def format_conversion_needed?(source_format, target_format)
+        # WOFF doesn't need outline conversion
+        return false if %i[woff woff2].include?(target_format)
+
+        # Check if outline formats differ
+        source_format != target_format
+      end
+
+      # Convert instance tables from source format to target format
+      #
+      # @param source_format [Symbol] Source format
+      # @param target_format [Symbol] Target format
+      # @return [Hash<String, String>] Converted tables
+      # @raise [Error] If conversion fails
+      def convert_format(source_format, target_format)
+        # Create temporary font object for conversion
+        temp_font = create_temp_font(@tables, source_format)
+
+        # Use OutlineConverter for format conversion
+        converter = Converters::OutlineConverter.new
+        converter.convert(
+          temp_font,
+          target_format: target_format,
+          optimize_cff: @options[:optimize] || false,
+        )
+      rescue StandardError => e
+        raise Fontisan::Error,
+              "Failed to convert instance from #{source_format} to " \
+              "#{target_format}: #{e.message}"
+      end
+
+      # Create temporary font object from tables
+      #
+      # @param tables [Hash<String, String>] Font tables
+      # @param format [Symbol] Font format
+      # @return [Object] Font object
+      def create_temp_font(tables, format)
+        # Create minimal font object that responds to required methods
+        font_class = format == :otf ? OpenTypeFont : TrueTypeFont
+        font = font_class.new
+
+        # Set table data
+        font.instance_variable_set(:@table_data, tables)
+
+        # Define required methods
+        font.define_singleton_method(:table_data) { tables }
+        font.define_singleton_method(:table_names) { tables.keys }
+        font.define_singleton_method(:has_table?) { |tag| tables.key?(tag) }
+        font.define_singleton_method(:table) do |tag|
+          # Return nil if table doesn't exist
+          return nil unless tables.key?(tag)
+
+          # Parse and return table object
+          # For conversion, we need to lazy-load tables
+          parse_table(tag, tables[tag])
+        end
+
+        font
+      end
+
+      # Parse table data into table object
+      #
+      # @param tag [String] Table tag
+      # @param data [String] Table binary data
+      # @return [Object] Parsed table object
+      def parse_table(tag, data)
+        # For OutlineConverter, we need head, maxp, loca, glyf for TTF
+        # and CFF for OTF
+        case tag
+        when "head"
+          Tables::Head.new.tap { |t| t.parse(data) }
+        when "maxp"
+          Tables::Maxp.new.tap { |t| t.parse(data) }
+        when "loca"
+          Tables::Loca.new.tap { |t| t.data = data }
+        when "glyf"
+          Tables::Glyf.new.tap { |t| t.data = data }
+        when "CFF "
+          Tables::Cff.new.tap { |t| t.parse(data) }
+        when "CFF2"
+          Tables::Cff2.new.tap { |t| t.parse(data) }
+        else
+          # For other tables, return a simple object that just holds data
+          Object.new.tap do |obj|
+            obj.define_singleton_method(:data) { data }
+          end
+        end
+      rescue StandardError => e
+        warn "Warning: Failed to parse #{tag} table: #{e.message}"
+        nil
+      end
+
+      # Write SFNT format (TTF or OTF)
+      #
+      # @param tables [Hash<String, String>] Output tables
+      # @param output_path [String] Output file path
+      # @param format [Symbol] Output format
+      # @return [Integer] Number of bytes written
+      def write_sfnt(tables, output_path, format)
+        # Determine SFNT version
+        sfnt_version = @options[:sfnt_version] || sfnt_version_for_format(
+          format,
+        )
+
+        # Write using FontWriter
+        FontWriter.write_to_file(tables, output_path,
+                                 sfnt_version: sfnt_version)
+      end
+
+      # Write WOFF format
+      #
+      # @param tables [Hash<String, String>] Output tables
+      # @param output_path [String] Output file path
+      # @param source_format [Symbol] Source format (for flavor detection)
+      # @return [Integer] Number of bytes written
+      def write_woff(tables, output_path, source_format)
+        # Create temporary font for WOFF writer
+        temp_font = create_temp_font(tables, source_format)
+
+        # Add cff? method for WoffWriter flavor detection
+        temp_font.define_singleton_method(:cff?) do
+          tables.key?("CFF ") || tables.key?("CFF2")
+        end
+
+        # Use WoffWriter to create WOFF
+        writer = Converters::WoffWriter.new
+        woff_data = writer.convert(temp_font)
+
+        # Write to file
+        File.binwrite(output_path, woff_data)
+      rescue StandardError => e
+        raise Fontisan::Error,
+              "Failed to write WOFF output: #{e.message}"
+      end
+
+      # Get SFNT version for output format
+      #
+      # @param format [Symbol] Output format
+      # @return [Integer] SFNT version constant
+      def sfnt_version_for_format(format)
+        format == :otf ? SFNT_VERSION_CFF : SFNT_VERSION_TRUETYPE
+      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