fontisan 0.2.10 → 0.2.12

data/lib/fontisan/conversion_options.rb

@@ -0,0 +1,378 @@
+# frozen_string_literal: true
+
+module Fontisan
+  # Conversion options for font format transformations
+  #
+  # Defines all options for opening (reading) and generating (writing) fonts
+  # during conversion operations. Includes validation, defaults, and presets.
+  #
+  # @example Using options directly
+  #   options = ConversionOptions.new(
+  #     from: :ttf,
+  #     to: :otf,
+  #     opening: { convert_curves: true, scale_to_1000: true },
+  #     generating: { hinting_mode: "auto" }
+  #   )
+  #
+  # @example Using recommended options
+  #   options = ConversionOptions.recommended(from: :ttf, to: :otf)
+  #
+  # @example Using a preset
+  #   options = ConversionOptions.from_preset(:type1_to_modern)
+  class ConversionOptions
+    # Opening options (input processing)
+    OPENING_OPTIONS = %i[
+      decompose_composites
+      convert_curves
+      scale_to_1000
+      scale_from_1000
+      autohint
+      generate_unicode
+      store_custom_tables
+      store_native_hinting
+      interpret_ot
+      read_all_records
+      preserve_encoding
+    ].freeze
+
+    # Generating options (output processing)
+    GENERATING_OPTIONS = %i[
+      write_pfm
+      write_afm
+      write_inf
+      select_encoding_automatically
+      hinting_mode
+      decompose_on_output
+      write_custom_tables
+      optimize_tables
+      reencode_first_256
+      encoding_vector
+      compression
+      transform_tables
+      preserve_metadata
+      strip_metadata
+      target_format
+    ].freeze
+
+    # Valid hinting modes
+    HINTING_MODES = %w[preserve auto none full].freeze
+
+    # Valid compression modes
+    COMPRESSION_MODES = %w[zlib brotli none].freeze
+
+    attr_reader :from, :to, :opening, :generating
+
+    # Initialize conversion options
+    #
+    # @param from [String, Symbol] Source format
+    # @param to [String, Symbol] Target format
+    # @param opening [Hash] Opening options
+    # @param generating [Hash] Generating options
+    def initialize(from:, to:, opening: {}, generating: {})
+      @from = self.class.normalize_format(from)
+      @to = self.class.normalize_format(to)
+      @opening = apply_opening_defaults(opening)
+      @generating = apply_generating_defaults(generating)
+      validate!
+    end
+
+    # Get recommended options for a conversion pair
+    #
+    # @param from [String, Symbol] Source format
+    # @param to [String, Symbol] Target format
+    # @return [ConversionOptions] Pre-configured options
+    def self.recommended(from:, to:)
+      from_sym = normalize_format(from)
+      to_sym = normalize_format(to)
+
+      options = RECOMMENDED_OPTIONS.dig(from_sym, to_sym) || {}
+      new(
+        from: from_sym,
+        to: to_sym,
+        opening: options[:opening] || {},
+        generating: options[:generating] || {},
+      )
+    end
+
+    # Load options from a named preset
+    #
+    # @param preset_name [Symbol, String] Preset name
+    # @return [ConversionOptions] Pre-configured options
+    def self.from_preset(preset_name)
+      preset_key = preset_name.to_sym
+      preset = PRESETS.fetch(preset_key) do
+        raise ArgumentError, "Unknown preset: #{preset_name}. " \
+                            "Available: #{PRESETS.keys.join(', ')}"
+      end
+
+      new(
+        from: preset[:from],
+        to: preset[:to],
+        opening: preset[:opening] || {},
+        generating: preset[:generating] || {},
+      )
+    end
+
+    # Check if an opening option is set
+    #
+    # @param key [Symbol] Option key
+    # @return [Boolean] true if option is truthy
+    def opening_option?(key)
+      !!@opening[key]
+    end
+
+    # Check if a generating option has a specific value
+    #
+    # @param key [Symbol] Option key
+    # @param value [Object] Value to check
+    # @return [Boolean] true if option equals value
+    def generating_option?(key, value = true)
+      @generating[key] == value
+    end
+
+    # Get list of available presets
+    #
+    # @return [Array<Symbol>] Available preset names
+    def self.available_presets
+      PRESETS.keys
+    end
+
+    private
+
+    # Normalize format symbol
+    #
+    # @param format [String, Symbol] Format identifier
+    # @return [Symbol] Normalized format symbol
+    def self.normalize_format(format)
+      case format.to_s.downcase
+      when "ttf", "truetype", "truetype-tt", "ot-tt" then :ttf
+      when "otf", "cff", "opentype", "ot-ps", "opentype-ps" then :otf
+      when "type1", "type-1", "t1", "pfb", "pfa" then :type1
+      when "ttc" then :ttc
+      when "otc" then :otc
+      when "dfont", "suitcase" then :dfont
+      when "woff" then :woff
+      when "woff2" then :woff2
+      when "svg" then :svg
+      else
+        raise ArgumentError, "Unknown format: #{format}. " \
+                            "Supported: ttf, otf, type1, ttc, otc, dfont, woff, woff2, svg"
+      end
+    end
+
+    # Apply default values for opening options
+    #
+    # @param options [Hash] User-provided options
+    # @return [Hash] Options with defaults applied
+    def apply_opening_defaults(options)
+      defaults = OPENING_DEFAULTS.dig(@from, @to) || {}
+      defaults.merge(options)
+    end
+
+    # Apply default values for generating options
+    #
+    # @param options [Hash] User-provided options
+    # @return [Hash] Options with defaults applied
+    def apply_generating_defaults(options)
+      defaults = GENERATING_DEFAULTS.dig(@from, @to) || {}
+      defaults.merge(options)
+    end
+
+    # Validate options
+    #
+    # @raise [ArgumentError] If options are invalid
+    def validate!
+      validate_opening_options!
+      validate_generating_options!
+    end
+
+    # Validate opening options
+    def validate_opening_options!
+      @opening.each_key do |key|
+        unless OPENING_OPTIONS.include?(key)
+          raise ArgumentError, "Unknown opening option: #{key}. " \
+                              "Available: #{OPENING_OPTIONS.join(', ')}"
+        end
+      end
+    end
+
+    # Validate generating options
+    def validate_generating_options!
+      @generating.each_key do |key|
+        unless GENERATING_OPTIONS.include?(key)
+          raise ArgumentError, "Unknown generating option: #{key}. " \
+                              "Available: #{GENERATING_OPTIONS.join(', ')}"
+        end
+      end
+
+      # Validate hinting_mode
+      if @generating[:hinting_mode]
+        mode = @generating[:hinting_mode].to_s
+        unless HINTING_MODES.include?(mode)
+          raise ArgumentError, "Invalid hinting_mode: #{mode}. " \
+                              "Available: #{HINTING_MODES.join(', ')}"
+        end
+      end
+
+      # Validate compression mode
+      if @generating[:compression]
+        comp = @generating[:compression].to_s
+        unless COMPRESSION_MODES.include?(comp)
+          raise ArgumentError, "Invalid compression: #{comp}. " \
+                              "Available: #{COMPRESSION_MODES.join(', ')}"
+        end
+      end
+
+      # Validate target_format for collection conversions
+      if @generating[:target_format]
+        target = @generating[:target_format].to_s
+        unless ["ttf", "otf", "preserve"].include?(target)
+          raise ArgumentError, "Invalid target_format: #{target}"
+        end
+      end
+    end
+
+    # Default opening options per conversion pair
+    OPENING_DEFAULTS = {
+      ttf: {
+        ttf: { decompose_composites: false, convert_curves: false,
+               store_custom_tables: true },
+        otf: { convert_curves: true, scale_to_1000: true,
+               autohint: true, decompose_composites: false },
+        type1: { convert_curves: true, scale_to_1000: true,
+                 autohint: true, decompose_composites: false },
+      },
+      otf: {
+        ttf: { convert_curves: true, decompose_composites: false,
+               interpret_ot: true },
+        otf: { decompose_composites: false, store_custom_tables: true },
+        type1: { decompose_composites: false },
+      },
+      type1: {
+        ttf: { decompose_composites: false, generate_unicode: true,
+               read_all_records: true },
+        otf: { decompose_composites: false, generate_unicode: true,
+               read_all_records: true },
+      },
+    }.freeze
+
+    # Default generating options per conversion pair
+    GENERATING_DEFAULTS = {
+      ttf: {
+        ttf: { hinting_mode: "preserve", write_custom_tables: true,
+               optimize_tables: true },
+        otf: { hinting_mode: "auto", decompose_on_output: false,
+               write_custom_tables: true },
+        type1: { write_pfm: true, write_afm: true, write_inf: true,
+                 select_encoding_automatically: true, hinting_mode: "auto" },
+      },
+      otf: {
+        ttf: { hinting_mode: "auto", decompose_on_output: false,
+               write_custom_tables: true },
+        otf: { hinting_mode: "preserve", decompose_on_output: false,
+               write_custom_tables: true, optimize_tables: true },
+        type1: { write_pfm: true, write_afm: true, write_inf: true,
+                 select_encoding_automatically: true, hinting_mode: "preserve",
+                 decompose_on_output: false },
+      },
+      type1: {
+        ttf: { hinting_mode: "auto", decompose_on_output: true },
+        otf: { hinting_mode: "preserve", decompose_on_output: true },
+        type1: { write_pfm: true, write_afm: true, write_inf: true,
+                 select_encoding_automatically: true },
+      },
+    }.freeze
+
+    # Recommended options from TypeTool 3 manual
+    # Based on "Options for Converting Fonts" table (lines 6735-6803)
+    RECOMMENDED_OPTIONS = {
+      ttf: {
+        ttf: {
+          opening: { convert_curves: false, scale_to_1000: false,
+                     decompose_composites: false, autohint: false,
+                     store_custom_tables: true, store_native_hinting: true },
+          generating: { hinting_mode: "full", write_custom_tables: true },
+        },
+        otf: {
+          opening: { convert_curves: true, scale_to_1000: true,
+                     autohint: true, decompose_composites: false,
+                     store_custom_tables: true },
+          generating: { hinting_mode: "auto", decompose_on_output: true },
+        },
+        type1: {
+          opening: { convert_curves: true, scale_to_1000: true,
+                     autohint: true, decompose_composites: false,
+                     store_custom_tables: false },
+          generating: { write_pfm: true, write_afm: true, write_inf: true,
+                        select_encoding_automatically: true },
+        },
+      },
+      otf: {
+        ttf: {
+          opening: { decompose_composites: false, read_all_records: true,
+                     interpret_ot: true, store_custom_tables: true,
+                     store_native_hinting: false },
+          generating: { hinting_mode: "full", reencode_first_256: false },
+        },
+        otf: {
+          opening: { decompose_composites: false, store_custom_tables: true },
+          generating: { hinting_mode: "none", decompose_on_output: false,
+                        write_custom_tables: true },
+        },
+        type1: {
+          opening: { decompose_composites: false },
+          generating: { write_pfm: true, write_afm: true, write_inf: true,
+                        select_encoding_automatically: true,
+                        hinting_mode: "none" },
+        },
+      },
+      type1: {
+        ttf: {
+          opening: { decompose_composites: false, generate_unicode: true },
+          generating: { hinting_mode: "full" },
+        },
+        otf: {
+          opening: { decompose_composites: false, generate_unicode: true },
+          generating: { hinting_mode: "none", decompose_on_output: true },
+        },
+        type1: {
+          opening: { decompose_composites: false, generate_unicode: true },
+          generating: { write_pfm: true, write_afm: true, write_inf: true,
+                        select_encoding_automatically: true },
+        },
+      },
+    }.freeze
+
+    # Named presets for common conversion scenarios
+    PRESETS = {
+      type1_to_modern: {
+        from: :type1,
+        to: :otf,
+        opening: { generate_unicode: true, decompose_composites: false },
+        generating: { hinting_mode: "preserve", decompose_on_output: true },
+      },
+      modern_to_type1: {
+        from: :otf,
+        to: :type1,
+        opening: { convert_curves: true, scale_to_1000: true,
+                   autohint: true, decompose_composites: false,
+                   store_custom_tables: false },
+        generating: { write_pfm: true, write_afm: true, write_inf: true,
+                      select_encoding_automatically: true, hinting_mode: "preserve" },
+      },
+      web_optimized: {
+        from: :otf,
+        to: :woff2,
+        opening: {},
+        generating: { compression: "brotli", transform_tables: true,
+                      optimize_tables: true, preserve_metadata: true },
+      },
+      archive_to_modern: {
+        from: :ttc,
+        to: :otf,
+        opening: { convert_curves: true, decompose_composites: false },
+        generating: { target_format: "otf", hinting_mode: "preserve" },
+      },
+    }.freeze
+  end
+end

data/lib/fontisan/converters/cff_table_builder.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require_relative "../tables/cff/index_builder"
+require_relative "../tables/cff/dict_builder"
+
+module Fontisan
+  module Converters
+    # Builds CFF table data from glyph outlines
+    #
+    # This module handles the construction of complete CFF tables including
+    # all INDEX structures (name, Top DICT, String, GlobalSubr, CharStrings, LocalSubr)
+    # and the Private DICT.
+    #
+    # The CFF table structure is:
+    # - Header (4 bytes)
+    # - Name INDEX
+    # - Top DICT INDEX
+    # - String INDEX
+    # - Global Subr INDEX
+    # - CharStrings INDEX
+    # - Private DICT (with offset in Top DICT)
+    # - Local Subr INDEX (with offset in Private DICT)
+    module CffTableBuilder
+      # Build complete CFF table from pre-built charstrings
+      #
+      # @param charstrings [Array<String>] Pre-built CharString data (already optimized if needed)
+      # @param local_subrs [Array<String>] Local subroutines from optimization
+      # @param font [TrueTypeFont] Source font (for metadata)
+      # @return [String] Complete CFF table binary data
+      def build_cff_table(charstrings, local_subrs, font)
+        # If we have local subrs from optimization, use them
+        local_subrs = [] unless local_subrs.is_a?(Array)
+
+        # Build font metadata
+        font_name = extract_font_name(font)
+
+        # Build all INDEXes
+        header_size = 4
+        name_index_data = Tables::Cff::IndexBuilder.build([font_name])
+        string_index_data = Tables::Cff::IndexBuilder.build([]) # Empty strings
+        global_subr_index_data = Tables::Cff::IndexBuilder.build([]) # Empty global subrs
+        charstrings_index_data = Tables::Cff::IndexBuilder.build(charstrings)
+        local_subrs_index_data = Tables::Cff::IndexBuilder.build(local_subrs)
+
+        # Build Private DICT with Subrs offset if we have local subroutines
+        private_dict_data, private_dict_size = build_private_dict(local_subrs)
+
+        # Calculate offsets with iterative refinement
+        top_dict_index_data, =
+          calculate_cff_offsets(
+            header_size,
+            name_index_data,
+            string_index_data,
+            global_subr_index_data,
+            charstrings_index_data,
+            private_dict_size,
+          )
+
+        # Build CFF Header
+        header = build_cff_header
+
+        # Assemble complete CFF table
+        header +
+          name_index_data +
+          top_dict_index_data +
+          string_index_data +
+          global_subr_index_data +
+          charstrings_index_data +
+          private_dict_data +
+          local_subrs_index_data
+      end
+
+      private
+
+      # Build Private DICT with optional Subrs offset
+      #
+      # @param local_subrs [Array<String>] Local subroutines
+      # @return [Array<String, Integer>] [Private DICT data, size]
+      def build_private_dict(local_subrs)
+        private_dict_hash = {
+          default_width_x: 1000,
+          nominal_width_x: 0,
+        }
+
+        # If we have local subroutines, add Subrs offset
+        # Subrs offset is relative to Private DICT start
+        if local_subrs.any?
+          # Add a placeholder Subrs offset first to get accurate size
+          private_dict_hash[:subrs] = 0
+
+          # Calculate size of Private DICT with Subrs entry
+          temp_private_dict_data = Tables::Cff::DictBuilder.build(private_dict_hash)
+          subrs_offset = temp_private_dict_data.bytesize
+
+          # Update with actual Subrs offset
+          private_dict_hash[:subrs] = subrs_offset
+        end
+
+        # Build final Private DICT
+        private_dict_data = Tables::Cff::DictBuilder.build(private_dict_hash)
+        [private_dict_data, private_dict_data.bytesize]
+      end
+
+      # Calculate CFF table offsets with iterative refinement
+      #
+      # @param header_size [Integer] CFF header size
+      # @param name_index_data [String] Name INDEX data
+      # @param string_index_data [String] String INDEX data
+      # @param global_subr_index_data [String] Global Subr INDEX data
+      # @param charstrings_index_data [String] CharStrings INDEX data
+      # @param private_dict_size [Integer] Private DICT size
+      # @return [Array<String, Integer, Integer>] [Top DICT INDEX, CharStrings offset, Private DICT offset]
+      def calculate_cff_offsets(
+        header_size,
+        name_index_data,
+        string_index_data,
+        global_subr_index_data,
+        charstrings_index_data,
+        private_dict_size
+      )
+        # Initial pass
+        top_dict_index_start = header_size + name_index_data.bytesize
+        string_index_start = top_dict_index_start + 100 # Approximate
+        global_subr_index_start = string_index_start + string_index_data.bytesize
+        charstrings_offset = global_subr_index_start + global_subr_index_data.bytesize
+
+        # Build Top DICT
+        top_dict_hash = {
+          charset: 0,
+          encoding: 0,
+          charstrings: charstrings_offset,
+        }
+        top_dict_data = Tables::Cff::DictBuilder.build(top_dict_hash)
+        top_dict_index_data = Tables::Cff::IndexBuilder.build([top_dict_data])
+
+        # Recalculate with actual Top DICT size
+        string_index_start = top_dict_index_start + top_dict_index_data.bytesize
+        global_subr_index_start = string_index_start + string_index_data.bytesize
+        charstrings_offset = global_subr_index_start + global_subr_index_data.bytesize
+        private_dict_offset = charstrings_offset + charstrings_index_data.bytesize
+
+        # Update Top DICT with Private DICT info
+        top_dict_hash = {
+          charset: 0,
+          encoding: 0,
+          charstrings: charstrings_offset,
+          private: [private_dict_size, private_dict_offset],
+        }
+        top_dict_data = Tables::Cff::DictBuilder.build(top_dict_hash)
+        top_dict_index_data = Tables::Cff::IndexBuilder.build([top_dict_data])
+
+        # Final recalculation
+        string_index_start = top_dict_index_start + top_dict_index_data.bytesize
+        global_subr_index_start = string_index_start + string_index_data.bytesize
+        charstrings_offset = global_subr_index_start + global_subr_index_data.bytesize
+        private_dict_offset = charstrings_offset + charstrings_index_data.bytesize
+
+        # Final Top DICT
+        top_dict_hash = {
+          charset: 0,
+          encoding: 0,
+          charstrings: charstrings_offset,
+          private: [private_dict_size, private_dict_offset],
+        }
+        top_dict_data = Tables::Cff::DictBuilder.build(top_dict_hash)
+        top_dict_index_data = Tables::Cff::IndexBuilder.build([top_dict_data])
+
+        [top_dict_index_data, charstrings_offset, private_dict_offset]
+      end
+
+      # Build CFF Header
+      #
+      # @return [String] 4-byte CFF header
+      def build_cff_header
+        [
+          1,    # major version
+          0,    # minor version
+          4,    # header size
+          4,    # offSize (will be in INDEX)
+        ].pack("C4")
+      end
+
+      # Extract font name from name table
+      #
+      # @param font [TrueTypeFont, OpenTypeFont] Font
+      # @return [String] Font name
+      def extract_font_name(font)
+        name_table = font.table("name")
+        if name_table
+          font_name = name_table.english_name(Tables::Name::FAMILY)
+          return font_name.dup.force_encoding("ASCII-8BIT") if font_name
+        end
+
+        "UnnamedFont"
+      end
+    end
+  end
+end

data/lib/fontisan/converters/collection_converter.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "../conversion_options"
 require_relative "format_converter"
 require_relative "../collection/builder"
 require_relative "../collection/dfont_builder"
@@ -27,14 +28,15 @@ module Fontisan
     #   converter = CollectionConverter.new
     #   result = converter.convert(ttc_path, target_type: :otc, output: 'family.otc')
     #
-    # @example Convert TTC to OTC with outline conversion
+    # @example Convert with ConversionOptions
+    #   options = ConversionOptions.recommended(from: :ttc, to: :otc)
     #   converter = CollectionConverter.new
-    #   result = converter.convert(ttc_path, target_type: :otc,
-    #                              options: { output: 'family.otc', convert_outlines: true })
+    #   result = converter.convert(ttc_path, target_type: :otc, options: { output: 'family.otc', options: options })
     #
-    # @example Convert dfont to TTC
+    # @example Convert TTC to OTC with outline conversion
     #   converter = CollectionConverter.new
-    #   result = converter.convert(dfont_path, target_type: :ttc, output: 'family.ttc')
+    #   result = converter.convert(ttc_path, target_type: :otc,
+    #                              options: { output: 'family.otc', target_format: 'otf' })
     class CollectionConverter
       # Convert collection to target format
       #
@@ -45,6 +47,7 @@ module Fontisan
       # @option options [String] :target_format Target outline format: 'preserve' (default), 'ttf', or 'otf'
       # @option options [Boolean] :optimize Enable table sharing (default: true, TTC/OTC only)
       # @option options [Boolean] :verbose Enable verbose output (default: false)
+      # @option options [ConversionOptions] :options ConversionOptions object
       # @return [Hash] Conversion result with:
       #   - :input [String] - Input collection path
       #   - :output [String] - Output collection path
@@ -57,9 +60,19 @@ module Fontisan
       def convert(collection_path, target_type:, options: {})
         validate_parameters!(collection_path, target_type, options)
 
+        # Extract ConversionOptions if provided
+        conv_options = extract_conversion_options(options)
+
         verbose = options.fetch(:verbose, false)
         output_path = options[:output]
-        target_format = options.fetch(:target_format, "preserve").to_s
+
+        # Determine target format from ConversionOptions or options hash
+        target_format = if conv_options&.generating_option?(:target_format,
+                                                            "otf")
+                          conv_options.generating[:target_format]
+                        else
+                          options.fetch(:target_format, "preserve").to_s
+                        end
 
         # Validate target_format
         unless %w[preserve ttf otf].include?(target_format)
@@ -84,7 +97,8 @@ module Fontisan
         # Step 2: Convert - transform fonts if requested
         puts "  Converting #{fonts.size} font(s)..." if verbose
         converted_fonts, conversions = convert_fonts(fonts, source_type,
-                                                     target_type, options.merge(target_format: target_format))
+                                                     target_type, options.merge(target_format: target_format),
+                                                     conv_options)
 
         # Step 3: Repack - build target collection
         puts "  Repacking into #{target_type.to_s.upcase} format..." if verbose
@@ -206,13 +220,20 @@ module Fontisan
       # @param source_type [Symbol] Source collection type
       # @param target_type [Symbol] Target collection type
       # @param options [Hash] Conversion options
+      # @param conv_options [ConversionOptions, nil] Conversion options object
       # @return [Array<(Array<Font>, Array<Hash>)>] [converted_fonts, conversions]
-      def convert_fonts(fonts, _source_type, target_type, options)
+      def convert_fonts(fonts, _source_type, target_type, options,
+conv_options = nil)
         converted_fonts = []
         conversions = []
 
         # Determine if outline conversion is needed
-        target_format = options.fetch(:target_format, "preserve").to_s
+        target_format = if conv_options&.generating_option?(:target_format,
+                                                            "otf")
+                          conv_options.generating[:target_format]
+                        else
+                          options.fetch(:target_format, "preserve").to_s
+                        end
 
         fonts.each_with_index do |font, index|
           source_format = detect_font_format(font)
@@ -224,8 +245,12 @@ module Fontisan
             desired_format = target_format == "preserve" ? source_format : target_format.to_sym
             converter = FormatConverter.new
 
+            # Build converter options, including ConversionOptions if provided
+            converter_opts = options.dup
+            converter_opts[:options] = conv_options if conv_options
+
             begin
-              tables = converter.convert(font, desired_format, options)
+              tables = converter.convert(font, desired_format, converter_opts)
               converted_font = build_font_from_tables(tables, desired_format)
               converted_fonts << converted_font
 
@@ -442,6 +467,16 @@ conversions)
 
         puts ""
       end
+
+      # Extract ConversionOptions from options hash
+      #
+      # @param options [Hash, ConversionOptions] Options or hash containing :options key
+      # @return [ConversionOptions, nil] Extracted ConversionOptions or nil
+      def extract_conversion_options(options)
+        return options if options.is_a?(ConversionOptions)
+
+        options[:options] if options.is_a?(Hash)
+      end
     end
   end
 end