fontisan 0.2.2 → 0.2.4

data/README.adoc

@@ -1043,6 +1043,37 @@ Fontisan provides comprehensive tools for managing TrueType Collections (TTC)
 and OpenType Collections (OTC). You can list fonts in a collection, extract
 individual fonts, unpack entire collections, and validate collection integrity.
 
+Both TTC and OTC files use the same `ttcf` tag in their binary format, but
+differ in the type of font data they contain:
+
+TTC (TrueType Collection):: Supported since OpenType 1.4. Contains fonts with
+TrueType outlines (glyf table). Multiple fonts can share identical tables for
+efficient storage. File extension: `.ttc`
+
+OTC (OpenType Collection):: Supported since OpenType 1.8. Contains fonts with
+CFF-format outlines (CFF table). Provides the same storage benefits and
+glyph-count advantages as TTC but for CFF fonts. File extension: `.otc`
+
+The collection format allows:
+
+Table sharing::
+Identical tables are stored once and referenced by multiple fonts
+
+Gap mode::
+Overcomes the 65,535 glyph limit per font by distributing glyphs across multiple
+fonts in a single file
+
+Efficient storage::
+Significant size reduction, especially for CJK fonts (e.g., Noto CJK OTC is ~10
+MB smaller than separate OTF files)
+
+Fontist returns the appropriate collection type based on the font data:
+
+* Examines font data within collection to determine type (TTC vs OTC)
+* TTC contains fonts with TrueType outlines (glyf table)
+* OTC contains fonts with CFF outlines (CFF table)
+* If ANY font in the collection has CFF outlines, use OpenTypeCollection
+* Only use TrueTypeCollection if ALL fonts have TrueType outlines
 
 === List fonts
 
@@ -1269,6 +1300,173 @@ $ fontisan validate FONT.{ttc,otc}
 NOTE: In `extract_ttc`, this was done with `extract_ttc --validate FONT.ttc`.
 
 
+
+
+== Color font support
+
+=== General
+
+Fontisan provides comprehensive analysis of all color font formats defined in the OpenType specification.
+
+=== Supported color font formats
+
+Fontisan supports all four color font table formats:
+
+COLR/CPAL:: Layered color glyphs with custom color palettes (Microsoft/Google standard)
+
+SVG:: Embedded SVG graphics with gzip compression support (W3C standard)
+
+CBDT/CBLC:: Bitmap glyphs at multiple ppem sizes (Google format)
+
+sbix:: Bitmap graphics with PNG/JPEG/TIFF support (Apple format)
+
+=== Analyzing color fonts
+
+[source,ruby]
+----
+require 'fontisan'
+
+# Load and analyze a color font
+info = Fontisan.info('emoji-font.ttf')
+
+# Color glyph detection
+puts info.is_color_font       # true if COLR/CPAL present
+puts info.has_svg_table        # true if SVG table present
+puts info.has_bitmap_glyphs    # true if CBDT/CBLC or sbix present
+
+# Get color palette information (COLR/CPAL)
+if info.is_color_font
+  puts "Color glyphs: #{info.color_glyphs}"
+  puts "Color palettes: #{info.color_palettes}"
+  puts "Colors per palette: #{info.colors_per_palette}"
+end
+
+# Get SVG glyph information
+if info.has_svg_table
+  puts "SVG glyphs: #{info.svg_glyph_count}"
+end
+
+# Get bitmap information
+if info.has_bitmap_glyphs
+  puts "Bitmap formats: #{info.bitmap_formats.join(', ')}"
+  puts "Available sizes (ppem): #{info.bitmap_ppem_sizes.join(', ')}"
+
+  info.bitmap_strikes.each do |strike|
+    puts "Strike at #{strike.ppem}ppem:"
+    puts "  - Glyphs: #{strike.num_glyphs}"
+    puts "  - Color depth: #{strike.color_depth}"
+  end
+end
+----
+
+=== Color font table access
+
+Access color font tables directly:
+
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('emoji-font.ttf')
+
+# Access COLR table (layered color)
+if font.has_table?('COLR')
+  colr = font.table('COLR')
+  puts "Color glyphs: #{colr.num_color_glyphs}"
+
+  # Get color layers for a glyph
+  layers = colr.layers_for_glyph(42)
+  layers.each do |layer|
+    puts "Layer glyph: #{layer.glyph_id}, Palette index: #{layer.palette_index}"
+  end
+end
+
+# Access CPAL table (color palettes)
+if font.has_table?('CPAL')
+  cpal = font.table('CPAL')
+
+  # Get colors from first palette
+  palette = cpal.palette(0)
+  palette.each_with_index do |color, i|
+    puts "Color #{i}: R=#{color.red} G=#{color.green} B=#{color.blue} A=#{color.alpha}"
+  end
+end
+
+# Access SVG table
+if font.has_table?('SVG ')
+  svg = font.table('SVG ')
+
+  # Get SVG document for glyph 100
+  svg_doc = svg.svg_document_for_glyph(100)
+  puts "Compressed: #{svg_doc.compressed?}"
+  puts "SVG data: #{svg_doc.svg_data}"
+end
+
+# Access bitmap tables
+if font.has_table?('CBLC')
+  cblc = font.table('CBLC')
+  puts "Available ppem sizes: #{cblc.ppem_sizes.join(', ')}"
+
+  # Check if glyph 50 has bitmap at 64ppem
+  if cblc.has_bitmap_for_glyph?(50, 64)
+    puts "Glyph 50 has bitmap at 64ppem"
+  end
+end
+
+if font.has_table?('sbix')
+  sbix = font.table('sbix')
+
+  # Get bitmap data for glyph 42 at 128ppem
+  glyph_data = sbix.glyph_data(42, 128)
+  if glyph_data
+    puts "Format: #{glyph_data[:graphic_type_name]}"
+    puts "Origin: (#{glyph_data[:origin_x]}, #{glyph_data[:origin_y]})"
+    puts "Data size: #{glyph_data[:data].length} bytes"
+  end
+end
+----
+
+=== Output formats
+
+Color font information can be serialized to multiple formats:
+
+[source,ruby]
+----
+info = Fontisan.info('emoji-font.ttf')
+
+# YAML output
+puts info.to_yaml
+
+# JSON output
+puts info.to_json
+
+# XML output
+puts info.to_xml
+----
+
+Example YAML output:
+
+[source,yaml]
+----
+font_format: truetype
+family_name: "Emoji Font"
+is_color_font: true
+color_glyphs: 872
+color_palettes: 1
+colors_per_palette: 256
+has_svg_table: true
+svg_glyph_count: 872
+has_bitmap_glyphs: true
+bitmap_ppem_sizes: [16, 32, 64, 128, 256]
+bitmap_formats: ["PNG"]
+bitmap_strikes:
+  - ppem: 128
+    start_glyph_id: 1
+    end_glyph_id: 872
+    bit_depth: 32
+    num_glyphs: 872
+    color_depth: "32-bit (full color with alpha)"
+----
+
+
 == Advanced features
 
 Fontisan provides capabilities:
@@ -1358,6 +1556,9 @@ The loading mode can be queried at any time.
 
 [source,ruby]
 ----
+# Check laziness
+font.lazy?                  # => true
+
 # Mode stored as font property
 font.loading_mode  # => :metadata or :full
 
@@ -1366,6 +1567,12 @@ font.table_available?(tag)  # => boolean
 
 # Access restricted based on mode
 font.table(tag)  # => Returns table or raises error
+
+# Test lazy loading with an expensive operation
+glyphs = [] if font.subset_glyphs(lazy: true) { glyphs = font.subset_glyphs }
+glyphs.count                # => Tests whether glyphs were already loaded
+font.table_available?("head") # => true (lazy loading enabled)
+font.table_available?("GSUB") # => false (lazy loading enabled)
 ----
 
 
@@ -1399,7 +1606,7 @@ fields:
 `family_name`:: Font family name (nameID 1)
 `subfamily_name`:: Font subfamily/style name (nameID 2)
 `full_name`:: Full font name (nameID 4)
-`post_script_name`:: PostScript name (nameID 6)
+`postscript_name`:: PostScript name (nameID 6)
 `preferred_family_name`:: Preferred family name (nameID 16, may be nil)
 `preferred_subfamily_name`:: Preferred subfamily name (nameID 17, may be nil)
 `units_per_em`:: Units per em from head table
@@ -1453,6 +1660,64 @@ font = Fontisan::FontLoader.load('font.ttf', mode: :full, lazy: false)
 ----
 
 
+=== Table preparedness
+
+Every table uses preparedness to avoid lazy initialization overhead. Function
+`table_available?` was added to check if table prepared for access.
+
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Check preparedness
+font.table_available?("head")     # => true
+font.table_available?("GSUB")     # => true
+font.table_available?("GPOS")     # => true
+
+# Force loading of a table
+head = font.table("head")
+puts head.metrics.units_per_em    # => Asks explicitly for metric value
+puts head.metrics.weight_class    # => Asks explicitly for metric value
+print head.ty                     # => Prints force loaded table
+
+# Check preparedness after loading
+font.table_available?("head")     # => true in cache
+font.table_available?("GSUB")     # => true in cache
+font.table_available?("GPOS")     # => true in cache
+----
+
+A table not present in a font file is loaded lazily and `table_available?`
+returns `false` after loading this table or after calling directly `table` for
+the given tag:
+
+[source,ruby]
+----
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Check preparedness
+font.standard_glyphs              # => instantly loading glyphs (CFF and GDEF)
+font.candlestick_and_widget_chart # => instantly loading glyphs (Colr)
+font.txt_encoder                  # => instantly loading glyphs (OutlinedFont)
+font.table_available?("post")     # => true (cached)
+
+font.table_available?("OS/2")     # => false (not loaded)
+font.table("OS/2")                # => instant loading tables (lazy loading)
+font.table_available?("OS/2")     # => true (cached)
+
+font.table_available?("VORG")     # => false (not loaded)
+font.table("VORG")                # => instant loading tables (lazy loading)
+# Raises Fontisan::Tables::VorgTableNotInFont: Not a valid sfnt font or sfnt table VORG not included in input font
+font.table_available?("VORG")     # => true (cached)
+
+font.table_available?("GLYC")     # => nil
+font.table("GLYC")                # => instant loading tables (lazy loading)
+# Raises Fontisan::TableNotFound: Table GLYC not found in font
+font.table_available?("GLYC")     # => nil (not cached)
+----
+
+NOTE: If you do not need to check whether the table is present before access
+it is faster to access directly `table` method and catch error with validation
+than first call table_available? for the table not present in the font file.
 
 
 == Outline format conversion
@@ -1568,6 +1833,31 @@ converter.supported_targets(:ttf)
 # => [:ttf, :otf, :woff2, :svg]
 ----
 
+=== Convert into WOFF2
+
+==== Validation
+
+WOFF2 encoding can be validated automatically to ensure spec compliance:
+
+.Validation example
+[example]
+====
+[source,ruby]
+----
+encoder = Fontisan::Converters::Woff2Encoder.new
+result = encoder.convert(font, {
+  transform_tables: true,
+  validate: true,
+  validation_level: :strict  # :strict, :standard, or :lenient
+})
+
+report = result[:validation_report]
+puts "Valid: #{report.valid}"
+puts "Compression: #{report.info_issues.first.message}"
+----
+====
+
+
 
 === Validation
 
@@ -2086,7 +2376,7 @@ end
 ====
 
 
-== Round-Trip validation
+== Round-trip validation
 
 === General
 
@@ -2159,7 +2449,7 @@ Loron.
 
 Support for layered import CFF color glyphs rasterizing on demand, with
 composite font support, a multi-layer color font represented by many
-CFF fonts stacked on top of each other.	ColorGlyph support contains
+CFF fonts stacked on top of each other.  ColorGlyph support contains
 color glyphs, advanced color fonts glyphs and raster images (PNG or JPG)
 combined with TrueType outlines.
 

data/Rakefile

@@ -87,6 +87,9 @@ namespace :fixtures do
 
   # Create file tasks for each font
   fonts.each do |name, config|
+    # Skip fonts that should not be downloaded (already committed)
+    next if config[:skip_download]
+
     file config[:marker] do
       if config[:single_file]
         download_single_file(name, config[:url], config[:marker])
@@ -97,16 +100,26 @@ namespace :fixtures do
   end
 
   desc "Download all test fixture fonts"
-  task download: fonts.values.map { |config| config[:marker] }
+  task download: fonts.values.reject { |config| config[:skip_download] }.map { |config| config[:marker] }
 
   desc "Clean downloaded fixtures"
   task :clean do
-    fonts.values.map { |config| config[:target_dir] }.each do |path|
-      next unless File.exist?(path)
-
-      puts "[fixtures:clean] Removing #{path}..."
-      FileUtils.rm_rf(path)
-      puts "[fixtures:clean] Removed #{path}"
+    fonts.values.reject { |config| config[:skip_download] }.each do |config|
+      if config[:single_file]
+        # For single files, just delete the marker file itself
+        if File.exist?(config[:marker])
+          puts "[fixtures:clean] Removing #{config[:marker]}..."
+          FileUtils.rm_f(config[:marker])
+          puts "[fixtures:clean] Removed #{config[:marker]}"
+        end
+      else
+        # For archives, delete the entire target directory
+        if File.exist?(config[:target_dir])
+          puts "[fixtures:clean] Removing #{config[:target_dir]}..."
+          FileUtils.rm_rf(config[:target_dir])
+          puts "[fixtures:clean] Removed #{config[:target_dir]}"
+        end
+      end
     end
   end
 end

data/lib/fontisan/base_collection.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "constants"
+
+module Fontisan
+  # Abstract base class for font collections (TTC/OTC)
+  #
+  # This class implements the shared logic for TrueTypeCollection and OpenTypeCollection
+  # using the Template Method pattern. Subclasses must implement the abstract methods
+  # to specify their font class and collection format.
+  #
+  # The BinData structure definition is shared between both collection types since
+  # both TTC and OTC files use the same "ttcf" tag and binary format. The only
+  # differences are:
+  # 1. The type of fonts contained (TrueType vs OpenType)
+  # 2. The format string used for display ("TTC" vs "OTC")
+  #
+  # @abstract Subclass and override {font_class} and {collection_format}
+  #
+  # @example Implementing a collection subclass
+  #   class TrueTypeCollection < BaseCollection
+  #     def self.font_class
+  #       TrueTypeFont
+  #     end
+  #
+  #     def self.collection_format
+  #       "TTC"
+  #     end
+  #   end
+  class BaseCollection < 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
+
+    # Abstract method: Get the font class for this collection type
+    #
+    # Subclasses must override this to return their specific font class
+    # (TrueTypeFont or OpenTypeFont).
+    #
+    # @return [Class] The font class (TrueTypeFont or OpenTypeFont)
+    # @raise [NotImplementedError] if not overridden by subclass
+    def self.font_class
+      raise NotImplementedError,
+            "#{name} must implement self.font_class"
+    end
+
+    # Abstract method: Get the collection format string
+    #
+    # Subclasses must override this to return "TTC" or "OTC".
+    #
+    # @return [String] Collection format ("TTC" or "OTC")
+    # @raise [NotImplementedError] if not overridden by subclass
+    def self.collection_format
+      raise NotImplementedError,
+            "#{name} must implement self.collection_format"
+    end
+
+    # Read collection from a file
+    #
+    # @param path [String] Path to the collection file
+    # @return [BaseCollection] 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)
+
+      File.open(path, "rb") { |io| read(io) }
+    rescue BinData::ValidityError => e
+      raise "Invalid #{collection_format} file: #{e.message}"
+    rescue EOFError => e
+      raise "Invalid #{collection_format} file: unexpected end of file - #{e.message}"
+    end
+
+    # Extract fonts from the collection
+    #
+    # Reads each font from the collection file and returns them as font objects.
+    #
+    # @param io [IO] Open file handle to read fonts from
+    # @return [Array] Array of font objects (TrueTypeFont or OpenTypeFont)
+    def extract_fonts(io)
+      font_class = self.class.font_class
+
+      font_offsets.map do |offset|
+        font_class.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 [TrueTypeFont, OpenTypeFont, nil] Font object or nil if index out of range
+    def font(index, io, mode: LoadingModes::FULL)
+      return nil if index >= num_fonts
+
+      font_class = self.class.font_class
+      font_class.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 collection version as a single integer
+    #
+    # @return [Integer] Version number (e.g., 0x00010000 for version 1.0)
+    def version
+      (major_version << 16) | minor_version
+    end
+
+    # Get the collection version as a string
+    #
+    # @return [String] Version string (e.g., "1.0")
+    def version_string
+      "#{major_version}.#{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.ttc", "rb") do |io|
+    #     collection = TrueTypeCollection.read(io)
+    #     list = collection.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 "tables/name"
+
+      font_class = self.class.font_class
+
+      fonts = font_offsets.map.with_index do |offset, index|
+        font = font_class.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.ttc", "rb") do |io|
+    #     collection = TrueTypeCollection.read(io)
+    #     info = collection.collection_info(io, "fonts.ttc")
+    #     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: self.class.collection_format,
+        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"
+
+      font_class = self.class.font_class
+
+      # Extract all fonts
+      fonts = font_offsets.map do |offset|
+        font_class.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