fontisan 0.1.0 → 0.2.0

data/lib/fontisan/hints/postscript_hint_applier.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "../models/hint"
+
+module Fontisan
+  module Hints
+    # Applies rendering hints to PostScript/CFF CharString data
+    #
+    # This applier converts universal Hint objects into PostScript hint
+    # operators and integrates them into CharString data. It ensures proper
+    # operator placement and maintains CharString validity.
+    #
+    # **PostScript Hint Placement:**
+    #
+    # - Stem hints (hstem/vstem) must appear at the beginning
+    # - Hintmask operators can appear throughout the CharString
+    # - Hints affect all subsequent path operations
+    #
+    # @example Apply hints to a CharString
+    #   applier = PostScriptHintApplier.new
+    #   charstring_with_hints = applier.apply(charstring, hints)
+    class PostScriptHintApplier
+      # CFF CharString operators
+      HSTEM = 1
+      VSTEM = 3
+      HINTMASK = 19
+      CNTRMASK = 20
+      HSTEM3 = [12, 2]
+      VSTEM3 = [12, 1]
+
+      # Apply hints to CharString
+      #
+      # @param charstring [String] Original CharString bytes
+      # @param hints [Array<Hint>] Hints to apply
+      # @return [String] CharString with applied hints
+      def apply(charstring, hints)
+        return charstring if hints.nil? || hints.empty?
+        return charstring if charstring.nil? || charstring.empty?
+
+        # Build hint operators
+        hint_ops = build_hint_operators(hints)
+
+        # Insert hints at the beginning of CharString
+        # (simplified - real implementation would analyze existing structure)
+        hint_ops + charstring
+      end
+
+      private
+
+      # Build hint operators from hints
+      #
+      # @param hints [Array<Hint>] Hints to convert
+      # @return [String] Hint operator bytes
+      def build_hint_operators(hints)
+        operators = "".b
+
+        # Group hints by type for proper ordering
+        stem_hints = hints.select { |h| h.type == :stem }
+        stem3_hints = hints.select { |h| h.type == :stem3 }
+        mask_hints = hints.select { |h| %i[hint_replacement counter].include?(h.type) }
+
+        # Add stem hints first
+        stem_hints.each do |hint|
+          operators << encode_stem_hint(hint)
+        end
+
+        # Add stem3 hints
+        stem3_hints.each do |hint|
+          operators << encode_stem3_hint(hint)
+        end
+
+        # Add mask hints
+        mask_hints.each do |hint|
+          operators << encode_mask_hint(hint)
+        end
+
+        operators
+      end
+
+      # Encode stem hint as CharString bytes
+      #
+      # @param hint [Hint] Stem hint
+      # @return [String] Encoded bytes
+      def encode_stem_hint(hint)
+        data = hint.to_postscript
+        return "".b if data.empty?
+
+        args = data[:args] || []
+        operator = data[:operator]
+
+        # Encode arguments as CFF integers
+        bytes = args.map { |arg| encode_cff_integer(arg) }.join
+
+        # Add operator
+        bytes << if operator == :vstem
+                   [VSTEM].pack("C")
+                 else
+                   [HSTEM].pack("C")
+                 end
+
+        bytes
+      end
+
+      # Encode stem3 hint as CharString bytes
+      #
+      # @param hint [Hint] Stem3 hint
+      # @return [String] Encoded bytes
+      def encode_stem3_hint(hint)
+        data = hint.to_postscript
+        return "".b if data.empty?
+
+        args = data[:args] || []
+        operator = data[:operator]
+
+        # Encode arguments
+        bytes = args.map { |arg| encode_cff_integer(arg) }.join
+
+        # Add two-byte operator (12 followed by subop)
+        bytes << if operator == :vstem3
+                   VSTEM3.pack("C*")
+                 else
+                   HSTEM3.pack("C*")
+                 end
+
+        bytes
+      end
+
+      # Encode mask hint as CharString bytes
+      #
+      # @param hint [Hint] Mask hint
+      # @return [String] Encoded bytes
+      def encode_mask_hint(hint)
+        operator = hint.type == :hint_replacement ? HINTMASK : CNTRMASK
+        mask = hint.data[:mask] || []
+
+        # Encode mask bytes
+        bytes = mask.map { |b| [b].pack("C") }.join
+
+        # Add operator
+        bytes + [operator].pack("C")
+      end
+
+      # Encode integer as CFF CharString number
+      #
+      # @param num [Integer] Number to encode
+      # @return [String] Encoded bytes
+      def encode_cff_integer(num)
+        # Range 1: -107 to 107 (single byte)
+        if num >= -107 && num <= 107
+          return [32 + num].pack("c")
+        end
+
+        # Range 2: 108 to 1131 (two bytes)
+        if num >= 108 && num <= 1131
+          b0 = 247 + ((num - 108) >> 8)
+          b1 = (num - 108) & 0xff
+          return [b0, b1].pack("C*")
+        end
+
+        # Range 3: -1131 to -108 (two bytes)
+        if num >= -1131 && num <= -108
+          b0 = 251 - ((num + 108) >> 8)
+          b1 = -(num + 108) & 0xff
+          return [b0, b1].pack("C*")
+        end
+
+        # Range 4: -32768 to 32767 (three bytes)
+        if num >= -32_768 && num <= 32_767
+          bytes = [28, (num >> 8) & 0xff, num & 0xff]
+          return bytes.pack("C*")
+        end
+
+        # Range 5: Larger numbers (five bytes)
+        bytes = [
+          255,
+          (num >> 24) & 0xff,
+          (num >> 16) & 0xff,
+          (num >> 8) & 0xff,
+          num & 0xff
+        ]
+        bytes.pack("C*")
+      end
+    end
+  end
+end

data/lib/fontisan/hints/postscript_hint_extractor.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative "../models/hint"
+
+module Fontisan
+  module Hints
+    # Extracts rendering hints from PostScript/CFF CharString data
+    #
+    # PostScript Type 1 and CFF fonts embed hints directly in the
+    # CharString data as operators. This extractor parses CharString
+    # sequences to identify and extract hint operators.
+    #
+    # **Supported PostScript Hint Operators:**
+    #
+    # - hstem/vstem - Horizontal/vertical stem hints
+    # - hstem3/vstem3 - Multiple stem hints
+    # - hintmask - Hint replacement masks
+    # - cntrmask - Counter control masks
+    #
+    # @example Extract hints from a CharString
+    #   extractor = PostScriptHintExtractor.new
+    #   hints = extractor.extract(charstring)
+    class PostScriptHintExtractor
+      # CFF CharString operators
+      HSTEM = 1
+      VSTEM = 3
+      HINTMASK = 19
+      CNTRMASK = 20
+      HSTEM3 = 12 << 8 | 2
+      VSTEM3 = 12 << 8 | 1
+
+      # Extract hints from CFF CharString
+      #
+      # @param charstring [CharString, String] CFF CharString object or bytes
+      # @return [Array<Hint>] Extracted hints
+      def extract(charstring)
+        return [] if charstring.nil?
+
+        # Get CharString bytes
+        bytes = if charstring.respond_to?(:data)
+                  charstring.data
+                elsif charstring.respond_to?(:bytes)
+                  charstring.bytes
+                elsif charstring.is_a?(String)
+                  charstring.bytes
+                else
+                  return []
+                end
+
+        return [] if bytes.empty?
+
+        parse_charstring(bytes)
+      end
+
+      private
+
+      # Parse CharString bytes to extract hints
+      #
+      # @param bytes [Array<Integer>] CharString bytes
+      # @return [Array<Hint>] Extracted hints
+      def parse_charstring(bytes)
+        hints = []
+        stack = []
+        i = 0
+
+        while i < bytes.length
+          byte = bytes[i]
+
+          if operator?(byte)
+            # Process operator
+            operator = if byte == 12
+                        # Two-byte operator
+                        i += 1
+                        (12 << 8) | bytes[i]
+                      else
+                        byte
+                      end
+
+            hint = process_operator(operator, stack)
+            hints << hint if hint
+
+            # Clear stack after operator
+            stack.clear
+            i += 1
+          else
+            # Number - push to stack
+            num, consumed = decode_number(bytes, i)
+            stack << num if num
+            i += consumed
+          end
+        end
+
+        hints
+      end
+
+      # Check if byte is an operator
+      #
+      # @param byte [Integer] Byte value
+      # @return [Boolean] True if operator
+      def operator?(byte)
+        byte <= 31 || byte == 255
+      end
+
+      # Decode a number from CharString
+      #
+      # @param bytes [Array<Integer>] CharString bytes
+      # @param index [Integer] Starting position
+      # @return [Array<Integer, Integer>] [number, bytes_consumed]
+      def decode_number(bytes, index)
+        byte = bytes[index]
+        return [nil, 1] if byte.nil?
+
+        case byte
+        when 28
+          # 3-byte signed integer
+          if index + 2 < bytes.length
+            num = (bytes[index + 1] << 8) | bytes[index + 2]
+            num = num - 65536 if num > 32767
+            [num, 3]
+          else
+            [nil, 1]
+          end
+        when 32..246
+          # Single byte integer
+          [byte - 139, 1]
+        when 247..250
+          # Positive 2-byte integer
+          if index + 1 < bytes.length
+            num = (byte - 247) * 256 + bytes[index + 1] + 108
+            [num, 2]
+          else
+            [nil, 1]
+          end
+        when 251..254
+          # Negative 2-byte integer
+          if index + 1 < bytes.length
+            num = -(byte - 251) * 256 - bytes[index + 1] - 108
+            [num, 2]
+          else
+            [nil, 1]
+          end
+        when 255
+          # 5-byte signed integer
+          if index + 4 < bytes.length
+            num = (bytes[index + 1] << 24) | (bytes[index + 2] << 16) |
+                  (bytes[index + 3] << 8) | bytes[index + 4]
+            num = num - 4294967296 if num > 2147483647
+            [num, 5]
+          else
+            [nil, 1]
+          end
+        else
+          [nil, 1]
+        end
+      end
+
+      # Process hint operator and create Hint object
+      #
+      # @param operator [Integer] Operator code
+      # @param stack [Array<Integer>] Current operand stack
+      # @return [Hint, nil] Hint object if operator is a hint
+      def process_operator(operator, stack)
+        case operator
+        when HSTEM
+          # Horizontal stem hint
+          extract_stem_hint(stack, :horizontal)
+
+        when VSTEM
+          # Vertical stem hint
+          extract_stem_hint(stack, :vertical)
+
+        when HSTEM3
+          # Multiple horizontal stems
+          extract_stem3_hint(stack, :horizontal)
+
+        when VSTEM3
+          # Multiple vertical stems
+          extract_stem3_hint(stack, :vertical)
+
+        when HINTMASK
+          # Hint replacement mask
+          Models::Hint.new(
+            type: :hint_replacement,
+            data: { mask: stack.dup },
+            source_format: :postscript
+          )
+
+        when CNTRMASK
+          # Counter control mask
+          Models::Hint.new(
+            type: :counter,
+            data: { zones: stack.dup },
+            source_format: :postscript
+          )
+
+        else
+          nil
+        end
+      end
+
+      # Extract stem hint from stack
+      #
+      # @param stack [Array<Integer>] Operand stack
+      # @param orientation [Symbol] :horizontal or :vertical
+      # @return [Hint] Stem hint
+      def extract_stem_hint(stack, orientation)
+        # Stack should have pairs of [position, width]
+        return nil if stack.empty? || stack.length < 2
+
+        # Take first pair
+        position = stack[0]
+        width = stack[1]
+
+        Models::Hint.new(
+          type: :stem,
+          data: {
+            position: position,
+            width: width,
+            orientation: orientation
+          },
+          source_format: :postscript
+        )
+      end
+
+      # Extract stem3 hint from stack
+      #
+      # @param stack [Array<Integer>] Operand stack
+      # @param orientation [Symbol] :horizontal or :vertical
+      # @return [Hint] Stem3 hint
+      def extract_stem3_hint(stack, orientation)
+        # Stack should have 6 values: 3 pairs of [position, width]
+        return nil if stack.length < 6
+
+        stems = []
+        (0..2).each do |i|
+          pos_idx = i * 2
+          stems << {
+            position: stack[pos_idx],
+            width: stack[pos_idx + 1]
+          }
+        end
+
+        Models::Hint.new(
+          type: :stem3,
+          data: {
+            stems: stems,
+            orientation: orientation
+          },
+          source_format: :postscript
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/hints/truetype_hint_applier.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../models/hint"
+
+module Fontisan
+  module Hints
+    # Applies rendering hints to TrueType glyph data
+    #
+    # 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.
+    #
+    # @example Apply hints to a glyph
+    #   applier = TrueTypeHintApplier.new
+    #   glyph_with_hints = applier.apply(glyph, hints)
+    class TrueTypeHintApplier
+      # Apply hints to TrueType glyph
+      #
+      # @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?
+
+        # Convert hints to TrueType instructions
+        instructions = build_instructions(hints)
+
+        # 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
+
+        # For now, we just return the glyph as-is since
+        # this is a complex operation requiring deep integration
+        # with the glyph structure
+        glyph
+      end
+
+      private
+
+      # Build TrueType instruction sequence from hints
+      #
+      # @param hints [Array<Hint>] Hints to convert
+      # @return [Array<Integer>] Instruction bytes
+      def build_instructions(hints)
+        instructions = []
+
+        hints.each do |hint|
+          hint_instructions = hint.to_truetype
+          instructions.concat(hint_instructions) if hint_instructions
+        end
+
+        instructions
+      end
+
+      # Validate instruction sequence
+      #
+      # @param instructions [Array<Integer>] Instructions to validate
+      # @return [Boolean] True if valid
+      def valid_instructions?(instructions)
+        return true if instructions.empty?
+
+        # Basic validation - check for valid opcodes
+        instructions.all? { |byte| byte >= 0 && byte <= 255 }
+      end
+    end
+  end
+end

data/lib/fontisan/hints/truetype_hint_extractor.rb

@@ -0,0 +1,162 @@
+# 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 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
+    end
+  end
+end