QRForge4J - Advanced QR Code Generation Library

🎯 The definitive QR code styling library for the JVM ecosystem

A powerful, modular QR code generation library written in Kotlin that provides:

• Full feature parity with the popular JavaScript qr-code-styling library
• 8 advanced visual features that go beyond the original
• Beautiful Kotlin DSL for type-safe QR generation
• Modular architecture (core, SVG renderer, DSL, CLI)
• High-quality SVG output with extensive styling options

Repository: github.com/willmortimer/QRForge4J

Features

🏗️ Modular Architecture

• qrgen-core: Core QR generation engine with type-safe configuration
• qrgen-svg: Advanced SVG renderer with all styling features
• qrgen-dsl: Beautiful Kotlin DSL for fluent API design
• qrgen-cli: Comprehensive command-line interface

🎨 Complete Styling System

• 6 Module Styles: Circle, square, classy rings, rounded, extra-rounded, classy-rounded
• 4 Corner Locator Styles: Square, circle, rounded, classy variants
• Logo Support: Center images with size control and hole carving
• Gradients: Linear and radial gradients with rotation control
• Colors: Full color customization with transparency support

🚀 Advanced Features (Beyond qr-code-styling)

• Module Outlines: Subtle contrasting strokes around modules
• Quiet Zone Accents: Decorative borders around the quiet zone
• Drop Shadows: SVG filter-based soft shadows and glows
• Pattern Backgrounds: Dots, grid, diagonal, hexagon patterns
• Gradient Masking: Distance-based color gradients across modules
• Micro Typography: Text rendering on circular or linear paths

💎 Beautiful Kotlin DSL

val qrSvg = QRCode.ofCircles()
    .size(600)
    .withColor("#2ecc71")
    .dropShadow()
    .backgroundPattern { dots() }
    .microTypography("Secure • Verified") { circular() }
    .buildSvg("https://example.com")

🖥️ Comprehensive CLI

• Multiple Encodings: UTF-8, Latin-1, Base64 input support
• Flexible I/O: File or stdin/stdout with proper error handling
• All Features Available: Every styling option accessible via command-line

Installation

Prerequisites

• Java 21 or higher
• Gradle (included via wrapper)

Build from Source

git clone <repository-url>
cd qr-generator
./gradlew build

Usage

Basic Examples

Generate a simple QR code:

echo "Hello World" | ./gradlew run --args="--enc latin1" > qr.svg

From file input:

./gradlew run --args="--input data.txt --enc latin1 --output qr.svg"

Styling Options

Different Module Styles

# Circular dots (default)
echo "https://example.com" | ./gradlew run --args="--enc latin1 --dots circle" > circular.svg

# Square pixels
echo "https://example.com" | ./gradlew run --args="--enc latin1 --dots square" > square.svg

# Rounded squares
echo "https://example.com" | ./gradlew run --args="--enc latin1 --dots square --rounded" > rounded.svg

# Classy ring style
echo "https://example.com" | ./gradlew run --args="--enc latin1 --dots classy" > classy.svg

Custom Colors

# Blue QR code on white background
echo "Styled QR" | ./gradlew run --args="--enc latin1 --fg #0066cc --bg #ffffff" > blue.svg

# Dark theme
echo "Dark QR" | ./gradlew run --args="--enc latin1 --fg #ffffff --bg #1a1a1a" > dark.svg

# Transparent background
echo "Transparent" | ./gradlew run --args="--enc latin1 --bg ''" > transparent.svg

Size and Layout

# Large QR code
echo "Big QR" | ./gradlew run --args="--enc latin1 --width 1024 --height 1024" > large.svg

# Custom margins
echo "Margins" | ./gradlew run --args="--enc latin1 --margin 50" > margins.svg

# Circular crop
echo "Circle" | ./gradlew run --args="--enc latin1 --circle" > circle.svg

Logo Integration

# With logo and hole
echo "Company" | ./gradlew run --args="--enc latin1 --logo logo.png --hole 40" > branded.svg

# Custom logo size
echo "Brand" | ./gradlew run --args="--enc latin1 --logo logo.svg --logo-size 0.3" > big-logo.svg

Corner Locator Styling

# Rounded corner locators
echo "Rounded" | ./gradlew run --args="--enc latin1 --corner-style rounded --corner-color #ff6b35" > corners.svg

# Classy corner style
echo "Classy" | ./gradlew run --args="--enc latin1 --corner-style classy --corner-color #2ecc71" > classy-corners.svg

Command Line Reference

Usage:
  echo "<base64|latin1 payload>" | qrcli [options]
  qrcli --input data.txt --enc latin1 --logo logo.png [options]

Options:
  -i, --input              Input file (default stdin)
  -o, --output             Output SVG file (default stdout)
  --enc <base64|latin1>    Encoding of payload (default base64)
  --width <px>             SVG canvas width (default 512)
  --height <px>            SVG canvas height (default 512)
  --margin <px>            Margin around QR (default 16)
  --circle                 Crop QR into a circle
  --dots <circle|square|classy>
                           Dot style (default circle)
  --rounded                Rounded squares (only with square dots)
  --dot-radius <0.0–0.5>   Radius factor (default 0.5)
  --fg <color>             Foreground color (default #000)
  --bg <color|null>        Background color (default #fff)
  --hole <px>              Carve out a logo hole (px)
  --ec <l|m|q|h>           Error correction level (default q)
  --logo <url>             URL or data-URI for center image
  --logo-size <0.0–1.0>    Center image size ratio (default 0.2)
  --corner-style <style>   Corner locator: square|circle|rounded|classy
  --corner-color <color>   Locator color (default #000)
  --corner-size <modules>  Locator box size in modules (default 7.0)
  -h, --help               Show this help

Architecture

Design Principles

• Clean Separation: Rendering logic separated from CLI interface
• Extensible: Easy to add new module shapes and styling options
• Performance: Optimized SVG generation with efficient path batching
• Quality: Built on proven QR generation algorithms

Core Components

QrRenderer.kt

The heart of the styling engine featuring:

• Module Rendering: Circle, square, and classy ring styles
• Path Optimization: Batched rectangle rendering for performance
• Gradient Support: Infrastructure for linear and radial gradients
• Locator Customization: Flexible finder pattern styling
• Layout Engine: Precise positioning with configurable margins

App.kt

Command-line interface providing:

• Flexible Input: File or stdin with encoding options
• Comprehensive Options: Full access to all rendering capabilities
• Pipeline Friendly: Easy integration with shell scripts and automation

Technical Highlights

Smart Path Batching

For square modules, consecutive modules in the same row are batched into single rectangle paths, significantly reducing SVG file size and improving rendering performance.

Precision Positioning

All coordinates use double precision and smart formatting that omits decimals when possible, creating clean, compact SVG output.

Modular Design

The rendering system is designed for easy extension - adding new module shapes or styling options requires minimal changes to core logic.

Comparison with qr-code-styling Library

This project was inspired by the excellent qr-code-styling JavaScript library. Here's how we compare:

Current Feature Parity

✅ Module Styles: Circle, square, classy (rounded squares planned)
✅ Color Control: Foreground/background colors
✅ Logo Integration: Center images with hole carving
✅ Corner Styling: Custom finder pattern appearance
✅ Size Control: Flexible dimensions and margins
✅ Error Correction: Full ECC level support

JavaScript Library Features To Implement

🔄 Gradients: Linear and radial gradient support (infrastructure ready)
🔄 Rounded Squares: Module corner radius control
🔄 Advanced Corners: More corner dot and square style variations
🔄 Background Rounds: Rounded background corners
🔄 Canvas Output: PNG/JPEG generation (SVG-first approach)

Kotlin-Specific Advantages

🚀 Pure SVG: Vector-first approach for infinite scalability
🚀 CLI Integration: Perfect for server-side generation and automation
🚀 Performance: JVM performance for high-throughput scenarios
🚀 Type Safety: Compile-time validation of parameters
🚀 Path Optimization: Intelligent SVG path batching

Roadmap

Phase 1: Core Styling Completion

• Linear Gradients: Implement gradient fills for modules
• Radial Gradients: Circular gradient patterns
• Rounded Squares: Module corner radius control
• Advanced Corners: Extended corner dot/square variations

Phase 2: Advanced Features

• Animation Support: SVG animations for dynamic QR codes
• Pattern Fills: Texture and pattern module fills
• Multi-format Output: PNG/JPEG generation via SVG conversion
• Batch Processing: Multiple QR generation in single command

Phase 3: Developer Experience

• Library Mode: Programmatic API for Kotlin/Java projects
• Configuration Files: JSON/YAML styling presets
• Interactive CLI: Guided styling mode
• Web Interface: Optional web preview server

Contributing

This project welcomes contributions! Areas where help is especially appreciated:

• Gradient Implementation: Completing the gradient system
• New Module Styles: Creative QR module designs
• Performance Optimization: SVG generation improvements
• Testing: Comprehensive test coverage
• Documentation: Examples and tutorials

Technical Details

Dependencies

• Nayuki QR Code Generator (io.nayuki:qrcodegen:1.8.0): Core QR generation
• Kotlin Standard Library: Language runtime
• Java 21: Modern JVM platform

Output Format

Generated SVGs use:

• Viewport: Precise coordinate system
• Shape Rendering: crispEdges for pixel-perfect output
• Optimized Paths: Minimal file size with batched rectangles
• Standard Compliance: Full SVG 1.1 compatibility

License

MIT License - see LICENSE file for details.

Acknowledgments

• Nayuki: Exceptional QR Code generator library
• qr-code-styling: Inspiration and feature reference
• QR Code Specification: Built according to ISO/IEC 18004 standard