fontisan 0.2.13 → 0.2.16

data/docs/guide/variable-fonts/advanced.md

@@ -0,0 +1,231 @@
+---
+title: Advanced Variable Font Topics
+---
+
+# Advanced Variable Font Topics
+
+Advanced operations for variable fonts.
+
+## avar Table
+
+The avar (Axis Variation) table defines non-linear axis value mappings.
+
+### What avar Does
+
+Without avar, interpolation is linear:
+
+```
+wght 400 → wght 500 → wght 600 → wght 700
+      50%        50%        50%
+```
+
+With avar, you can have non-linear interpolation:
+
+```
+wght 400 → wght 500 → wght 600 → wght 700
+      70%        20%        10%
+```
+
+### Checking for avar
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+avar = font.tables['avar']
+
+if avar
+  puts "Non-linear interpolation detected"
+
+  avar.axis_mappings.each do |axis_tag, mapping|
+    puts "#{axis_tag}:"
+    mapping.each do |from, to|
+      puts "  #{from} → #{to}"
+    end
+  end
+end
+```
+
+## STAT Table
+
+The STAT (Style Attributes) table provides style attributes and axis value names.
+
+### STAT Benefits
+
+- Better font menu organization
+- Consistent naming across fonts
+- Style linking information
+
+### Reading STAT
+
+```ruby
+stat = font.tables['STAT']
+
+if stat
+  # Get design coordinates
+  stat.design_axis_values.each do |axis_value|
+    puts "#{axis_value.axis_tag}: #{axis_value.name}"
+    puts "  Value: #{axis_value.value}"
+  end
+end
+```
+
+## Metrics Variation Tables
+
+### HVAR (Horizontal Metrics Variation)
+
+```ruby
+hvar = font.tables['HVAR']
+
+if hvar
+  # Get advance width variation
+  width_delta = hvar.advance_width_delta(glyph_id, coordinates)
+  # Apply to base width
+  final_width = base_width + width_delta
+end
+```
+
+### MVAR (Metrics Variation)
+
+```ruby
+mvar = font.tables['MVAR']
+
+if mvar
+  # Get OS/2 typo ascender delta
+  ascender_delta = mvar.metric_delta('hasc', coordinates)
+end
+```
+
+### VVAR (Vertical Metrics Variation)
+
+```ruby
+vvar = font.tables['VVAR']
+
+if vvar
+  # Get vertical advance delta
+  v_advance_delta = vvar.advance_height_delta(glyph_id, coordinates)
+end
+```
+
+## Delta Processing
+
+### Understanding Deltas
+
+Variable fonts store changes (deltas) from the default:
+
+```ruby
+# Default glyph outline
+default_outline = font.glyphs[glyph_id].outline
+
+# Delta at wght=700
+delta = gvar.delta_for_glyph(glyph_id, wght: 700)
+
+# Apply delta to get bold outline
+bold_outline = default_outline + delta
+```
+
+### Interpolation
+
+```ruby
+# Interpolate between two masters
+weight = 600  # Between regular (400) and bold (700)
+
+# Calculate interpolation factor
+t = (weight - 400) / (700 - 400)  # 0.667
+
+# Interpolate delta
+interpolated_delta = gvar.interpolate(glyph_id, t, wght: weight)
+```
+
+## CFF2 Variable Fonts
+
+### CFF2 vs CFF
+
+| Feature | CFF | CFF2 |
+|---------|-----|------|
+| Variation | No | Yes |
+| CharStrings | Standard | With blend operators |
+| Private DICT | Per-font | Per-local |
+
+### Reading CFF2
+
+```ruby
+cff2 = font.tables['CFF2']
+
+if cff2
+  # Get blend values for coordinates
+  blend_values = cff2.blend_values(glyph_id, coordinates)
+
+  # Access variation store
+  variation_store = cff2.variation_store
+end
+```
+
+## Validation
+
+### Variable Font Validation
+
+```ruby
+# Validate variable font structure
+result = Fontisan.validate('variable.ttf', profile: :production)
+
+# Check variable-specific issues
+if result.valid?
+  # Verify fvar/gvar consistency
+  fvar = font.tables['fvar']
+  gvar = font.tables['gvar']
+
+  if fvar && gvar
+    # Check axis count matches
+    unless gvar.axis_count == fvar.axes.length
+      puts "Warning: gvar axis count mismatch"
+    end
+  end
+end
+```
+
+### Common Issues
+
+- **Missing gvar/CFF2**: Font has fvar but no variation data
+- **Axis mismatch**: gvar axis count differs from fvar
+- **Invalid coordinates**: Instance coordinates outside axis ranges
+- **Missing default instance**: No default coordinates defined
+
+## Performance Optimization
+
+### Caching
+
+```ruby
+# Create writer once for multiple instances
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+# Cache is reused across calls
+instances = weights.map { |w| writer.generate_instance(wght: w) }
+```
+
+### Batch Processing
+
+```ruby
+# Process multiple fonts in parallel
+fonts = Dir.glob('fonts/*.ttf').map { |f| Fontisan::FontLoader.load(f) }
+
+fonts.map do |font|
+  Thread.new do
+    writer = Fontisan::Variation::InstanceWriter.new(font)
+    writer.generate_instance(wght: 700)
+  end
+end.each(&:join)
+```
+
+## SVG Generation
+
+### Limitations
+
+Variable fonts cannot be directly exported to SVG. Generate static instances first:
+
+```ruby
+# Generate instance
+writer = Fontisan::Variation::InstanceWriter.new(font)
+static = writer.generate_instance(wght: 700)
+
+# Export to SVG
+Fontisan::FontWriter.write(static, 'bold.svg', format: :svg)
+```

data/docs/guide/variable-fonts/axes.md

@@ -0,0 +1,209 @@
+---
+title: Axes and Instances
+---
+
+# Axes and Instances
+
+Work with variation axes and named instances in variable fonts.
+
+## Getting Axis Information
+
+### CLI
+
+```bash
+# Show axis information
+fontisan info variable.ttf
+
+# Example output:
+# Variable Font Axes: 2
+#   wght (Weight): 100 - 900, default: 400
+#   wdth (Width): 75 - 125, default: 100
+```
+
+### API
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+
+# List axes
+fvar.axes.each do |axis|
+  puts "Tag: #{axis.tag}"
+  puts "  Min: #{axis.min_value}"
+  puts "  Max: #{axis.max_value}"
+  puts "  Default: #{axis.default_value}"
+  puts "  Name: #{axis.name}"
+end
+```
+
+## Axis Properties
+
+Each axis has these properties:
+
+| Property | Description |
+|----------|-------------|
+| `tag` | Four-character axis identifier (e.g., `wght`) |
+| `min_value` | Minimum value on the axis |
+| `max_value` | Maximum value on the axis |
+| `default_value` | Default value when no variation applied |
+| `name` | Human-readable axis name |
+
+## Registered Axes
+
+### Weight (`wght`)
+
+Controls font weight.
+
+```ruby
+# Range: typically 100-900
+# Common values:
+# 100 - Thin
+# 200 - Extra Light
+# 300 - Light
+# 400 - Regular
+# 500 - Medium
+# 600 - Semi Bold
+# 700 - Bold
+# 800 - Extra Bold
+# 900 - Black
+```
+
+### Width (`wdth`)
+
+Controls font width.
+
+```ruby
+# Range: typically 50-200 (percentage)
+# Common values:
+# 50  - Ultra Condensed
+# 62.5 - Extra Condensed
+# 75  - Condensed
+# 87.5 - Semi Condensed
+# 100 - Normal
+# 112.5 - Semi Expanded
+# 125 - Expanded
+# 150 - Extra Expanded
+# 200 - Ultra Expanded
+```
+
+### Slant (`slnt`)
+
+Controls slant angle.
+
+```ruby
+# Range: -90 to 90 degrees
+# Common values:
+# 0   - Upright
+# -12 - Typical italic slant
+```
+
+### Italic (`ital`)
+
+Binary italic toggle.
+
+```ruby
+# Range: 0-1
+# 0 - Roman (upright)
+# 1 - Italic
+```
+
+### Optical Size (`opsz`)
+
+Controls optical sizing.
+
+```ruby
+# Range: varies by font
+# Example values:
+# 8   - Caption
+# 12  - Text
+# 24  - Subhead
+# 72  - Display
+```
+
+## Named Instances
+
+### List Named Instances
+
+```bash
+# CLI
+fontisan instance variable.ttf --list-instances
+
+# Example output:
+# Named Instances: 6
+#   0: Thin (wght=100)
+#   1: Light (wght=300)
+#   2: Regular (wght=400)
+#   3: Medium (wght=500)
+#   4: Bold (wght=700)
+#   5: Black (wght=900)
+```
+
+### API Access
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+
+# List named instances
+fvar.instances.each_with_index do |instance, index|
+  puts "#{index}: #{instance.name}"
+  instance.coordinates.each do |tag, value|
+    puts "  #{tag} = #{value}"
+  end
+end
+```
+
+## Using Named Instances
+
+### CLI
+
+```bash
+# Generate using instance index
+fontisan instance variable.ttf --named-instance 0 --output thin.ttf
+
+# Generate using instance name
+fontisan instance variable.ttf --named-instance "Bold" --output bold.ttf
+```
+
+### API
+
+```ruby
+# Get named instance coordinates
+fvar = font.tables['fvar']
+instance = fvar.instances.find { |i| i.name == "Bold" }
+
+# Generate instance with those coordinates
+writer = Fontisan::Variation::InstanceWriter.new(font)
+bold_font = writer.generate_instance(instance.coordinates)
+```
+
+## avar Table
+
+The avar (Axis Variation) table defines non-linear axis value mappings.
+
+```ruby
+# Check for avar table
+avar = font.tables['avar']
+
+if avar
+  puts "Non-linear interpolation present"
+  avar.mappings.each do |tag, map|
+    puts "#{tag}: #{map}"
+  end
+end
+```
+
+## STAT Table
+
+The STAT (Style Attributes) table provides style attributes and axis value names.
+
+```ruby
+stat = font.tables['STAT']
+
+if stat
+  # Get axis values
+  stat.axis_values.each do |axis_value|
+    puts "#{axis_value.name}: #{axis_value.value}"
+  end
+end
+```

data/docs/guide/variable-fonts/conversion.md

@@ -0,0 +1,197 @@
+---
+title: Format Conversion
+---
+
+# Format Conversion
+
+Convert variable fonts between formats while preserving or converting variation data.
+
+## Conversion Strategy
+
+### Compatible Formats (Same Outline)
+
+- Variable TTF ↔ Variable TTF/WOFF/WOFF2: All variation tables preserved
+- Variable OTF ↔ Variable OTF/WOFF/WOFF2: All variation tables preserved
+
+### Convertible Formats (Different Outline)
+
+- Variable TTF ↔ Variable OTF: Common tables preserved (fvar, avar, STAT, metrics)
+- Outline-specific tables require conversion (gvar ↔ CFF2 blend)
+
+### Unsupported
+
+- Variable fonts to SVG: Creates instance at default coordinates
+
+## CLI Usage
+
+### Preserve Variation
+
+```bash
+# Variable TTF to WOFF2 (preserves all variation)
+fontisan convert variable.ttf --to woff2 --output variable.woff2
+
+# Variable OTF to WOFF2 (preserves all variation)
+fontisan convert variable.otf --to woff2 --output variable.woff2
+```
+
+### Convert Outline Format
+
+```bash
+# Variable TTF to OTF (preserves common variation tables)
+fontisan convert variable.ttf --to otf --output variable.otf
+
+# Note: Shows warning about gvar → CFF2 conversion
+# Preserves: fvar, avar, STAT, HVAR, VVAR, MVAR
+# Does not preserve: gvar (requires conversion to CFF2)
+```
+
+### Create Static Font
+
+```bash
+# Remove all variation data
+fontisan convert variable.ttf --to ttf --output static.ttf --no-preserve-variation
+
+# Creates static font at default variation coordinates
+```
+
+## Ruby API
+
+### Preserve Variation
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+
+# Convert with variation preservation
+options = Fontisan::ConversionOptions.new(
+  preserve_variation: true
+)
+
+Fontisan::FontWriter.write(font, 'variable.woff2', options: options)
+```
+
+### Convert Outline Format
+
+```ruby
+# Variable TTF to OTF
+converter = Fontisan::Converters::OutlineConverter.new
+
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  preserve_variation: true  # Preserves fvar, avar, STAT
+)
+
+result = converter.convert(font, options: options)
+```
+
+### Remove Variation
+
+```ruby
+# Create static font at default coordinates
+writer = Fontisan::Variation::InstanceWriter.new(font)
+static_font = writer.generate_instance({})  # Empty hash = default values
+
+Fontisan::FontWriter.write(static_font, 'static.ttf')
+```
+
+## Tables Preserved
+
+### Same Outline Format
+
+All variation tables preserved:
+
+| Table | Preserved |
+|-------|-----------|
+| fvar | ✓ |
+| gvar | ✓ (TrueType) |
+| CFF2 | ✓ (OpenType) |
+| avar | ✓ |
+| STAT | ✓ |
+| HVAR | ✓ |
+| VVAR | ✓ |
+| MVAR | ✓ |
+
+### Cross Outline Format
+
+Common tables preserved:
+
+| Table | Preserved |
+|-------|-----------|
+| fvar | ✓ |
+| avar | ✓ |
+| STAT | ✓ |
+| HVAR | ✓ |
+| VVAR | ✓ |
+| MVAR | ✓ |
+| gvar | ✗ (requires CFF2 conversion) |
+| CFF2 | ✗ (requires gvar conversion) |
+
+## Limitations
+
+### gvar ↔ CFF2
+
+Converting between TrueType (gvar) and OpenType (CFF2) variation data is not fully implemented:
+
+- **TTF → OTF**: gvar variation data is lost
+- **OTF → TTF**: CFF2 blend operators are lost
+
+The fvar, avar, and STAT tables are preserved, but the actual glyph variation data is not.
+
+### Workaround
+
+Generate static instances before conversion:
+
+```ruby
+# Generate instances from variable TTF
+writer = Fontisan::Variation::InstanceWriter.new(font)
+instance = writer.generate_instance(wght: 700)
+
+# Convert instance to OTF
+converter = Fontisan::Converters::OutlineConverter.new
+otf_font = converter.convert(instance, options: otf_options)
+```
+
+## Web Font Conversion
+
+### Variable WOFF2
+
+```bash
+# Smallest file size with variation
+fontisan convert variable.ttf --to woff2 --output variable.woff2
+```
+
+Benefits:
+- 30-50% smaller than variable TTF
+- All variation preserved
+- Best for web delivery
+
+### Instance Generation for Web
+
+```bash
+# Generate instances as WOFF2
+fontisan instance variable.ttf --wght 700 --to woff2 --output bold.woff2
+```
+
+## Examples
+
+### Convert Variable Font Family
+
+```ruby
+require 'fontisan'
+
+# Load variable font
+font = Fontisan::FontLoader.load('variable.ttf')
+
+# Convert to WOFF2
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+Fontisan::FontWriter.write(font, 'variable.woff2', options: options)
+
+# Generate key instances
+fvar = font.tables['fvar']
+writer = Fontisan::Variation::InstanceWriter.new(font)
+
+[400, 500, 600, 700].each do |wght|
+  instance = writer.generate_instance(wght: wght)
+  Fontisan::FontWriter.write(instance, "weight-#{wght}.woff2", options: options)
+end
+```

data/docs/guide/variable-fonts/index.md

@@ -0,0 +1,84 @@
+---
+title: Variable Fonts Overview
+---
+
+# Variable Fonts Overview
+
+Variable fonts are OpenType fonts that contain multiple variations of a typeface in a single file. Instead of having separate font files for different weights, widths, or styles, a variable font uses variation axes to interpolate between different design extremes.
+
+## Key Tables
+
+| Table | Description |
+|-------|-------------|
+| `fvar` | Defines variation axes and named instances |
+| `gvar` | (TrueType) Glyph variation data as delta tuples |
+| `CFF2` | (OpenType) Variation data as blend operators |
+| `avar` | (Optional) Axis value mappings for non-linear interpolation |
+| `STAT` | (Optional) Style attributes and axis value names |
+| `HVAR/VVAR/MVAR` | (Optional) Metrics variation tables |
+
+## Variation Axes
+
+Each axis represents a design dimension along which the font can vary.
+
+### Common Registered Axes
+
+| Tag | Name | Range | Typical Values |
+|-----|------|-------|----------------|
+| `wght` | Weight | 1-1000 | 400 (Regular) to 700 (Bold) |
+| `wdth` | Width | 1-1000 | 75 (Condensed) to 125 (Expanded) |
+| `slnt` | Slant | -90 to 90 | Degrees |
+| `ital` | Italic | 0 or 1 | 0 (Roman), 1 (Italic) |
+| `opsz` | Optical Size | Varies | Point size for optical sizing |
+
+### Custom Axes
+
+Custom axes use four-character tags starting with uppercase letter:
+
+- `GRAD` — Grade
+- `XOPQ` — X-Optical-Size
+- `YOPQ` — Y-Optical-Size
+- `XTRA` — X-Transparency
+- And many others...
+
+## Named Instances
+
+Variable fonts can define named instances — predefined points in the design space with specific names:
+
+- "Regular"
+- "Bold"
+- "Light"
+- "Condensed Bold"
+- "Expanded Italic"
+
+## Guides
+
+- [Axes & Instances](/guide/variable-fonts/axes) — Working with axes and named instances
+- [Instance Generation](/guide/variable-fonts/instances) — Generate static fonts from variable fonts
+- [Format Conversion](/guide/variable-fonts/conversion) — Convert variable fonts between formats
+- [Named Instances](/guide/variable-fonts/named-instances) — Work with named instances
+- [Static Fonts](/guide/variable-fonts/static) — Convert to static fonts
+- [Advanced Topics](/guide/variable-fonts/advanced) — Advanced variable font operations
+
+## Quick Start
+
+### Get Axis Information
+
+```ruby
+font = Fontisan::FontLoader.load('variable.ttf')
+fvar = font.tables['fvar']
+
+fvar.axes.each do |axis|
+  puts "#{axis.tag}: #{axis.min_value} - #{axis.max_value}"
+end
+```
+
+### Generate Instance
+
+```bash
+# Generate bold instance
+fontisan instance variable.ttf --wght 700 --output bold.ttf
+
+# Generate with multiple axes
+fontisan instance variable.ttf --wght 700 --wdth 75 --output condensed-bold.ttf
+```