TTFunk

TTFunk is a pure Ruby library designed for working with TrueType and OpenType fonts. Its primary capabilities include:

• Parsing font files
• Encoding fonts
• Limited font subsetting

The recommended way to install the TTFunk library is using the gem install command.

gem install ttfunk

You can use TTFunk::File.open to load a TrueType or OpenType font file. Once opened, you can access font metadata such as the font name, ascent, and descent values.

require 'ttfunk'

file = TTFunk::File.open("some/path/myfont.ttf")
puts "name    : #{file.name.font_name.join(', ')}"
puts "ascent  : #{file.ascent}"
puts "descent : #{file.descent}"

By default, TTFEncoder does not include the kern (kerning) table. This is an optimization for PDF generation because PDF readers typically handle kerning as text is drawn. If you are using ttfunk for a purpose other than PDF generation and require the kerning information to be embedded in the font file, you must explicitly enable it in the options hash.

# Enable kerning
encoder = TTFEncoder.new(original, subset, kerning: true)

Once a TTFunk::File is loaded, you can access common font metrics and bounding box information directly through the instance methods:

• #ascent: Returns the glyph ascent (prioritizes OS/2 table, falls back to hhea).
• #descent: Returns the glyph descent (prioritizes OS/2 table, falls back to hhea).
• #line_gap: Returns the line gap (prioritizes OS/2 table, falls back to hhea).
• #bbox: Returns the glyph bounding box as an array: [x_min, y_min, x_max, y_max] using the head table.

font = TTFunk::File.open('font.ttf')
puts font.ascent
puts font.descent
puts font.line_gap.inspect
puts font.bbox.inspect

Use TTFunk::File.from_ttc to extract a specific font from a TrueType Collection (.ttc) file. The which parameter accepts an integer index of the font within the collection.

# Load the second font in the collection
font = TTFunk::File.from_ttc('path/to/collection.ttc', 1)

Use TTFunk::File.from_dfont to load a specific font from a DFont resource file. You can specify the font to load using either an integer index or a string name via the which parameter.

# Load the first font in the DFont resource
font = TTFunk::File.from_dfont('path/to/resource.dfont', 0)

# Load a font by name
font = TTFunk::File.from_dfont('path/to/resource.dfont', 'Arial')

Use TTFunk::File.open to load a font from an IO object or a file path. This method returns a TTFunk::File instance representing an individual TrueType or OpenType font. The resulting object provides access to font tables and metadata.

# From a file path
font = TTFunk::File.open('path/to/font.ttf')

# From an IO object
File.open('path/to/font.otf', 'rb') do |io|
  font = TTFunk::File.open(io)
end

Use TTFunk::File#find_glyph(glyph_id) to retrieve glyph data for a specific index. The return type depends on the font format:

• For CFF-based OpenType fonts: Returns a TTFunk::Table::Cff::Charstring.
• For TrueType fonts: Returns either a TTFunk::Table::Glyf::Simple or TTFunk::Table::Glyf::Compound object.

font = TTFunk::File.open('font.ttf')
glyph = font.find_glyph(42)

A TTFunk::File provides access to various SFNT-based tables. Most tables are accessed via methods that return a table object (e.g., TTFunk::Table::Head). Common tables include:

• #header: Font Header (head)
• #cmap: Character to Glyph Index Mapping (cmap)
• #horizontal_header: Horizontal Header (hhea)
• #horizontal_metrics: Horizontal Metrics (hmtx)
• #maximum_profile: Maximum Profile (maxp)
• #kerning: Kerning (kern)
• #name: Naming (name)
• #os2: OS/2 and Windows Metrics (OS/2)
• #postscript: PostScript (post)
• #glyph_locations: Index to Location (loca)
• #glyph_outlines: Glyph Data (glyf)
• #cff: Compact Font Format (CFF )
• #sbix: Standard Bitmap Graphics (sbix)

You can also check for a specific table's existence in the directory using #directory_info(tag).

The TTFunk::OTFEncoder class is used to encode CFF-based (Compact Font Format) OpenType font subsets into their binary representation. Unlike standard TTF fonts, CFF-based fonts store glyph information in the CFF charstrings index rather than a glyf table. Consequently, OTFEncoder does not maintain glyf or loca tables.

When using this encoder, the resulting binary output follows an optimal table order according to the OpenType specification, ensuring that the DSIG table is always placed last.

# Note: This is a conceptual usage based on the class definition.
# OTFEncoder inherits from TTFEncoder and is used for CFF-based OpenType fonts.
encoder = TTFunk::OTFEncoder.new(original_font, subset)
binary_data = encoder.encode