pic-gen

Unified Image Generation Tool - Cover (cover), Mermaid (mermaid), Card (card), and Terminal (terminal) Generation

Features

• Cover Image Generation (cover): Generate cover images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM) based on HTML templates with Playwright; SVG is pure vector for built-in templates
• Mermaid Diagram Generation (mermaid): Render Mermaid text to PNG/SVG/APNG/GIF/WebP/MP4/WebM, with default optimization for dynamic edges and branch-differentiated colors (can be disabled)
• Card Image Generation (card): Generate card images/videos in unified formats (PNG/SVG/APNG/GIF/WebP/MP4/WebM)
• Terminal Animation Generation (terminal): Generate terminal images/videos (SVG/PNG/APNG/GIF/WebP/MP4/WebM)
• REST API: REST API with OpenAPI specification
• Docker Deployment: One-click Docker Compose deployment

Quick Start

Install Dependencies

npm install
npx playwright install chromium

CLI Usage

# Show help
node cli.js --help

# Cover image generation
node cli.js cover templates                               # List all templates
node cli.js cover gen --primary "Title" --secondary "Subtitle" -f png -o cover.png
node cli.js cover gen --primary "Title" -f svg -o cover.svg    # Pure vector SVG

# Mermaid diagram generation
node cli.js mermaid gen input.mmd -o output.png           # Generate PNG
node cli.js mermaid gen input.mmd -o output.svg           # Default optimize: dynamic edges + diversified branch colors
node cli.js mermaid gen input.mmd --no-optimize -o output.svg
node cli.js mermaid optimize input.mmd -o optimized.mmd   # Output optimized Mermaid source
node cli.js mermaid check input.mmd                       # Syntax check

# Card image generation
node cli.js card gen -i card.json -f svg -o card.svg      # Render card to SVG
node cli.js card gen -i card.json -f webp -o card.webp

# Terminal image/video generation
node cli.js terminal gen -i terminal.json -f svg -o terminal.svg

API Server

# Start server
npm run api

# Access Swagger documentation
open http://localhost:3000/docs

Docker Deployment

# Build and start
docker-compose up -d

# View logs
docker-compose logs -f

# Stop service
docker-compose down

API Endpoints

| Method | Path | Description | | ------ | ------------------------ | ----------------------------- | | GET | /health | Health check | | GET | /api/cover/templates | Get cover template list | | POST | /api/cover/generate | Generate cover image | | POST | /api/mermaid/render | Render Mermaid diagram | | POST | /api/mermaid/validate | Validate Mermaid syntax | | GET | /api/card/layouts | Get card layouts/presets | | POST | /api/card/generate | Generate card image/video | | GET | /api/terminal/schema | Get terminal JSON schema | | GET | /api/terminal/styles | Get terminal styles | | GET | /api/terminal/formats | Get terminal formats | | POST | /api/terminal/generate | Generate terminal image/video | | POST | /api/terminal/parse | Parse text to terminal JSON |

Example Requests

Generate Cover Image

curl -X POST http://localhost:3000/api/cover/generate \
  -H "Content-Type: application/json" \
  -d '{"template":"black-yellow","primary":"Title","secondary":"Subtitle"}' \
  --output cover.png

Render Mermaid Diagram

curl -X POST http://localhost:3000/api/mermaid/render \
  -H "Content-Type: application/json" \
  -d '{"code":"flowchart LR\n  A-->B","format":"png","optimize":true,"backgroundMotion":"dots"}' \
  --output diagram.png

Generate Card Image

curl -X POST http://localhost:3000/api/card/generate \
  -H "Content-Type: application/json" \
  -d '{"layout":"table-2col","ratio":"9:16","theme":"dark","format":"png","title":"Card","header":["Key","Value"],"rows":[["name","pic-gen"]],"backgroundMotion":"grid"}' \
  --output card.png

Generate Terminal Image

curl -X POST http://localhost:3000/api/terminal/generate \
  -H "Content-Type: application/json" \
  -d '{"format":"svg","style":"bash","theme":"dark","steps":[{"type":"input","text":"echo hi"},{"type":"output","text":"hi"}]}' \
  --output terminal.svg

LLM Tool Directory Conventions

All tools in this directory are designed to assist Large Language Models (LLMs) in safely and predictably executing tasks within automated workflows. Tool designs should follow these general conventions for stable LLM invocation:

• Target Audience: Tools are designed for programmatic/unattended scenarios, not human interaction.
• Composability: Support non-interactive invocation through parameters; do not enter interactive mode by default.
• Standard IO:
  • Input supports two methods: -i <file> for file input or read from STDIN (using -i -).
  • Text results default to STDOUT; binary results (e.g., PNG) must be explicitly saved to disk via -o <path>.
• Discoverability: Provide -h/--help with parameter descriptions and examples; provide --version if applicable.
• Determinism: Same input and parameters produce same output; avoid implicit network requests or unstable dependencies.
• Idempotency and Retryability: Multiple executions should not cause unexpected side effects; failures return non-zero exit codes and provide parseable error messages on STDERR.
• Paths and Permissions: Avoid writing to parent directories of relative paths; only write files when user explicitly specifies -o/--output.
• Compatibility: Be cross-platform (Windows/Linux/macOS); avoid interactive TTY dependencies.
• Performance and Resources: Minimize unnecessary logging; write necessary logs to STDERR and support suppression via --quiet.

Unified Parameter Conventions (recommended, tools may declare deviations in README):

• -i, --input <file>: Input file; - means read from STDIN.
• -o, --output <path>: Output file or directory; defaults to STDOUT if not provided (for text results).
• -h, --help: Show help and exit.
• --version: Show version and exit (if applicable).
• --quiet: Reduce unnecessary log output (logs to STDERR).

Directory Structure Recommendations:

• Each tool in its own subdirectory, containing:
  • Executable entry point (e.g., bin/<tool>.js).
  • package.json (if using Node.js).
  • Tool-specific README.md (with examples and common error explanations).
  • Optional: examples/ directory for quick validation.

Quality and Testing:

• Provide minimal runnable examples for LLM verification.
• Define clear error codes and messages; avoid vague descriptions (e.g., "failed").
• Once published, external interfaces should remain backward compatible or document changes in help.

Tool Index (brief description):

• mermaid-gen: Generate Mermaid images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM), supports gen/check/optimize, and can output Markdown with ```mermaid code blocks via --md-output.
• cover-gen: Generate cover images/videos (PNG/SVG/APNG/GIF/WebP/MP4/WebM) based on HTML templates with Playwright; supports single/batch rendering and template listing; covers should be strongly related to article themes (see usage below).
  • Built-in templates (black-yellow / blue-tech / dark-minimal / red-black / pornhub) support pure vector SVG.
  • Animation defaults: svg/apng/gif/webp/mp4/webm animate by default, png is always static. CLI 不再提供动画参数开关，需在 JSON/API 中设置。
• terminal-gen: Generate terminal typing animation outputs in SVG/PNG/APNG/GIF/WebP/MP4/WebM; supports text parsing and style switching.

Unified Directory Requirements (in progress):

• Each tool must have:
  • bin/<tool>.js (CLI entry point, providing -h/--help)
  • package.json (with bin field)
  • README.md (including purpose, parameters, examples, and notes)
  • Optional: examples/ (example inputs)

Testcase Schema Conventions:

• Each generator type has a dedicated schema under project-root schemas/:
  • cover-gen.schema.json
  • mermaid-gen.schema.json
  • card-gen.schema.json
  • terminal-gen.schema.json
• Every JSON file under testcase/<module>/ should include a $schema field pointing to the corresponding file in ../../schemas/.

Remote Image Specifications (for all articles)

• Images in article body must use remote absolute URLs (OSS/S3, etc.); local relative paths are prohibited.
• Use standard Markdown image syntax in body: ![Description](https://...), e.g., ![spec-kit-arch](https://share.jqknono.com/articles/gh-spec-kit/images/spec-kit-arch.gif).
• Use npm run dist:sync to sync dist/ to remote during distribution, overwriting with local version.

Image Output and Storage Paths (unified convention)

• All article-related images (including covers) are saved to ./dist/<slug>/images/ directory.
• Cover images output to ./dist/<slug>/images/cover.png.
• Example:
  • Mermaid rendering (export PNG/GIF/WebP/SVG simultaneously; prioritize remote GIF links in published body; use vertical layout when horizontal elements exceed 8, e.g., flowchart TD/TB; animations show data flow, set as needed but prefer animated versions):
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.png
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.gif
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.webp
    • node tools/mermaid-gen/cli.js input.mmd -o dist/<slug>/images/arch.svg

Common Pitfalls and Fixes (must read)

• Do not use Python entry for Mermaid rendering (e.g., python -m tools.mermaid_gen.cli or tools.mermaid_gen.cli do not exist); only use Node version: node tools/mermaid-gen/cli.js.
• cover-gen regarding --output and directories:
  • If --output is a relative path, final file is written to tools/cover-gen/out/<relative path>, and tool only pre-creates outputDir, not deeper subdirectories.
  • Recommended safe approaches:
    1. Use absolute path: --output "$PWD/dist/gh-<slug>/images/cover.png", and run mkdir -p dist/gh-<slug>/images first.
    2. Use --output-dir "$PWD/dist/gh-<slug>/images" --output cover.png, also after mkdir -p dist/gh-<slug>/images.
  • Default --device both outputs -desktop/-mobile versions; for single cover.png, use --size 1200x630 to limit size and generate only cover.png.
• Node/Chromium dependencies: Both cover-gen and mermaid-gen depend on headless browsers (Playwright/Puppeteer). If browser is not found at runtime, run npm i --omit=dev in tool subdirectory and retry.

Mermaid Flowchart Animation (enabled by default)

When generating Mermaid flowcharts, animations should be added to connection lines by default to enhance readability and visual guidance. If you need raw rendering without preprocessing, use CLI --no-optimize or API optimize: false.

• Animation options only support fast and slow; medium is prohibited.
• Color guidelines: Different blocks should use different fill colors for better readability. For example, use blue tones for clients, green tones for servers, orange tones for network devices, etc.
• Reference documentation:
  • Turning an animation on: https://mermaid.js.org/syntax/flowchart.html#turning-an-animation-on
  • Selecting type of animation: https://mermaid.js.org/syntax/flowchart.html#selecting-type-of-animation
  • Using classDef statements for animations: https://mermaid.js.org/syntax/flowchart.html#using-classdef-statements-for-animations
• Recommended examples (Mermaid v11 syntax):

flowchart LR
  A e1@==> B
  e1@{ animate: true }

flowchart LR
  A e1@--> B
  e1@{ animation: fast }

Mermaid Sequence Diagram 规则（建议）

• sequenceDiagram 建议使用 autonumber。
• 提示：Mermaid 原生仅 flowchart/graph 支持 eN@{ ... } 连接线动画语法；sequenceDiagram 不支持，避免写 eN@{ ... } 以免解析报错。

Cover Generation (cover-gen) Usage

• Installation: Run npm i --omit=dev in tools/cover-gen directory, then run node cli.js -h to view help.
• Single generation:

node cli.js cover gen \
  --template blue-tech \
  --primary "<Article title or repo name + theme>" \
  --secondary "<One-sentence value proposition/key feature>" \
  --desc "<Optional: supplementary context or version>" \
  --format svg \
  --output dist/<slug>/images/cover.svg

• Animation controls:

  • Default: svg/apng/gif/webp/mp4/webm are animated, png is static.
  • 相关参数仅支持 JSON/API 设置：noAnimation、fps、duration、loop、backgroundMotion、backgroundMotionOptions、watermark、watermarkText。
  • cover gen 额外支持 CLI 快捷参数：--bg-icons <csv>（用于 dots 图标列表，iconCount 会按图标数量自动推导，最多 4）。
  • backgroundMotion 默认 dots，可在 JSON 里改为 none|lines|grid|gradient。
  • 当 backgroundMotion='dots' 且未配置 icons 时，默认图标为 circle（圆点）。
  • backgroundMotionOptions 支持：iconCount(1-4)、icons[]、DotsIconSizes{primary,secondary}(1-64)、DotsIconSpacing(1-12, integer multiple, default 2 for multi-icons)、moveMode(diagonal|direction|stagger-row|stagger-col)、angle(0-360)。未显式提供 iconCount 时会按 icons 数量自动推导（最多 4）。

• Devices and dimensions:

  • When --size/--device are not specified, defaults to output both desktop and mobile versions: cover-desktop.png, cover-mobile.png.
  • Use --device desktop|mobile|both to control exports.
  • Specify --size WIDTHxHEIGHT to output only that size file.

• Batch tasks (JSON):

node cli.js --input examples/tasks.json

• Template selection: Match the article theme (engineering/technical feel: blue-tech/dark-minimal; emphasis on contrast: black-yellow/red-black).
• Article integration: Place cover.png in ./dist/<slug>/images/ (path: ./dist/<slug>/images/cover.png), ensuring the text matches the article title/summary and is relevant.

flowchart LR
  A e1@--> B
  classDef animate stroke-dasharray: 9,5,stroke-dashoffset: 900,animation: dash 25s linear infinite;
  class e1 animate