fontisan 0.1.0 → 0.2.1

data/lib/fontisan/outline_extractor.rb

@@ -0,0 +1,423 @@
+# frozen_string_literal: true
+
+require_relative "models/glyph_outline"
+
+module Fontisan
+  # Extracts glyph outlines from font tables
+  #
+  # [`OutlineExtractor`](lib/fontisan/outline_extractor.rb) provides a unified
+  # interface for extracting glyph outline data from both TrueType (glyf table)
+  # and CFF (Compact Font Format) fonts. It uses a strategy pattern to handle
+  # the different outline formats transparently.
+  #
+  # The extractor:
+  # - Automatically detects font format (TrueType vs CFF)
+  # - Handles simple glyphs (direct outline data)
+  # - Handles compound glyphs (recursively resolves components)
+  # - Returns standardized [`GlyphOutline`](lib/fontisan/models/glyph_outline.rb) objects
+  #
+  # This class is responsible for extraction only, not business logic or
+  # presentation. It's designed to be composed with
+  # [`GlyphAccessor`](lib/fontisan/glyph_accessor.rb) for higher-level operations.
+  #
+  # @example Extracting a glyph outline
+  #   extractor = Fontisan::OutlineExtractor.new(font)
+  #   outline = extractor.extract(65)  # 'A' character
+  #
+  #   puts outline.contour_count
+  #   puts outline.to_svg_path
+  #
+  # @example Using with GlyphAccessor
+  #   accessor = Fontisan::GlyphAccessor.new(font)
+  #   outline = accessor.outline_for_char('A')
+  #
+  # Reference: [`docs/GETTING_STARTED.md:125-172`](docs/GETTING_STARTED.md:125)
+  class OutlineExtractor
+    # @return [TrueTypeFont, OpenTypeFont] Font instance
+    attr_reader :font
+
+    # Initialize a new outline extractor
+    #
+    # @param font [TrueTypeFont, OpenTypeFont] Font to extract outlines from
+    # @raise [ArgumentError] If font is nil or doesn't have required tables
+    def initialize(font)
+      raise ArgumentError, "Font cannot be nil" if font.nil?
+
+      unless font.respond_to?(:table)
+        raise ArgumentError, "Font must respond to :table method"
+      end
+
+      @font = font
+    end
+
+    # Extract outline for a specific glyph
+    #
+    # This method automatically detects the font format and delegates to
+    # the appropriate extraction strategy. For compound glyphs (TrueType only),
+    # it recursively resolves component outlines and combines them with
+    # proper transformations.
+    #
+    # @param glyph_id [Integer] The glyph index (0-based, 0 is .notdef)
+    # @return [Models::GlyphOutline, nil] The outline or nil if glyph not
+    #   found or empty
+    # @raise [ArgumentError] If glyph_id is invalid
+    # @raise [Fontisan::MissingTableError] If required tables are missing
+    #
+    # @example Extract a simple glyph
+    #   outline = extractor.extract(65)
+    #   puts "Glyph has #{outline.contour_count} contours"
+    #
+    # @example Handle empty glyphs (like space)
+    #   outline = extractor.extract(space_glyph_id)
+    #   # => nil (empty glyphs return nil)
+    def extract(glyph_id)
+      validate_glyph_id!(glyph_id)
+
+      if cff_font?
+        extract_cff_outline(glyph_id)
+      elsif truetype_font?
+        extract_truetype_outline(glyph_id)
+      else
+        raise Fontisan::MissingTableError,
+              "Font has neither glyf nor CFF table"
+      end
+    end
+
+    private
+
+    # Check if this is a CFF font
+    #
+    # @return [Boolean] True if font has CFF table
+    def cff_font?
+      font.table(Constants::CFF_TAG) != nil
+    end
+
+    # Check if this is a TrueType font
+    #
+    # @return [Boolean] True if font has glyf table
+    def truetype_font?
+      font.has_table?("glyf")
+    end
+
+    # Validate glyph ID
+    #
+    # @param glyph_id [Integer] Glyph ID to validate
+    # @raise [ArgumentError] If glyph ID is invalid
+    def validate_glyph_id!(glyph_id)
+      if glyph_id.nil?
+        raise ArgumentError, "glyph_id cannot be nil"
+      end
+
+      if glyph_id.negative?
+        raise ArgumentError, "glyph_id must be >= 0, got: #{glyph_id}"
+      end
+
+      maxp = font.table("maxp")
+      if maxp && glyph_id >= maxp.num_glyphs
+        raise ArgumentError,
+              "glyph_id #{glyph_id} exceeds number of glyphs (#{maxp.num_glyphs})"
+      end
+    end
+
+    # Extract outline from TrueType glyph
+    #
+    # Handles both simple and compound glyphs. For compound glyphs,
+    # recursively resolves component outlines and applies transformations.
+    #
+    # @param glyph_id [Integer] Glyph ID
+    # @return [Models::GlyphOutline, nil] Outline or nil if empty
+    # @raise [Fontisan::MissingTableError] If required tables are missing
+    def extract_truetype_outline(glyph_id)
+      glyph = get_truetype_glyph(glyph_id)
+      return nil unless glyph
+
+      # Handle empty glyphs (space, etc.)
+      return nil if glyph.respond_to?(:empty?) && glyph.empty?
+
+      if glyph.simple?
+        extract_simple_outline(glyph)
+      elsif glyph.compound?
+        extract_compound_outline(glyph)
+      else
+        raise Fontisan::Error, "Unknown glyph type: #{glyph.class}"
+      end
+    end
+
+    # Extract outline from CFF glyph
+    #
+    # CFF glyphs don't have compound structures, so extraction is
+    # straightforward from the CharString.
+    #
+    # @param glyph_id [Integer] Glyph ID
+    # @return [Models::GlyphOutline, nil] Outline or nil if empty
+    # @raise [Fontisan::MissingTableError] If CFF table is missing
+    def extract_cff_outline(glyph_id)
+      cff = font.table(Constants::CFF_TAG)
+      raise_missing_table!(Constants::CFF_TAG) unless cff
+
+      # Get CharString for glyph
+      charstring = cff.charstring_for_glyph(glyph_id)
+      return nil unless charstring
+
+      # CharString has path data
+      path = charstring.path
+      return nil if path.empty?
+
+      # Convert CharString path to contours
+      contours = convert_cff_path_to_contours(path)
+      return nil if contours.empty?
+
+      # Get bounding box from CharString
+      bbox_array = charstring.bounding_box
+      return nil unless bbox_array
+
+      bbox = {
+        x_min: bbox_array[0],
+        y_min: bbox_array[1],
+        x_max: bbox_array[2],
+        y_max: bbox_array[3],
+      }
+
+      Models::GlyphOutline.new(
+        glyph_id: glyph_id,
+        contours: contours,
+        bbox: bbox,
+      )
+    rescue StandardError => e
+      warn "Failed to extract CFF outline for glyph #{glyph_id}: #{e.message}"
+      nil
+    end
+
+    # Get TrueType glyph from glyf table
+    #
+    # @param glyph_id [Integer] Glyph ID
+    # @return [SimpleGlyph, CompoundGlyph, nil] Glyph object
+    # @raise [Fontisan::MissingTableError] If required tables are missing
+    def get_truetype_glyph(glyph_id)
+      glyf = font.table("glyf")
+      raise_missing_table!("glyf") unless glyf
+
+      loca = font.table("loca")
+      raise_missing_table!("loca") unless loca
+
+      head = font.table("head")
+      raise_missing_table!("head") unless head
+
+      # Ensure loca is parsed
+      unless loca.parsed?
+        maxp = font.table("maxp")
+        raise_missing_table!("maxp") unless maxp
+        loca.parse_with_context(head.index_to_loc_format, maxp.num_glyphs)
+      end
+
+      glyf.glyph_for(glyph_id, loca, head)
+    end
+
+    # Extract outline from a simple TrueType glyph
+    #
+    # @param glyph [SimpleGlyph] Simple glyph object
+    # @return [Models::GlyphOutline] Outline object
+    def extract_simple_outline(glyph)
+      contours = []
+
+      # Process each contour
+      glyph.num_contours.times do |contour_index|
+        points = glyph.points_for_contour(contour_index)
+        contours << points if points && !points.empty?
+      end
+
+      bbox = {
+        x_min: glyph.x_min,
+        y_min: glyph.y_min,
+        x_max: glyph.x_max,
+        y_max: glyph.y_max,
+      }
+
+      Models::GlyphOutline.new(
+        glyph_id: glyph.glyph_id,
+        contours: contours,
+        bbox: bbox,
+      )
+    end
+
+    # Extract outline from a compound TrueType glyph
+    #
+    # Recursively resolves component glyphs and applies transformations
+    # to combine them into a single outline.
+    #
+    # @param glyph [CompoundGlyph] Compound glyph object
+    # @return [Models::GlyphOutline] Combined outline object
+    def extract_compound_outline(glyph)
+      all_contours = []
+      combined_bbox = nil
+
+      # Process each component
+      glyph.components.each do |component|
+        component_outline = extract(component.glyph_index)
+        next unless component_outline
+
+        # Get transformation matrix
+        matrix = component.transformation_matrix
+
+        # Transform component contours
+        transformed_contours = transform_contours(
+          component_outline.contours,
+          matrix,
+        )
+        all_contours.concat(transformed_contours)
+
+        # Update combined bounding box
+        component_bbox = component_outline.bbox
+        combined_bbox = merge_bboxes(combined_bbox, component_bbox, matrix)
+      end
+
+      # Use original bbox if we couldn't compute one
+      combined_bbox ||= {
+        x_min: glyph.x_min,
+        y_min: glyph.y_min,
+        x_max: glyph.x_max,
+        y_max: glyph.y_max,
+      }
+
+      Models::GlyphOutline.new(
+        glyph_id: glyph.glyph_id,
+        contours: all_contours,
+        bbox: combined_bbox,
+      )
+    end
+
+    # Transform contours using an affine transformation matrix
+    #
+    # @param contours [Array<Array<Hash>>] Original contours
+    # @param matrix [Array<Float>] Transformation matrix [a, b, c, d, e, f]
+    # @return [Array<Array<Hash>>] Transformed contours
+    def transform_contours(contours, matrix)
+      a, b, c, d, e, f = matrix
+
+      contours.map do |contour|
+        contour.map do |point|
+          x = point[:x]
+          y = point[:y]
+
+          # Apply affine transformation: x' = a*x + c*y + e, y' = b*x + d*y + f
+          new_x = (a * x + c * y + e).round
+          new_y = (b * x + d * y + f).round
+
+          {
+            x: new_x,
+            y: new_y,
+            on_curve: point[:on_curve],
+          }
+        end
+      end
+    end
+
+    # Merge two bounding boxes
+    #
+    # @param bbox1 [Hash, nil] First bounding box
+    # @param bbox2 [Hash] Second bounding box
+    # @param matrix [Array<Float>] Transformation matrix for bbox2
+    # @return [Hash] Merged bounding box
+    def merge_bboxes(bbox1, bbox2, matrix)
+      # Transform bbox2 corners
+      a, b, c, d, e, f = matrix
+
+      corners = [
+        [bbox2[:x_min], bbox2[:y_min]],
+        [bbox2[:x_max], bbox2[:y_min]],
+        [bbox2[:x_min], bbox2[:y_max]],
+        [bbox2[:x_max], bbox2[:y_max]],
+      ]
+
+      transformed_corners = corners.map do |x, y|
+        [
+          (a * x + c * y + e).round,
+          (b * x + d * y + f).round,
+        ]
+      end
+
+      transformed_bbox = {
+        x_min: transformed_corners.map(&:first).min,
+        y_min: transformed_corners.map(&:last).min,
+        x_max: transformed_corners.map(&:first).max,
+        y_max: transformed_corners.map(&:last).max,
+      }
+
+      return transformed_bbox unless bbox1
+
+      # Merge with existing bbox
+      {
+        x_min: [bbox1[:x_min], transformed_bbox[:x_min]].min,
+        y_min: [bbox1[:y_min], transformed_bbox[:y_min]].min,
+        x_max: [bbox1[:x_max], transformed_bbox[:x_max]].max,
+        y_max: [bbox1[:y_max], transformed_bbox[:y_max]].max,
+      }
+    end
+
+    # Convert CFF CharString path to contours
+    #
+    # CFF paths are stored as arrays of command hashes. We need to
+    # convert them to the contour format used by GlyphOutline.
+    #
+    # @param path [Array<Hash>] CharString path data
+    # @return [Array<Array<Hash>>] Contours array
+    def convert_cff_path_to_contours(path)
+      contours = []
+      current_contour = []
+
+      path.each do |cmd|
+        case cmd[:type]
+        when :move_to
+          # Start new contour
+          contours << current_contour unless current_contour.empty?
+          current_contour = []
+          current_contour << {
+            x: cmd[:x].round,
+            y: cmd[:y].round,
+            on_curve: true,
+          }
+        when :line_to
+          current_contour << {
+            x: cmd[:x].round,
+            y: cmd[:y].round,
+            on_curve: true,
+          }
+        when :curve_to
+          # CFF uses cubic Bézier curves
+          # For now, we'll add control points and end point
+          # This is a simplification - proper handling would require
+          # converting cubic to quadratic or keeping cubic format
+          current_contour << {
+            x: cmd[:x1].round,
+            y: cmd[:y1].round,
+            on_curve: false,
+          }
+          current_contour << {
+            x: cmd[:x2].round,
+            y: cmd[:y2].round,
+            on_curve: false,
+          }
+          current_contour << {
+            x: cmd[:x].round,
+            y: cmd[:y].round,
+            on_curve: true,
+          }
+        end
+      end
+
+      # Add final contour
+      contours << current_contour unless current_contour.empty?
+
+      contours
+    end
+
+    # Raise MissingTableError
+    #
+    # @param table_tag [String] Table tag
+    # @raise [Fontisan::MissingTableError]
+    def raise_missing_table!(table_tag)
+      raise Fontisan::MissingTableError,
+            "Required table '#{table_tag}' not found in font"
+    end
+  end
+end

data/lib/fontisan/pipeline/format_detector.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative "../font_loader"
+
+module Fontisan
+  module Pipeline
+    # Detects font format and capabilities
+    #
+    # This class analyzes font files to determine:
+    # - Format: TTF, OTF, TTC, OTC, WOFF, WOFF2, SVG
+    # - Variation type: static, gvar (TrueType variable), CFF2 (OpenType variable)
+    # - Capabilities: outline type, variation support, collection support
+    #
+    # Used by the universal transformation pipeline to determine conversion
+    # strategies and validate compatibility.
+    #
+    # @example Detecting a font's format
+    #   detector = FormatDetector.new("font.ttf")
+    #   info = detector.detect
+    #   puts info[:format]        # => :ttf
+    #   puts info[:variation_type] # => :gvar
+    #   puts info[:capabilities][:outline] # => :truetype
+    class FormatDetector
+      # @return [String] Path to font file
+      attr_reader :file_path
+
+      # @return [TrueTypeFont, OpenTypeFont, TrueTypeCollection, OpenTypeCollection, nil] Loaded font
+      attr_reader :font
+
+      # Initialize detector
+      #
+      # @param file_path [String] Path to font file
+      def initialize(file_path)
+        @file_path = file_path
+        @font = nil
+      end
+
+      # Detect format and capabilities
+      #
+      # @return [Hash] Detection results with :format, :variation_type, :capabilities
+      def detect
+        load_font
+
+        {
+          format: detect_format,
+          variation_type: detect_variation,
+          capabilities: detect_capabilities,
+        }
+      end
+
+      # Detect font format
+      #
+      # @return [Symbol] One of :ttf, :otf, :ttc, :otc, :woff, :woff2, :svg
+      def detect_format
+        # Check for SVG first (from file extension even if font failed to load)
+        return :svg if @file_path.end_with?(".svg")
+
+        return :unknown unless @font
+
+        # Use is_a? for proper class checking
+        case @font
+        when Fontisan::TrueTypeCollection
+          :ttc
+        when Fontisan::OpenTypeCollection
+          :otc
+        when Fontisan::TrueTypeFont
+          if @file_path.end_with?(".woff")
+            :woff
+          elsif @file_path.end_with?(".woff2")
+            :woff2
+          else
+            :ttf
+          end
+        when Fontisan::OpenTypeFont
+          if @file_path.end_with?(".woff")
+            :woff
+          elsif @file_path.end_with?(".woff2")
+            :woff2
+          else
+            :otf
+          end
+        else
+          :unknown
+        end
+      end
+
+      # Detect variation type
+      #
+      # @return [Symbol] One of :static, :gvar, :cff2
+      def detect_variation
+        return :static unless @font
+
+        # Collections don't have has_table? method
+        # Return :static for collections (variation detection would need to load first font)
+        return :static if collection?
+
+        # Check for variable font tables
+        if @font.has_table?("fvar")
+          # Variable font detected - check variation type
+          if @font.has_table?("gvar")
+            :gvar # TrueType variable font
+          elsif @font.has_table?("CFF2")
+            :cff2 # OpenType variable font (CFF2)
+          else
+            :static # Has fvar but no variation data (shouldn't happen)
+          end
+        else
+          :static
+        end
+      end
+
+      # Detect font capabilities
+      #
+      # @return [Hash] Capabilities hash
+      def detect_capabilities
+        return default_capabilities unless @font
+
+        # Check if this is a collection
+        is_collection = collection?
+
+        font_to_check = if is_collection
+                          # Collections don't have fonts method, need to load first font
+                          nil # Will handle in API usage
+                        else
+                          @font
+                        end
+
+        # For collections, return basic capabilities
+        if is_collection
+          return {
+            outline: :unknown, # Would need to load first font to know
+            variation: false,  # Would need to load first font to know
+            collection: true,
+            tables: [],
+          }
+        end
+
+        return default_capabilities unless font_to_check
+
+        {
+          outline: detect_outline_type(font_to_check),
+          variation: detect_variation != :static,
+          collection: false,
+          tables: available_tables(font_to_check),
+        }
+      end
+
+      # Check if font is a collection
+      #
+      # @return [Boolean] True if collection (TTC/OTC)
+      def collection?
+        @font.is_a?(Fontisan::TrueTypeCollection) ||
+          @font.is_a?(Fontisan::OpenTypeCollection)
+      end
+
+      # Check if font is variable
+      #
+      # @return [Boolean] True if variable font
+      def variable?
+        detect_variation != :static
+      end
+
+      # Check if format is compatible with target
+      #
+      # @param target_format [Symbol] Target format (:ttf, :otf, etc.)
+      # @return [Boolean] True if conversion is possible
+      def compatible_with?(target_format)
+        current_format = detect_format
+        variation_type = detect_variation
+
+        # Same format is always compatible
+        return true if current_format == target_format
+
+        # Collection formats
+        if %i[ttc otc].include?(current_format)
+          return %i[ttc otc].include?(target_format)
+        end
+
+        # Variable font constraints
+        if variation_type == :static
+          # Static fonts can convert to any format
+          true
+        else
+          case variation_type
+          when :gvar
+            # TrueType variable can convert to TrueType formats
+            %i[ttf ttc woff woff2].include?(target_format)
+          when :cff2
+            # OpenType variable can convert to OpenType formats
+            %i[otf otc woff woff2].include?(target_format)
+          end
+        end
+      end
+
+      private
+
+      # Load font from file
+      def load_font
+        # Check if it's a collection first
+        @font = if FontLoader.collection?(@file_path)
+                  FontLoader.load_collection(@file_path)
+                else
+                  FontLoader.load(@file_path, mode: :full)
+                end
+      rescue StandardError => e
+        warn "Failed to load font: #{e.message}"
+        @font = nil
+      end
+
+      # Detect outline type
+      #
+      # @param font [Font] Font object
+      # @return [Symbol] :truetype or :cff
+      def detect_outline_type(font)
+        if font.has_table?("glyf") || font.has_table?("gvar")
+          :truetype
+        elsif font.has_table?("CFF ") || font.has_table?("CFF2")
+          :cff
+        else
+          :unknown
+        end
+      end
+
+      # Get available tables
+      #
+      # @param font [Font] Font object
+      # @return [Array<String>] List of table tags
+      def available_tables(font)
+        return [] unless font.respond_to?(:table_names)
+
+        font.table_names
+      rescue StandardError
+        []
+      end
+
+      # Default capabilities when font cannot be loaded
+      #
+      # @return [Hash] Default capabilities
+      def default_capabilities
+        {
+          outline: :unknown,
+          variation: false,
+          collection: false,
+          tables: [],
+        }
+      end
+    end
+  end
+end