fontisan 0.2.2 → 0.2.3

data/lib/fontisan/font_loader.rb

@@ -102,6 +102,37 @@ module Fontisan
     # without extracting individual fonts. Useful for inspecting collection
     # metadata and structure.
     #
+    # = Collection Format Understanding
+    #
+    # Both TTC (TrueType Collection) and OTC (OpenType Collection) files use
+    # the same "ttcf" signature. The distinction between TTC and OTC is NOT
+    # in the collection format itself, but in the fonts contained within:
+    #
+    # - TTC typically contains TrueType fonts (glyf outlines)
+    # - OTC typically contains OpenType fonts (CFF/CFF2 outlines)
+    # - Mixed collections are possible (both TTF and OTF in same collection)
+    #
+    # Each collection can contain multiple SFNT-format font files, with table
+    # deduplication to save space. Individual fonts within a collection are
+    # stored at different offsets within the file, each with their own table
+    # directory and data tables.
+    #
+    # = Detection Strategy
+    #
+    # This method scans ALL fonts in the collection to determine the collection
+    # type accurately:
+    #
+    # 1. Reads all font offsets from the collection header
+    # 2. Examines the sfnt_version of each font in the collection
+    # 3. Counts TrueType fonts (0x00010000 or 0x74727565 "true") vs OpenType fonts (0x4F54544F "OTTO")
+    # 4. If ANY font is OpenType (CFF), returns OpenTypeCollection
+    # 5. Only returns TrueTypeCollection if ALL fonts are TrueType
+    #
+    # This approach correctly handles:
+    # - Homogeneous collections (all TTF or all OTF)
+    # - Mixed collections (both TTF and OTF fonts) - uses OpenTypeCollection
+    # - Large collections with many fonts (like NotoSerifCJK.ttc with 35 fonts)
+    #
     # @param path [String] Path to the collection file
     # @return [TrueTypeCollection, OpenTypeCollection] The collection object
     # @raise [Errno::ENOENT] if file does not exist
@@ -121,23 +152,43 @@ module Fontisan
                 "File is not a collection (TTC/OTC). Use FontLoader.load instead."
         end
 
-        # Read first font offset to detect collection type
-        io.seek(12) # Skip tag (4) + versions (4) + num_fonts (4)
-        first_offset = io.read(4).unpack1("N")
+        # Read version and num_fonts
+        io.seek(8) # Skip tag (4) + version (4)
+        num_fonts = io.read(4).unpack1("N")
+
+        # Read all font offsets
+        font_offsets = num_fonts.times.map { io.read(4).unpack1("N") }
+
+        # Scan all fonts to determine collection type (not just first)
+        truetype_count = 0
+        opentype_count = 0
+
+        font_offsets.each do |offset|
+          io.rewind
+          io.seek(offset)
+          sfnt_version = io.read(4).unpack1("N")
+
+          case sfnt_version
+          when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
+            truetype_count += 1
+          when Constants::SFNT_VERSION_OTTO
+            opentype_count += 1
+          else
+            raise InvalidFontError,
+                  "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
+          end
+        end
 
-        # Peek at first font's sfnt_version
-        io.seek(first_offset)
-        sfnt_version = io.read(4).unpack1("N")
         io.rewind
 
-        case sfnt_version
-        when Constants::SFNT_VERSION_TRUETYPE
-          TrueTypeCollection.from_file(path)
-        when Constants::SFNT_VERSION_OTTO
+        # Determine collection type based on what fonts are inside
+        # If ANY font is OpenType, use OpenTypeCollection (more general format)
+        # Only use TrueTypeCollection if ALL fonts are TrueType
+        if opentype_count > 0
           OpenTypeCollection.from_file(path)
         else
-          raise InvalidFontError,
-                "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+          # All fonts are TrueType
+          TrueTypeCollection.from_file(path)
         end
       end
     end
@@ -167,6 +218,23 @@ module Fontisan
 
     # Load from a collection file (TTC or OTC)
     #
+    # This is the internal method that handles loading individual fonts from
+    # collection files. It reads the collection header to determine the type
+    # (TTC vs OTC) and extracts the requested font.
+    #
+    # = Collection Header Structure
+    #
+    # TTC/OTC files start with:
+    # - Bytes 0-3: "ttcf" tag (4 bytes)
+    # - Bytes 4-7: version (2 bytes major + 2 bytes minor)
+    # - Bytes 8-11: num_fonts (4 bytes, big-endian uint32)
+    # - Bytes 12+: font offset array (4 bytes per font, big-endian uint32)
+    #
+    # CRITICAL: The method seeks to position 8 (after tag and version) to read
+    # num_fonts, NOT position 12 which is where the offset array starts. This
+    # was a bug that caused "Unknown font type" errors when the first offset
+    # was misread as num_fonts.
+    #
     # @param io [IO] Open file handle
     # @param path [String] Path to the collection file
     # @param font_index [Integer] Index of font to extract
@@ -177,7 +245,7 @@ module Fontisan
     def self.load_from_collection(io, path, font_index,
 mode: LoadingModes::FULL, lazy: true)
       # Read collection header to get font offsets
-      io.seek(12) # Skip tag (4) + major_version (2) + minor_version (2) + num_fonts marker (4)
+      io.seek(8) # Skip tag (4) + version (4)
       num_fonts = io.read(4).unpack1("N")
 
       if font_index >= num_fonts
@@ -185,26 +253,41 @@ mode: LoadingModes::FULL, lazy: true)
               "Font index #{font_index} out of range (collection has #{num_fonts} fonts)"
       end
 
-      # Read first offset to detect collection type
-      first_offset = io.read(4).unpack1("N")
+      # Read all font offsets
+      font_offsets = num_fonts.times.map { io.read(4).unpack1("N") }
+
+      # Scan all fonts to determine collection type (not just first)
+      truetype_count = 0
+      opentype_count = 0
+
+      font_offsets.each do |offset|
+        io.rewind
+        io.seek(offset)
+        sfnt_version = io.read(4).unpack1("N")
+
+        case sfnt_version
+        when Constants::SFNT_VERSION_TRUETYPE, 0x74727565 # 0x74727565 = 'true'
+          truetype_count += 1
+        when Constants::SFNT_VERSION_OTTO
+          opentype_count += 1
+        else
+          raise InvalidFontError,
+                "Unknown font type in collection at offset #{offset} (sfnt version: 0x#{sfnt_version.to_s(16)})"
+        end
+      end
 
-      # Peek at first font's sfnt_version to determine TTC vs OTC
-      io.seek(first_offset)
-      sfnt_version = io.read(4).unpack1("N")
       io.rewind
 
-      case sfnt_version
-      when Constants::SFNT_VERSION_TRUETYPE
-        # TrueType Collection
-        ttc = TrueTypeCollection.from_file(path)
-        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
-      when Constants::SFNT_VERSION_OTTO
+      # If ANY font is OpenType, use OpenTypeCollection (more general format)
+      # Only use TrueTypeCollection if ALL fonts are TrueType
+      if opentype_count > 0
         # OpenType Collection
         otc = OpenTypeCollection.from_file(path)
         File.open(path, "rb") { |f| otc.font(font_index, f, mode: mode) }
       else
-        raise InvalidFontError,
-              "Unknown font type in collection (sfnt version: 0x#{sfnt_version.to_s(16)})"
+        # TrueType Collection (all fonts are TrueType)
+        ttc = TrueTypeCollection.from_file(path)
+        File.open(path, "rb") { |f| ttc.font(font_index, f, mode: mode) }
       end
     end
 

data/lib/fontisan/formatters/text_formatter.rb

@@ -364,20 +364,36 @@ module Fontisan
       def format_collection_info(info)
         lines = []
 
-        # Header section
-        lines << "=== Collection Information ==="
-        lines << ""
-        lines << "File: #{info.collection_path}"
-        lines << "Format: #{info.collection_format}"
+        # Header section with type and version (like brief mode)
+        lines << "Collection: #{info.collection_path}"
+
+        # Format collection type for display with OpenType version
+        if info.collection_format
+          collection_type_display = case info.collection_format
+                                    when "TTC"
+                                      "TrueType Collection (OpenType 1.4)"
+                                    when "OTC"
+                                      "OpenType Collection (OpenType 1.8)"
+                                    else
+                                      info.collection_format
+                                    end
+          lines << "Type: #{collection_type_display}"
+        end
+
+        lines << "Version: #{info.version_string}"
         lines << "Size: #{format_bytes(info.file_size_bytes)}"
+        lines << "Fonts: #{info.num_fonts}"
         lines << ""
 
-        # Header details
-        lines << "=== Header ==="
-        lines << "Tag: #{info.ttc_tag}"
-        lines << "Version: #{info.version_string} (#{info.version_hex})"
-        lines << "Number of fonts: #{info.num_fonts}"
-        lines << ""
+        # Table sharing statistics
+        if info.table_sharing
+          lines << "=== Table Sharing ==="
+          lines << "Shared tables: #{info.table_sharing.shared_tables}"
+          lines << "Unique tables: #{info.table_sharing.unique_tables}"
+          lines << "Sharing: #{format_float(info.table_sharing.sharing_percentage)}%"
+          lines << "Space saved: #{format_bytes(info.table_sharing.space_saved_bytes)}"
+          lines << ""
+        end
 
         # Font offsets
         lines << "=== Font Offsets ==="
@@ -387,13 +403,35 @@ module Fontisan
         end
         lines << ""
 
-        # Table sharing statistics
-        if info.table_sharing
-          lines << "=== Table Sharing ==="
-          lines << "Shared tables: #{info.table_sharing.shared_tables}"
-          lines << "Unique tables: #{info.table_sharing.unique_tables}"
-          lines << "Sharing: #{format_float(info.table_sharing.sharing_percentage)}%"
-          lines << "Space saved: #{format_bytes(info.table_sharing.space_saved_bytes)}"
+        # Individual font information (like brief mode)
+        if info.fonts && !info.fonts.empty?
+          lines << "=== Fonts ==="
+          lines << ""
+
+          info.fonts.each_with_index do |font_info, index|
+            # Show font index with offset
+            if font_info.collection_offset
+              lines << "Font #{index} (offset: #{font_info.collection_offset}):"
+            else
+              lines << "Font #{index}:"
+            end
+            lines << ""
+
+            # Format each font using same structure as brief mode
+            font_type_display = format_font_type_display(font_info.font_format, font_info.is_variable)
+            add_line(lines, "Font type", font_type_display)
+            add_line(lines, "Family", font_info.family_name)
+            add_line(lines, "Subfamily", font_info.subfamily_name)
+            add_line(lines, "Full name", font_info.full_name)
+            add_line(lines, "PostScript name", font_info.postscript_name)
+            add_line(lines, "Version", font_info.version)
+            add_line(lines, "Vendor ID", font_info.vendor_id)
+            add_line(lines, "Font revision", format_float(font_info.font_revision))
+            add_line(lines, "Units per em", font_info.units_per_em)
+
+            # Blank line between fonts (except after last)
+            lines << "" unless index == info.num_fonts - 1
+          end
         end
 
         lines.join("\n")
@@ -406,8 +444,23 @@ module Fontisan
       def format_collection_brief_info(info)
         lines = []
 
-        # Collection header
+        # Collection header with type and version
         lines << "Collection: #{info.collection_path}"
+
+        # Format collection type for display with OpenType version
+        if info.collection_type
+          collection_type_display = case info.collection_type
+                                    when "TTC"
+                                      "TrueType Collection (OpenType 1.4)"
+                                    when "OTC"
+                                      "OpenType Collection (OpenType 1.8)"
+                                    else
+                                      info.collection_type
+                                    end
+          lines << "Type: #{collection_type_display}"
+        end
+
+        lines << "Version: #{info.collection_version}" if info.collection_version
         lines << "Fonts: #{info.num_fonts}"
         lines << ""
 

data/lib/fontisan/models/collection_brief_info.rb

@@ -13,16 +13,22 @@ module Fontisan
     # @example Creating collection brief info
     #   info = CollectionBriefInfo.new(
     #     collection_path: "fonts.ttc",
+    #     collection_type: "TTC",
+    #     collection_version: "1.0",
     #     num_fonts: 3,
     #     fonts: [font_info1, font_info2, font_info3]
     #   )
     class CollectionBriefInfo < Lutaml::Model::Serializable
       attribute :collection_path, :string
+      attribute :collection_type, :string
+      attribute :collection_version, :string
       attribute :num_fonts, :integer
       attribute :fonts, FontInfo, collection: true
 
       key_value do
         map "collection_path", to: :collection_path
+        map "collection_type", to: :collection_type
+        map "collection_version", to: :collection_version
         map "num_fonts", to: :num_fonts
         map "fonts", to: :fonts
       end

data/lib/fontisan/models/collection_info.rb

@@ -2,6 +2,7 @@
 
 require "lutaml/model"
 require_relative "table_sharing_info"
+require_relative "font_info"
 
 module Fontisan
   module Models
@@ -20,7 +21,8 @@ module Fontisan
     #     num_fonts: 6,
     #     font_offsets: [48, 380, 712, 1044, 1376, 1676],
     #     file_size_bytes: 2240000,
-    #     table_sharing: table_sharing_obj
+    #     table_sharing: table_sharing_obj,
+    #     fonts: [font_info1, font_info2, ...]
     #   )
     class CollectionInfo < Lutaml::Model::Serializable
       attribute :collection_path, :string
@@ -32,6 +34,7 @@ module Fontisan
       attribute :font_offsets, :integer, collection: true
       attribute :file_size_bytes, :integer
       attribute :table_sharing, TableSharingInfo
+      attribute :fonts, FontInfo, collection: true
 
       yaml do
         map "collection_path", to: :collection_path
@@ -43,6 +46,7 @@ module Fontisan
         map "font_offsets", to: :font_offsets
         map "file_size_bytes", to: :file_size_bytes
         map "table_sharing", to: :table_sharing
+        map "fonts", to: :fonts
       end
 
       json do
@@ -55,6 +59,7 @@ module Fontisan
         map "font_offsets", to: :font_offsets
         map "file_size_bytes", to: :file_size_bytes
         map "table_sharing", to: :table_sharing
+        map "fonts", to: :fonts
       end
 
       # Get version as a formatted string

data/lib/fontisan/open_type_collection.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
-require "bindata"
-require_relative "constants"
+require_relative "base_collection"
 
 module Fontisan
-  # OpenType Collection domain object using BinData
+  # OpenType Collection domain object
   #
-  # Represents a complete OpenType Collection file (OTC) using BinData's declarative
-  # DSL for binary structure definition. Parallel to TrueTypeCollection but for OpenType fonts.
+  # Represents a complete OpenType Collection file (OTC). Inherits all shared
+  # functionality from BaseCollection and implements OTC-specific behavior.
   #
   # @example Reading and extracting fonts
   #   File.open("fonts.otc", "rb") do |io|
@@ -15,39 +14,26 @@ module Fontisan
   #     puts otc.num_fonts  # => 4
   #     fonts = otc.extract_fonts(io)  # => [OpenTypeFont, OpenTypeFont, ...]
   #   end
-  class OpenTypeCollection < BinData::Record
-    endian :big
-
-    string :tag, length: 4, assert: "ttcf"
-    uint16 :major_version
-    uint16 :minor_version
-    uint32 :num_fonts
-    array :font_offsets, type: :uint32, initial_length: :num_fonts
-
-    # Read OpenType Collection from a file
+  class OpenTypeCollection < BaseCollection
+    # Get the font class for OpenType collections
     #
-    # @param path [String] Path to the OTC file
-    # @return [OpenTypeCollection] A new instance
-    # @raise [ArgumentError] if path is nil or empty
-    # @raise [Errno::ENOENT] if file does not exist
-    # @raise [RuntimeError] if file format is invalid
-    def self.from_file(path)
-      if path.nil? || path.to_s.empty?
-        raise ArgumentError,
-              "path cannot be nil or empty"
-      end
-      raise Errno::ENOENT, "File not found: #{path}" unless File.exist?(path)
+    # @return [Class] OpenTypeFont class
+    def self.font_class
+      require_relative "open_type_font"
+      OpenTypeFont
+    end
 
-      File.open(path, "rb") { |io| read(io) }
-    rescue BinData::ValidityError => e
-      raise "Invalid OTC file: #{e.message}"
-    rescue EOFError => e
-      raise "Invalid OTC file: unexpected end of file - #{e.message}"
+    # Get the collection format identifier
+    #
+    # @return [String] "OTC" for OpenType Collection
+    def self.collection_format
+      "OTC"
     end
 
     # Extract fonts as OpenTypeFont objects
     #
     # Reads each font from the OTC file and returns them as OpenTypeFont objects.
+    # This method uses the from_collection method.
     #
     # @param io [IO] Open file handle to read fonts from
     # @return [Array<OpenTypeFont>] Array of font objects
@@ -58,194 +44,5 @@ module Fontisan
         OpenTypeFont.from_collection(io, offset)
       end
     end
-
-    # Get a single font from the collection
-    #
-    # @param index [Integer] Index of the font (0-based)
-    # @param io [IO] Open file handle
-    # @param mode [Symbol] Loading mode (:metadata or :full, default: :full)
-    # @return [OpenTypeFont, nil] Font object or nil if index out of range
-    def font(index, io, mode: LoadingModes::FULL)
-      return nil if index >= num_fonts
-
-      require_relative "open_type_font"
-      OpenTypeFont.from_collection(io, font_offsets[index], mode: mode)
-    end
-
-    # Get font count
-    #
-    # @return [Integer] Number of fonts in collection
-    def font_count
-      num_fonts
-    end
-
-    # Validate format correctness
-    #
-    # @return [Boolean] true if the format is valid, false otherwise
-    def valid?
-      tag == Constants::TTC_TAG && num_fonts.positive? && font_offsets.length == num_fonts
-    rescue StandardError
-      false
-    end
-
-    # Get the OTC version as a single integer
-    #
-    # @return [Integer] Version number (e.g., 0x00010000 for version 1.0)
-    def version
-      (major_version << 16) | minor_version
-    end
-
-    # List all fonts in the collection with basic metadata
-    #
-    # Returns a CollectionListInfo model containing summaries of all fonts.
-    # This is the API method used by the `ls` command for collections.
-    #
-    # @param io [IO] Open file handle to read fonts from
-    # @return [CollectionListInfo] List of fonts with metadata
-    #
-    # @example List fonts in collection
-    #   File.open("fonts.otc", "rb") do |io|
-    #     otc = OpenTypeCollection.read(io)
-    #     list = otc.list_fonts(io)
-    #     list.fonts.each { |f| puts "#{f.index}: #{f.family_name}" }
-    #   end
-    def list_fonts(io)
-      require_relative "models/collection_list_info"
-      require_relative "models/collection_font_summary"
-      require_relative "open_type_font"
-      require_relative "tables/name"
-
-      fonts = font_offsets.map.with_index do |offset, index|
-        font = OpenTypeFont.from_collection(io, offset)
-
-        # Extract basic font info
-        name_table = font.table("name")
-        post_table = font.table("post")
-
-        family_name = name_table&.english_name(Tables::Name::FAMILY) || "Unknown"
-        subfamily_name = name_table&.english_name(Tables::Name::SUBFAMILY) || "Regular"
-        postscript_name = name_table&.english_name(Tables::Name::POSTSCRIPT_NAME) || "Unknown"
-
-        # Determine font format
-        sfnt = font.header.sfnt_version
-        font_format = case sfnt
-                      when 0x00010000, 0x74727565 # 0x74727565 = 'true'
-                        "TrueType"
-                      when 0x4F54544F # 'OTTO'
-                        "OpenType"
-                      else
-                        "Unknown"
-                      end
-
-        num_glyphs = post_table&.glyph_names&.length || 0
-        num_tables = font.table_names.length
-
-        Models::CollectionFontSummary.new(
-          index: index,
-          family_name: family_name,
-          subfamily_name: subfamily_name,
-          postscript_name: postscript_name,
-          font_format: font_format,
-          num_glyphs: num_glyphs,
-          num_tables: num_tables,
-        )
-      end
-
-      Models::CollectionListInfo.new(
-        collection_path: nil, # Will be set by command
-        num_fonts: num_fonts,
-        fonts: fonts,
-      )
-    end
-
-    # Get comprehensive collection metadata
-    #
-    # Returns a CollectionInfo model with header information, offsets,
-    # and table sharing statistics.
-    # This is the API method used by the `info` command for collections.
-    #
-    # @param io [IO] Open file handle to read fonts from
-    # @param path [String] Collection file path (for file size)
-    # @return [CollectionInfo] Collection metadata
-    #
-    # @example Get collection info
-    #   File.open("fonts.otc", "rb") do |io|
-    #     otc = OpenTypeCollection.read(io)
-    #     info = otc.collection_info(io, "fonts.otc")
-    #     puts "Version: #{info.version_string}"
-    #   end
-    def collection_info(io, path)
-      require_relative "models/collection_info"
-      require_relative "models/table_sharing_info"
-
-      # Calculate table sharing statistics
-      table_sharing = calculate_table_sharing(io)
-
-      # Get file size
-      file_size = path ? File.size(path) : 0
-
-      Models::CollectionInfo.new(
-        collection_path: path,
-        collection_format: "OTC",
-        ttc_tag: tag,
-        major_version: major_version,
-        minor_version: minor_version,
-        num_fonts: num_fonts,
-        font_offsets: font_offsets.to_a,
-        file_size_bytes: file_size,
-        table_sharing: table_sharing,
-      )
-    end
-
-    private
-
-    # Calculate table sharing statistics
-    #
-    # Analyzes which tables are shared between fonts and calculates
-    # space savings from deduplication.
-    #
-    # @param io [IO] Open file handle
-    # @return [TableSharingInfo] Sharing statistics
-    def calculate_table_sharing(io)
-      require_relative "models/table_sharing_info"
-      require_relative "open_type_font"
-
-      # Extract all fonts
-      fonts = font_offsets.map do |offset|
-        OpenTypeFont.from_collection(io, offset)
-      end
-
-      # Build table hash map (checksum -> size)
-      table_map = {}
-      total_table_size = 0
-
-      fonts.each do |font|
-        font.tables.each do |entry|
-          key = entry.checksum
-          size = entry.table_length
-          table_map[key] ||= size
-          total_table_size += size
-        end
-      end
-
-      # Count unique vs shared
-      unique_tables = table_map.size
-      total_tables = fonts.sum { |f| f.tables.length }
-      shared_tables = total_tables - unique_tables
-
-      # Calculate space saved
-      unique_size = table_map.values.sum
-      space_saved = total_table_size - unique_size
-
-      # Calculate sharing percentage
-      sharing_pct = total_tables.positive? ? (shared_tables.to_f / total_tables * 100).round(2) : 0.0
-
-      Models::TableSharingInfo.new(
-        shared_tables: shared_tables,
-        unique_tables: unique_tables,
-        sharing_percentage: sharing_pct,
-        space_saved_bytes: space_saved,
-      )
-    end
   end
 end