fontisan 0.2.0 → 0.2.2

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "set"
+
 module Fontisan
   # Loading modes module that defines which tables are loaded in each mode.
   #
@@ -26,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
@@ -78,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,31 @@
+# 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",
+    #     num_fonts: 3,
+    #     fonts: [font_info1, font_info2, font_info3]
+    #   )
+    class CollectionBriefInfo < Lutaml::Model::Serializable
+      attribute :collection_path, :string
+      attribute :num_fonts, :integer
+      attribute :fonts, FontInfo, collection: true
+
+      key_value do
+        map "collection_path", to: :collection_path
+        map "num_fonts", to: :num_fonts
+        map "fonts", to: :fonts
+      end
+    end
+  end
+end

data/lib/fontisan/models/font_info.rb

@@ -36,37 +36,9 @@ module Fontisan
       attribute :font_revision, :float
       attribute :permissions, :string
       attribute :units_per_em, :integer
+      attribute :collection_offset, :integer
 
-      json do
-        map "font_format", to: :font_format
-        map "is_variable", to: :is_variable
-        map "family_name", to: :family_name
-        map "subfamily_name", to: :subfamily_name
-        map "full_name", to: :full_name
-        map "postscript_name", to: :postscript_name
-        map "postscript_cid_name", to: :postscript_cid_name
-        map "preferred_family", to: :preferred_family
-        map "preferred_subfamily", to: :preferred_subfamily
-        map "mac_font_menu_name", to: :mac_font_menu_name
-        map "version", to: :version
-        map "unique_id", to: :unique_id
-        map "description", to: :description
-        map "designer", to: :designer
-        map "designer_url", to: :designer_url
-        map "manufacturer", to: :manufacturer
-        map "vendor_url", to: :vendor_url
-        map "vendor_id", to: :vendor_id
-        map "trademark", to: :trademark
-        map "copyright", to: :copyright
-        map "license_description", to: :license_description
-        map "license_url", to: :license_url
-        map "sample_text", to: :sample_text
-        map "font_revision", to: :font_revision
-        map "permissions", to: :permissions
-        map "units_per_em", to: :units_per_em
-      end
-
-      yaml do
+      key_value do
         map "font_format", to: :font_format
         map "is_variable", to: :is_variable
         map "family_name", to: :family_name
@@ -93,6 +65,7 @@ module Fontisan
         map "font_revision", to: :font_revision
         map "permissions", to: :permissions
         map "units_per_em", to: :units_per_em
+        map "collection_offset", to: :collection_offset
       end
     end
   end

data/lib/fontisan/models/hint.rb

@@ -1,7 +1,136 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Fontisan
   module Models
+    # Container for all font hint data
+    #
+    # This model holds complete hint information from a font including
+    # font-level programs, control values, and per-glyph hints. It provides
+    # a format-agnostic representation that can be converted between
+    # TrueType and PostScript formats.
+    #
+    # @example Creating a HintSet
+    #   hint_set = HintSet.new(
+    #     format: :truetype,
+    #     font_program: fpgm_data,
+    #     control_value_program: prep_data
+    #   )
+    class HintSet
+      # @return [String] Hint format (:truetype or :postscript)
+      attr_accessor :format
+
+      # TrueType font-level hint data
+      # @return [String] Font program (fpgm table) - bytecode executed once
+      attr_accessor :font_program
+
+      # @return [String] Control value program (prep table) - initialization code
+      attr_accessor :control_value_program
+
+      # @return [Array<Integer>] Control values (cvt table) - metrics for hinting
+      attr_accessor :control_values
+
+      # PostScript font-level hint data
+      # @return [String] CFF Private dict hint data (BlueValues, StdHW, etc.) as JSON
+      attr_accessor :private_dict_hints
+
+      # @return [Integer] Number of glyphs with hints
+      attr_accessor :hinted_glyph_count
+
+      # @return [Boolean] Whether hints are present
+      attr_accessor :has_hints
+
+      # Initialize a new HintSet
+      #
+      # @param format [String, Symbol] Hint format (:truetype or :postscript)
+      # @param font_program [String] Font program bytecode
+      # @param control_value_program [String] Control value program bytecode
+      # @param control_values [Array<Integer>] Control values
+      # @param private_dict_hints [String] Private dict hints as JSON
+      # @param hinted_glyph_count [Integer] Number of hinted glyphs
+      # @param has_hints [Boolean] Whether hints are present
+      def initialize(format: nil, font_program: "", control_value_program: "",
+                     control_values: [], private_dict_hints: "{}",
+                     hinted_glyph_count: 0, has_hints: false)
+        @format = format.to_s if format
+        @font_program = font_program || ""
+        @control_value_program = control_value_program || ""
+        @control_values = control_values || []
+        @private_dict_hints = private_dict_hints || "{}"
+        @glyph_hints = "{}"
+        @hinted_glyph_count = hinted_glyph_count
+        @has_hints = has_hints
+      end
+
+      # Add hints for a specific glyph
+      #
+      # @param glyph_id [Integer, String] Glyph identifier
+      # @param hints [Array<Hint>] Hints for the glyph
+      def add_glyph_hints(glyph_id, hints)
+        return if hints.nil? || hints.empty?
+
+        glyph_hints_hash = parse_glyph_hints
+        # Convert Hint objects to hashes for storage
+        hints_data = hints.map do |h|
+          {
+            type: h.type,
+            data: h.data,
+            source_format: h.source_format,
+          }
+        end
+        glyph_hints_hash[glyph_id.to_s] = hints_data
+        @glyph_hints = glyph_hints_hash.to_json
+        @hinted_glyph_count = glyph_hints_hash.keys.length
+        @has_hints = true
+      end
+
+      # Get hints for a specific glyph
+      #
+      # @param glyph_id [Integer, String] Glyph identifier
+      # @return [Array<Hint>] Hints for the glyph
+      def get_glyph_hints(glyph_id)
+        glyph_hints_hash = parse_glyph_hints
+        hints_data = glyph_hints_hash[glyph_id.to_s]
+        return [] unless hints_data
+
+        # Reconstruct Hint objects from serialized data
+        hints_data.map { |h| Hint.new(**h.transform_keys(&:to_sym)) }
+      end
+
+      # Get all glyph IDs with hints
+      #
+      # @return [Array<String>] Glyph identifiers
+      def hinted_glyph_ids
+        parse_glyph_hints.keys
+      end
+
+      # Check if empty (no hints)
+      #
+      # @return [Boolean] True if no hints present
+      def empty?
+        !has_hints &&
+          (font_program.nil? || font_program.empty?) &&
+          (control_value_program.nil? || control_value_program.empty?) &&
+          (control_values.nil? || control_values.empty?) &&
+          (private_dict_hints.nil? || private_dict_hints == "{}")
+      end
+
+      private
+
+      # @return [String] Glyph hints as JSON
+      attr_accessor :glyph_hints
+
+      # Parse glyph hints JSON
+      def parse_glyph_hints
+        return {} if @glyph_hints.nil? || @glyph_hints.empty? || @glyph_hints == "{}"
+
+        JSON.parse(@glyph_hints)
+      rescue JSON::ParserError
+        {}
+      end
+    end
+
     # Universal hint representation supporting both TrueType and PostScript hints
     #
     # Hints are instructions that improve font rendering at small sizes by
@@ -60,16 +189,21 @@ module Fontisan
         case type
         when :stem
           convert_stem_to_truetype
+        when :stem3
+          convert_stem3_to_truetype
         when :flex
           convert_flex_to_truetype
         when :counter
           convert_counter_to_truetype
+        when :hint_replacement
+          convert_hintmask_to_truetype
         when :delta
           # Already in TrueType format
           data[:instructions] || []
         when :interpolate
           # IUP instruction
-          [0x30] # IUP[y], or [0x31] for IUP[x]
+          axis = data[:axis] || :y
+          axis == :x ? [0x31] : [0x30] # IUP[x] or IUP[y]
         when :shift
           # SHP instruction
           data[:instructions] || []
@@ -80,6 +214,9 @@ module Fontisan
           # Unknown hint type - return empty
           []
         end
+      rescue StandardError => e
+        warn "Error converting hint type #{type} to TrueType: #{e.message}"
+        []
       end
 
       # Convert hint to PostScript hint format
@@ -106,6 +243,9 @@ module Fontisan
           # Unknown hint type
           {}
         end
+      rescue StandardError => e
+        warn "Error converting hint type #{type} to PostScript: #{e.message}"
+        {}
       end
 
       # Check if hint is compatible with target format
@@ -129,23 +269,22 @@ module Fontisan
 
       # Convert stem hint to TrueType instructions
       def convert_stem_to_truetype
-        position = data[:position] || 0
-        width = data[:width] || 0
+        data[:position] || 0
+        data[:width] || 0
         orientation = data[:orientation] || :vertical
 
         # TrueType uses MDAP (Move Direct Absolute Point) and MDRP (Move Direct Relative Point)
         # to control stem positioning
         instructions = []
 
-        if orientation == :vertical
-          # Vertical stem: use Y-axis instructions
-          instructions << 0x2E # MDAP[rnd] - mark reference point
-          instructions << 0xC0 # MDRP[min,rnd,black] - move relative point
-        else
-          # Horizontal stem: use X-axis instructions
-          instructions << 0x2F # MDAP[rnd]
-          instructions << 0xC0 # MDRP[min,rnd,black]
-        end
+        instructions << if orientation == :vertical
+                          # Vertical stem: use Y-axis instructions
+                          0x2E # MDAP[rnd] - mark reference point
+                        else
+                          # Horizontal stem: use X-axis instructions
+                          0x2F # MDAP[rnd]
+                        end
+        instructions << 0xC0 # MDRP[min,rnd,black] - move relative point
 
         instructions
       end
@@ -166,6 +305,38 @@ module Fontisan
         []
       end
 
+      # Convert stem3 hint to TrueType instructions
+      def convert_stem3_to_truetype
+        stems = data[:stems] || []
+        orientation = data[:orientation] || :vertical
+
+        # Generate MDAP/MDRP pairs for each stem
+        instructions = []
+
+        stems.each do |_stem|
+          instructions << if orientation == :vertical
+                            # Vertical stem: use Y-axis instructions
+                            0x2E # MDAP[rnd] - mark reference point
+                          else
+                            # Horizontal stem: use X-axis instructions
+                            0x2F # MDAP[rnd]
+                          end
+          instructions << 0xC0 # MDRP[min,rnd,black] - move relative point
+        end
+
+        instructions
+      end
+
+      # Convert hintmask hint to TrueType instructions
+      def convert_hintmask_to_truetype
+        # Hintmask controls which hints are active at runtime
+        # TrueType doesn't have a direct equivalent
+        # We can use conditional instructions, but it's complex
+        # For now, return empty and let the main stems handle hinting
+        # TODO: Implement conditional instruction generation if needed
+        []
+      end
+
       # Convert stem hint to PostScript operators
       def convert_stem_to_postscript
         position = data[:position] || 0

data/lib/fontisan/models/outline.rb

@@ -121,7 +121,10 @@ module Fontisan
 
         # Get path from CharString
         path = charstring.path
-        raise ArgumentError, "CharString has no path data" if path.nil? || path.empty?
+        if path.nil? || path.empty?
+          raise ArgumentError,
+                "CharString has no path data"
+        end
 
         commands = convert_cff_path_to_commands(path)