chart-image

# Chart Image Generator

Generate PNG chart images from data using Vega-Lite. Perfect for headless server environments.

## Why This Skill?

**Built for Fly.io / VPS / Docker deployments:**
- ✅ **No native compilation** - Uses Sharp with prebuilt binaries (unlike `canvas` which requires build tools)
- ✅ **No Puppeteer/browser** - Pure Node.js, no Chrome download, no headless browser overhead
- ✅ **Lightweight** - ~15MB total dependencies vs 400MB+ for Puppeteer-based solutions
- ✅ **Fast cold starts** - No browser spinup delay, generates charts in <500ms
- ✅ **Works offline** - No external API calls (unlike QuickChart.io)

## Setup (one-time)

```bash
cd /data/clawd/skills/chart-image/scripts && npm install
```

## Quick Usage

```bash
node /data/clawd/skills/chart-image/scripts/chart.mjs \
  --type line \
  --data '[{"x":"10:00","y":25},{"x":"10:30","y":27},{"x":"11:00","y":31}]' \
  --title "Price Over Time" \
  --output chart.png
```

## Chart Types

### Line Chart (default)
```bash
node chart.mjs --type line --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output line.png
```

### Bar Chart
```bash
node chart.mjs --type bar --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output bar.png
```

### Area Chart
```bash
node chart.mjs --type area --data '[{"x":"A","y":10},{"x":"B","y":15}]' --output area.png
```

### Pie / Donut Chart
```bash
# Pie
node chart.mjs --type pie --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output pie.png

# Donut (with hole)
node chart.mjs --type donut --data '[{"category":"A","value":30},{"category":"B","value":70}]' \
  --category-field category --y-field value --output donut.png
```

### Candlestick Chart (OHLC)
```bash
node chart.mjs --type candlestick \
  --data '[{"x":"Mon","open":100,"high":110,"low":95,"close":105}]' \
  --open-field open --high-field high --low-field low --close-field close \
  --title "Stock Price" --output candle.png
```

### Heatmap
```bash...

# 📊 chart-image

**Publication-quality chart images from data. No browser, no Puppeteer, no native compilation.**

Generate beautiful PNG charts directly from JSON data — perfect for bots, dashboards, alerts, and automated reports. Runs anywhere Node.js runs.

![Line chart example](readme-assets/framed-line.png)

## Why chart-image?

Most chart libraries need a browser (Puppeteer, Playwright) or native dependencies (`canvas`, `cairo`). That means 400MB+ installs, painful Docker builds, and slow cold starts.

**chart-image uses Vega-Lite + Sharp with prebuilt binaries:**

| | chart-image | Puppeteer + Chart.js | QuickChart.io |
|---|---|---|---|
| **Install size** | ~15MB | ~400MB+ | 0 (API) |
| **Native deps** | None | Chromium | N/A |
| **Cold start** | <500ms | 2-5s | Network latency |
| **Offline** | ✅ | ✅ | ❌ |
| **Fly.io/Docker** | Just works | Pain | Depends on uptime |

## Install

### Via ClawHub (recommended)
```bash
clawhub install chart-image
```

### Manual
```bash
git clone https://github.com/Cluka-399/chart-image.git skills/chart-image
cd skills/chart-image/scripts && npm install
```

## Quick Start

```bash
node scripts/chart.mjs \
  --type line \
  --data '[{"x":"Mon","y":10},{"x":"Tue","y":25},{"x":"Wed","y":18}]' \
  --title "Weekly Trend" \
  --dark \
  --output chart.png
```

That's it. One command, one PNG.

---

## Chart Types

### 📈 Line Chart

Track trends over time. The default chart type.

```bash
node scripts/chart.mjs --type line \
  --data '[{"x":"Mon","y":142},{"x":"Tue","y":148},{"x":"Wed","y":145},{"x":"Thu","y":155},{"x":"Fri","y":162}]' \
  --title "AAPL Weekly Price" --y-title "Price (USD)" \
  --dark --show-values --output chart.png
```

![Line chart](readme-assets/framed-line.png)

### 📊 Bar Chart

Compare categories side by side.

```bash
node scripts/chart.mjs --type bar \
  --data '[{"x":"React","y":45},{"x":"Vue","y":28},{"x":"Svelte","y":15},{"x":"Angular","y":12}]' \
  --title "Framework Usage %" --output chart.png
``...