eink-template-gen 0.2.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
   1. Development Version
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 (--no-auto-adjust) shows blurry, anti-aliased lines. The image on the right (default) shows the pixel-perfect, crisp lines this tool creates.

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

Problem: Margin Respect The image on the left (built-in template) shows the margins 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: 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

Development Version

If you want the latest unreleased features or want to contribute to development, you can install the package directly from this repository.

Clone the repository:

git clone [https://github.com/calebc42/eink-template-gen.git](https://github.com/calebc42/eink-template-gen.git)
cd eink-template-gen

Create and activate a virtual environment:

# On macOS/Linux
python3 -m venv .venv
source .venv/bin/activate

# On Windows
python -m venv .venv
.\.venv\Scripts\activate

Install in editable mode: This links the command eink-template-gen to your local source code, so any changes you make are immediately reflected.

pip install -e .

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.