blueprinter 0.1.0

Hand-drawn style diagram renderer CLI — turn SVG into sketchy SVG
Documentation

blueprinter

Hand-drawn style embedded-visual renderer CLI.

Turn SVG into sketchy SVG today. Rasterize to PNG / WebP. Mermaid input is supported via the external mmdc (mermaid-cli). The Markdown pipeline currently batch-renders embedded mermaid blocks and is planned to expand into a general embedded-visual compiler, starting with latex-render blocks for editorial cards, lists, and tables. draw.io direct input is planned.

Installation

cargo install blueprinter

Or download a prebuilt binary from GitHub Releases once v0.1.0+ tags are published.

Usage

# Render a Mermaid diagram (requires mmdc on PATH)
blueprinter render -i flowchart.mmd -o flowchart.svg --theme manga --seed 42

# Batch-render every supported embedded visual block in a Markdown file
blueprinter md -i README.md -o ./diagrams --theme manga --format png --width 800

# Transform an existing SVG with the default blueprint theme
blueprinter transform -i input.svg -o output.svg --theme blueprint --seed 42

# Tune the hand-drawn intensity
blueprinter transform -i input.svg -o output.svg \
  --seed 42 \
  --jitter-amplitude 3.5 \
  --jitter-frequency 7 \
  --jitter-stroke-width-var 0.4

# Override text font-family while keeping layout intact
blueprinter transform -i input.svg -o output.svg \
  --seed 42 \
  --font-family "Virgil"

# Export to PNG (2x scale)
blueprinter transform -i input.svg -o output.png \
  --format png \
  --scale 2.0

# Export to PNG with explicit dimensions (maintains aspect ratio)
blueprinter transform -i input.svg -o output.png \
  --format png \
  --width 800

# Export to lossless WebP (smaller than PNG for diagram content)
blueprinter transform -i input.svg -o output.webp \
  --format webp \
  --width 800

--jitter-amplitude controls how far coordinates can wobble, --jitter-frequency controls how densely strokes are subdivided before wobble is applied, and --jitter-stroke-width-var controls relative stroke-thickness variation. Omitting them preserves today's defaults. --font-family overrides SVG text font-family; if omitted, existing text fonts and stylesheet-driven fonts are left as authored.

Themes

  • blueprint — accepted; full technical drawing styling with Gaussian blur
  • sumi — Japanese ink wash painting with grayscale ink bleed effect (now implemented)
  • watercolor — soft pigment bleeding and color mixing (now implemented)
  • chalk — white chalk on a blackboard, with dust/breakup filter (now implemented)
  • marker — bold neon marker strokes on a dark sketchbook (now implemented)
  • manga — black ink lines on white paper with screentone fills (now implemented)

Sumi Theme

The sumi (墨) theme mimics traditional Japanese ink painting with grayscale strokes and a soft bleed effect.

blueprinter transform -i input.svg -o output.svg --theme sumi --seed 42

Features:

  • Grayscale color palette (black to light gray)
  • Gaussian blur filter with 2–4px standard deviation
  • Semi-transparent stroke opacity (0.6–1.0) for ink wash effect

Watercolor Theme

The watercolor theme simulates soft pigment mixing and color bleeding with pastel colors.

blueprinter transform -i input.svg -o output.svg --theme watercolor --seed 42

Features:

  • Pastel color palette (#FFB3BA, #FFDFBA, #FFFFBA, #BAFFC9, #BAE1FF, #E0BBE4, #FFC7F5)
  • Gaussian blur filter with 4–8px standard deviation for diffuse bleed
  • Color matrix saturation adjustment (90%) for soft, washed appearance
  • Semi-transparent fills (0.5–0.9) for transparency effect

Manga Theme

The manga theme renders crisp black ink lines on white paper, with closed shapes filled by <pattern>-based screentones (sparse dots, dense dots, or diagonal lines) sampled per shape.

blueprinter transform -i input.svg -o output.svg --theme manga --seed 42

Features:

  • White paper background (#ffffff)
  • Pure black strokes (#000000) — no per-shape color randomization
  • Three SVG <pattern> screentones injected into <defs> and referenced via fill="url(#manga-...)"
  • Closed shapes get a screentone picked from manga-dots-light, manga-dots-dark, or manga-lines-diag

Marker Theme

The marker theme renders strokes in saturated neon highlighter colors on a dark navy background, with a soft halo behind each shape.

blueprinter transform -i input.svg -o output.svg --theme marker --seed 42

Features:

  • Dark navy background (#1a1a2e) inserted automatically
  • Six-color neon palette (hot pink, cyan, lime, orange, yellow, magenta) — sampled per shape
  • Closed shapes get a translucent palette-colored fill (~20% alpha) for highlighter-style overlap
  • marker-glow filter (Gaussian blur halo merged behind source) for a slight bleed
  • Stroke opacity 0.85–1.0 — marker ink is consistent

Chalk Theme

The chalk theme renders strokes as white (and occasional pale color) chalk on a slate-green chalkboard, with a dust filter that breaks each stroke up.

blueprinter transform -i input.svg -o output.svg --theme chalk --seed 42

Features:

  • Chalkboard background (#1f2a25) inserted automatically
  • White-dominated palette with pale yellow / pink / blue / green chalk accents
  • chalk-dust filter combining feTurbulence + feDisplacementMap + light Gaussian blur for a powdery, broken-line look
  • Semi-transparent stroke opacity (0.7–0.95) per stroke for uneven pressure
  • Closed shapes get fill="none" — chalk is treated as a line medium

Current Status

Implemented

  • transform command: SVG → hand-drawn SVG transformation
  • PNG output: --format png, with --scale, --width, --height options
  • WebP output: --format webp (lossless; same flags as PNG)
  • render command: Mermaid (.mmd / .mermaid) → mmdc → blueprinter pipeline. Supports the same theme / output-format / jitter / font flags as transform. Requires mermaid-cli: npm install -g @mermaid-js/mermaid-cli
  • md command: currently extracts every ```mermaid block from a Markdown file and writes them to an output directory as <stem>-<n>.<ext>. This command is intended to grow into the general pipeline for embedded visual blocks such as future latex-render.
  • Blueprint theme: complete with stroke/fill styling and background
  • Sumi theme: ink wash effect with grayscale colors and blur filters
  • Watercolor theme: pastel color palette with diffuse bleed effect
  • Chalk theme: white chalk strokes on a chalkboard with dust/breakup filter
  • Marker theme: bold neon highlighter strokes on a dark navy background with halo
  • Manga theme: black ink lines on white paper with three screentone patterns for fills
  • Jitter controls: --jitter-amplitude, --jitter-frequency, --jitter-stroke-width-var
  • Text overrides: --font-family for font replacement
  • Reproducible output: --seed for deterministic jitter
  • Shape jittering: rect, line, polyline, path, circle, ellipse, polygon (latter three via Bezier approximation)

Planned

  • md pipeline expansion: support ```latex-render blocks and replace them with generated SVG/PNG cards in a companion Markdown output
  • More screentone variants and (eventually) speed-line layout for manga
  • Full theme styling for blueprint (currently basic)
  • Text outline conversion for advanced effects
  • draw.io input path for render
  • convert command (general format conversion)

Release

blueprinter is prepared as a Rust CLI crate with:

  • cargo install blueprinter
  • GitHub Actions CI on pushes and pull requests
  • a tag-driven GitHub Releases workflow for Linux, macOS, and Windows artifacts

The first public crate/release target is v0.1.0.

Font Resolution

When rasterizing to PNG / WebP, blueprinter loads the host's system fonts so any font-family referenced in the input SVG (e.g. Arial, Helvetica) resolves. If the requested face is not installed, resvg falls back to a generic family.

For cross-platform reproducibility, pass --font-dir <path> to load every .ttf / .otf in a directory into the rasterizer's font database. This is the recommended way to pin specific fonts:

blueprinter transform -i input.svg -o output.png --format png \
  --font-dir ./fonts \
  --font-family "Caveat"

The repo-level fonts/ directory is reserved for future built-in bundling; see fonts/README.md for license-compatible OFL fonts that fit each theme.

Known Limitations

  • XML declarations, comments, processing instructions, doctypes, and CDATA boundaries are not preserved
  • Symbols and definitions under defs/symbol/marker are preserved without jitter

License

MIT