fontisan 0.4.6 → 0.4.7

data/docs/SVG_TO_GLYF.adoc

@@ -0,0 +1,118 @@
+= SVG to Glyph Guide
+
+== General
+
+`Fontisan::SvgToGlyf` converts SVG path data — as produced by ucode's
+code-chart extraction — into `Ufo::Glyph` objects that feed directly
+into the UFO → TTF/OTF compile pipeline.
+
+SvgToGlyf emits cubic Bezier contours (matching UFO/PostScript
+conventions). The cubic-to-quadratic conversion and winding-order
+correction happen later, in `Ufo::Compile::Filters::CubicToQuadratic`
+and `ReverseContourDirection`, when the glyph is compiled to TTF.
+
+== API
+
+[cols="2,3", options="header"]
+|===
+| Method | Purpose
+
+| `SvgToGlyf.convert(path_data, upm:, codepoint:, name:, viewbox:, transform:)`
+| Convert a single SVG path `d` string into a `Ufo::Glyph`
+
+| `SvgToGlyf.from_svg_file(file_path, upm:, codepoint:)`
+| Convert one `.svg` file into a `Ufo::Glyph`
+
+| `SvgToGlyf.from_directory(dir, upm:)`
+| Convert a directory of `.svg` files into a `Ufo::Font` (one glyph
+  per file)
+|===
+
+The default `upm` is 1000.
+
+== Single path
+
+[source,ruby]
+----
+glyph = Fontisan::SvgToGlyf.convert(
+  "M 0 0 L 500 0 L 500 700 L 0 700 Z",
+  upm: 1000,
+  codepoint: 0x10940,
+)
+# → #<Fontisan::Ufo::Glyph name="uni10940" ...>
+----
+
+== Single file
+
+[source,ruby]
+----
+glyph = Fontisan::SvgToGlyf.from_svg_file("U+10940.svg", upm: 1000)
+----
+
+If the codepoint is not supplied, it is derived from the filename when
+it matches `U+XXXX.svg` or `hexcode.svg`.
+
+== Directory → Font
+
+For batch conversion of a code-chart directory (one SVG per
+codepoint):
+
+[source,ruby]
+----
+font = Fontisan::SvgToGlyf.from_directory(
+  "/tmp/chart-svg/Khitan",
+  upm: 1000,
+)
+Fontisan::Ufo::Compile::TtfCompiler.new(font)
+  .compile(output_path: "Khitan.ttf")
+----
+
+Or feed it directly to the Stitcher:
+
+[source,ruby]
+----
+stitcher = Fontisan::Stitcher.new
+stitcher.add_source(:khitan, font)
+stitcher.include_range(0x18B00..0x18CFF, from: :khitan, into: :main)
+stitcher.write_to("Khitan.ttf", format: :ttf, subfont: :main)
+----
+
+== SVG subset supported
+
+SvgToGlyf handles the subset of SVG that real chart extractions use:
+
+* Path commands: `M`, `L`, `H`, `V`, `C`, `S`, `Q`, `T`, `A`, `Z`
+  (absolute and lowercase relative variants)
+* `<svg>` `viewBox` and `width`/`height` for coordinate scaling
+* `<g transform="...">` group transforms (matrix, translate, scale,
+  rotate)
+* `<path d="...">` elements
+
+Unsupported SVG features (filters, masks, embedded raster images) are
+ignored. SvgToGlyf is a vector-only converter — for raster emoji, use
+the CBDT/CBLC passthrough path (see link:STITCHER_GUIDE.adoc[Stitcher Guide]).
+
+== Coordinate system
+
+SVG uses a y-down coordinate system; UFO uses y-up. SvgToGlyf flips
+the y-axis using the SVG `viewBox` height so glyphs render right-way-up
+in font rendering contexts. When no `viewBox` is present, the
+`<svg>` `width`/`height` attributes are used as a fallback.
+
+== Namespace layout
+
+[source]
+----
+Fontisan::SvgToGlyf
+├── Path       # SVG path parser → contour builder
+├── Geometry   # AffineTransform, vector math
+├── Document   # <svg> document parsing, viewBox handling
+└── Assembler  # top-level glue: builds Ufo::Glyph / Ufo::Font
+----
+
+== See also
+
+* link:UFO_COMPILATION.adoc[UFO Compilation Guide] — compile converted
+  glyphs to binary fonts
+* link:STITCHER_GUIDE.adoc[Stitcher Guide] — combine converted fonts
+  with other donors

data/docs/UFO_COMPILATION.adoc

@@ -0,0 +1,119 @@
+= UFO Compilation Guide
+
+== General
+
+Fontisan compiles UFO (Unified Font Object) v2/v3 sources into binary
+OpenType fonts — TTF, OTF (CFF1), and OTF2 (CFF2) — entirely in pure
+Ruby. No AFDKO or Python fonttools required.
+
+All compilers live under `Fontisan::Ufo::Compile` and share a common
+`BaseCompiler` orchestrator that emits the required set of OpenType
+tables (head, hhea, maxp, OS/2, name, post, hmtx, cmap, plus an
+optional GPOS kern table when the source has kerning data). Subclasses
+add format-specific outline tables.
+
+== Compilers
+
+[cols="1,1,3", options="header"]
+|===
+| Class | Output | Outline format
+
+| `Ufo::Compile::TtfCompiler`
+| `.ttf`
+| Quadratic Bezier curves in the `glyf` table
+
+| `Ufo::Compile::OtfCompiler`
+| `.otf` (CFF1)
+| Cubic Bezier curves in the `CFF ` table using Type 2 charstrings
+
+| `Ufo::Compile::Otf2Compiler`
+| `.otf` (CFF2)
+| Cubic Bezier curves in the `CFF2` table — modern format, supports
+  variable fonts via blend/vsindex operators
+|===
+
+== Building a single font
+
+[source,ruby]
+----
+require "fontisan"
+
+font = Fontisan::Ufo::Font.open("MyFont.ufo")
+
+# TrueType
+Fontisan::Ufo::Compile::TtfCompiler.new(font)
+  .compile(output_path: "MyFont.ttf")
+
+# OpenType / CFF1
+Fontisan::Ufo::Compile::OtfCompiler.new(font)
+  .compile(output_path: "MyFont.otf")
+
+# OpenType / CFF2 (modern, supports variable fonts)
+Fontisan::Ufo::Compile::Otf2Compiler.new(font)
+  .compile(output_path: "MyFont-CFF2.otf")
+----
+
+== TTF filters
+
+The TTF compiler applies two UFO glyph filters automatically:
+
+1. `CubicToQuadratic` — converts cubic Bezier control points to
+   quadratic. TTF `glyf` only supports quadratic curves; UFO sources
+   typically use cubics (matching PostScript/CFF conventions).
+2. `ReverseContourDirection` — reverses winding order. CFF and TTF
+   use opposite fill conventions (CFF: non-zero wind; TTF: even-odd by
+   default), so contour direction must be flipped.
+
+These filters live under `Ufo::Compile::Filters` and are applied to
+each glyph before serialization to `glyf`.
+
+== Tables emitted
+
+Every compiler emits this shared set:
+
+[cols="1,3", options="header"]
+|===
+| Tag | Purpose
+
+| `head` | Font header (units per em, bounding box, timestamps)
+| `hhea` | Horizontal header (ascender, descender, line gap)
+| `maxp` | Maximum profile (glyph count, point/contour limits)
+| `OS/2` | OS/2 and Windows-specific metrics
+| `name` | Name records (family, subfamily, copyright, etc.)
+| `post` | PostScript name table (glyph names)
+| `hmtx` | Horizontal metrics (advance width, left side bearing)
+| `cmap` | Character to glyph mapping
+| `GPOS` | Optional — present only when the UFO has kerning data
+|===
+
+Format-specific outline tables:
+
+* TTF → `glyf` + `loca`
+* OTF (CFF1) → `CFF `
+* OTF2 (CFF2) → `CFF2`
+
+== GPOS kerning
+
+If the UFO source includes kerning data (`kerning.plist`), the compiler
+emits a `GPOS` table with a pair-positioning lookup (feature `kern`).
+When no kerning is present, no `GPOS` table is written — the file stays
+smaller.
+
+== Round-tripping binary ↔ UFO
+
+To go the other way — extract a UFO from an existing binary font:
+
+[source,ruby]
+----
+ttf = Fontisan::FontLoader.load("MyFont.ttf")
+ufo = Fontisan::Ufo::Convert::FromBinData.convert(ttf)
+Fontisan::Ufo::Writer.new(ufo).write("MyFont.ufo")
+----
+
+== See also
+
+* link:CFF2_SUPPORT.adoc[CFF2 Support Guide] — variable-font blend
+  operators, FDSelect, subroutines, VariationStore
+* link:VARIABLE_FONT_OPERATIONS.adoc[Variable Font Operations] —
+  reading and modifying existing variable fonts
+- link:STITCHER_GUIDE.adoc[Stitcher Guide] — multi-source assembly

data/lib/fontisan/collection/writer.rb

@@ -19,6 +19,10 @@ module Fontisan
       VERSION_1_0_MAJOR = 1
       VERSION_1_0_MINOR = 0
 
+      # TTC version 2.0 (major=2, minor=0) — supports DSIG reference
+      VERSION_2_0_MAJOR = 2
+      VERSION_2_0_MINOR = 0
+
       # Initialize writer
       #
       # @param fonts [Array<TrueTypeFont, OpenTypeFont>] Source fonts
@@ -91,12 +95,7 @@ module Fontisan
       #
       # @return [String] TTC header binary
       def write_ttc_header
-        [
-          TTC_TAG,                  # char[4] - tag
-          VERSION_1_0_MAJOR,        # uint16 - major version
-          VERSION_1_0_MINOR,        # uint16 - minor version
-          @fonts.size, # uint32 - number of fonts
-        ].pack("a4 n n N")
+        [TTC_TAG, VERSION_1_0_MAJOR, VERSION_1_0_MINOR, @fonts.size].pack("a4nnN")
       end
 
       # Write offset table

data/lib/fontisan/error.rb

@@ -206,6 +206,37 @@ module Fontisan
   # CBDT/CBLC across multiple sources requires a dedicated rebuild.
   class MultipleCbdtSourcesError < Error; end
 
+  # Stitcher produced more glyphs than the output format supports.
+  #
+  # Raised by Stitcher::GlyphLimit.check! before writing, so the user
+  # gets an actionable message instead of a silently truncated font.
+  class GlyphLimitExceededError < Error
+    attr_reader :actual, :limit, :format
+
+    def initialize(actual:, limit:, format:)
+      @actual = actual
+      @limit = limit
+      @format = format
+      super(build_message)
+    end
+
+    private
+
+    def build_message
+      "Stitcher produced #{actual} unique glyphs, exceeding the " \
+        "#{format.to_s.upcase} limit of #{format_limit}. Both TTF and OTF " \
+        "(CFF1) cap at 65,535 glyphs — the maxp.num_glyphs field is uint16 " \
+        "and the CFF CharStrings INDEX count is card16. Options: " \
+        "(1) split the output into a TTC (TrueType Collection) by Unicode plane, " \
+        "(2) reduce the number of donors, " \
+        "(3) wait for CFF2 support in fontisan (card24 INDEX counts, no glyph cap)."
+    end
+
+    def format_limit
+      limit == Float::INFINITY ? "infinity" : limit.to_s
+    end
+  end
+
   # Variation data corrupted (for use in data_extractor)
   #
   # Raised when extracted variation data appears corrupted.

data/lib/fontisan/stitcher/deduplicator.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Registry mapping glyph signatures to canonical glyph names in
+    # the target font. Enables signature-based deduplication: when
+    # two bindings produce glyphs with identical outlines, they share
+    # one gid and the duplicate's codepoint is redirected to the
+    # canonical glyph.
+    #
+    # Replaces the Stitcher's previous name-based dedup with
+    # outline-based dedup. This merges visually identical glyphs
+    # from different donors even when their names differ, reducing
+    # the glyph count below the TrueType 65,535 cap.
+    class Deduplicator
+      attr_reader :signatures
+
+      def initialize
+        @signatures = {}
+      end
+
+      # Record that `glyph` maps to `canonical_name` in the target.
+      # @param glyph [Fontisan::Ufo::Glyph]
+      # @param canonical_name [String] the name under which the glyph
+      #   was added to the target font
+      def register(glyph, canonical_name)
+        @signatures[GlyphSignature.for(glyph)] = canonical_name
+      end
+
+      # @param glyph [Fontisan::Ufo::Glyph]
+      # @return [String, nil] the canonical name if an identical
+      #   glyph was already registered, nil otherwise
+      def find(glyph)
+        @signatures[GlyphSignature.for(glyph)]
+      end
+
+      # @return [Integer] number of unique signatures registered
+      def size
+        @signatures.size
+      end
+
+      def empty?
+        @signatures.empty?
+      end
+    end
+  end
+end

data/lib/fontisan/stitcher/glyph_limit.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Fontisan
+  class Stitcher
+    # Format-specific glyph-count caps.
+    #
+    # Both TTF and OTF (CFF1) cap at 65,535 because:
+    #   - TTF: maxp.num_glyphs is uint16
+    #   - OTF (CFF1): maxp.num_glyphs is uint16 AND the CFF CharStrings
+    #     INDEX count is card16
+    #
+    # Exceeding the cap produces a silently truncated font (the BinData
+    # uint16 writer truncates without raising). The Stitcher checks
+    # the cap BEFORE writing so the user gets a clear error.
+    #
+    # To exceed 65,535 glyphs, the font must be split into a TTC
+    # (TrueType Collection) or fontisan must implement CFF2 (card24
+    # INDEX counts). Both are future work.
+    module GlyphLimit
+      TTF_GLYPH_CAP = 65_535
+      OTF_GLYPH_CAP = 65_535
+
+      # @param format [Symbol] :ttf or :otf
+      # @return [Integer, Float::INFINITY] the max glyph count
+      def self.for_format(format)
+        case format.to_sym
+        when :ttf then TTF_GLYPH_CAP
+        when :otf then OTF_GLYPH_CAP
+        when :otf2 then OTF_GLYPH_CAP # CFF2 CharStrings count must match maxp.numGlyphs
+        else
+          raise ArgumentError, "unknown format: #{format.inspect}"
+        end
+      end
+
+      # Raise GlyphLimitExceededError if `glyph_count` exceeds the cap
+      # for the given format.
+      #
+      # @param glyph_count [Integer]
+      # @param format [Symbol]
+      # @raise [GlyphLimitExceededError]
+      def self.check!(glyph_count, format:)
+        limit = for_format(format)
+        return if glyph_count <= limit
+
+        raise GlyphLimitExceededError.new(
+          actual: glyph_count,
+          limit: limit,
+          format: format,
+        )
+      end
+    end
+  end
+end

data/lib/fontisan/stitcher/glyph_signature.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Fontisan
+  class Stitcher
+    # Stateless signature computation for a Ufo::Glyph's visual identity.
+    #
+    # Two glyphs with the same signature are visually interchangeable
+    # and can share a gid in the output font. The signature captures
+    # advance width, every contour's points (x, y, type), and every
+    # component reference (base glyph + transform presence).
+    #
+    # Used by Deduplicator to merge identical outlines from different
+    # donors, reducing the glyph count below the TrueType 65,535 cap.
+    module GlyphSignature
+      # @param glyph [Fontisan::Ufo::Glyph]
+      # @return [String] SHA-256 hex digest of the glyph's outline identity
+      def self.for(glyph)
+        Digest::SHA256.hexdigest(canonical_representation(glyph))
+      end
+
+      # Build a deterministic string capturing the glyph's visual identity.
+      # The representation is ordered and normalized so that semantically
+      # identical glyphs produce byte-identical strings.
+      #
+      # @param glyph [Fontisan::Ufo::Glyph]
+      # @return [String]
+      def self.canonical_representation(glyph)
+        io = +""
+        io << "w:#{glyph.width.to_i};"
+
+        glyph.contours.each_with_index do |contour, ci|
+          io << "c#{ci}:"
+          contour.points.each do |pt|
+            io << "#{pt.x.to_i},#{pt.y.to_i},#{pt.type};"
+          end
+        end
+
+        glyph.components.each_with_index do |comp, i|
+          io << "comp#{i}:#{comp.base_glyph}"
+          io << ":t" if comp.transformation
+        end
+
+        io
+      end
+
+      private_class_method :canonical_representation
+    end
+  end
+end