fontisan 0.2.0 → 0.2.2

data/lib/fontisan/hints/truetype_hint_applier.rb

@@ -1,70 +1,116 @@
 # frozen_string_literal: true
 
-require_relative "../models/hint"
-
 module Fontisan
   module Hints
-    # Applies rendering hints to TrueType glyph data
+    # Applies rendering hints to TrueType font tables
+    #
+    # This applier writes TrueType hint data into font-level tables:
+    # - fpgm (Font Program) - bytecode executed once at font initialization
+    # - prep (Control Value Program) - bytecode for glyph preparation
+    # - cvt (Control Values) - array of 16-bit values for hinting metrics
     #
-    # This applier converts universal Hint objects into TrueType bytecode
-    # instructions and integrates them into glyph data. It ensures proper
-    # instruction sequencing and maintains compatibility with TrueType
-    # instruction execution model.
+    # The applier ensures proper table structure with correct checksums
+    # and does not corrupt the font if hint application fails.
     #
-    # @example Apply hints to a glyph
+    # @example Apply hints from a HintSet
     #   applier = TrueTypeHintApplier.new
-    #   glyph_with_hints = applier.apply(glyph, hints)
+    #   tables = {}
+    #   updated_tables = applier.apply(hint_set, tables)
     class TrueTypeHintApplier
-      # Apply hints to TrueType glyph
+      # Apply TrueType hints to font tables
       #
-      # @param glyph [Glyph] Target glyph
-      # @param hints [Array<Hint>] Hints to apply
-      # @return [Glyph] Glyph with applied hints
-      def apply(glyph, hints)
-        return glyph if hints.nil? || hints.empty?
-        return glyph if glyph.nil?
+      # @param hint_set [HintSet] Hint data to apply
+      # @param tables [Hash] Font tables to update
+      # @return [Hash] Updated font tables
+      def apply(hint_set, tables)
+        return tables if hint_set.nil? || hint_set.empty?
+        return tables unless hint_set.format == "truetype"
 
-        # Convert hints to TrueType instructions
-        instructions = build_instructions(hints)
+        # Write fpgm table if present
+        if hint_set.font_program && !hint_set.font_program.empty?
+          tables["fpgm"] = build_fpgm_table(hint_set.font_program)
+        end
 
-        # Apply to glyph (this is a simplified version)
-        # In a real implementation, we would need to:
-        # 1. Analyze existing glyph structure
-        # 2. Insert instructions at appropriate points
-        # 3. Update glyph instruction data
+        # Write prep table if present
+        if hint_set.control_value_program && !hint_set.control_value_program.empty?
+          tables["prep"] = build_prep_table(hint_set.control_value_program)
+        end
 
-        # For now, we just return the glyph as-is since
-        # this is a complex operation requiring deep integration
-        # with the glyph structure
-        glyph
+        # Write cvt table if present
+        if hint_set.control_values && !hint_set.control_values.empty?
+          tables["cvt "] = build_cvt_table(hint_set.control_values)
+        end
+
+        # Future enhancement: Apply per-glyph hints to glyf table
+        # For now, font-level tables only
+
+        tables
       end
 
       private
 
-      # Build TrueType instruction sequence from hints
+      # Build fpgm (Font Program) table
       #
-      # @param hints [Array<Hint>] Hints to convert
-      # @return [Array<Integer>] Instruction bytes
-      def build_instructions(hints)
-        instructions = []
+      # @param program_data [String] Raw bytecode
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_fpgm_table(program_data)
+        {
+          tag: "fpgm",
+          data: program_data,
+          checksum: calculate_checksum(program_data),
+        }
+      end
 
-        hints.each do |hint|
-          hint_instructions = hint.to_truetype
-          instructions.concat(hint_instructions) if hint_instructions
-        end
+      # Build prep (Control Value Program) table
+      #
+      # @param program_data [String] Raw bytecode
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_prep_table(program_data)
+        {
+          tag: "prep",
+          data: program_data,
+          checksum: calculate_checksum(program_data),
+        }
+      end
+
+      # Build cvt (Control Values) table
+      #
+      # CVT values are 16-bit signed integers (FWORD) in big-endian format.
+      # Each value represents a design-space coordinate used for hinting.
+      #
+      # @param control_values [Array<Integer>] Array of 16-bit signed values
+      # @return [Hash] Table structure with tag, data, and checksum
+      def build_cvt_table(control_values)
+        # Pack as 16-bit big-endian signed integers (s> = signed big-endian)
+        data = control_values.pack("s>*")
 
-        instructions
+        {
+          tag: "cvt ",
+          data: data,
+          checksum: calculate_checksum(data),
+        }
       end
 
-      # Validate instruction sequence
+      # Calculate OpenType table checksum
+      #
+      # OpenType spec requires tables to be checksummed as 32-bit unsigned
+      # integers in big-endian format. The table is padded to a multiple of
+      # 4 bytes with zeros before checksum calculation.
       #
-      # @param instructions [Array<Integer>] Instructions to validate
-      # @return [Boolean] True if valid
-      def valid_instructions?(instructions)
-        return true if instructions.empty?
+      # @param data [String] Table data
+      # @return [Integer] 32-bit checksum
+      def calculate_checksum(data)
+        # Pad to 4-byte boundary with zeros
+        padding_needed = (4 - data.length % 4) % 4
+        padded = data + ("\x00" * padding_needed)
+
+        # Sum as 32-bit unsigned integers in big-endian
+        checksum = 0
+        (0...padded.length).step(4) do |i|
+          checksum = (checksum + padded[i, 4].unpack1("N")) & 0xFFFFFFFF
+        end
 
-        # Basic validation - check for valid opcodes
-        instructions.all? { |byte| byte >= 0 && byte <= 255 }
+        checksum
       end
     end
   end

data/lib/fontisan/hints/truetype_hint_extractor.rb

@@ -29,12 +29,36 @@ module Fontisan
       MDRP_MIN_RND_BLACK = 0xC0
       IUP_Y = 0x30
       IUP_X = 0x31
-      SHP = [0x32, 0x33]
+      SHP = [0x32, 0x33].freeze
       ALIGNRP = 0x3C
       DELTAP1 = 0x5D
       DELTAP2 = 0x71
       DELTAP3 = 0x72
 
+      # Extract complete hint data from TrueType font
+      #
+      # This extracts both font-level hints (fpgm, prep, cvt tables) and
+      # per-glyph hints from glyph instructions.
+      #
+      # @param font [TrueTypeFont] TrueType font object
+      # @return [Models::HintSet] Complete hint set
+      def extract_from_font(font)
+        hint_set = Models::HintSet.new(format: "truetype")
+
+        # Extract font-level programs
+        hint_set.font_program = extract_font_program(font)
+        hint_set.control_value_program = extract_control_value_program(font)
+        hint_set.control_values = extract_control_values(font)
+
+        # Extract per-glyph hints
+        extract_glyph_hints(font, hint_set)
+
+        # Update metadata
+        hint_set.has_hints = !hint_set.empty?
+
+        hint_set
+      end
+
       # Extract hints from TrueType glyph
       #
       # @param glyph [Glyph] TrueType glyph with instructions
@@ -80,7 +104,7 @@ module Fontisan
             hints << Models::Hint.new(
               type: :interpolate,
               data: { axis: opcode == IUP_Y ? :y : :x },
-              source_format: :truetype
+              source_format: :truetype,
             )
             i += 1
 
@@ -89,7 +113,7 @@ module Fontisan
             hints << Models::Hint.new(
               type: :shift,
               data: { instructions: [opcode] },
-              source_format: :truetype
+              source_format: :truetype,
             )
             i += 1
 
@@ -98,7 +122,7 @@ module Fontisan
             hints << Models::Hint.new(
               type: :align,
               data: {},
-              source_format: :truetype
+              source_format: :truetype,
             )
             i += 1
 
@@ -113,9 +137,9 @@ module Fontisan
                 type: :delta,
                 data: {
                   instructions: [opcode] + [count] + delta_data,
-                  count: count
+                  count: count,
                 },
-                source_format: :truetype
+                source_format: :truetype,
               )
               i += count * 2 + 1
             end
@@ -141,7 +165,7 @@ module Fontisan
 
         # Check if next instruction is MDRP (stem width)
         has_width = index + 1 < bytes.length &&
-                    bytes[index + 1] == MDRP_MIN_RND_BLACK
+          bytes[index + 1] == MDRP_MIN_RND_BLACK
 
         if has_width
           Models::Hint.new(
@@ -149,14 +173,113 @@ module Fontisan
             data: {
               position: 0, # Would be extracted from graphics state
               width: 0,    # Would be calculated from MDRP
-              orientation: :vertical # Inferred from instruction context
+              orientation: :vertical, # Inferred from instruction context
             },
-            source_format: :truetype
+            source_format: :truetype,
           )
-        else
-          nil
         end
       end
+
+      # Extract font program (fpgm table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [String] Font program bytecode (binary string)
+      def extract_font_program(font)
+        return "" unless font.has_table?("fpgm")
+
+        font_program_data = font.instance_variable_get(:@table_data)["fpgm"]
+        return "" unless font_program_data
+
+        # Return as binary string
+        font_program_data.force_encoding("ASCII-8BIT")
+      rescue StandardError => e
+        warn "Failed to extract font program: #{e.message}"
+        ""
+      end
+
+      # Extract control value program (prep table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [String] Control value program bytecode (binary string)
+      def extract_control_value_program(font)
+        return "" unless font.has_table?("prep")
+
+        prep_data = font.instance_variable_get(:@table_data)["prep"]
+        return "" unless prep_data
+
+        # Return as binary string
+        prep_data.force_encoding("ASCII-8BIT")
+      rescue StandardError => e
+        warn "Failed to extract control value program: #{e.message}"
+        ""
+      end
+
+      # Extract control values (cvt table)
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @return [Array<Integer>] Control values
+      def extract_control_values(font)
+        return [] unless font.has_table?("cvt ")
+
+        cvt_data = font.instance_variable_get(:@table_data)["cvt "]
+        return [] unless cvt_data
+
+        # CVT table is an array of 16-bit signed integers (FWord values)
+        values = []
+        io = StringIO.new(cvt_data)
+        while !io.eof?
+          # Read 16-bit big-endian signed integer
+          bytes = io.read(2)
+          break unless bytes&.length == 2
+
+          value = bytes.unpack1("n") # Unsigned short
+          # Convert to signed
+          value = value - 65536 if value > 32767
+          values << value
+        end
+
+        values
+      rescue StandardError => e
+        warn "Failed to extract control values: #{e.message}"
+        []
+      end
+
+      # Extract per-glyph hints from glyf table
+      #
+      # @param font [TrueTypeFont] TrueType font
+      # @param hint_set [Models::HintSet] Hint set to populate
+      # @return [void]
+      def extract_glyph_hints(font, hint_set)
+        return unless font.has_table?("glyf")
+
+        glyf_table = font.table("glyf")
+        return unless glyf_table
+
+        # Get number of glyphs from maxp table
+        maxp_table = font.table("maxp")
+        return unless maxp_table
+
+        num_glyphs = maxp_table.num_glyphs
+
+        # Iterate through all glyphs
+        (0...num_glyphs).each do |glyph_id|
+          glyph = glyf_table.glyph_for(glyph_id)
+          next unless glyph
+          next if glyph.number_of_contours <= 0 # Skip compound glyphs and empty glyphs
+
+          # Extract hints from simple glyph instructions
+          hints = extract(glyph)
+          next if hints.empty?
+
+          # Store glyph hints
+          hint_set.add_glyph_hints(glyph_id, hints)
+        rescue StandardError
+          # Skip glyphs that fail to parse
+          next
+        end
+      rescue StandardError => e
+        warn "Failed to extract glyph hints: #{e.message}"
+      end
     end
   end
 end

data/lib/fontisan/hints/truetype_instruction_analyzer.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Hints
+    # Analyzes TrueType bytecode instructions to extract hint parameters
+    #
+    # This analyzer parses fpgm (Font Program) and prep (Control Value Program)
+    # bytecode to extract semantic hint information that can be converted to
+    # PostScript Private dict parameters.
+    #
+    # **Key Extracted Parameters:**
+    #
+    # - Blue zones (alignment zones for baseline, x-height, cap-height)
+    # - Stem widths (from CVT setup in prep)
+    # - Delta base and shift values
+    # - Twilight zone setup
+    #
+    # @example Analyze prep program
+    #   analyzer = TrueTypeInstructionAnalyzer.new
+    #   params = analyzer.analyze_prep(prep_bytecode, cvt_values)
+    class TrueTypeInstructionAnalyzer
+      # TrueType instruction opcodes relevant for hint extraction
+      NPUSHB = 0x40   # Push N bytes
+      NPUSHW = 0x41   # Push N words
+      PUSHB = (0xB0..0xB7).to_a  # Push 1-8 bytes
+      PUSHW = (0xB8..0xBF).to_a  # Push 1-8 words
+      SVTCA_Y = 0x00  # Set freedom and projection vectors to Y-axis
+      SVTCA_X = 0x01  # Set freedom and projection vectors to X-axis
+      RCVT = 0x45     # Read CVT
+      WCVTP = 0x44    # Write CVT (in Pixels)
+      WCVTF = 0x70    # Write CVT (in FUnits)
+      MDAP = [0x2E, 0x2F].freeze  # Move Direct Absolute Point
+      SCVTCI = 0x1D   # Set Control Value Table Cut In
+      SSWCI = 0x1E    # Set Single Width Cut In
+      SSW = 0x1F      # Set Single Width
+
+      # Analyze prep program to extract hint parameters
+      #
+      # @param prep [String] Control value program bytecode
+      # @param cvt [Array<Integer>] Control values
+      # @return [Hash] Extracted hint parameters
+      def analyze_prep(prep, cvt = [])
+        return {} if prep.nil? && (cvt.nil? || cvt.empty?)
+
+        params = {}
+
+        # Parse prep bytecode if present
+        if prep && !prep.empty?
+          bytes = prep.bytes
+          stack = []
+          i = 0
+
+          while i < bytes.length
+            opcode = bytes[i]
+
+            case opcode
+            when NPUSHB
+              # Push N bytes
+              i += 1
+              count = bytes[i]
+              i += 1
+              count.times do
+                stack.push(bytes[i])
+                i += 1
+              end
+              next
+
+            when NPUSHW
+              # Push N words (16-bit values)
+              i += 1
+              count = bytes[i]
+              i += 1
+              count.times do
+                value = (bytes[i] << 8) | bytes[i + 1]
+                # Convert to signed
+                value = value - 65536 if value > 32767
+                stack.push(value)
+                i += 2
+              end
+              next
+
+            when *PUSHB
+              # Push 1-8 bytes
+              count = opcode - 0xB0 + 1
+              i += 1
+              count.times do
+                stack.push(bytes[i])
+                i += 1
+              end
+              next
+
+            when *PUSHW
+              # Push 1-8 words
+              count = opcode - 0xB8 + 1
+              i += 1
+              count.times do
+                value = (bytes[i] << 8) | bytes[i + 1]
+                value = value - 65536 if value > 32767
+                stack.push(value)
+                i += 2
+              end
+              next
+
+            when WCVTP, WCVTF
+              # Write to CVT - this shows which CVT indices are being set up
+              # Pattern: value cvt_index WCVTP (stack top to bottom)
+              if stack.length >= 2
+                value = stack.pop
+                cvt_index = stack.pop
+                # Track CVT modifications (useful for understanding setup)
+              end
+
+            when SSW
+              # Set Single Width - used for stem width control
+              if stack.length >= 1
+                width = stack.pop
+                params[:single_width] = width unless params[:single_width]
+              end
+
+            when SSWCI
+              # Set Single Width Cut In
+              if stack.length >= 1
+                params[:single_width_cut_in] = stack.pop
+              end
+
+            when SCVTCI
+              # Set CVT Cut In
+              if stack.length >= 1
+                params[:cvt_cut_in] = stack.pop
+              end
+            end
+
+            i += 1
+          end
+        end
+
+        # Extract blue zones from CVT analysis (always do this if CVT is present)
+        if cvt && !cvt.empty?
+          params.merge!(extract_blue_zones_from_cvt(cvt))
+        end
+
+        params
+      rescue StandardError => e
+        warn "Error analyzing prep program: #{e.message}"
+        {}
+      end
+
+      # Analyze Font Program (fpgm) for complexity indicators
+      #
+      # The fpgm contains font-level function definitions. While we don't
+      # fully decompile it, we can extract useful metadata about hint complexity.
+      #
+      # @param fpgm [String] Binary fpgm data
+      # @return [Hash] Analysis results with complexity indicators
+      def analyze_fpgm(fpgm)
+        return {} if fpgm.nil? || fpgm.empty?
+
+        size = fpgm.bytesize
+
+        # Estimate complexity based on size
+        complexity = if size < 100
+                       :simple
+                     elsif size < 200
+                       :moderate
+                     else
+                       :complex
+                     end
+
+        {
+          fpgm_size: size,
+          has_functions: size > 0,
+          complexity: complexity,
+        }
+      rescue StandardError
+        # Return empty hash on any error
+        {}
+      end
+
+      # Extract blue zones from CVT values using heuristics
+      #
+      # Blue zones in PostScript define alignment constraints for
+      # baseline, x-height, cap-height, ascender, and descender.
+      # TrueType doesn't have explicit blue zones, but we can derive
+      # them from CVT values using common patterns.
+      #
+      # Heuristics:
+      # - Negative values near -250 to -200: Descender zones
+      # - Values near 0: Baseline zones
+      # - Values near 500-550: X-height zones
+      # - Values near 700-750: Cap-height zones
+      # - For large UPM (>2000): Scale thresholds proportionally
+      #
+      # @param cvt [Array<Integer>] Control Value Table entries
+      # @return [Hash] Extracted blue zone parameters
+      def extract_blue_zones_from_cvt(cvt)
+        return {} if cvt.nil? || cvt.empty?
+
+        zones = {}
+
+        # Detect scale from maximum absolute value
+        max_value = cvt.map(&:abs).max
+        scale_factor = max_value > 1000 ? (max_value / 1000.0) : 1.0
+
+        # Scaled thresholds
+        descender_min = (-300 * scale_factor).to_i
+        descender_max = (-150 * scale_factor).to_i
+        baseline_range = (50 * scale_factor).to_i
+        xheight_min = (450 * scale_factor).to_i
+        xheight_max = (600 * scale_factor).to_i
+        capheight_min = (650 * scale_factor).to_i
+        capheight_max = (1500 * scale_factor).to_i  # Wider range for large UPM
+
+        # Group CVT values by typical alignment zones
+        descender_values = cvt.select { |v| v < descender_max && v > descender_min }
+        baseline_values = cvt.select { |v| v >= -baseline_range && v <= baseline_range }
+        xheight_values = cvt.select { |v| v >= xheight_min && v <= xheight_max }
+        capheight_values = cvt.select { |v| v >= capheight_min && v <= capheight_max }
+
+        # Build blue_values (baseline and top zones)
+        blue_values = []
+
+        # Add baseline zone if detected
+        if baseline_values.any?
+          min_baseline = baseline_values.min
+          max_baseline = baseline_values.max
+          blue_values << min_baseline << max_baseline
+        end
+
+        # Add cap-height zone if detected (or any top zone for large UPM)
+        if capheight_values.any?
+          min_cap = capheight_values.min
+          max_cap = capheight_values.max
+          blue_values << min_cap << max_cap
+        end
+
+        zones[:blue_values] = blue_values unless blue_values.empty?
+
+        # Build other_blues (descender zones)
+        if descender_values.any?
+          min_desc = descender_values.min
+          max_desc = descender_values.max
+          zones[:other_blues] = [min_desc, max_desc]
+        end
+
+        zones
+      end
+
+      private
+
+      # Estimate complexity of bytecode program
+      #
+      # @param bytes [Array<Integer>] Bytecode
+      # @return [Symbol] Complexity level (:simple, :moderate, :complex)
+      def estimate_complexity(bytes)
+        return :simple if bytes.length < 50
+        return :moderate if bytes.length < 200
+        :complex
+      end
+    end
+  end
+end