fontisan 0.1.0 → 0.2.0

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/subset/builder.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require_relative "options"
+require_relative "profile"
+require_relative "glyph_mapping"
+require_relative "table_subsetter"
+require_relative "../font_writer"
+
+module Fontisan
+  module Subset
+    # Main font subsetting engine
+    #
+    # The [`Builder`](lib/fontisan/subset/builder.rb) class orchestrates the entire
+    # subsetting process:
+    # 1. Validates input parameters
+    # 2. Calculates glyph closure (including composite dependencies)
+    # 3. Builds glyph ID mapping (old GID → new GID)
+    # 4. Subsets each table according to the selected profile
+    # 5. Assembles the final subset font binary
+    #
+    # The subsetting process ensures that .notdef (GID 0) is always included
+    # as the first glyph, as required by the OpenType specification.
+    #
+    # @example Basic subsetting
+    #   font = Fontisan::TrueTypeFont.from_file('font.ttf')
+    #   builder = Fontisan::Subset::Builder.new(
+    #     font,
+    #     [0, 65, 66, 67],  # .notdef, A, B, C
+    #     Options.new(profile: 'pdf')
+    #   )
+    #   subset_data = builder.build
+    #
+    # @example Subsetting with retain_gids
+    #   options = Options.new(profile: 'pdf', retain_gids: true)
+    #   builder = Fontisan::Subset::Builder.new(font, glyph_ids, options)
+    #   subset_data = builder.build
+    #
+    # @example Web subsetting with dropped hints
+    #   options = Options.new(profile: 'web', drop_hints: true, drop_names: true)
+    #   builder = Fontisan::Subset::Builder.new(font, glyph_ids, options)
+    #   subset_data = builder.build
+    #
+    # Reference: [`docs/ttfunk-feature-analysis.md:455-492`](docs/ttfunk-feature-analysis.md:455)
+    class Builder
+      # Font instance to subset
+      # @return [TrueTypeFont, OpenTypeFont]
+      attr_reader :font
+
+      # Base set of glyph IDs requested for subsetting
+      # @return [Array<Integer>]
+      attr_reader :glyph_ids
+
+      # Subsetting options
+      # @return [Options]
+      attr_reader :options
+
+      # Complete set of glyph IDs after closure calculation
+      # @return [Set<Integer>]
+      attr_reader :closure
+
+      # Glyph ID mapping (old GID → new GID)
+      # @return [GlyphMapping]
+      attr_reader :mapping
+
+      # Initialize a new subsetting builder
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font to subset
+      # @param glyph_ids [Array<Integer>] Base glyph IDs to include
+      # @param options [Options, Hash] Subsetting options
+      # @raise [ArgumentError] If parameters are invalid
+      #
+      # @example
+      #   builder = Builder.new(font, [0, 65, 66], Options.new(profile: 'pdf'))
+      def initialize(font, glyph_ids, options = {})
+        @font = font
+        @glyph_ids = Array(glyph_ids)
+        @options = options.is_a?(Options) ? options : Options.new(options)
+        @closure = nil
+        @mapping = nil
+      end
+
+      # Build the subset font
+      #
+      # This is the main entry point that performs the entire subsetting
+      # workflow:
+      # 1. Validates all input parameters
+      # 2. Calculates the glyph closure (composite dependencies)
+      # 3. Builds the glyph ID mapping
+      # 4. Subsets all required tables
+      # 5. Assembles the final font binary
+      #
+      # @return [String] Binary data of the subset font
+      # @raise [ArgumentError] If validation fails
+      # @raise [Fontisan::SubsettingError] If subsetting fails
+      #
+      # @example
+      #   subset_binary = builder.build
+      #   File.binwrite('subset.ttf', subset_binary)
+      def build
+        validate_input!
+        calculate_closure
+        build_mapping
+        tables = subset_tables
+        assemble_font(tables)
+      end
+
+      private
+
+      # Validate input parameters
+      #
+      # Ensures that the font, glyph IDs, and options are all valid for
+      # subsetting. Checks that required tables exist and that glyph IDs
+      # are within valid range.
+      #
+      # @raise [ArgumentError] If validation fails
+      def validate_input!
+        raise ArgumentError, "Font cannot be nil" if font.nil?
+
+        unless font.respond_to?(:table)
+          raise ArgumentError, "Font must respond to :table method"
+        end
+
+        # Validate options
+        options.validate!
+
+        # Ensure we have at least one glyph ID
+        if glyph_ids.empty?
+          raise ArgumentError, "At least one glyph ID must be provided"
+        end
+
+        # Validate that required tables exist
+        validate_required_tables!
+
+        # Validate glyph IDs are within range
+        validate_glyph_ids!
+      end
+
+      # Validate that required tables exist in the font
+      #
+      # @raise [Fontisan::MissingTableError] If required tables are missing
+      def validate_required_tables!
+        required = %w[head maxp]
+        required.each do |tag|
+          table = font.table(tag)
+          next if table
+
+          raise Fontisan::MissingTableError,
+                "Required table '#{tag}' not found in font"
+        end
+      end
+
+      # Validate that all glyph IDs are within valid range
+      #
+      # @raise [ArgumentError] If any glyph ID is invalid
+      def validate_glyph_ids!
+        maxp = font.table("maxp")
+        num_glyphs = maxp.num_glyphs
+
+        glyph_ids.each do |gid|
+          if gid.nil? || gid.negative?
+            raise ArgumentError, "Invalid glyph ID: #{gid.inspect}"
+          end
+
+          if gid >= num_glyphs
+            raise ArgumentError,
+                  "Glyph ID #{gid} exceeds font's glyph count " \
+                  "(#{num_glyphs})"
+          end
+        end
+      end
+
+      # Calculate glyph closure
+      #
+      # Uses [`GlyphAccessor`](lib/fontisan/glyph_accessor.rb) to recursively
+      # collect all glyphs needed, including component glyphs referenced by
+      # composite glyphs. Always ensures GID 0 (.notdef) is included.
+      #
+      # The closure is stored in the `@closure` instance variable as a Set.
+      def calculate_closure
+        accessor = Fontisan::GlyphAccessor.new(font)
+
+        # Ensure .notdef (GID 0) is included if specified in options
+        base_gids = glyph_ids.dup
+        base_gids.unshift(0) if options.include_notdef && !base_gids.include?(0)
+
+        # Calculate closure using GlyphAccessor
+        @closure = accessor.closure_for(base_gids)
+      end
+
+      # Build glyph mapping
+      #
+      # Creates a [`GlyphMapping`](lib/fontisan/subset/glyph_mapping.rb)
+      # object that maps old glyph IDs to new glyph IDs. The mapping respects
+      # the `retain_gids` option:
+      # - Compact mode (retain_gids: false): Sequential renumbering
+      # - Retain mode (retain_gids: true): Preserve original GIDs
+      #
+      # The mapping is stored in the `@mapping` instance variable.
+      def build_mapping
+        @mapping = GlyphMapping.new(
+          closure.to_a,
+          retain_gids: options.retain_gids,
+        )
+      end
+
+      # Subset all tables according to profile
+      #
+      # For each table specified in the subsetting profile, performs
+      # table-specific subsetting operations using [`TableSubsetter`](lib/fontisan/subset/table_subsetter.rb).
+      # Tables not in the profile are excluded from the subset font.
+      #
+      # @return [Hash<String, String>] Hash of table tag => binary data
+      # @raise [Fontisan::SubsettingError] If table subsetting fails
+      def subset_tables
+        profile_tables = Profile.for_name(options.profile)
+        subset = {}
+
+        # Create table subsetter
+        subsetter = TableSubsetter.new(font, mapping, options)
+
+        profile_tables.each do |tag|
+          table = font.table(tag)
+          next unless table
+
+          begin
+            subset[tag] = subsetter.subset_table(tag, table)
+          rescue StandardError => e
+            raise Fontisan::SubsettingError,
+                  "Failed to subset table '#{tag}': #{e.message}"
+          end
+        end
+
+        subset
+      end
+
+      # Assemble final font
+      #
+      # Builds the complete font binary from subset tables, including:
+      # - Offset table (font directory)
+      # - Table directory entries
+      # - Table data
+      # - Proper padding and checksums
+      #
+      # @param tables [Hash<String, String>] Table tag => binary data
+      # @return [String] Complete font binary
+      def assemble_font(tables)
+        # Determine sfnt version based on font type
+        sfnt_version = determine_sfnt_version(tables)
+
+        # Use FontWriter to assemble the complete font
+        FontWriter.write_font(tables, sfnt_version: sfnt_version)
+      end
+
+      # Determine the sfnt version for the font
+      #
+      # @param tables [Hash<String, String>] Table tag => binary data
+      # @return [Integer] sfnt version number
+      def determine_sfnt_version(tables)
+        # If font has CFF or CFF2 table, use OpenType version
+        if tables.key?("CFF ") || tables.key?("CFF2")
+          0x4F54544F # 'OTTO' for OpenType/CFF
+        else
+          0x00010000 # 1.0 for TrueType
+        end
+      end
+    end
+  end
+end