fontisan 0.2.1 → 0.2.3

data/lib/fontisan/hints/truetype_hint_extractor.rb

@@ -29,7 +29,7 @@ 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
@@ -104,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
 
@@ -113,7 +113,7 @@ module Fontisan
             hints << Models::Hint.new(
               type: :shift,
               data: { instructions: [opcode] },
-              source_format: :truetype
+              source_format: :truetype,
             )
             i += 1
 
@@ -122,7 +122,7 @@ module Fontisan
             hints << Models::Hint.new(
               type: :align,
               data: {},
-              source_format: :truetype
+              source_format: :truetype,
             )
             i += 1
 
@@ -137,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
@@ -165,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(
@@ -173,12 +173,10 @@ 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
 
@@ -265,21 +263,19 @@ module Fontisan
 
         # Iterate through all glyphs
         (0...num_glyphs).each do |glyph_id|
-          begin
-            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 => e
-            # Skip glyphs that fail to parse
-            next
-          end
+          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}"

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

data/lib/fontisan/hints/truetype_instruction_generator.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Hints
+    # Generates TrueType instruction bytecode from PostScript hint parameters
+    #
+    # This class is the inverse of TrueTypeInstructionAnalyzer - it takes
+    # PostScript hint parameters and generates equivalent TrueType prep/fpgm
+    # programs and CVT values.
+    #
+    # TrueType Instruction Opcodes:
+    # - NPUSHB (0x40): Push n bytes
+    # - NPUSHW (0x41): Push n words (16-bit)
+    # - PUSHB[n] (0xB0-0xB7): Push 1-8 bytes
+    # - PUSHW[n] (0xB8-0xBF): Push 1-8 words
+    # - SSW (0x1F): Set Single Width
+    # - SSWCI (0x1E): Set Single Width Cut-In
+    # - SCVTCI (0x1D): Set CVT Cut-In
+    # - WCVTP (0x44): Write CVT in Pixels
+    # - WCVTF (0x70): Write CVT in FUnits
+    #
+    # @example Generate TrueType programs
+    #   generator = TrueTypeInstructionGenerator.new
+    #   programs = generator.generate({
+    #     blue_scale: 0.039625,
+    #     std_hw: 80,
+    #     std_vw: 90
+    #   })
+    #   programs[:prep] # => Binary prep program
+    #   programs[:fpgm] # => Binary fpgm program (usually empty)
+    #   programs[:cvt]  # => Array of CVT values
+    class TrueTypeInstructionGenerator
+      # TrueType instruction opcodes
+      NPUSHB = 0x40  # Push n bytes
+      NPUSHW = 0x41  # Push n words (16-bit)
+      PUSHB_BASE = 0xB0  # PUSHB[0] through PUSHB[7]
+      PUSHW_BASE = 0xB8  # PUSHW[0] through PUSHW[7]
+      SSW = 0x1F     # Set Single Width
+      SSWCI = 0x1E   # Set Single Width Cut-In
+      SCVTCI = 0x1D  # Set CVT Cut-In
+      WCVTP = 0x44   # Write CVT in Pixels
+      WCVTF = 0x70   # Write CVT in FUnits
+
+      # Size thresholds for instruction selection
+      MAX_PUSHB_INLINE = 8  # Maximum bytes for PUSHB[n]
+      MAX_PUSHW_INLINE = 8  # Maximum words for PUSHW[n]
+      BYTE_MAX = 255        # Maximum value for byte
+      WORD_MAX = 65535      # Maximum value for word
+
+      # Generate TrueType programs and CVT from PostScript parameters
+      #
+      # @param ps_params [Hash] PostScript hint parameters
+      # @option ps_params [Float] :blue_scale Blue scale value (0.0-1.0)
+      # @option ps_params [Integer] :std_hw Standard horizontal width
+      # @option ps_params [Integer] :std_vw Standard vertical width
+      # @option ps_params [Array<Integer>] :stem_snap_h Horizontal stem snap values
+      # @option ps_params [Array<Integer>] :stem_snap_v Vertical stem snap values
+      # @option ps_params [Array<Integer>] :blue_values Blue zone values
+      # @option ps_params [Array<Integer>] :other_blues Other blue zone values
+      # @return [Hash] Hash with :prep, :fpgm, and :cvt keys
+      def generate(ps_params)
+        # Normalize keys to symbols
+        ps_params = normalize_keys(ps_params)
+
+        {
+          fpgm: generate_fpgm(ps_params),
+          prep: generate_prep(ps_params),
+          cvt: generate_cvt(ps_params)
+        }
+      end
+
+      # Generate prep (Control Value Program) from PostScript parameters
+      #
+      # The prep program sets up global hint parameters:
+      # - CVT Cut-In (from blue_scale)
+      # - Single Width Cut-In (from std_hw/std_vw)
+      # - Single Width (from std_hw or std_vw)
+      #
+      # @param ps_params [Hash] PostScript parameters
+      # @return [String] Binary instruction bytes
+      def generate_prep(ps_params)
+        instructions = []
+
+        # Set CVT Cut-In from blue_scale if present
+        if ps_params[:blue_scale]
+          cvt_cut_in = calculate_cvt_cut_in(ps_params[:blue_scale])
+          instructions.concat(push_value(cvt_cut_in))
+          instructions << SCVTCI
+        end
+
+        # Set Single Width Cut-In if we have stem widths
+        if ps_params[:std_hw] || ps_params[:std_vw]
+          sw_cut_in = calculate_sw_cut_in(ps_params)
+          instructions.concat(push_value(sw_cut_in))
+          instructions << SSWCI
+        end
+
+        # Set Single Width (prefer horizontal, fall back to vertical)
+        single_width = ps_params[:std_hw] || ps_params[:std_vw]
+        if single_width
+          instructions.concat(push_value(single_width))
+          instructions << SSW
+        end
+
+        instructions.pack("C*")
+      end
+
+      # Generate fpgm (Font Program) from PostScript parameters
+      #
+      # For converted fonts, fpgm is typically empty as font-level
+      # functions are not needed for basic hint conversion.
+      #
+      # @param _ps_params [Hash] PostScript parameters (unused)
+      # @return [String] Binary instruction bytes (empty for converted fonts)
+      def generate_fpgm(_ps_params)
+        # For converted fonts, fpgm is typically empty
+        # Advanced implementations might generate function definitions here
+        "".b
+      end
+
+      # Generate CVT (Control Value Table) from PostScript parameters
+      #
+      # CVT entries are derived from:
+      # - stem_snap_h/stem_snap_v: Stem widths
+      # - blue_values/other_blues: Alignment zones
+      # - std_hw/std_vw: Standard widths
+      #
+      # Duplicates are removed and values sorted for optimal CVT organization.
+      #
+      # @param ps_params [Hash] PostScript parameters
+      # @return [Array<Integer>] Array of 16-bit signed integers
+      def generate_cvt(ps_params)
+        cvt = []
+
+        # Add standard widths to CVT
+        cvt << ps_params[:std_hw] if ps_params[:std_hw]
+        cvt << ps_params[:std_vw] if ps_params[:std_vw]
+
+        # Add stem snap values
+        if ps_params[:stem_snap_h]
+          cvt.concat(ps_params[:stem_snap_h])
+        end
+
+        if ps_params[:stem_snap_v]
+          cvt.concat(ps_params[:stem_snap_v])
+        end
+
+        # Add blue zone values (as pairs: bottom, top)
+        if ps_params[:blue_values]
+          cvt.concat(ps_params[:blue_values])
+        end
+
+        if ps_params[:other_blues]
+          cvt.concat(ps_params[:other_blues])
+        end
+
+        # Remove duplicates and sort for optimal CVT organization
+        cvt.uniq.sort
+      end
+
+      private
+
+      # Normalize hash keys to symbols
+      #
+      # @param hash [Hash] Input hash with string or symbol keys
+      # @return [Hash] Hash with symbol keys
+      def normalize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+        return hash if hash.empty? || hash.keys.first.is_a?(Symbol)
+
+        hash.transform_keys(&:to_sym)
+      end
+
+      # Calculate CVT Cut-In from PostScript blue_scale
+      #
+      # Blue scale controls the threshold at which alignment zones apply.
+      # We convert this to TrueType's CVT Cut-In value.
+      #
+      # @param blue_scale [Float] PostScript blue scale (0.0-1.0)
+      # @return [Integer] CVT Cut-In value in pixels
+      def calculate_cvt_cut_in(blue_scale)
+        # blue_scale of 0.039625 (common default) maps to ~17px cut-in
+        # Linear scaling: 0.039625 -> 17, 0.0 -> 0, 1.0 -> 428
+        (blue_scale * 428).round.clamp(0, 255)
+      end
+
+      # Calculate Single Width Cut-In from stem widths
+      #
+      # The cut-in determines when to apply single-width rounding.
+      # We use 9 pixels as a sensible default.
+      #
+      # @param _ps_params [Hash] PostScript parameters (for future use)
+      # @return [Integer] Single Width Cut-In in pixels
+      def calculate_sw_cut_in(_ps_params)
+        9 # Standard value: 9 pixels
+      end
+
+      # Push a single value onto the TrueType stack
+      #
+      # Selects the most efficient instruction based on value size.
+      #
+      # @param value [Integer] Value to push
+      # @return [Array<Integer>] Instruction bytes
+      def push_value(value)
+        if value <= BYTE_MAX
+          push_bytes([value])
+        else
+          push_words([value])
+        end
+      end
+
+      # Push byte values using most efficient instruction
+      #
+      # Uses PUSHB[n] for 1-8 values, NPUSHB for more.
+      #
+      # @param values [Array<Integer>] Byte values (0-255)
+      # @return [Array<Integer>] Instruction bytes
+      def push_bytes(values)
+        return [] if values.empty?
+
+        # Validate all values fit in bytes
+        unless values.all? { |v| v >= 0 && v <= BYTE_MAX }
+          raise ArgumentError, "Values must be in range 0-255 for PUSHB"
+        end
+
+        count = values.size
+
+        if count <= MAX_PUSHB_INLINE
+          # Use PUSHB[n-1] for 1-8 values
+          [PUSHB_BASE + count - 1] + values
+        else
+          # Use NPUSHB for more than 8 values
+          [NPUSHB, count] + values
+        end
+      end
+
+      # Push word values using most efficient instruction
+      #
+      # Uses PUSHW[n] for 1-8 values, NPUSHW for more.
+      # Words are encoded big-endian (high byte first).
+      #
+      # @param values [Array<Integer>] Word values (0-65535)
+      # @return [Array<Integer>] Instruction bytes
+      def push_words(values)
+        return [] if values.empty?
+
+        # Validate all values fit in words
+        unless values.all? { |v| v >= 0 && v <= WORD_MAX }
+          raise ArgumentError, "Values must be in range 0-65535 for PUSHW"
+        end
+
+        count = values.size
+        # Convert words to big-endian byte pairs
+        word_bytes = values.flat_map { |v| [(v >> 8) & 0xFF, v & 0xFF] }
+
+        if count <= MAX_PUSHW_INLINE
+          # Use PUSHW[n-1] for 1-8 values
+          [PUSHW_BASE + count - 1] + word_bytes
+        else
+          # Use NPUSHW for more than 8 values
+          [NPUSHW, count] + word_bytes
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/loading_modes.rb

@@ -28,12 +28,12 @@ module Fontisan
     MODES = {
       METADATA => {
         tables: %w[name head hhea maxp OS/2 post].freeze,
-        description: "Metadata mode - loads only identification and metrics tables (otfinfo-equivalent)"
+        description: "Metadata mode - loads only identification and metrics tables (otfinfo-equivalent)",
       }.freeze,
       FULL => {
         tables: :all,
-        description: "Full mode - loads all tables in the font"
-      }.freeze
+        description: "Full mode - loads all tables in the font",
+      }.freeze,
     }.freeze
 
     # Pre-computed Set for O(1) lookup of metadata tables
@@ -80,7 +80,7 @@ module Fontisan
     # @raise [ArgumentError] if mode is invalid
     def self.default_lazy?(mode)
       validate_mode!(mode)
-      true  # Lazy loading is recommended for all modes
+      true # Lazy loading is recommended for all modes
     end
 
     # Get mode description

data/lib/fontisan/models/collection_brief_info.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+require_relative "font_info"
+
+module Fontisan
+  module Models
+    # Model for collection brief information
+    #
+    # Represents collection metadata plus brief info for each font.
+    # Used by InfoCommand in brief mode for collections.
+    #
+    # @example Creating collection brief info
+    #   info = CollectionBriefInfo.new(
+    #     collection_path: "fonts.ttc",
+    #     collection_type: "TTC",
+    #     collection_version: "1.0",
+    #     num_fonts: 3,
+    #     fonts: [font_info1, font_info2, font_info3]
+    #   )
+    class CollectionBriefInfo < Lutaml::Model::Serializable
+      attribute :collection_path, :string
+      attribute :collection_type, :string
+      attribute :collection_version, :string
+      attribute :num_fonts, :integer
+      attribute :fonts, FontInfo, collection: true
+
+      key_value do
+        map "collection_path", to: :collection_path
+        map "collection_type", to: :collection_type
+        map "collection_version", to: :collection_version
+        map "num_fonts", to: :num_fonts
+        map "fonts", to: :fonts
+      end
+    end
+  end
+end