eink-template-gen 0.5.1

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

Table of Contents

1. Table of Contents
2. Badges
3. About
4. Why This Tool?
5. What this tool is NOT
6. Features
7. Installation
8. Quick Start (Wizard)
9. Full Documentation
10. Supported Devices
11. Configuration
12. Usage Examples
    1. Basic Templates
13. Output
14. AI-Assisted Development (ai-wizard-prompt.org)
15. Contributing
    1. Development Setup
16. License
17. Credits

Table of Contents

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

• Interactive Wizard: A guided, step-by-step terminal wizard to create complex templates without needing to memorize flags. Just run eink-template-gen --wizard.
• 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

Quick Start (Wizard)

For the easiest experience, use the interactive wizard.

1. Install the tool (if you haven't already):

   pip install eink-template-gen
   

2. Run the wizard:

   eink-template-gen --wizard
   

This will guide you step-by-step through selecting a device, template, and all the relevant options, then generate the file for you.

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.

AI-Assisted Development (ai-wizard-prompt.org)

This project includes a file named ai-wizard-prompt.org (and .md). This file is not used by the Python code.

It is a comprehensive "system prompt" or context file that defines the entire logic of the wizard as a persona for a Large Language Model (AI).

When to use it:

• Prototyping: Quickly test new or complex feature combinations without writing Python code for the wizard.
• Assistance: If you are unsure of the flags, you can have an AI act as the complete wizard to guide you and generate the final command or JSON file.

How to use it:

1. Open ai-wizard-prompt.org or ai-wizard-prompt.md.
2. Copy the entire contents of the file.
3. Paste the contents into a new chat session with a capable LLM (like Gemini, Claude, or ChatGPT).
4. On a new line after the pasted text, type: Okay, you are the eink-template-gen Wizard. Start.
5. The AI will then take on the persona of the wizard and begin asking you questions, one at a time, to build your template.

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)

Development Setup

To set up a development environment:

# Clone the repo
git clone https://github.com/calebc42/eink-template-gen.git
cd eink-template-gen

# Install in editable mode with dev/test dependencies
pip install -e .[dev,test]

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.