BulkTextRenderer

A high-performance CLI tool for bulk rendering text onto PDF, PNG, and JPEG templates. Perfect for generating personalized invitations, certificates, name cards, and other documents from a CSV list of names or text entries.

Available as both a JAR (universal compatibility) and native executable (platform-specific, fast startup).

Features

Multiple Format Support: Render text on PDF, PNG, JPG, and JPEG template files
Bulk Processing: Process multiple entries from a CSV file in one command
Multi-Column CSV: Support for name,prefix,postfix format with automatic text assembly
Adaptive Threading: Automatically uses sequential processing for small batches (<10 jobs), parallel for larger batches
Flexible Text Positioning: Precise X/Y coordinate placement with pixel or millimeter units
Unified Coordinate System: Top-left origin (0,0) for all formats
Text Alignment: Left, center, or right alignment options
Custom Fonts: Use system fonts or built-in PDF fonts
Customizable Output: Add prefix and postfix to output filenames
Progress Tracking: Real-time progress feedback during processing
Configurable Logging: Verbose and debug modes for troubleshooting
Native Image Support: Compile to platform-specific native executable with GraalVM

Prerequisites

For JAR

Java 24 or higher

For Native Build

GraalVM 24 or higher (Oracle GraalVM recommended)
Gradle 8.x (wrapper included)

Installation

Option 1: JAR (Recommended for PNG/JPEG)

Download the latest JAR from Releases:

java -jar BulkTextRenderer-{VERSION}.jar --help

Advantages:

✅ Universal - works on all platforms (macOS, Linux, Windows)
✅ Full format support (PDF, PNG, JPEG)
✅ No platform-specific dependencies

Requirements: Java 24+

Option 2: Native Executable (Platform-Specific)

Download platform-specific native executable from Releases:

./BulkTextRenderer --help

Advantages:

✅ Fast startup time (~instant)
✅ Lower memory footprint
✅ No JRE required

Limitations:

⚠️ macOS: PDF only (PNG/JPEG not supported - see #28)
✅ Linux: Full support (PDF, PNG, JPEG)
✅ Windows: Full support (PDF, PNG, JPEG)

Platform Compatibility Matrix

Platform	JAR	Native Exec	PDF	PNG	JPEG
macOS	✅	✅	✅	✅ (JAR) / ❌ (Native)	✅ (JAR) / ❌ (Native)
Linux	✅	✅	✅	✅	✅
Windows	✅	✅	✅	✅	✅

Note: On macOS, use the JAR for PNG/JPEG rendering. The native executable only supports PDF due to GraalVM AWT limitations.

Build Instructions

Build the Project

./gradlew build

Run Tests

./gradlew test

Build Fat JAR

./gradlew jar

The JAR file will be created at: build/libs/BulkTextRenderer-{VERSION}.jar

Build Native Executable

Requires GraalVM 24:

# Install GraalVM (via sdkman)
sdk install java 24.0.2-graal

# Build native image
./gradlew nativeCompile

The native executable will be at: build/native/nativeCompile/BulkTextRenderer

Note: On macOS, the native executable will only support PDF rendering (see #28).

Usage

Basic Usage (JAR)

java -jar BulkTextRenderer-{VERSION}.jar \
  -t template.pdf \
  -c names.csv \
  -o output \
  --x 297 \
  --y 500

Basic Usage (Native)

./BulkTextRenderer \
  -t template.pdf \
  -c names.csv \
  -o output \
  --x 297 \
  --y 500

With All Options

java -jar BulkTextRenderer-{VERSION}.jar \
  -t template.pdf \
  -c names.csv \
  -o output \
  --x 297 \
  --y 500 \
  -u px \
  -a CENTER \
  -f Helvetica \
  -s 24 \
  -p 4 \
  --sequential-threshold 10 \
  --prefix wedding \
  --postfix final \
  --verbose

List Available Fonts

java -jar BulkTextRenderer-{VERSION}.jar --list-fonts

Display Help

java -jar BulkTextRenderer-{VERSION}.jar --help

CLI Options Reference

Option	Short	Description	Default
`--template`	`-t`	Template file path (PDF, PNG, JPG, JPEG)	required
`--csv`	`-c`	CSV file path containing text entries	required
`--output`	`-o`	Output folder for generated files	`./output`
`--x`		X coordinate for text placement	required
`--y`		Y coordinate for text placement	required
`--unit`	`-u`	Measurement unit: PX (pixels) or MM (millimeters)	`PX`
`--align`	`-a`	Text alignment: left, center, right (case-insensitive)	`LEFT`
`--font`	`-f`	Font name	`Times New Roman`
`--font-size`	`-s`	Font size in points	`12`
`--threads`	`-p`	Number of parallel threads (for jobs ≥ threshold)	CPU cores
`--sequential-threshold`		Jobs below this count use sequential processing	`10`
`--prefix`		Output filename prefix	none
`--postfix`		Output filename postfix	none
`--list-fonts`		List available fonts and exit
`--verbose`	`-v`	Enable verbose logging (INFO level)
`--debug`		Enable debug logging (DEBUG level)
`--help`	`-h`	Display help message
`--version`	`-V`	Display version information

CSV File Format

Simple Format (Single Column)

The CSV file can contain one text entry per line:

John Doe
Jane Smith
Robert Brown

Multi-Column Format (Recommended)

For more control, use the multi-column format with name,prefix,postfix:

name,prefix,postfix
Adam Smith,Mr.,
Jane Doe,Dr.,PhD
John Williams,,Jr.

The display text is assembled as: <prefix> <name> <postfix>

Mr. Adam Smith
Dr. Jane Doe PhD
John Williams Jr.

The filename uses only the name column (cleaner filenames without title prefixes).

Note:

Header row (name,prefix,postfix) is automatically detected and skipped
Empty prefix/postfix columns are supported
Single-column CSV still works for backward compatibility

Coordinate System

Both PDF and PNG templates use a unified coordinate system with top-left origin:

Origin (0,0) is at the top-left corner
Y values increase downward
X values increase rightward

Measurement Units

Unit	Description	Conversion
`px`	Pixels (default)	1px = 1px
`mm`	Millimeters	1mm ≈ 2.835px (at 72 DPI)

Example with millimeters:

--x 50 --y 100 --unit mm

Common Page Dimensions

Format	Width	Height
A4 PDF	595 pts (210mm)	842 pts (297mm)
Letter PDF	612 pts	792 pts
PNG/JPEG	Varies by image

Example: To place text 100 points from the left and 50 points from the top:

--x 100 --y 50

Text Alignment

The -a/--align option positions text relative to the specified X coordinate:

Alignment	Behavior	Description
`left`	`[Text]→X`	Text is positioned to the LEFT of point X (text ends at X)
`center`	`Te\|xt`	Text is centered on point X
`right`	`X→[Text]`	Text is positioned to the RIGHT of point X (text starts at X)

Visual representation (X marks the coordinate point):

LEFT alignment:    [Hello World]X
CENTER alignment:  [Hello X World]
RIGHT alignment:   X[Hello World]

Example: Place text centered at the horizontal middle of an A4 page:

--x 297 --y 100 -a center

Available Fonts

Use --list-fonts to see all available fonts categorized as:

Built-in Fonts

Fonts that work without any system dependencies:

Helvetica
Courier
Times New Roman

System Fonts

Any font installed on your operating system (Arial, Verdana, etc.)

Examples

For detailed visual examples and sample commands, see the Examples Directory.

Wedding Invitations (PDF)

java -jar BulkTextRenderer-{VERSION}.jar \
  -t wedding-template.pdf \
  -c guests.csv \
  -o invitations \
  --x 297 \
  --y 500 \
  -a CENTER \
  -f Helvetica \
  -s 28 \
  --prefix invite \
  --postfix 2024

Name Badges (PNG) - JAR Mode

java -jar BulkTextRenderer-{VERSION}.jar \
  -t badge-template.png \
  -c attendees.csv \
  -o badges \
  --x 200 \
  --y 150 \
  -a CENTER \
  -f SansSerif \
  -s 32

Certificates (PDF) - Native Mode

./BulkTextRenderer \
  -t certificate-template.pdf \
  -c recipients.csv \
  -o certificates \
  --x 400 \
  --y 350 \
  -a CENTER \
  -f "Times New Roman" \
  -s 36

Large Batch with Custom Threading

java -jar BulkTextRenderer-{VERSION}.jar \
  -t template.pdf \
  -c large-list.csv \
  -o output \
  --x 297 \
  --y 500 \
  --threads 8 \
  --sequential-threshold 20 \
  --verbose

Output

Files are saved to the specified output folder with names derived from the text content:

Spaces are replaced with underscores
Special characters are removed
Optional prefix and postfix are added

Example: wedding-John_Doe-final.pdf

Error Handling

The tool provides clear error messages for:

Missing template or CSV files
Invalid file formats
Missing required options
File permission issues
Platform-specific limitations (e.g., PNG/JPEG on macOS native-image)

Exit codes:

0 - Success
1 - Runtime error (file not found, processing error)
2 - Invalid arguments

Troubleshooting

PNG/JPEG Rendering Fails on macOS Native Executable

Symptom: Error message about missing AWT support

Solution: Use the JAR version instead:

java -jar BulkTextRenderer-{VERSION}.jar -t template.png ...

Explanation: GraalVM native-image on macOS doesn't bundle AWT native libraries required for PNG/JPEG rendering. See #28 for details.

Alternatives:

Use JAR mode (recommended)
Use Linux or Windows for native builds
Use Docker with Linux base image

Performance Tips

For small batches (<10 files), the tool automatically uses sequential processing (faster due to reduced overhead)
For larger batches (≥10 files), parallel processing is enabled by default
Adjust the threshold: --sequential-threshold 20 (custom cutoff)
Control thread count: --threads 8 (for parallel jobs)

Verbose Logging

Enable detailed logging to troubleshoot issues:

# INFO level logging
java -jar BulkTextRenderer-{VERSION}.jar ... --verbose

# DEBUG level logging (very detailed)
java -jar BulkTextRenderer-{VERSION}.jar ... --debug

License

BulkTextRenderer is released under the MIT License. See LICENSE for the full text.

Known Issues

See GitHub Issues for known bugs and limitations.

Notable issues:

#28 - AWT not supported in GraalVM native-image on macOS (PNG/JPEG limitation)
#29 - Release strategy: Include Fat JAR alongside native executables
#30 - Comprehensive error handling improvements

Contributing

Contributions are welcome! Please ensure:

All tests pass (./gradlew test)
Code follows existing patterns
New features include tests
Update documentation as needed

See IMPLEMENTATION_PROGRESS.md for development notes and architectural decisions.

Technical Details

Threading Strategy

The application uses adaptive threading:

Sequential mode: For small batches (<10 jobs by default)
- Uses main thread only
- Lower overhead for quick tasks
Parallel mode: For larger batches (≥10 jobs)
- Uses virtual threads (Java 21+)
- Configurable thread count
- Custom exception handler for visibility

Threshold is configurable via --sequential-threshold.

GraalVM Native Image

The project supports compilation to native executables using GraalVM:

Fast startup time (~instant vs ~1-2s for JAR)
Lower memory footprint
Platform-specific binaries
Limitation: PNG/JPEG not supported on macOS (see #28)

Build with:

./gradlew nativeCompile

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github		.github
.idea		.idea
example		example
gradle/wrapper		gradle/wrapper
src		src
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
build.gradle		build.gradle
gradle.properties		gradle.properties
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle		settings.gradle

Folders and files

Latest commit

History

Repository files navigation

BulkTextRenderer

Features

Prerequisites

For JAR

For Native Build

Installation

Option 1: JAR (Recommended for PNG/JPEG)

Option 2: Native Executable (Platform-Specific)

Platform Compatibility Matrix

Build Instructions

Build the Project

Run Tests

Build Fat JAR

Build Native Executable

Usage

Basic Usage (JAR)

Basic Usage (Native)

With All Options

List Available Fonts

Display Help

CLI Options Reference

CSV File Format

Simple Format (Single Column)

Multi-Column Format (Recommended)

Coordinate System

Measurement Units

Common Page Dimensions

Text Alignment

Available Fonts

Built-in Fonts

System Fonts

Examples

Wedding Invitations (PDF)

Name Badges (PNG) - JAR Mode

Certificates (PDF) - Native Mode

Large Batch with Custom Threading

Output

Error Handling

Troubleshooting

PNG/JPEG Rendering Fails on macOS Native Executable

Performance Tips

Verbose Logging

License

Known Issues

Contributing

Technical Details

Threading Strategy

GraalVM Native Image

Repo Activity

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 6

Uh oh!

Contributors

Uh oh!

Languages