fontisan 0.1.0 → 0.2.1

data/lib/fontisan/hints/truetype_hint_extractor.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative "../models/hint"
+
+module Fontisan
+  module Hints
+    # Extracts rendering hints from TrueType glyph data
+    #
+    # TrueType uses bytecode instructions for hinting. This extractor
+    # analyzes glyph instruction sequences and converts them into
+    # universal Hint objects for format-agnostic representation.
+    #
+    # **Supported TrueType Instructions:**
+    #
+    # - MDAP - Move Direct Absolute Point (stem positioning)
+    # - MDRP - Move Direct Relative Point (stem width)
+    # - IUP - Interpolate Untouched Points (smooth interpolation)
+    # - SHP - Shift Point (point adjustments)
+    # - ALIGNRP - Align to Reference Point (alignment)
+    # - DELTA - Delta instructions (pixel-level adjustments)
+    #
+    # @example Extract hints from a glyph
+    #   extractor = TrueTypeHintExtractor.new
+    #   hints = extractor.extract(glyph)
+    class TrueTypeHintExtractor
+      # TrueType instruction opcodes
+      MDAP_RND = 0x2E
+      MDAP_NORND = 0x2F
+      MDRP_MIN_RND_BLACK = 0xC0
+      IUP_Y = 0x30
+      IUP_X = 0x31
+      SHP = [0x32, 0x33]
+      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
+      # @return [Array<Hint>] Extracted hints
+      def extract(glyph)
+        return [] if glyph.nil? || glyph.empty?
+        return [] unless glyph.respond_to?(:instructions)
+
+        instructions = glyph.instructions || []
+        return [] if instructions.empty?
+
+        parse_instructions(instructions)
+      end
+
+      private
+
+      # Parse TrueType instruction bytes into Hint objects
+      #
+      # @param instructions [String, Array<Integer>] Instruction bytes
+      # @return [Array<Hint>] Parsed hints
+      def parse_instructions(instructions)
+        hints = []
+        bytes = instructions.is_a?(String) ? instructions.bytes : instructions
+        i = 0
+
+        while i < bytes.length
+          opcode = bytes[i]
+
+          case opcode
+          when MDAP_RND, MDAP_NORND
+            # Stem positioning hint
+            hint = extract_stem_hint(bytes, i)
+            hints << hint if hint
+            i += 1
+
+          when MDRP_MIN_RND_BLACK
+            # Stem width hint (usually follows MDAP)
+            # This is typically part of a stem hint pair
+            i += 1
+
+          when IUP_Y, IUP_X
+            # Interpolation hint
+            hints << Models::Hint.new(
+              type: :interpolate,
+              data: { axis: opcode == IUP_Y ? :y : :x },
+              source_format: :truetype
+            )
+            i += 1
+
+          when *SHP
+            # Shift point hint
+            hints << Models::Hint.new(
+              type: :shift,
+              data: { instructions: [opcode] },
+              source_format: :truetype
+            )
+            i += 1
+
+          when ALIGNRP
+            # Alignment hint
+            hints << Models::Hint.new(
+              type: :align,
+              data: {},
+              source_format: :truetype
+            )
+            i += 1
+
+          when DELTAP1, DELTAP2, DELTAP3
+            # Delta hint - pixel-level adjustments
+            # Next byte is the count
+            i += 1
+            if i < bytes.length
+              count = bytes[i]
+              delta_data = bytes[i + 1, count * 2] || []
+              hints << Models::Hint.new(
+                type: :delta,
+                data: {
+                  instructions: [opcode] + [count] + delta_data,
+                  count: count
+                },
+                source_format: :truetype
+              )
+              i += count * 2 + 1
+            end
+
+          else
+            # Unknown or data bytes - skip
+            i += 1
+          end
+        end
+
+        hints
+      end
+
+      # Extract stem hint from MDAP instruction
+      #
+      # @param bytes [Array<Integer>] Instruction bytes
+      # @param index [Integer] Current position
+      # @return [Hint, nil] Stem hint if found
+      def extract_stem_hint(bytes, index)
+        # In TrueType, stem hints are inferred from MDAP + MDRP pairs
+        # This is a simplified extraction - real implementation would
+        # need to track the graphics state and point references
+
+        # Check if next instruction is MDRP (stem width)
+        has_width = index + 1 < bytes.length &&
+                    bytes[index + 1] == MDRP_MIN_RND_BLACK
+
+        if has_width
+          Models::Hint.new(
+            type: :stem,
+            data: {
+              position: 0, # Would be extracted from graphics state
+              width: 0,    # Would be calculated from MDRP
+              orientation: :vertical # Inferred from instruction context
+            },
+            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|
+          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
+        end
+      rescue StandardError => e
+        warn "Failed to extract glyph hints: #{e.message}"
+      end
+    end
+  end
+end

data/lib/fontisan/loading_modes.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Fontisan
+  # Loading modes module that defines which tables are loaded in each mode.
+  #
+  # This module provides a MECE (Mutually Exclusive, Collectively Exhaustive)
+  # architecture for font loading modes. Each mode defines a specific set of
+  # tables to load, enabling efficient parsing for different use cases.
+  #
+  # @example Using metadata mode
+  #   mode = LoadingModes::METADATA
+  #   tables = LoadingModes.tables_for(mode)  # => ["name", "head", "hhea", "maxp", "OS/2", "post"]
+  #
+  # @example Checking table availability
+  #   LoadingModes.table_allowed?(:metadata, "GSUB")  # => false
+  #   LoadingModes.table_allowed?(:full, "GSUB")      # => true
+  module LoadingModes
+    # Metadata mode: loads only tables needed for font identification and metrics
+    # Equivalent to otfinfo functionality
+    METADATA = :metadata
+
+    # Full mode: loads all tables in the font
+    FULL = :full
+
+    # Mode definitions with their respective table lists
+    MODES = {
+      METADATA => {
+        tables: %w[name head hhea maxp OS/2 post].freeze,
+        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
+    }.freeze
+
+    # Pre-computed Set for O(1) lookup of metadata tables
+    # This constant avoids recreating the Set on every font load
+    METADATA_TABLES_SET = MODES[METADATA][:tables].to_set.freeze
+
+    # Get the list of tables allowed for a given mode
+    #
+    # @param mode [Symbol] The loading mode (:metadata or :full)
+    # @return [Array<String>, Symbol] Array of table tags or :all for full mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.tables_for(mode)
+      validate_mode!(mode)
+      MODES[mode][:tables]
+    end
+
+    # Check if a table is allowed in a given mode
+    #
+    # @param mode [Symbol] The loading mode (:metadata or :full)
+    # @param tag [String] The table tag to check
+    # @return [Boolean] true if table is allowed in the mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.table_allowed?(mode, tag)
+      validate_mode!(mode)
+
+      tables = MODES[mode][:tables]
+      return true if tables == :all
+
+      tables.include?(tag)
+    end
+
+    # Validate that a mode is valid
+    #
+    # @param mode [Symbol] The mode to validate
+    # @return [Boolean] true if mode is valid
+    def self.valid_mode?(mode)
+      MODES.key?(mode)
+    end
+
+    # Get the default lazy loading setting for a mode
+    #
+    # @param mode [Symbol] The loading mode
+    # @return [Boolean] true if lazy loading is recommended for this mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.default_lazy?(mode)
+      validate_mode!(mode)
+      true  # Lazy loading is recommended for all modes
+    end
+
+    # Get mode description
+    #
+    # @param mode [Symbol] The loading mode
+    # @return [String] Description of the mode
+    # @raise [ArgumentError] if mode is invalid
+    def self.description(mode)
+      validate_mode!(mode)
+      MODES[mode][:description]
+    end
+
+    # Get all available modes
+    #
+    # @return [Array<Symbol>] List of all mode symbols
+    def self.all_modes
+      MODES.keys
+    end
+
+    # Validate mode and raise error if invalid
+    #
+    # @param mode [Symbol] The mode to validate
+    # @return [void]
+    # @raise [ArgumentError] if mode is invalid
+    def self.validate_mode!(mode)
+      return if valid_mode?(mode)
+
+      raise ArgumentError,
+            "Invalid mode: #{mode.inspect}. Valid modes are: #{all_modes.map(&:inspect).join(', ')}"
+    end
+  end
+end

data/lib/fontisan/metrics_calculator.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+require_relative "constants"
+
+module Fontisan
+  # High-level utility class for accessing font metrics
+  #
+  # MetricsCalculator provides a convenient API for querying font metrics from
+  # multiple OpenType tables without needing to work with the low-level table
+  # structures directly. It wraps access to hhea, hmtx, head, maxp, and cmap
+  # tables.
+  #
+  # The calculator handles missing tables gracefully and provides both
+  # individual glyph metrics and string-level calculations.
+  #
+  # @example Basic usage
+  #   font = FontLoader.from_file("path/to/font.ttf")
+  #   calc = MetricsCalculator.new(font)
+  #
+  #   puts calc.ascent          # => 2048
+  #   puts calc.descent         # => -512
+  #   puts calc.line_height     # => 2650
+  #   puts calc.units_per_em    # => 2048
+  #
+  # @example Glyph metrics
+  #   width = calc.glyph_width(42)
+  #   lsb = calc.glyph_left_side_bearing(42)
+  #
+  # @example String width calculation
+  #   width = calc.string_width("Hello")
+  #
+  # @example Checking for metrics support
+  #   if calc.has_metrics?
+  #     puts "Font has complete horizontal metrics"
+  #   end
+  class MetricsCalculator
+    # The font object this calculator operates on
+    #
+    # @return [OpenTypeFont, TrueTypeFont] The font instance
+    attr_reader :font
+
+    # Initialize a new MetricsCalculator
+    #
+    # @param font [OpenTypeFont, TrueTypeFont] Font instance to calculate metrics for
+    # @raise [ArgumentError] if font is nil
+    def initialize(font)
+      raise ArgumentError, "Font cannot be nil" if font.nil?
+
+      @font = font
+      @hhea_table = nil
+      @hmtx_table = nil
+      @head_table = nil
+      @maxp_table = nil
+      @cmap_table = nil
+      @hmtx_parsed = false
+    end
+
+    # Get typographic ascent from hhea table
+    #
+    # The ascent is the distance from the baseline to the highest ascender.
+    # It is a positive value in font units (FUnits).
+    #
+    # @return [Integer, nil] Ascent value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.ascent # => 2048
+    def ascent
+      hhea&.ascent
+    end
+
+    # Get typographic descent from hhea table
+    #
+    # The descent is the distance from the baseline to the lowest descender.
+    # It is typically a negative value in font units (FUnits).
+    #
+    # @return [Integer, nil] Descent value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.descent # => -512
+    def descent
+      hhea&.descent
+    end
+
+    # Get line gap from hhea table
+    #
+    # The line gap is additional vertical space between lines of text.
+    # It is a non-negative value in font units (FUnits).
+    #
+    # @return [Integer, nil] Line gap value in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.line_gap # => 90
+    def line_gap
+      hhea&.line_gap
+    end
+
+    # Get units per em from head table
+    #
+    # This value defines the font's coordinate system scale. Common values
+    # are 1000 (PostScript fonts) or 2048 (TrueType fonts).
+    #
+    # @return [Integer, nil] Units per em value, or nil if head table is missing
+    #
+    # @example
+    #   calc.units_per_em # => 2048
+    def units_per_em
+      head&.units_per_em
+    end
+
+    # Get advance width for a specific glyph
+    #
+    # The advance width is the horizontal distance to advance the pen position
+    # after rendering this glyph. It is in font units (FUnits).
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Advance width in FUnits, or nil if not available
+    #
+    # @example
+    #   calc.glyph_width(42) # => 1234
+    def glyph_width(glyph_id)
+      ensure_hmtx_parsed
+      return nil unless hmtx
+
+      metric = hmtx.metric_for(glyph_id)
+      metric&.dig(:advance_width)
+    end
+
+    # Alias for {#glyph_width}
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Advance width in FUnits, or nil if not available
+    alias glyph_advance_width glyph_width
+
+    # Get left side bearing for a specific glyph
+    #
+    # The left side bearing (LSB) is the horizontal distance from the pen
+    # position to the leftmost point of the glyph. It can be negative if
+    # the glyph extends to the left of the pen position.
+    #
+    # @param glyph_id [Integer] The glyph ID (0-based)
+    # @return [Integer, nil] Left side bearing in FUnits, or nil if not available
+    #
+    # @example
+    #   calc.glyph_left_side_bearing(42) # => 50
+    def glyph_left_side_bearing(glyph_id)
+      ensure_hmtx_parsed
+      return nil unless hmtx
+
+      metric = hmtx.metric_for(glyph_id)
+      metric&.dig(:lsb)
+    end
+
+    # Calculate total width for a string
+    #
+    # Calculates the sum of advance widths for all characters in the string.
+    # This is a simplified calculation that does not account for kerning,
+    # ligatures, or other advanced typography features.
+    #
+    # Characters not mapped in the font are skipped.
+    #
+    # @param string [String] The string to measure
+    # @return [Integer, nil] Total width in FUnits, or nil if metrics unavailable
+    #
+    # @example
+    #   calc.string_width("Hello") # => 5420
+    def string_width(string)
+      return nil unless has_metrics?
+      return 0 if string.nil? || string.empty?
+
+      total_width = 0
+      string.each_codepoint do |codepoint|
+        glyph_id = codepoint_to_glyph_id(codepoint)
+        next unless glyph_id
+
+        width = glyph_width(glyph_id)
+        total_width += width if width
+      end
+
+      total_width
+    end
+
+    # Calculate line height
+    #
+    # Line height is calculated as: ascent - descent + line_gap
+    # This represents the recommended spacing between consecutive baselines.
+    #
+    # @return [Integer, nil] Line height in FUnits, or nil if hhea table is missing
+    #
+    # @example
+    #   calc.line_height # => 2650 (when ascent=2048, descent=-512, line_gap=90)
+    def line_height
+      return nil unless hhea
+
+      ascent - descent + line_gap
+    end
+
+    # Alias for {#units_per_em}
+    #
+    # @return [Integer, nil] Units per em value, or nil if head table is missing
+    alias em_height units_per_em
+
+    # Check if font has complete horizontal metrics
+    #
+    # Returns true if the font has all required tables for horizontal metrics:
+    # hhea, hmtx, head, and maxp tables.
+    #
+    # @return [Boolean] True if all metrics tables are present
+    #
+    # @example
+    #   calc.has_metrics? # => true
+    def has_metrics?
+      !hhea.nil? && !hmtx.nil? && !head.nil? && !maxp.nil?
+    end
+
+    private
+
+    # Get hhea table, caching the result
+    #
+    # @return [Tables::Hhea, nil] The hhea table or nil
+    def hhea
+      @hhea ||= font.table(Constants::HHEA_TAG)
+    end
+
+    # Get hmtx table, caching the result
+    #
+    # @return [Tables::Hmtx, nil] The hmtx table or nil
+    def hmtx
+      @hmtx ||= font.table(Constants::HMTX_TAG)
+    end
+
+    # Get head table, caching the result
+    #
+    # @return [Tables::Head, nil] The head table or nil
+    def head
+      @head ||= font.table(Constants::HEAD_TAG)
+    end
+
+    # Get maxp table, caching the result
+    #
+    # @return [Tables::Maxp, nil] The maxp table or nil
+    def maxp
+      @maxp ||= font.table(Constants::MAXP_TAG)
+    end
+
+    # Get cmap table, caching the result
+    #
+    # @return [Tables::Cmap, nil] The cmap table or nil
+    def cmap
+      @cmap ||= font.table(Constants::CMAP_TAG)
+    end
+
+    # Ensure hmtx table is parsed with context
+    #
+    # The hmtx table requires numberOfHMetrics from hhea and numGlyphs from maxp
+    # to be parsed correctly. This method ensures parsing happens lazily on first use.
+    #
+    # @return [void]
+    def ensure_hmtx_parsed
+      return if @hmtx_parsed
+      return unless hmtx && hhea && maxp
+
+      hmtx.parse_with_context(hhea.number_of_h_metrics, maxp.num_glyphs)
+      @hmtx_parsed = true
+    end
+
+    # Map Unicode codepoint to glyph ID using cmap table
+    #
+    # @param codepoint [Integer] Unicode codepoint
+    # @return [Integer, nil] Glyph ID or nil if not mapped
+    def codepoint_to_glyph_id(codepoint)
+      return nil unless cmap
+
+      mappings = cmap.unicode_mappings
+      mappings[codepoint]
+    end
+  end
+end