fontisan 0.2.13 → 0.2.16

data/docs/guide/conversion/curves.md

@@ -0,0 +1,246 @@
+---
+title: Curve Conversion
+---
+
+# Curve Conversion
+
+Fontisan handles conversion between TrueType's quadratic Bézier curves and OpenType/CFF's cubic Bézier curves.
+
+## Overview
+
+| Format | Curve Type | Math |
+|--------|------------|------|
+| TrueType (TTF) | Quadratic Bézier | 1 control point |
+| OpenType/CFF (OTF) | Cubic Bézier | 2 control points |
+
+## Quadratic Bézier Curves (TrueType)
+
+Quadratic curves have one control point between two on-curve points:
+
+```
+P0 ---- Q1 ---- P2
+
+Where:
+- P0, P2 are on-curve points
+- Q1 is the control point
+```
+
+### Formula
+
+```
+B(t) = (1-t)²·P0 + 2(1-t)t·Q1 + t²·P2
+```
+
+## Cubic Bézier Curves (OpenType/CFF)
+
+Cubic curves have two control points:
+
+```
+P0 -- C1 -- C2 -- P3
+
+Where:
+- P0, P3 are on-curve points
+- C1, C2 are control points
+```
+
+### Formula
+
+```
+B(t) = (1-t)³·P0 + 3(1-t)²t·C1 + 3(1-t)t²·C2 + t³·P3
+```
+
+## Quadratic → Cubic (TTF → OTF)
+
+This conversion is mathematically exact.
+
+### Conversion Process
+
+```ruby
+# TrueType quadratic: P0, Q1, P2
+# Converts to cubic: P0, C1, C2, P2
+#
+# C1 = P0 + (2/3)(Q1 - P0)
+# C2 = P2 + (2/3)(Q1 - P2)
+```
+
+### Example
+
+```ruby
+# Source: TrueType quadratic curve
+p0 = [100, 100]
+q1 = [150, 200]  # control point
+p2 = [200, 100]
+
+# Convert to cubic
+c1 = [
+  p0[0] + (2.0/3) * (q1[0] - p0[0]),  # 133.33
+  p0[1] + (2.0/3) * (q1[1] - p0[1])   # 166.67
+]
+c2 = [
+  p2[0] + (2.0/3) * (q1[0] - p2[0]),  # 166.67
+  p2[1] + (2.0/3) * (q1[1] - p2[1])   # 166.67
+]
+
+# Result: [100, 100] -> [133.33, 166.67] -> [166.67, 166.67] -> [200, 100]
+```
+
+### Characteristics
+
+- **Exact** — No approximation needed
+- **Point count may increase** — Due to implicit on-curve points in TrueType
+
+## Cubic → Quadratic (OTF → TTF)
+
+This conversion requires approximation since cubic curves cannot be exactly represented as quadratic.
+
+### Approximation Methods
+
+Fontisan uses the midpoint approximation method:
+
+```ruby
+# Cubic: P0, C1, C2, P3
+# Approximate with multiple quadratic curves
+#
+# Method: Subdivide until quadratic fits within tolerance
+```
+
+### Tolerance Setting
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  curve_tolerance: 0.5  # Lower = more accurate, more points
+)
+```
+
+| Tolerance | Accuracy | Point Count |
+|-----------|----------|-------------|
+| 1.0 | Lower | Fewer |
+| 0.5 | Medium | Medium |
+| 0.1 | Higher | More |
+
+### Example
+
+```ruby
+# Source: Cubic curve
+p0 = [100, 100]
+c1 = [120, 200]
+c2 = [180, 200]
+p3 = [200, 100]
+
+# May require 2+ quadratic curves:
+# Quad 1: P0 -> Q1 -> P_mid
+# Quad 2: P_mid -> Q2 -> P3
+```
+
+### Characteristics
+
+- **Approximate** — Some precision loss unavoidable
+- **Point count increases** — Multiple quadratic curves per cubic
+- **Tolerance affects quality** — Lower tolerance = more accurate
+
+## Implicit On-Curve Points
+
+TrueType uses an optimization where on-curve points can be implicit:
+
+```ruby
+# If two consecutive off-curve points exist,
+# the midpoint is an implicit on-curve point
+#
+# Q1 ---- (implicit P) ---- Q2
+#
+# P = (Q1 + Q2) / 2
+```
+
+This can reduce point count but must be expanded for conversion.
+
+## Curve Conversion Options
+
+### CLI
+
+```bash
+# Enable curve conversion
+fontisan convert font.ttf --to otf --convert-curves
+
+# With tolerance (OTF → TTF only)
+fontisan convert font.otf --to ttf --curve-tolerance 0.5
+```
+
+### API
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: {
+    convert_curves: true
+  },
+  curve_tolerance: 0.5  # For OTF → TTF
+)
+```
+
+## Preserving Curves
+
+To skip curve conversion (same-format operations):
+
+```ruby
+options = Fontisan::ConversionOptions.new(
+  opening: { convert_curves: false }
+)
+```
+
+## Quality vs Size Trade-off
+
+### TTF → OTF
+
+- **No trade-off** — Exact conversion
+- File size may increase due to explicit points
+
+### OTF → TTF
+
+- **Trade-off exists** — Approximation required
+- Lower tolerance = better quality, larger files
+- Higher tolerance = lower quality, smaller files
+
+```bash
+# High quality
+fontisan convert font.otf --to ttf --curve-tolerance 0.1
+
+# Smaller file
+fontisan convert font.otf --to ttf --curve-tolerance 1.0
+```
+
+## Technical Details
+
+### Checking Curve Types
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+# Check glyph format
+glyph = font.glyphs[0]
+puts glyph.curve_type  # :quadratic or :cubic
+```
+
+### Counting Points
+
+```ruby
+font = Fontisan::FontLoader.load('font.ttf')
+
+total_on_curve = 0
+total_off_curve = 0
+
+font.glyphs.each do |glyph|
+  glyph.contours.each do |contour|
+    contour.points.each do |point|
+      if point.on_curve?
+        total_on_curve += 1
+      else
+        total_off_curve += 1
+      end
+    end
+  end
+end
+
+puts "On-curve: #{total_on_curve}"
+puts "Off-curve: #{total_off_curve}"
+```

data/docs/guide/conversion/index.md

@@ -0,0 +1,157 @@
+---
+title: Conversion Overview
+---
+
+# Conversion Overview
+
+Fontisan's conversion system is based on the TypeTool 3 manual's recommended options for different font format conversions. The system provides:
+
+- **Type-safe option validation** — Catch errors before conversion
+- **Format-specific defaults** — Recommended options per conversion type
+- **Named presets** — Common workflows pre-configured
+- **Fine-grained control** — Override any option when needed
+
+## Quick Start
+
+### Using the CLI
+
+```bash
+# Basic conversion
+fontisan convert input.ttf --to otf --output output.otf
+
+# Show recommended options
+fontisan convert input.ttf --to otf --show-options
+
+# Use a preset
+fontisan convert font.pfb --to otf --preset type1_to_modern --output output.otf
+
+# Custom options
+fontisan convert input.ttf --to otf --autohint --hinting-mode auto --output output.otf
+```
+
+### Using the API
+
+```ruby
+require 'fontisan'
+
+# Get recommended options
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+
+# Use a preset
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+
+# Build custom options
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: { autohint: true, convert_curves: true },
+  generating: { hinting_mode: "auto" }
+)
+
+# Convert with options
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, options: options)
+```
+
+## Supported Formats
+
+### Input Formats
+
+| Format | Description | Extensions |
+|--------|-------------|------------|
+| TTF | TrueType Font | .ttf |
+| OTF | OpenType/CFF Font | .otf |
+| Type 1 | Adobe Type 1 Font | .pfb, .pfa |
+| TTC | TrueType Collection | .ttc |
+| OTC | OpenType Collection | .otc |
+| dfont | Apple Data Fork Font | .dfont |
+| WOFF | Web Open Font Format | .woff |
+| WOFF2 | Web Open Font Format 2 | .woff2 |
+| SVG | SVG Font | .svg |
+
+### Output Formats
+
+All input formats can be converted to: **TTF, OTF, WOFF, WOFF2**
+
+Collections (TTC, OTC, dfont) can be converted between each other.
+
+## Conversion Guides
+
+- [TTF ↔ OTF](/guide/conversion/ttf-otf) — TrueType and OpenType conversion
+- [Type 1 → Modern](/guide/conversion/type1) — Converting legacy Type 1 fonts
+- [Web Formats](/guide/conversion/web) — WOFF and WOFF2 optimization
+- [Collections](/guide/conversion/collections) — TTC, OTC, and dfont handling
+- [Curve Conversion](/guide/conversion/curves) — Quadratic ↔ Cubic curves
+- [Options Reference](/guide/conversion/options) — Complete option documentation
+
+## Presets
+
+Fontisan includes presets for common workflows:
+
+| Preset | Description |
+|--------|-------------|
+| `type1_to_modern` | Type 1 → OpenType for modern use |
+| `modern_to_type1` | OpenType → Type 1 for legacy systems |
+| `web_optimized` | Any → WOFF2 for web delivery |
+| `archive_to_modern` | Collection → Individual OTF files |
+
+```ruby
+# Using presets
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+```
+
+## Hinting Modes
+
+Control hinting behavior with `--hinting-mode`:
+
+| Mode | Description | Use Case |
+|------|-------------|----------|
+| `preserve` | Keep original hints | Same-format conversions |
+| `auto` | Apply automatic hinting | Cross-format conversions |
+| `none` | Remove all hints | Maximum file size reduction |
+| `full` | Full hint conversion | Print applications |
+
+## Best Practices
+
+1. **Use presets when possible** — Presets are optimized for common workflows
+2. **Show options first** — Use `--show-options` to understand what will be applied
+3. **Test conversions** — Always verify output fonts in target applications
+4. **Preserve metadata** — Keep copyright and license information intact
+
+## Troubleshooting
+
+### Conversion Fails
+
+```bash
+# Check if source file is valid
+fontisan info font.ttf
+
+# Validate source font
+fontisan validate font.ttf
+
+# Try with verbose flag
+fontisan convert font.ttf --to otf --verbose
+```
+
+### Output Font Too Large
+
+```bash
+# Enable optimization
+fontisan convert font.ttf --to otf --optimize-tables
+
+# Remove hinting
+fontisan convert font.ttf --to otf --hinting-mode none
+
+# Use web font format
+fontisan convert font.ttf --to woff2
+```
+
+### Poor Rendering Quality
+
+```bash
+# Use autohinting
+fontisan convert font.ttf --to otf --autohint --hinting-mode auto
+
+# Preserve original hints
+fontisan convert font.ttf --to otf --hinting-mode preserve
+```

data/docs/guide/conversion/options.md

@@ -0,0 +1,251 @@
+---
+title: Options Reference
+---
+
+# Options Reference
+
+Complete reference for Fontisan's conversion options.
+
+## Opening Options
+
+Opening options control how the source font is read and processed.
+
+| Option | Type | Description | Use Case |
+|--------|------|-------------|----------|
+| `decompose_composites` | Boolean | Decompose composite glyphs into simple glyphs | Target format doesn't support composites |
+| `convert_curves` | Boolean | Convert curve types during conversion | Quadratic ↔ Cubic conversion |
+| `scale_to_1000` | Boolean | Scale UPM to 1000 | Type 1 → OTF conversions |
+| `scale_from_1000` | Boolean | Scale from 1000 UPM | OTF → TTF conversions |
+| `autohint` | Boolean | Auto-hint the font | Source lacks hints or incompatible |
+| `generate_unicode` | Boolean | Generate Unicode from glyph names | Type 1 conversions |
+| `store_custom_tables` | Boolean | Preserve non-standard tables | Custom tables need preservation |
+| `store_native_hinting` | Boolean | Preserve native hinting data | Hints for source format |
+| `interpret_ot` | Boolean | Interpret OpenType layout features | GSUB/GPOS processing needed |
+| `read_all_records` | Boolean | Load all font dictionary records | Type 1 with custom data |
+| `preserve_encoding` | String | Preserve character encoding | Custom encoding required |
+
+## Generating Options
+
+Generating options control how the output font is written.
+
+| Option | Type | Description | Use Case |
+|--------|------|-------------|----------|
+| `write_pfm` | Boolean | Write PFM file | Type 1 output |
+| `write_afm` | Boolean | Write AFM file | Type 1 output |
+| `write_inf` | Boolean | Write INF file | Type 1 output |
+| `select_encoding_automatically` | Boolean | Auto-select encoding | Type 1 output |
+| `hinting_mode` | String | Hint mode: preserve, auto, none, full | Control hinting |
+| `decompose_on_output` | Boolean | Decompose composites in output | Target doesn't support composites |
+| `write_custom_tables` | Boolean | Write custom tables | Preserve non-standard tables |
+| `optimize_tables` | Boolean | Enable table optimization | Reduce file size |
+| `reencode_first_256` | Boolean | Reencode first 256 glyphs | Type 1 output |
+| `encoding_vector` | String | Custom encoding vector | Type 1 output |
+| `compression` | String | Compression: zlib, brotli, none | Web font output |
+| `transform_tables` | Boolean | Transform tables for output | Format-specific |
+| `preserve_metadata` | Boolean | Preserve copyright/license metadata | Maintain metadata |
+| `strip_metadata` | Boolean | Remove metadata | Reduce file size |
+| `target_format` | String | Collection target format | Collection conversions |
+| `curve_tolerance` | Float | Curve approximation tolerance | OTF → TTF |
+
+## CLI Option Mapping
+
+### Opening Options
+
+```bash
+# Decompose composite glyphs
+--decompose           # Enable decomposition
+--no-decompose        # Preserve composite glyphs
+
+# Curve conversion
+--convert-curves      # Convert quadratic ↔ cubic
+
+# UPM scaling
+--scale-to-1000       # Scale to 1000 UPM
+--scale-from-1000     # Scale from 1000 UPM
+
+# Hinting
+--autohint            # Apply automatic hinting
+
+# Unicode and encoding
+--generate-unicode    # Generate Unicode from glyph names
+--preserve-encoding   # Preserve character encoding
+
+# Table handling
+--preserve-custom-tables  # Preserve non-standard tables
+--interpret-ot            # Interpret OpenType tables
+```
+
+### Generating Options
+
+```bash
+# Type 1 metrics files
+--write-pfm           # Generate PFM file
+--write-afm           # Generate AFM file
+--write-inf           # Generate INF file
+
+# Encoding
+--auto-encoding        # Auto-detect encoding
+--encoding VECTOR      # Use specific encoding vector
+
+# Hinting
+--hinting-mode MODE   # preserve|auto|none|full
+
+# Optimization
+--optimize-tables      # Enable optimization
+--no-optimization      # Disable optimization
+
+# Metadata
+--preserve-metadata    # Preserve copyright/license
+--strip-metadata       # Remove metadata
+
+# Collections
+--target-format FORMAT # ttf|otf|preserve
+
+# Curves
+--curve-tolerance N   # Approximation tolerance (0.1-2.0)
+```
+
+### Preset Option
+
+```bash
+--preset NAME          # type1_to_modern, web_optimized, etc.
+```
+
+## Hinting Modes
+
+| Mode | Description | Best For |
+|------|-------------|----------|
+| `preserve` | Keep original hints | Same-format, compatible hints |
+| `auto` | Apply automatic hinting | Cross-format, missing hints |
+| `none` | Remove all hints | Web fonts, smallest size |
+| `full` | Full hint conversion | Print, maximum quality |
+
+### preserve
+
+```ruby
+generating: { hinting_mode: "preserve" }
+```
+
+- Works best when source and target formats share hinting systems
+- TTF → TTF: TrueType instructions preserved
+- OTF → OTF: PostScript hints preserved
+- Cross-format: May result in lost hints
+
+### auto
+
+```ruby
+generating: { hinting_mode: "auto" }
+```
+
+- TTF → OTF: Autohinting applied to CFF output
+- OTF → TTF: Autohinting applied to TrueType output
+- Type 1 → Modern: Autohinting based on outlines
+
+### none
+
+```ruby
+generating: { hinting_mode: "none" }
+```
+
+- Smallest file size
+- No rendering optimizations
+- Useful when file size matters more than rendering
+
+### full
+
+```ruby
+generating: { hinting_mode: "full" }
+```
+
+- Attempts to preserve all hint information
+- May generate larger files
+- Best quality for print applications
+
+## Presets
+
+### type1_to_modern
+
+Type 1 fonts to modern OpenType format.
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:type1_to_modern)
+# From: :type1, To: :otf
+# opening: { generate_unicode: true, decompose_composites: false }
+# generating: { hinting_mode: "preserve", decompose_on_output: true }
+```
+
+### modern_to_type1
+
+Modern fonts to Type 1 format.
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:modern_to_type1)
+# From: :otf, To: :type1
+# opening: { convert_curves: true, scale_to_1000: true,
+#           autohint: true }
+# generating: { write_pfm: true, write_afm: true, write_inf: true }
+```
+
+### web_optimized
+
+Fonts optimized for web delivery.
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:web_optimized)
+# From: :otf, To: :woff2
+# opening: {}
+# generating: { compression: "brotli", transform_tables: true,
+#              optimize_tables: true, preserve_metadata: true }
+```
+
+### archive_to_modern
+
+Collection extraction and modernization.
+
+```ruby
+Fontisan::ConversionOptions.from_preset(:archive_to_modern)
+# From: :ttc, To: :otf
+# opening: { convert_curves: true, decompose_composites: false }
+# generating: { target_format: "otf", hinting_mode: "preserve" }
+```
+
+## Using Options
+
+### CLI
+
+```bash
+# Show options before conversion
+fontisan convert font.ttf --to otf --show-options
+
+# Use preset
+fontisan convert font.pfb --to otf --preset type1_to_modern
+
+# Custom options
+fontisan convert font.ttf --to otf \
+  --autohint \
+  --hinting-mode auto \
+  --optimize-tables \
+  --output font.otf
+```
+
+### API
+
+```ruby
+# Get recommended options
+options = Fontisan::ConversionOptions.recommended(from: :ttf, to: :otf)
+
+# Use preset
+options = Fontisan::ConversionOptions.from_preset(:web_optimized)
+
+# Build custom options
+options = Fontisan::ConversionOptions.new(
+  from: :ttf,
+  to: :otf,
+  opening: { autohint: true, convert_curves: true },
+  generating: { hinting_mode: "auto", optimize_tables: true }
+)
+
+# Convert with options
+converter = Fontisan::Converters::OutlineConverter.new
+tables = converter.convert(font, options: options)
+```