fontisan 0.1.0 → 0.2.1

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

data/lib/fontisan/subset/glyph_mapping.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Fontisan
+  module Subset
+    # Glyph ID mapping management
+    #
+    # This class manages the mapping between original glyph IDs (GIDs) in the
+    # source font and new GIDs in the subset font. It supports two modes:
+    #
+    # 1. Compact mode (retain_gids: false): Glyphs are renumbered sequentially,
+    #    eliminating gaps from removed glyphs. This produces smaller fonts.
+    #
+    # 2. Retain mode (retain_gids: true): Original glyph IDs are preserved,
+    #    with removed glyphs leaving empty slots. This maintains glyph
+    #    references but produces larger fonts.
+    #
+    # @example Compact mode (default)
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10, 15])
+    #   mapping.new_id(5)  # => 1
+    #   mapping.new_id(10) # => 2
+    #   mapping.size       # => 4
+    #
+    # @example Retain mode
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10, 15], retain_gids: true)
+    #   mapping.new_id(5)  # => 5
+    #   mapping.new_id(10) # => 10
+    #   mapping.size       # => 16 (0..15)
+    #
+    # @example Reverse lookup
+    #   mapping = Fontisan::Subset::GlyphMapping.new([0, 5, 10])
+    #   mapping.old_id(1) # => 5
+    class GlyphMapping
+      # @return [Hash<Integer, Integer>] mapping from old GIDs to new GIDs
+      attr_reader :old_to_new
+
+      # @return [Hash<Integer, Integer>] mapping from new GIDs to old GIDs
+      attr_reader :new_to_old
+
+      # @return [Boolean] whether original GIDs are retained
+      attr_reader :retain_gids
+
+      # Initialize glyph mapping
+      #
+      # @param old_glyph_ids [Array<Integer>] array of glyph IDs to include
+      #   in the subset, typically sorted
+      # @param retain_gids [Boolean] whether to preserve original glyph IDs
+      #
+      # @example Create compact mapping
+      #   mapping = GlyphMapping.new([0, 3, 5, 10])
+      #
+      # @example Create mapping that retains GIDs
+      #   mapping = GlyphMapping.new([0, 3, 5, 10], retain_gids: true)
+      def initialize(old_glyph_ids, retain_gids: false)
+        @old_to_new = {}
+        @new_to_old = {}
+        @retain_gids = retain_gids
+
+        build_mappings(old_glyph_ids)
+      end
+
+      # Get new glyph ID for an old glyph ID
+      #
+      # @param old_id [Integer] original glyph ID
+      # @return [Integer, nil] new glyph ID, or nil if not in subset
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.new_id(5)  # => 1
+      #   mapping.new_id(99) # => nil
+      def new_id(old_id)
+        old_to_new[old_id]
+      end
+
+      # Get old glyph ID for a new glyph ID
+      #
+      # @param new_id [Integer] new glyph ID in subset
+      # @return [Integer, nil] original glyph ID, or nil if invalid
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.old_id(1) # => 5
+      #   mapping.old_id(99) # => nil
+      def old_id(new_id)
+        new_to_old[new_id]
+      end
+
+      # Get number of glyphs in the subset
+      #
+      # In compact mode, this is the number of included glyphs.
+      # In retain mode, this is the highest old GID + 1.
+      #
+      # @return [Integer] number of glyphs
+      #
+      # @example Compact mode
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.size # => 3
+      #
+      # @example Retain mode
+      #   mapping = GlyphMapping.new([0, 5, 10], retain_gids: true)
+      #   mapping.size # => 11 (0..10)
+      def size
+        new_to_old.size
+      end
+
+      # Check if a glyph is included in the subset
+      #
+      # @param old_id [Integer] original glyph ID to check
+      # @return [Boolean] true if glyph is in subset
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.include?(5)  # => true
+      #   mapping.include?(99) # => false
+      def include?(old_id)
+        old_to_new.key?(old_id)
+      end
+
+      # Get array of all old glyph IDs in subset
+      #
+      # @return [Array<Integer>] sorted array of old glyph IDs
+      #
+      # @example
+      #   mapping = GlyphMapping.new([10, 0, 5])
+      #   mapping.old_ids # => [0, 5, 10]
+      def old_ids
+        old_to_new.keys.sort
+      end
+
+      # Get array of all new glyph IDs in subset
+      #
+      # @return [Array<Integer>] sorted array of new glyph IDs
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.new_ids # => [0, 1, 2]
+      def new_ids
+        new_to_old.keys.sort
+      end
+
+      # Iterate over all glyph mappings
+      #
+      # Yields old_id and new_id pairs in order of old glyph IDs.
+      #
+      # @yield [old_id, new_id] each glyph mapping
+      # @yieldparam old_id [Integer] original glyph ID
+      # @yieldparam new_id [Integer] new glyph ID
+      #
+      # @example
+      #   mapping = GlyphMapping.new([0, 5, 10])
+      #   mapping.each do |old_id, new_id|
+      #     puts "#{old_id} => #{new_id}"
+      #   end
+      #   # Output:
+      #   # 0 => 0
+      #   # 5 => 1
+      #   # 10 => 2
+      def each
+        return enum_for(:each) unless block_given?
+
+        old_ids.each do |old_id|
+          yield old_id, old_to_new[old_id]
+        end
+      end
+
+      private
+
+      # Build the bidirectional mapping tables
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_mappings(old_glyph_ids)
+        if retain_gids
+          build_retained_mappings(old_glyph_ids)
+        else
+          build_compact_mappings(old_glyph_ids)
+        end
+      end
+
+      # Build mappings in compact mode
+      #
+      # Assigns sequential new GIDs starting from 0, preserving the order
+      # of old GIDs.
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_compact_mappings(old_glyph_ids)
+        sorted_ids = old_glyph_ids.sort.uniq
+        sorted_ids.each_with_index do |old_id, new_id|
+          old_to_new[old_id] = new_id
+          new_to_old[new_id] = old_id
+        end
+      end
+
+      # Build mappings in retain GID mode
+      #
+      # Preserves original GIDs, creating empty slots for removed glyphs.
+      #
+      # @param old_glyph_ids [Array<Integer>] glyph IDs to map
+      def build_retained_mappings(old_glyph_ids)
+        sorted_ids = old_glyph_ids.sort.uniq
+        max_id = sorted_ids.max || 0
+
+        # Map each glyph to itself
+        sorted_ids.each do |old_id|
+          old_to_new[old_id] = old_id
+          new_to_old[old_id] = old_id
+        end
+
+        # Fill in empty slots for removed glyphs with nil mappings
+        # This ensures size calculation includes the empty slots
+        (0..max_id).each do |gid|
+          new_to_old[gid] ||= nil
+        end
+      end
+    end
+  end
+end

data/lib/fontisan/subset/options.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module Fontisan
+  module Subset
+    # Subsetting configuration class
+    #
+    # This class defines all available options for font subsetting operations.
+    # It provides sensible defaults for various subsetting scenarios and uses
+    # Lutaml::Model for serialization support.
+    #
+    # @example Create default PDF subsetting options
+    #   options = Fontisan::Subset::Options.new
+    #   options.profile # => "pdf"
+    #   options.drop_hints # => false
+    #
+    # @example Create custom web subsetting options
+    #   options = Fontisan::Subset::Options.new(
+    #     profile: "web",
+    #     drop_hints: true,
+    #     unicode_ranges: false
+    #   )
+    #
+    # @example Retain original glyph IDs
+    #   options = Fontisan::Subset::Options.new(retain_gids: true)
+    class Options < Lutaml::Model::Serializable
+      # Subsetting profile name (pdf, web, minimal, or custom)
+      #
+      # @return [String] the profile name
+      attribute :profile, :string, default: -> { "pdf" }
+
+      # Whether to drop hinting instructions
+      #
+      # Hinting improves text rendering at small sizes but increases file size.
+      # Web fonts typically don't need hints due to modern rendering engines.
+      #
+      # @return [Boolean] true to drop hints, false to retain them
+      attribute :drop_hints, :boolean, default: -> { false }
+
+      # Whether to drop glyph names from the post table
+      #
+      # Glyph names are useful for debugging but not required for rendering.
+      # Dropping them reduces file size.
+      #
+      # @return [Boolean] true to drop names, false to retain them
+      attribute :drop_names, :boolean, default: -> { false }
+
+      # Whether to prune OS/2 Unicode ranges
+      #
+      # Updates the OS/2 table's Unicode range bits to reflect only the
+      # glyphs present in the subset.
+      #
+      # @return [Boolean] true to prune ranges, false to keep original
+      attribute :unicode_ranges, :boolean, default: -> { true }
+
+      # Whether to retain original glyph IDs
+      #
+      # When true, removed glyphs leave empty slots in the glyf table,
+      # preserving original GID assignments. When false, glyphs are
+      # compacted to eliminate gaps.
+      #
+      # @return [Boolean] true to retain GIDs, false to compact
+      attribute :retain_gids, :boolean, default: -> { false }
+
+      # Whether to include the .notdef glyph
+      #
+      # The .notdef glyph is displayed for missing characters. It is
+      # typically required by font specifications.
+      #
+      # @return [Boolean] true to include .notdef, false to exclude
+      attribute :include_notdef, :boolean, default: -> { true }
+
+      # Whether to include the .null glyph
+      #
+      # The .null glyph (U+0000) is sometimes used for control purposes.
+      #
+      # @return [Boolean] true to include .null, false to exclude
+      attribute :include_null, :boolean, default: -> { false }
+
+      # OpenType features to retain in the subset
+      #
+      # An empty array means all features are retained. Specify feature
+      # tags (e.g., ['liga', 'kern']) to keep only those features.
+      #
+      # @return [Array<String>] array of feature tags to retain
+      attribute :features, :string, collection: true, default: -> { [] }
+
+      # Script tags to retain in the subset
+      #
+      # An array containing "*" means all scripts are retained. Specify
+      # script tags (e.g., ['latn', 'arab']) to keep only those scripts.
+      #
+      # @return [Array<String>] array of script tags to retain
+      attribute :scripts, :string, collection: true, default: -> { ["*"] }
+
+      # Initialize options with custom values
+      #
+      # @param attributes [Hash] hash of attribute values
+      # @option attributes [String] :profile ("pdf") subsetting profile
+      # @option attributes [Boolean] :drop_hints (false) drop hinting
+      # @option attributes [Boolean] :drop_names (false) drop glyph names
+      # @option attributes [Boolean] :unicode_ranges (true) prune OS/2 ranges
+      # @option attributes [Boolean] :retain_gids (false) retain glyph IDs
+      # @option attributes [Boolean] :include_notdef (true) include .notdef
+      # @option attributes [Boolean] :include_null (false) include .null
+      # @option attributes [Array<String>] :features ([]) features to keep
+      # @option attributes [Array<String>] :scripts (["*"]) scripts to keep
+      def initialize(attributes = {})
+        super
+      end
+
+      # Check if all features should be retained
+      #
+      # @return [Boolean] true if features array is empty
+      def all_features?
+        features.empty?
+      end
+
+      # Check if all scripts should be retained
+      #
+      # @return [Boolean] true if scripts contains "*"
+      def all_scripts?
+        scripts.include?("*")
+      end
+
+      # Validate the options configuration
+      #
+      # @raise [ArgumentError] if profile is invalid
+      # @return [Boolean] true if valid
+      def validate!
+        valid_profiles = %w[pdf web minimal custom]
+        unless valid_profiles.include?(profile)
+          raise ArgumentError,
+                "Invalid profile '#{profile}'. Must be one of: #{valid_profiles.join(', ')}"
+        end
+
+        true
+      end
+    end
+  end
+end