Font Engine Inspector

Real-time font rendering comparison for fonts.sanchaya.net

Compare how your Kannada fonts render across HarfBuzz and your browser, in real-time.

Upload a .ttf or .otf font and instantly see:

• Native browser rendering (your platform: Safari, Chrome, Firefox, Edge)
• HarfBuzz reference rendering (ground-truth text shaping engine)
• Side-by-side comparison with overlay/diff modes
• Raw glyph metrics (advances, offsets, clusters) for debugging

No pre-generation, no static images — pure on-demand rendering.

---

🚀 Quick Start (5 minutes)

Requirements

• Node.js 16+
• Python 3.10+
• npm or yarn

Setup

1. Clone the repo

   git clone https://github.com/sanchaya/font-engine-inspector.git
   cd font-engine-inspector

2. Install dependencies

   npm install
   pip install -r requirements.txt --break-system-packages

3. Run

   npm start
   # Server running on http://localhost:3000
   # View: http://localhost:3000/engine-inspector

4. Test

   • Upload a Kannada .ttf font
   • Enter test text (try: ಕರ್ನಾಟಕ or ಕ್ಷ)
   • Click Render
   • See results instantly

---

📁 Project Structure

.
├── src/
│   └── app.js                 # Express.js main app
├── routes/
│   └── engine-inspector.js    # API endpoints (/api/render/hb, /api/test-strings)
├── public/
│   ├── index.html             # Sanchaya-branded viewer UI
│   ├── css/
│   │   └── sanchaya-theme.css # Deep blue, gold, Kannada-inspired styling
│   ├── js/                    # (future: client-side utilities)
│   └── fonts/                 # (optional: reference fonts)
├── bin/
│   └── render-harfbuzz.py     # Python worker: HarfBuzz + FreeType rendering
├── docs/                      # Documentation
├── tests/                      # Unit tests
└── package.json

---

🎨 Features

Interactive Viewer

• Drag-and-drop font upload (or file picker)
• Live text input — modify test string, see results
• Font size slider (12px–200px)
• OpenType feature toggle — enable/disable kern, liga, etc. in JSON format
• Multiple view modes:
  • Side-by-side — browser native vs HarfBuzz
  • Overlay — red/blue fringing to spot positioning drift
• Glyph inspector table — see advances, offsets, cluster IDs

Backend API

• POST /api/render/hb — Render text with HarfBuzz + FreeType

  • Accepts multipart font upload or reference to existing font
  • Returns PNG as base64 + raw glyph metrics

• GET /api/test-strings — Curated Kannada test cases

  • 7 categories: conjuncts, reph, vattu, matras, punctuation, mixed text, long passage
  • ~31 test strings targeting real-world kerning trouble spots

Sanchaya Branding

• Deep blue & gold color palette (Indian heritage aesthetic)
• Kannada typography integrated in headers
• Professional UI — matches fonts.sanchaya.net design language
• Responsive design — works on mobile, tablet, desktop

---

🔧 Configuration

Environment Variables

Create a .env file:

# Port to run on (default: 3000)
PORT=3000

# Environment (development or production)
NODE_ENV=development

# Path to fonts directory (optional)
FONTS_DIR=./public/fonts

Python Render Script

The bin/render-harfbuzz.py script is called by Node via subprocess. It:

1. Loads a font with HarfBuzz
2. Shapes text (produces glyph IDs, advances, offsets)
3. Rasterizes glyphs with FreeType
4. Outputs PNG + JSON glyph data

Usage directly:

python3 bin/render-harfbuzz.py <font.ttf> <text> <output.png> [size] [script] [language] [features]

Example:

python3 bin/render-harfbuzz.py fonts/Kannada.ttf "ಕನ್ನಡ" /tmp/out.png 64 "Knda" "kan" '{"kern": 1}'

---

📊 API Reference

POST /api/render/hb

Multipart file upload:

curl -X POST http://localhost:3000/api/render/hb \
  -F "fontFile=@font.ttf" \
  -F "text=ಕನ್ನಡ" \
  -F "fontSize=72" \
  -F "features={\"kern\": 1}"

JSON (for existing fonts):

curl -X POST http://localhost:3000/api/render/hb \
  -H "Content-Type: application/json" \
  -d '{
    "fontPath": "Kannada.ttf",
    "text": "ಕನ್ನಡ",
    "fontSize": 72,
    "script": "Knda",
    "language": "kan",
    "features": {"kern": 1, "liga": 0}
  }'

Response:

{
  "ok": true,
  "image": "data:image/png;base64,...",
  "width": 320,
  "height": 100,
  "glyph_count": 5,
  "font_size": 72,
  "padding": 20,
  "glyphs": [
    {
      "glyph_id": 12,
      "cluster": 0,
      "x_advance": 450,
      "y_advance": 0,
      "x_offset": 0,
      "y_offset": 0
    },
    ...
  ]
}

GET /api/test-strings

Returns curated Kannada test strings organized by category.

curl http://localhost:3000/api/test-strings

Response:

{
  "sets": [
    {
      "id": "conjuncts",
      "label": "Conjuncts (Ottakshara)",
      "note": "Full ligature conjuncts...",
      "strings": ["ಕ್ಷ", "ಜ್ಞ", "ತ್ರ", ...]
    },
    ...
  ]
}

---

⚡ Performance

• First render: ~500ms (Python startup overhead)
• Subsequent renders: ~200ms (fast shaping/rasterization)
• Browser native render: <50ms (Canvas 2D)
• Total UI response: <1 second per render

For production with heavy load, consider:

• Caching renders by font MD5 + text hash
• Worker pool to keep Python processes warm
• Rate limiting to prevent abuse (e.g., 1 render per user per 500ms)

---

🌍 Deployment

Docker

FROM node:18-bullseye

RUN apt-get update && apt-get install -y python3 python3-pip

WORKDIR /app
COPY . .
RUN npm install
RUN pip install -r requirements.txt

EXPOSE 3000
CMD ["npm", "start"]

Railway, Render, Vercel (with serverless limits)

⚠️ Note: Python subprocess (HarfBuzz rendering) may timeout on serverless platforms. Recommended for traditional VPS/container deployment.

Production Checklist

• Set NODE_ENV=production
• Configure PORT in environment
• Enable CORS if serving on different domain
• Add rate limiting middleware
• Enable request logging
• Set up error monitoring (e.g., Sentry)
• Cache renders (Redis or in-memory)
• Test with real-world font files

---

🧪 Testing

# Run Node tests
npm test

# Lint code
npm run lint

# Test Python render script directly
python3 bin/render-harfbuzz.py public/fonts/Kannada.ttf "ಕನ್ನಡ" /tmp/test.png 72

---

🤝 Contributing

Contributions welcome! Areas for improvement:

• Add more test strings for other Indic scripts
• Support for macOS CoreText / Windows DirectWrite rendering
• Caching layer for high-traffic deployments
• WebSocket support for real-time font editing
• Support for variable fonts (wght, wdth axes)
• Export comparison reports as PDF

Please open issues on GitHub.

---

📜 License

MIT License — Free for commercial and non-commercial use.

Uses open-source libraries:

• HarfBuzz — OFL (text shaping)
• FreeType — FTL/GPL (font rasterization)
• fontTools — MIT
• Express.js — MIT
• Pillow — HPND (image processing)

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: Sanchaya contact

---

Happy font testing! 🎨