fontisan 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0fe760da43bddcfad046aef63c311613ea3767569245b21a2bda6a6d5f100a5f
-  data.tar.gz: 7571202d9bc900928ee4c3859e4081af6d561f53740587f0f94f7a159dbbbec3
+  metadata.gz: '020862878eef5569b82edb88989afdc3b7c21d3f01d19b605132af70cabe524f'
+  data.tar.gz: d8d685a687c94f987835e440619aca344a615368ea78d6caf6a882c34c2900d3
 SHA512:
-  metadata.gz: 66e94f6047f20385c27583a191d5c78ded6589ee8d2004386613062adb2071aba41644736c632be4087e24998ae29a7066fc17e42773a3627832c32f67d3c670
-  data.tar.gz: b9180051a16410731a112602c4ff5d18b679b6c6e521d31f092b5be2c550aceaae8992729c6bc71d7dd919b71b669217866febd26ce014528cd91eb392af1c96
+  metadata.gz: a98055b753907dedfd44fd89c61fd3d5d797d405d702e65730bae1e3299665354f385b135529ca6b48708672e37cfa0e10a7b518ce0b624ccb46fae9459cfb22
+  data.tar.gz: 46af4e780f4a1786501e2b874d4b439614c212b839b0b398316806a2baa9348b67c8e4db3e63b85142d79ae015df3f093db957f055ddbd3f4955268caa2c1dfa

data/README.adoc

@@ -2376,6 +2376,106 @@ Fontisan can:
 * Importing and generation PNG block ruler layers
 
 
+== UFO source operations
+
+fontisan reads, writes, and compiles UFO (Unified Font Object) v2/v3
+font sources into binary font formats (TTF, OTF). No AFDKO or Python
+fonttools needed.
+
+=== Build a UFO to binary
+
+[source,bash]
+----
+# TTF (TrueType outlines)
+fontisan ufo build font.ufo --output out.ttf --to ttf
+
+# OTF (CFF outlines)
+fontisan ufo build font.ufo --output out.otf --to otf
+----
+
+The TTF compiler automatically applies:
+- `cubic_to_quadratic` filter (UFO cubic Beziers -> TTF quadratic)
+- `reverse_contour_direction` filter (TTF winding convention)
+
+=== Convert between UFO and binary
+
+[source,bash]
+----
+# UFO -> binary
+fontisan ufo convert font.ufo out.ttf --to ttf
+
+# Binary -> UFO (reverse direction)
+fontisan ufo convert font.ttf font.ufo/
+----
+
+=== Validate a UFO source
+
+[source,bash]
+----
+fontisan ufo validate font.ufo
+----
+
+Checks: glyphs present, family name set, unitsPerEm set, .notdef exists.
+
+=== Ruby API
+
+[source,ruby]
+----
+require "fontisan"
+
+# Read a UFO
+font = Fontisan::Ufo::Font.open("font.ufo")
+puts font.family_name
+puts font.glyphs.size
+
+# Compile to TTF
+Fontisan::Ufo::Compile::TtfCompiler.new(font).compile(output_path: "out.ttf")
+
+# Compile to OTF
+Fontisan::Ufo::Compile::OtfCompiler.new(font).compile(output_path: "out.otf")
+
+# Write back to UFO (round-trip)
+Fontisan::Ufo::Writer.new(font).write("out.ufo")
+
+# Convert a binary font to UFO
+ttf = Fontisan::FontLoader.load("font.ttf")
+ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
+----
+
+== Font stitching
+
+The Stitcher combines glyphs from multiple source fonts into one new
+font. Sources can be UFO directories or loaded TTF/OTF files.
+
+=== Ruby API
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:latin, Fontisan::FontLoader.load("NotoSans.ttf"))
+stitcher.add_source(:cjk, Fontisan::FontLoader.load("FSung-m.ttf"))
+
+stitcher.include_range(0x41..0x5A, from: :latin)    # A-Z
+stitcher.include_range(0x4E00..0x9FFF, from: :cjk)  # CJK Unified
+stitcher.include_notdef(from: :latin)
+
+stitcher.write_to("stitched.ttf", format: :ttf)
+----
+
+=== CLI
+
+[source,bash]
+----
+fontisan stitch \
+  --source latin=NotoSans.ttf \
+  --source cjk=FSung-m.ttf \
+  --include-range latin=0x41-0x5A \
+  --include-range cjk=0x4E00-0x9FFF \
+  --notdef-from latin \
+  --output stitched.ttf
+----
+
+
 == Testing
 
 === General

data/lib/fontisan/error.rb

@@ -199,6 +199,13 @@ module Fontisan
     end
   end
 
+  # Multiple CBDT sources detected in Stitcher
+  #
+  # Raised when more than one CBDT/CBLC source is registered with the
+  # Stitcher. Only single-source CBDT passthrough is supported; merging
+  # CBDT/CBLC across multiple sources requires a dedicated rebuild.
+  class MultipleCbdtSourcesError < Error; end
+
   # Variation data corrupted (for use in data_extractor)
   #
   # Raised when extracted variation data appears corrupted.

data/lib/fontisan/stitcher/source.rb

@@ -10,6 +10,11 @@ module Fontisan
     # via Ufo::Convert::FromBinData on first glyph access, then cached.
     # This is O(n) in donor glyph count but amortized across all
     # codepoint extractions from that donor.
+    #
+    # CBDT/CBLC sources (e.g. NotoColorEmoji) are detected via
+    # #bitmap_mode. When a source is :cbdt, the Stitcher propagates
+    # the raw CBDT/CBLC tables into the output instead of extracting
+    # outlines. The glyph data lives in the bitmap tables, not in glyf.
     class Source
       attr_reader :font
 
@@ -28,6 +33,27 @@ module Fontisan
         end
       end
 
+      # Detect how this source stores glyph data.
+      #
+      # - :glyf — TrueType outlines (glyf table present)
+      # - :cbdt — Color bitmaps (CBDT + CBLC tables, no glyf)
+      # - :mixed — Both glyf and CBDT
+      # - :none  — UFO source or neither table present
+      #
+      # @return [Symbol]
+      def bitmap_mode
+        return :none if @font.is_a?(Fontisan::Ufo::Font)
+        return :none unless @font.respond_to?(:has_table?)
+
+        has_cbdt = @font.has_table?("CBDT") && @font.has_table?("CBLC")
+        has_glyf = @font.has_table?("glyf") || @font.has_table?("CFF ")
+        return :mixed if has_cbdt && has_glyf
+        return :cbdt if has_cbdt
+        return :glyf if has_glyf
+
+        :none
+      end
+
       # Find the gid for a Unicode codepoint in this source.
       # @param codepoint [Integer]
       # @return [Integer, nil]
@@ -39,6 +65,9 @@ module Fontisan
       end
 
       # Extract a glyph by gid.
+      #
+      # For CBDT sources, returns a placeholder glyph (no contours)
+      # since the glyph data lives in the bitmap tables, not outlines.
       # @param gid [Integer]
       # @return [Fontisan::Ufo::Glyph, nil]
       def glyph_for_gid(gid)
@@ -48,6 +77,18 @@ module Fontisan
         end
       end
 
+      # Raw table bytes from the loaded font (for passthrough).
+      # @param tag [String] 4-byte table tag (e.g. "CBDT", "CBLC")
+      # @return [String, nil] raw bytes or nil if table not present
+      def raw_table_bytes(tag)
+        sfnt_table = @font.table(tag)
+        return nil unless sfnt_table
+
+        sfnt_table.raw_data
+      rescue StandardError
+        nil
+      end
+
       private
 
       # ---------- UFO source ----------

data/lib/fontisan/stitcher.rb

@@ -70,12 +70,23 @@ module Fontisan
     end
 
     # Write the stitched font to disk.
+    #
+    # For CBDT/CBLC sources (e.g. NotoColorEmoji), the raw CBDT and
+    # CBLC tables are copied byte-for-byte into the output. This works
+    # because CBDT-mode glyphs are processed first (GIDs 0..N-1),
+    # matching the source's GID layout. Only one CBDT source is
+    # supported; multiple CBDT sources raise MultipleCbdtSourcesError.
+    #
     # @param path [String] output file path
     # @param format [Symbol] :ttf or :otf
     def write_to(path, format: :ttf)
       build_target_font
       compiler = compiler_for(format)
-      compiler.new(@target).compile(output_path: path)
+      compiler_instance = compiler.new(@target)
+      compiler_instance.compile(output_path: path)
+
+      propagate_cbdt_tables(path) if cbdt_source
+
       path
     end
 
@@ -96,6 +107,53 @@ module Fontisan
       end
     end
 
+    # Find the single CBDT source among registered sources, if any.
+    # Raises if more than one CBDT source is present (merge not supported).
+    # @return [Source, nil]
+    def cbdt_source
+      cbdts = @sources.values.select { |s| s.bitmap_mode == :cbdt }
+      if cbdts.size > 1
+        raise MultipleCbdtSourcesError,
+              "multiple CBDT sources not supported (found #{cbdts.size})"
+      end
+
+      cbdts.first
+    end
+
+    # Copy raw CBDT + CBLC table bytes from the CBDT source into the
+    # compiled output file. The GIDs must match (CBDT glyphs are at
+    # the same GIDs in both source and output because they were added
+    # first during build_target_font).
+    def propagate_cbdt_tables(path)
+      source = cbdt_source
+      return unless source
+
+      compiled = Fontisan::FontLoader.load(path)
+
+      tables = {}
+      compiled.table_names.each do |tag|
+        raw = extract_raw_table(compiled, tag)
+        tables[tag] = raw if raw
+      end
+
+      cbdt_bytes = source.raw_table_bytes("CBDT")
+      cblc_bytes = source.raw_table_bytes("CBLC")
+      tables["CBDT"] = cbdt_bytes if cbdt_bytes
+      tables["CBLC"] = cblc_bytes if cblc_bytes
+
+      sfnt = tables.key?("CFF ") ? 0x4F54544F : 0x00010000
+      Fontisan::FontWriter.write_to_file(tables, path, sfnt_version: sfnt)
+    end
+
+    def extract_raw_table(font, tag)
+      sfnt_table = font.table(tag)
+      return nil unless sfnt_table
+
+      sfnt_table.raw_data
+    rescue StandardError
+      nil
+    end
+
     def compiler_for(format)
       case format.to_sym
       when :ttf then Ufo::Compile::TtfCompiler
@@ -107,26 +165,28 @@ module Fontisan
 
     # Walk bindings in codepoint order, assign sequential new gids,
     # copy each glyph into the target font's default layer.
+    #
+    # When a CBDT source is present, its glyphs are added FIRST (in
+    # source GID order) so that the CBLC's GID references remain valid.
+    # Glyf-source bindings are processed AFTER, appending new glyphs.
     def assign_gids_and_copy_glyphs
-      # Always put .notdef at gid 0 first.
-      notdef_binding = @bindings.find { |b| b[:donor_gid].zero? }
-      if notdef_binding
-        copy_glyph_into(@target, name: ".notdef",
-                                 source: notdef_binding[:source],
-                                 donor_gid: 0)
+      cbdt = cbdt_source
+
+      if cbdt
+        add_all_cbdt_glyphs(cbdt)
       else
-        # Synthesize an empty .notdef
-        @target.layers.default_layer.add(Ufo::Glyph.new(name: ".notdef"))
+        add_notdef_from_bindings
       end
 
       sorted_bindings.each do |binding|
-        next if binding[:donor_gid].zero? # already handled
+        next if binding[:donor_gid].zero?
+
+        # Skip bindings from the CBDT source — its glyphs are already added.
+        next if cbdt && binding[:source].equal?(cbdt)
 
         glyph = binding[:source].glyph_for_gid(binding[:donor_gid])
         next unless glyph
 
-        # If multiple codepoints map to the same glyph, only the first
-        # binding creates the glyph; subsequent ones add unicode entries.
         if @target.glyphs.key?(glyph.name)
           add_extra_unicode(glyph.name, binding[:codepoint])
         else
@@ -159,6 +219,51 @@ module Fontisan
       glyph.add_unicode(codepoint) unless glyph.unicodes.include?(codepoint)
     end
 
+    # Add .notdef at GID 0 from the first binding that references gid 0.
+    # Falls back to a synthesized empty .notdef if none found.
+    def add_notdef_from_bindings
+      notdef_binding = @bindings.find { |b| b[:donor_gid].zero? }
+      if notdef_binding
+        copy_glyph_into(@target, name: ".notdef",
+                                 source: notdef_binding[:source],
+                                 donor_gid: 0)
+      else
+        @target.layers.default_layer.add(Ufo::Glyph.new(name: ".notdef"))
+      end
+    end
+
+    # Add ALL glyphs from a CBDT source in source GID order. This
+    # ensures the CBLC's GID references remain valid in the output
+    # without rewriting the table. Each glyph gets a placeholder
+    # (no contours) since the bitmap data is in CBDT, not glyf.
+    def add_all_cbdt_glyphs(source)
+      ufo = source.font.is_a?(Ufo::Font) ? source.font : nil
+      if ufo
+        ufo.glyphs.each_value { |g| @target.layers.default_layer.add(clone_glyph(g, name: g.name)) }
+        return
+      end
+
+      # For loaded TTF/OTF sources, iterate via cmap to get glyph names.
+      # CBDT fonts (like NotoColorEmoji) may have thousands of glyphs;
+      # we add them all as placeholders.
+      maxp = source.font.table("maxp")
+      num_glyphs = maxp&.num_glyphs || 0
+      cmap = source.font.table("cmap")
+      mappings = cmap&.unicode_mappings || {}
+
+      # Build gid → [codepoints] from cmap
+      gid_cps = Hash.new { |h, k| h[k] = [] }
+      mappings.each { |cp, gid| gid_cps[gid] << cp }
+
+      num_glyphs.times do |gid|
+        name = gid.zero? ? ".notdef" : "gid#{gid}"
+        glyph = Ufo::Glyph.new(name: name)
+        glyph.width = 0
+        gid_cps[gid].each { |cp| glyph.add_unicode(cp) }
+        @target.layers.default_layer.add(glyph)
+      end
+    end
+
     # Deep-copy a glyph with a new name. Used so multiple target
     # glyphs can share the same source outline without aliasing.
     def clone_glyph(original, name:)

data/lib/fontisan/ufo/compile/cff.rb

@@ -53,7 +53,8 @@ module Fontisan
         end
 
         def self.empty_charstring(width)
-          Fontisan::Tables::Cff::CharStringBuilder.build_empty(width: width.zero? ? nil : width)
+          builder = Fontisan::Tables::Cff::CharStringBuilder.new
+          builder.build_empty(width: width.zero? ? nil : width)
         end
 
         # ---------- layout ----------

data/lib/fontisan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fontisan
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fontisan
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-29 00:00:00.000000000 Z
+date: 2026-06-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64