eink-template-gen 0.3.0

Pixel-perfect template generator for e-ink devices like Supernote, reMarkable, and Boox

Table of Contents

1. Badges
2. About
3. Why This Tool?
4. What this tool is NOT
5. Features
6. Installation
7. Full Documentation
8. Supported Devices
9. Configuration
10. Usage Examples
    1. Basic Templates
11. Output
12. Contributing
13. License
14. Credits

Badges

About

A device-agnostic command-line tool for generating mathematically balanced, pixel-perfect page templates for e-ink devices. Developed with the Supernote Manta, this tool supports millimeter or pixel specifications for human-readable, technically-precise, or true-scale template configurations.

Why This Tool?

This tool was born from the frustration of online generators that fail to handle "half-lines" or pixel alignment, resulting in uneven, blurry, or aliased lines on high-DPI e-ink screens. This generator calculates exact pixel-perfect margins and spacing based on your device's specific resolution and DPI, ensuring every line is crisp and uniform.

Problem: Blurry Lines (Fractional Pixels) "The image on the left (using --true-scale) shows blurry, aliased lines caused by fractional pixels. The image on the right (default) shows the tool's pixel-perfect rounding, which ensures every line is crisp."

"Before" (Blurry)	"After" (Pixel-Perfect)

Problem: Toolbar/Overlay The image on the left (built-in template) shows the file name and page count overlays displaying over the template. The image on the right shows the lines being automatically adjusted to render within the margins.

"Before" (OEM Template)	"After" (Pixel-Perfect)

Problem: Half-Spaced Lines and Cells The image on the left (using --enforce-margins) shows lines and cells being cut off abruptly at the exact margin. The image on the right (default) shows the tool's smart grid-centering, which automatically pads the margins to prevent 'half-cells' and create a cleaner, more balanced page.

"Before" (cut-off cells)	"After" (Pixel-Perfect)

Problem: Grid Misalignment The image on the left (default) shows a grid being awkwardly cut off. The image on the right (--force-major-alignment) shows the margins being automatically adjusted to end perfectly on a major grid line.

"Before" (Misaligned)	"After" (Force-Aligned)

What this tool is NOT

• Calendar/Schedule Generator
• Task/To Do list Generator
• Color e-ink Template Generator (yet)
• Real-Time GUI Editor
• Monetized or Paywalled Tool

Features

• Pixel-Perfect Alignment: Automatically adjusts margins and spacing to eliminate blurry lines and aliasing artifacts.
• Multiple Template Types: Generate lined, dotgrid, grid, manuscript, french ruled, music staff, isometric, hexgrid, and hybrid pages.
• Flexible Layouts: Create single pages, uniform N x M grids, mixed-type grids, and complex, ratio-based layouts using JSON.
• Decorative Title Pages: Generate artistic cover pages using Truchet tiles, L-System fractals, noise fields, and more.
• Powerful Customization: Add major/minor lines, decorative separators, line numbers, and axis labels.
• Flexible Spacing: Define layouts using millimeters (default), exact pixels, or by fitting an exact line count.

Installation

pip install eink-template-gen

Full Documentation

For detailed guides, feature deep-dives, and advanced examples, please see the docs/ directory:

• Features
  • Template Types
  • Flexible Layouts
  • Decorative Title Pages
• Guides
  • Customization Options (Separators, Labels, etc.)
  • Spacing Modes (mm, px, line count)
• Examples
  • Advanced Usage Examples
• Reference
  • Command Reference (All Flags)
  • Technical Details (Algorithm, Palette)

Supported Devices

Built-in device profiles:

• Supernote Manta (10.7", 1920x2560, 300 DPI)
• Supernote A5 X (10.3", 1404x1872, 226 DPI)
• Supernote A6 X (7.8", 1404x1872, 300 DPI)
• Supernote Nomad (7.8", 1404x1872, 300 DPI)

Configuration

Set a default device to avoid specifying --device every time:

eink-template-gen util set-default-device manta
eink-template-gen util set-default-margin 10

Configuration is stored locally in config.json.

Usage Examples

Basic Templates

# Simple lined paper
eink-template-gen lined --spacing 7mm

# Dot grid with major crosshairs
eink-template-gen dotgrid --spacing 5mm --major_every 5

# Graph paper with axis labels
eink-template-gen grid --spacing 5mm --major_every 5 --axis-labels

# Manuscript paper for handwriting practice
eink-template-gen manuscript --spacing 8mm

For more complex examples, including multi, layout, and title commands, see the Advanced Usage Examples documentation.

Output

Templates are saved to out/<device_id>/ by default:

out/
├── manta/
│   ├── lined_7mm_0_5px.png
│   ├── grid_5mm_0_5px_h-wavy.png
│   └── title_truchet_10mm_seed42.png
└── a5x/
    └── lined_6mm_71px.png

Use --output-dir and --filename to customize output location.

Contributing

Contributions are welcome! This project uses:

• Cairo for high-quality 2D graphics rendering
• Python 3.8+
• Pure Python implementation (no external dependencies for noise/fractals)

License

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for details.

Credits

Developed for the Supernote community with love for pixel-perfect templates.