imagedit

A Rust CLI tool for generating PDF documents from image templates with customizable text overlays and QR codes.

Features

• Template-based Generation: Use any PNG image as a template
• Multi-element Support: Add multiple text fields and QR codes to a single document
• Flexible Positioning: Full control over x/y coordinates for each element
• Text Customization:
• Custom font files (TTF/OTF supported)
• Adjustable font sizes
• RGB/RGBA color support
• Horizontal centering option
• QR Code Generation: Add QR codes with custom content, size, and positioning
• PDF Export: Automatic conversion to PDF format using printpdf library
• Font Management: Load and reuse multiple fonts in a single document

Installation

Prerequisites

• Rust (1.70 or later)
• Cargo package manager

From crates.io

cargo install imagedit

Build from Source

git clone <repository-url>
cd imagedit
cargo build --release

The compiled binary will be available at target/release/imagedit.

Usage

Basic Example

imagedit \
--template badge-template.png \
--output my-badge \
--text "John Doe" \
--text-font-size 80.0 \
--text-x 0 \
--text-y 1250 \
--text-font ./font.otf \
--text-center true \
--text-color "0,0,0"

Command Line Options

Template and Output

| Option     | Short | Description                          | Required |
|------------|-------|--------------------------------------|----------|
| --template | -t    | Path to template image (PNG)         | Yes      |
| --output   | -o    | Output file name (without extension) | Yes      |

Text Elements

All text options use num_args = 1, meaning you can specify multiple texts
by repeating the flags. All text arrays must have matching lengths.

| Option           | Description                 | Example
|
|------------------|-----------------------------|-------------------------
-|
| --text           | Text content to display     | "John Doe"
|
| --text-font-size | Font size in points         | 80.0
|
| --text-x         | X coordinate (pixels)       | 0
|
| --text-y         | Y coordinate (pixels)       | 1250
|
| --text-font      | Path to font file (TTF/OTF) | ./font.otf
|
| --text-center    | Center text horizontally    | true or false
|
| --text-color     | RGB or RGBA color           | "0,0,0" or "255,0,0,128"
|

QR Code Elements

QR codes also use num_args = 1 for multiple QR codes. All QR arrays must
have matching lengths.

| Option      | Description                   | Example
          |
|-------------|-------------------------------|----------------------------
------------|
| --qr-text   | Content to encode in QR code  |
"550e8400-e29b-41d4-a716-446655440000" |
| --qr-size   | Minimum QR code size (pixels) | 500
          |
| --qr-x      | X coordinate (pixels)         | 0
          |
| --qr-y      | Y coordinate (pixels)         | 1780
          |
| --qr-center | Center QR code horizontally   | true or false
          |

Note: QR codes include a 30px white border for visibility.

Examples

Single Text Element

imagedit \
--template template.png \
--output certificate \
--text "Certificate of Achievement" \
--text-font-size 60.0 \
--text-x 0 \
--text-y 500 \
--text-font ./fonts/heading.otf \
--text-center true \
--text-color "0,0,128"

Multiple Text Elements

imagedit \
--template badge-template.png \
--output badge \
--text "Juan Carlos Pérez" \
--text-font-size 80.0 \
--text-x 0 \
--text-y 1250 \
--text-font ./font.otf \
--text-center true \
--text-color "0,0,0" \
--text "CC" \
--text-font-size 80.0 \
--text-x 0 \
--text-y 1435 \
--text-font ./font.otf \
--text-center true \
--text-color "255,255,255" \
--text "1234567890" \
--text-font-size 80.0 \
--text-x 0 \
--text-y 1565 \
--text-font ./font.otf \
--text-center true \
--text-color "0,0,0"

With QR Code

imagedit \
--template badge-template.png \
--output badge-with-qr \
--text "John Doe" \
--text-font-size 80.0 \
--text-x 0 \
--text-y 1250 \
--text-font ./font.otf \
--text-center true \
--text-color "0,0,0" \
--qr-text "550e8400-e29b-41d4-a716-446655440000" \
--qr-size 500 \
--qr-x 0 \
--qr-y 1780 \
--qr-center true

Using Semi-transparent Colors

imagedit \
--template background.png \
--output watermark \
--text "DRAFT" \
--text-font-size 120.0 \
--text-x 0 \
--text-y 800 \
--text-font ./font.otf \
--text-center true \
--text-color "255,0,0,80"  # Red with 80/255 opacity

Color Format

Colors are specified as comma-separated RGB or RGBA values:

- RGB: "r,g,b" - e.g., "255,0,0" for red
- RGBA: "r,g,b,a" - e.g., "255,0,0,128" for semi-transparent red

All values range from 0-255. If alpha is omitted, it defaults to 255 (fully
opaque).

Centering Behavior

When --text-center true or --qr-center true is specified:

- Text: The x coordinate is treated as the center point. Text width is
calculated and offset accordingly.
- QR Code: Centered horizontally based on the template image width. The x
coordinate is ignored when centering is enabled.

Output

The tool generates a PDF file at the specified output path. If PDF
conversion succeeds:
- Output: {output}.pdf

If ImageMagick is not available or conversion fails:
- Fallback: {output}.png

Template Requirements

- Format: PNG images
- Size: Any size (coordinates are in pixels relative to the template)
- Recommendation: Use high-resolution templates for better PDF quality

Dependencies

- image (0.25): Image loading and manipulation
- imageproc (0.25): Drawing primitives
- ab_glyph (0.2): Font handling and text measurement
- qrcode (0.14): QR code generation
- clap (4.5): CLI argument parsing
- printpdf (0.8.2): PDF document creation

Error Handling

Common errors and solutions:

- "Number of --text-X must match number of --text": Ensure all text arrays
have the same length
- "Number of --qr-X must match number of --qr-text": Ensure all QR arrays
have the same length
- Font loading errors: Verify font file exists and is a valid TTF/OTF file
- Template not found: Check template path and file format
- Invalid color format: Use "r,g,b" or "r,g,b,a" format with values 0-255

Project Structure

imagedit/
├── src/
│   ├── main.rs        # Entry point and orchestration
│   ├── cli.rs         # Command-line argument parsing
│   ├── models.rs      # Data structures (Text, QR)
│   ├── generator.rs   # Document generation engine
│   └── drawing.rs     # Low-level drawing utilities
├── Cargo.toml
└── README.md