fontisan 0.1.0 → 0.2.1

data/lib/fontisan/hints/hint_converter.rb

@@ -0,0 +1,310 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../models/hint"
+
+module Fontisan
+  module Hints
+    # Converts hints between TrueType and PostScript formats
+    #
+    # This converter handles bidirectional conversion of rendering hints,
+    # translating between TrueType instruction-based hinting and PostScript
+    # operator-based hinting while preserving intent where possible.
+    #
+    # **Conversion Strategy:**
+    #
+    # - TrueType → PostScript: Extract semantic meaning from instructions
+    #   and convert to corresponding PostScript operators
+    # - PostScript → TrueType: Analyze hint operators and generate
+    #   equivalent TrueType instructions
+    #
+    # @example Convert TrueType hints to PostScript
+    #   converter = HintConverter.new
+    #   ps_hints = converter.to_postscript(tt_hints)
+    #
+    # @example Convert PostScript hints to TrueType
+    #   converter = HintConverter.new
+    #   tt_hints = converter.to_truetype(ps_hints)
+    class HintConverter
+      # Convert hints to PostScript format
+      #
+      # @param hints [Array<Hint>] Source hints (any format)
+      # @return [Array<Hint>] Hints in PostScript format
+      def to_postscript(hints)
+        return [] if hints.nil? || hints.empty?
+
+        hints.map do |hint|
+          next hint if hint.source_format == :postscript
+
+          convert_hint_to_postscript(hint)
+        end.compact
+      end
+
+      # Convert hints to TrueType format
+      #
+      # @param hints [Array<Hint>] Source hints (any format)
+      # @return [Array<Hint>] Hints in TrueType format
+      def to_truetype(hints)
+        return [] if hints.nil? || hints.empty?
+
+        hints.map do |hint|
+          next hint if hint.source_format == :truetype
+
+          convert_hint_to_truetype(hint)
+        end.compact
+      end
+
+      # Optimize hint set by removing redundant hints
+      #
+      # @param hints [Array<Hint>] Hints to optimize
+      # @return [Array<Hint>] Optimized hints
+      def optimize(hints)
+        return [] if hints.nil? || hints.empty?
+
+        # Remove duplicate hints
+        unique_hints = hints.uniq { |h| [h.type, h.data] }
+
+        # Remove conflicting hints (keep first)
+        remove_conflicts(unique_hints)
+      end
+
+      # Convert entire HintSet between formats
+      #
+      # @param hint_set [Models::HintSet] Source hint set
+      # @param target_format [Symbol] Target format (:truetype or :postscript)
+      # @return [Models::HintSet] Converted hint set
+      def convert_hint_set(hint_set, target_format)
+        return hint_set if hint_set.format == target_format.to_s
+
+        result = Models::HintSet.new(format: target_format.to_s)
+
+        case target_format
+        when :postscript
+          # Convert font-level TT → PS
+          if hint_set.font_program || hint_set.control_value_program ||
+             hint_set.control_values&.any?
+            ps_dict = convert_tt_programs_to_ps_dict(
+              hint_set.font_program,
+              hint_set.control_value_program,
+              hint_set.control_values
+            )
+            result.private_dict_hints = ps_dict.to_json
+          end
+
+          # Convert per-glyph hints
+          hint_set.hinted_glyph_ids.each do |glyph_id|
+            glyph_hints = hint_set.get_glyph_hints(glyph_id)
+            ps_hints = to_postscript(glyph_hints)
+            result.add_glyph_hints(glyph_id, ps_hints) unless ps_hints.empty?
+          end
+
+        when :truetype
+          # Convert font-level PS → TT
+          if hint_set.private_dict_hints && hint_set.private_dict_hints != "{}"
+            tt_programs = convert_ps_dict_to_tt_programs(
+              JSON.parse(hint_set.private_dict_hints)
+            )
+            result.font_program = tt_programs[:fpgm]
+            result.control_value_program = tt_programs[:prep]
+            result.control_values = tt_programs[:cvt]
+          end
+
+          # Convert per-glyph hints
+          hint_set.hinted_glyph_ids.each do |glyph_id|
+            glyph_hints = hint_set.get_glyph_hints(glyph_id)
+            tt_hints = to_truetype(glyph_hints)
+            result.add_glyph_hints(glyph_id, tt_hints) unless tt_hints.empty?
+          end
+        end
+
+        result.has_hints = !result.empty?
+        result
+      end
+
+      private
+
+      # Convert a single hint to PostScript format
+      #
+      # @param hint [Hint] Source hint
+      # @return [Hint, nil] Converted hint or nil if incompatible
+      def convert_hint_to_postscript(hint)
+        return nil unless hint.compatible_with?(:postscript)
+
+        # Get PostScript representation from hint
+        ps_data = hint.to_postscript
+
+        # Create new hint with PostScript format
+        Models::Hint.new(
+          type: hint.type,
+          data: ps_data,
+          source_format: :postscript
+        )
+      rescue StandardError => e
+        warn "Failed to convert hint to PostScript: #{e.message}"
+        nil
+      end
+
+      # Convert a single hint to TrueType format
+      #
+      # @param hint [Hint] Source hint
+      # @return [Hint, nil] Converted hint or nil if incompatible
+      def convert_hint_to_truetype(hint)
+        return nil unless hint.compatible_with?(:truetype)
+
+        # Get TrueType representation from hint
+        tt_instructions = hint.to_truetype
+
+        # Create new hint with TrueType format
+        Models::Hint.new(
+          type: hint.type,
+          data: { instructions: tt_instructions },
+          source_format: :truetype
+        )
+      rescue StandardError => e
+        warn "Failed to convert hint to TrueType: #{e.message}"
+        nil
+      end
+
+      # Remove conflicting hints from set
+      #
+      # @param hints [Array<Hint>] Hints to check
+      # @return [Array<Hint>] Non-conflicting hints
+      def remove_conflicts(hints)
+        non_conflicting = []
+
+        hints.each do |hint|
+          # Check if this hint conflicts with any already selected
+          conflicts = non_conflicting.any? do |existing|
+            hints_conflict?(hint, existing)
+          end
+
+          non_conflicting << hint unless conflicts
+        end
+
+        non_conflicting
+      end
+
+      # Check if two hints conflict
+      #
+      # @param hint1 [Hint] First hint
+      # @param hint2 [Hint] Second hint
+      # @return [Boolean] True if hints conflict
+      def hints_conflict?(hint1, hint2)
+        # Hints of different types don't conflict
+        return false if hint1.type != hint2.type
+
+        case hint1.type
+        when :stem
+          # Stem hints conflict if they overlap
+          stems_overlap?(hint1.data, hint2.data)
+        when :interpolate
+          # Multiple interpolation hints on same axis conflict
+          hint1.data[:axis] == hint2.data[:axis]
+        else
+          # Other hint types don't conflict
+          false
+        end
+      end
+
+      # Check if two stem hints overlap
+      #
+      # @param stem1 [Hash] First stem data
+      # @param stem2 [Hash] Second stem data
+      # @return [Boolean] True if stems overlap
+      def stems_overlap?(stem1, stem2)
+        # Must be same orientation to conflict
+        return false if stem1[:orientation] != stem2[:orientation]
+
+        pos1 = stem1[:position] || 0
+        width1 = stem1[:width] || 0
+        pos2 = stem2[:position] || 0
+        width2 = stem2[:width] || 0
+
+        # Check if ranges overlap
+        end1 = pos1 + width1
+        end2 = pos2 + width2
+
+        pos1 < end2 && pos2 < end1
+      end
+
+      # Convert TrueType font programs to PostScript Private dict
+      #
+      # Analyzes TrueType fpgm, prep, and cvt to extract semantic intent
+      # and generate corresponding PostScript hint parameters.
+      #
+      # @param fpgm [String] Font program bytecode
+      # @param prep [String] Control value program bytecode
+      # @param cvt [Array<Integer>] Control values
+      # @return [Hash] PostScript Private dict hint parameters
+      def convert_tt_programs_to_ps_dict(fpgm, prep, cvt)
+        hints = {}
+
+        # Extract stem widths from cvt if present
+        # CVT values typically contain standard widths
+        if cvt && !cvt.empty?
+          # First CVT value often represents standard horizontal stem
+          hints[:std_hw] = cvt[0].abs if cvt.length > 0
+          # Second CVT value often represents standard vertical stem
+          hints[:std_vw] = cvt[1].abs if cvt.length > 1
+        end
+
+        # Analyze control value program for alignment zones
+        # TrueType doesn't have exact Blue zones, so we use defaults
+        # These are standard values that work for most Latin fonts
+        hints[:blue_values] = [-20, 0, 706, 726]
+
+        # Optional: Add other_blues for descenders if we detect them
+        # This would require analyzing prep program, which is complex
+        # For now, use conservative defaults
+
+        hints
+      rescue StandardError => e
+        warn "Error converting TT programs to PS dict: #{e.message}"
+        {}
+      end
+
+      # Convert PostScript Private dict to TrueType font programs
+      #
+      # Generates TrueType control values and programs from PostScript
+      # hint parameters.
+      #
+      # @param ps_dict [Hash] PostScript Private dict parameters
+      # @return [Hash] TrueType programs ({ fpgm:, prep:, cvt: })
+      def convert_ps_dict_to_tt_programs(ps_dict)
+        # Handle both string and symbol keys from JSON
+        ps_dict = ps_dict.transform_keys(&:to_sym) if ps_dict.keys.first.is_a?(String)
+
+        # Generate control values from PS parameters
+        cvt = []
+
+        # Add standard stem widths as CVT values
+        cvt << ps_dict[:std_hw] if ps_dict[:std_hw]
+        cvt << ps_dict[:std_vw] if ps_dict[:std_vw]
+
+        # Add stem snap values if present
+        if ps_dict[:stem_snap_h]&.is_a?(Array)
+          cvt.concat(ps_dict[:stem_snap_h])
+        end
+        if ps_dict[:stem_snap_v]&.is_a?(Array)
+          cvt.concat(ps_dict[:stem_snap_v])
+        end
+
+        # Remove duplicates and sort
+        cvt = cvt.uniq.sort
+
+        # Generate basic prep program (empty for converted fonts)
+        # A real implementation would generate instructions to set up CVT
+        prep = ""
+
+        # fpgm typically empty for converted fonts
+        # Functions would need to be synthesized from scratch
+        fpgm = ""
+
+        { fpgm: fpgm, prep: prep, cvt: cvt }
+      rescue StandardError => e
+        warn "Error converting PS dict to TT programs: #{e.message}"
+        { fpgm: "", prep: "", cvt: [] }
+      end
+    end
+  end
+end

data/lib/fontisan/hints/postscript_hint_applier.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require_relative "../models/hint"
+require "json"
+
+module Fontisan
+  module Hints
+    # Applies rendering hints to PostScript/CFF font tables
+    #
+    # This applier validates and applies PostScript hint data to CFF fonts by
+    # rebuilding the entire CFF table structure with updated Private DICT parameters.
+    #
+    # **Status**: Fully Operational (Phase 10A Complete)
+    #
+    # **PostScript Hint Parameters (Private DICT)**:
+    #
+    # - blue_values: Alignment zones for overshoot suppression
+    # - other_blues: Additional alignment zones
+    # - std_hw: Standard horizontal stem width
+    # - std_vw: Standard vertical stem width
+    # - stem_snap_h: Horizontal stem snap widths
+    # - stem_snap_v: Vertical stem snap widths
+    # - blue_scale, blue_shift, blue_fuzz: Overshoot parameters
+    # - force_bold: Force bold flag
+    # - language_group: Language group (0=Latin, 1=CJK)
+    #
+    # @example Apply PostScript hints
+    #   applier = PostScriptHintApplier.new
+    #   tables = { "CFF " => cff_table }
+    #   hint_set = HintSet.new(format: "postscript", private_dict_hints: hints_json)
+    #   result = applier.apply(hint_set, tables)
+    class PostScriptHintApplier
+      # Apply PostScript hints to font tables
+      #
+      # Validates hint data and rebuilds CFF table with updated Private DICT.
+      # Supports arbitrary Private DICT size changes through full table reconstruction.
+      # Also supports per-glyph hints injected directly into CharStrings.
+      #
+      # @param hint_set [HintSet] Hint data to apply
+      # @param tables [Hash] Font tables (must include "CFF " or "CFF2 ")
+      # @return [Hash] Updated font tables with hints applied
+      def apply(hint_set, tables)
+        return tables if hint_set.nil? || hint_set.empty?
+        return tables unless hint_set.format == "postscript"
+
+        if cff2_table?(tables)
+          apply_cff2_hints(hint_set, tables)
+        elsif cff_table?(tables)
+          apply_cff_hints(hint_set, tables)
+        else
+          tables
+        end
+      end
+
+      private
+
+      # Check if tables contain CFF2 table
+      #
+      # @param tables [Hash] Font tables
+      # @return [Boolean] True if CFF2 table present
+      def cff2_table?(tables)
+        tables.key?("CFF2") || tables.key?("CFF2 ")
+      end
+
+      # Check if tables contain CFF table
+      #
+      # @param tables [Hash] Font tables
+      # @return [Boolean] True if CFF table present
+      def cff_table?(tables)
+        tables.key?("CFF ")
+      end
+
+      # Apply hints to CFF2 variable font
+      #
+      # @param hint_set [HintSet] Hint set with font-level and per-glyph hints
+      # @param tables [Hash] Font tables
+      # @return [Hash] Updated tables
+      def apply_cff2_hints(hint_set, tables)
+        # Load CFF2 table
+        cff2_data = tables["CFF2"] || tables["CFF2 "]
+
+        begin
+          require_relative "../tables/cff2/table_reader"
+          require_relative "../tables/cff2/table_builder"
+
+          reader = Tables::Cff2::TableReader.new(cff2_data)
+
+          # Validate CFF2 version
+          reader.read_header
+          unless reader.header[:major_version] == 2
+            warn "Invalid CFF2 table version: #{reader.header[:major_version]}"
+            return tables
+          end
+
+          # Build with hints
+          builder = Tables::Cff2::TableBuilder.new(reader, hint_set)
+          modified_table = builder.build
+
+          # Update tables
+          table_key = tables.key?("CFF2") ? "CFF2" : "CFF2 "
+          tables[table_key] = modified_table
+
+          tables
+        rescue StandardError => e
+          warn "Error applying CFF2 hints: #{e.message}"
+          tables
+        end
+      end
+
+      # Apply hints to CFF font
+      #
+      # @param hint_set [HintSet] Hint set with font-level and per-glyph hints
+      # @param tables [Hash] Font tables
+      # @return [Hash] Updated tables
+      def apply_cff_hints(hint_set, tables)
+        return tables unless tables["CFF "]
+
+        # Validate hint parameters (Private DICT)
+        hint_params = parse_hint_parameters(hint_set)
+
+        # Check if we have per-glyph hints
+        has_per_glyph_hints = hint_set.hinted_glyph_count.positive?
+
+        # If neither font-level nor per-glyph hints, return unchanged
+        return tables unless hint_params || has_per_glyph_hints
+
+        # Validate font-level parameters if present
+        if hint_params && !valid_hint_parameters?(hint_params)
+          return tables
+        end
+
+        # Apply hints (both font-level and per-glyph)
+        begin
+          require_relative "../tables/cff/table_builder"
+          require_relative "../tables/cff/charstring_rebuilder"
+          require_relative "../tables/cff/hint_operation_injector"
+          require_relative "../tables/cff"
+
+          # Parse CFF binary data into Cff object if needed
+          cff_data = tables["CFF "]
+          cff_table = if cff_data.is_a?(Tables::Cff)
+                        cff_data
+                      else
+                        Tables::Cff.read(cff_data)
+                      end
+
+          # Prepare per-glyph hint data if present
+          per_glyph_hints = if has_per_glyph_hints
+                              extract_per_glyph_hints(hint_set)
+                            else
+                              nil
+                            end
+
+          new_cff_data = Tables::Cff::TableBuilder.rebuild(
+            cff_table,
+            private_dict_hints: hint_params,
+            per_glyph_hints: per_glyph_hints
+          )
+
+          tables["CFF "] = new_cff_data
+          tables
+        rescue StandardError => e
+          warn "Failed to apply PostScript hints: #{e.message}"
+          tables
+        end
+      end
+
+      # Parse hint parameters from HintSet
+      #
+      # @param hint_set [HintSet] Hint set with Private dict hints
+      # @return [Hash, nil] Parsed hint parameters, or nil if invalid
+      def parse_hint_parameters(hint_set)
+        return nil unless hint_set.private_dict_hints
+        return nil if hint_set.private_dict_hints == "{}"
+
+        JSON.parse(hint_set.private_dict_hints)
+      rescue JSON::ParserError => e
+        warn "Failed to parse Private dict hints: #{e.message}"
+        nil
+      end
+
+      # Validate hint parameters against CFF specification limits
+      #
+      # @param params [Hash] Hint parameters
+      # @return [Boolean] True if all parameters are valid
+      def valid_hint_parameters?(params)
+        # Validate blue values (must be pairs, max 7 pairs = 14 values)
+        if params["blue_values"] || params[:blue_values]
+          values = params["blue_values"] || params[:blue_values]
+          return false unless values.is_a?(Array)
+          return false if values.length > 14  # Max 7 pairs
+          return false if values.length.odd?  # Must be pairs
+        end
+
+        # Validate other_blues (max 5 pairs = 10 values)
+        if params["other_blues"] || params[:other_blues]
+          values = params["other_blues"] || params[:other_blues]
+          return false unless values.is_a?(Array)
+          return false if values.length > 10
+          return false if values.length.odd?
+        end
+
+        # Validate stem widths (single values)
+        if params["std_hw"] || params[:std_hw]
+          value = params["std_hw"] || params[:std_hw]
+          return false unless value.is_a?(Numeric)
+          return false if value.negative?
+        end
+
+        if params["std_vw"] || params[:std_vw]
+          value = params["std_vw"] || params[:std_vw]
+          return false unless value.is_a?(Numeric)
+          return false if value.negative?
+        end
+
+        # Validate stem snaps (arrays, max 12 values each)
+        %w[stem_snap_h stem_snap_v].each do |key|
+          next unless params[key] || params[key.to_sym]
+
+          values = params[key] || params[key.to_sym]
+          return false unless values.is_a?(Array)
+          return false if values.length > 12
+        end
+
+        # Validate blue_scale (should be positive)
+        if params["blue_scale"] || params[:blue_scale]
+          value = params["blue_scale"] || params[:blue_scale]
+          return false unless value.is_a?(Numeric)
+          return false if value <= 0
+        end
+
+        # Validate language_group (0 or 1 only)
+        if params["language_group"] || params[:language_group]
+          value = params["language_group"] || params[:language_group]
+          return false unless [0, 1].include?(value)
+        end
+
+        true
+      end
+
+      # Extract specific hint parameter with symbol/string key support
+      #
+      # @param params [Hash] Hint parameters
+      # @param key [String] Parameter name
+      # @return [Object, nil] Parameter value
+      def extract_param(params, key)
+        params[key] || params[key.to_sym]
+      end
+
+      # Extract per-glyph hint data from HintSet
+      #
+      # @param hint_set [HintSet] Hint set with per-glyph hints
+      # @return [Hash] Hash mapping glyph_id => Array<Hint>
+      def extract_per_glyph_hints(hint_set)
+        per_glyph = {}
+
+        hint_set.hinted_glyph_ids.each do |glyph_id|
+          hints = hint_set.get_glyph_hints(glyph_id)
+          per_glyph[glyph_id.to_i] = hints unless hints.empty?
+        end
+
+        per_glyph
+      end
+    end
+  end
+end