Vecline

<img src="https://raw.githubusercontent.com/shunyagatha/Vecline/main/extensions/figma/thumbnail.png" alt="Vecline">

# Vecline

**Measurable raster ⇄ SVG conversion — and a broad image + document toolkit.** Ten raster formats, every one convertible to every other, with the accuracy of every conversion actually measured rather than asserted; plus **PDF & Office** (docx/xlsx/pptx) rendering and conversion, **images → PDF**, **DXF at a real physical cut size** alongside EPS and G-code for makers, centerline tracing and content-aware crop — most of it in a **zero-dependency** core that is CI-proven to bundle for a browser.

On flat artwork — logos, icons, UI, screenshots, pixel art — the output is **bit-exact**: `SSIM 1.0000`, `PSNR ∞`, zero differing pixels, and on a real logo **smaller than imagetracerjs or vtracer manage while still only approximating** — 24 KB against their 60 and 64. That comes from recognising the image is cheaper to encode exactly than to approximate, not from a better curve fit. **Tracing now emits real curves by default** — sub-pixel edge placement is on, which is the only thing that lets the curve fitter run at all; before this the default returned a staircase with zero curve commands on real artwork. It costs about 2.35x the gzipped bytes, because moving coordinates off the integer lattice costs compression, and `--no-subpixel` buys the old smaller output back. Pixel and exact modes are untouched and stay bit-exact. potrace is smaller than everyone and much less accurate, which is a real trade and not one this README will hide. On real photographs it leads all three on SSIM by 0.05–0.18 *at their default settings*; one documented vtracer flag closes part of that. It is not the fastest — imagetracerjs is quicker on every fixture measured. Every number in this README is reproducible: `node scripts/fetch-corpus.mjs && npm run compare`. (The corpus is fetched rather than committed — the photographs are not ours to redistribute.)

[![npm version](https://img.shields.io/npm/v/vecline.svg)](https://www.npmjs.com/package/vecline)
[![npm downloads](https://img.shields.io/npm/dm/vecline.svg)](https://www.npmjs.com/package/vecline)
[![CI](https://github.com/shunyagatha/Vecline/actions/workflows/ci.yml/badge.svg)](https://github.com/shunyagatha/Vecline/actions/workflows/ci.yml)
[![types](https://img.shields.io/npm/types/vecline.svg)](https://www.npmjs.com/package/vecline)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![node](https://img.shields.io/badge/node-%3E%3D18.17-brightgreen.svg)](https://nodejs.org)

**▶ [Vecline Studio — vecline.xyz](https://vecline.xyz)** — the whole toolkit in your browser. Drop an image, a **PDF**, or a TGA/PNM/ICO no browser can read; tune it; watch live SSIM / PSNR / CIEDE2000; export SVG, DXF **at a real cut size**, EPS, PDF, G-code, React/Vue/Svelte/Solid components, colour separations, sprite sheets, favicons, BlurHash, or just re-encode between ten raster formats. Free, unlimited, no signup, works offline, and **nothing is uploaded** — every conversion runs in your tab, not on a server. ([How it compares](https://vecline.xyz/compare.html) · [dev playground](https://shunyagatha.github.io/Vecline/))

```bash
vecline vectorize logo.png --verify
```

```
✓ logo.svg  400×300  pixel mode  4 shapes  2.1 KB → 7.5 KB  228 ms
  · Auto-selected pixel mode: 4 distinct colours, 1.0% run density. Output is bit-exact.

Accuracy  bit-exact (lossless)
  PSNR        ∞
  SSIM        1.000000 (luma 1.000000)
  RMSE        0.0000
```

---

## The lossless guarantee

```bash
vecline vectorize anything.png --lossless
```

`--lossless` returns a **bit-exact** SVG or it **fails**. It never silently gives you a near-miss.

That is enforced by measurement, not by construction. Every candidate encoding is rendered back to pixels and compared against the source; anything that is not bit-identical is discarded, and if nothing survives, the command errors out. Candidates are tried in order of how useful the result is:

1. **Exact geometry** — real, editable, infinitely scalable paths. Rectangles or contours, whichever encodes smaller.
2. **Embed, original bytes preserved** — a **byte-identical** round trip of the source *file*, not just of its pixels.
3. **Embed, re-encoded as PNG** — always renders exactly, but no longer carries the original file.

Measured across every fixture in the test suite — flat artwork, pixel art, soft alpha, photographs, JPEG sources, a single pixel — all of them come back `PSNR ∞`, `maxChannelDiff 0`.

### Byte-identical, and provable

When the original file is preserved, the SVG records its SHA-256. `extract` hands the file back and checks the digest:

```bash
vecline vectorize logo.png -o keep.svg --mode embed --embed-strategy preserve
vecline extract keep.svg -o recovered.png --against logo.png
```

```
✓ recovered.png  image/png  2.1 KB
  sha256   1c4f95f66b28a40a75672614796de762f6ef8a6afec3191b460dbbd556f10366
  digest   matches the value recorded when the SVG was written
  payload  the original file, preserved byte for byte
  vs source byte-identical to logo.png
```

`extract` exits non-zero on any mismatch, so it works as a CI gate. Note the honest caveat: an *embedded JPEG* survives byte for byte but does **not** render bit-identically, because resvg's decoder rounds its inverse DCT differently. Strict `--lossless` detects that, discards the candidate, and says so.

### Which one you get

| Input | Result | Size | Exact? |
|---|---|--:|:--:|
| Flat artwork 400×300 | real geometry (contours) | 3.9 KB | ✅ |
| Pixel art 128×128 | real geometry (rectangles) | 0.6 KB | ✅ |
| `favicon.ico` 64×64 | real geometry (rectangles) | 0.5 KB | ✅ |
| BMP 400×300 | real geometry (contours) | 3.9 KB | ✅ |
| Photo 320×240 | embedded PNG | 230 KB | ✅ |

A photograph *can* be emitted as exact geometry, and `--prefer geometry` will do it — but it costs one rectangle per pixel, so that same photo becomes a 1.99 MB file of 42,933 shapes. It is vector in name only, so `auto` uses the bitmap and tells you the ratio it measured. Nothing is hidden.

## The honest version of "100% accuracy"

Most vectorizers claim perfect accuracy. Here is what is actually true, because it determines which tool you should use:

| Direction | Can it be exact? | Why |
|---|---|---|
| **SVG → raster** | **Yes**, at any resolution you name | Rendering is a well-defined computation. Ask for 4000px wide and you get exactly that, correct to the renderer's rasterisation rules. |
| **Raster → SVG, lossless** | **Yes** | Two different ways, both bit-exact. See `pixel` and `embed` below. |
| **Raster → SVG, traced into curves** | **No, and it never can be** | A photograph holds more independent information than any compact set of Bézier curves can encode. Tracing is approximation by definition. |

Anyone promising exact photo-to-curves vectorization is either embedding a bitmap and calling it vector, or is wrong. **Vecline does both exact conversions properly, does the approximate one well, and always tells you which one you got and how close it landed.**

## Three strategies, and when each is right

| Mode | Output | Exact? | Use it for |
|---|---|---|---|
| **`lossless`** | Real geometry, or an embedded bitmap | **Bit-exact, verified** | Anything, when exactness is non-negotiable |
| **`pixel`** | Real vector geometry (rectangles or contours) | **Bit-exact** | Logos, icons, pixel art, screenshots, diagrams, flat colour |
| **`trace`** | Real Bézier curves | Approximate, measured | Photos, complex art, anything you want to *scale* or *edit* |
| **`embed`** | Bitmap inside an SVG wrapper | **Bit-exact** | You need this exact image, in an SVG container |

`auto` (the default) inspects the image and picks between `pixel` and `trace`. `--lossless` overrides everything with the guarantee described above.

**`pixel` mode is the one people don't expect.** It produces genuine, editable, infinitely-scalable vector paths that rasterise back to your input with **zero** differing pixels — not "visually identical", literally identical. For flat artwork it is usually what you actually wanted.

## Install

```bash
npm install -g vecline        # the CLI
npm install vecline           # the library
```

Node.js 18.17+. The native dependencies ([sharp](https://sharp.pixelplumbing.com/), [resvg](https://github.com/yisibl/resvg-js)) ship prebuilt binaries for Linux, macOS and Windows.

### Any project architecture

| You want | Import | Native deps |
|---|---|:--:|
| The full Node toolkit | `import { vectorize } from 'vecline'` | yes |
| … from CommonJS | `const { vectorize } = require('vecline')` | yes |
| Just the vectoriser | `import { trace } from 'vecline/vectorize'` | **none** |
| Just the metrics | `import { compareImages } from 'vecline/metrics'` | **none** |
| Just the pure-TS codecs | `import { encodeBmp } from 'vecline/formats'` | **none** |
| Everything portable | `import { vectorizeExact } from 'vecline/core'` | **none** |
| Image editing (resize, rotate…) | `import { editImage } from 'vecline/ops'` | sharp only |
| Register a custom codec | `import { registerDecoder } from 'vecline/codecs'` | **none** |

Install only what you use. Every `none` subpath imports in isolation with the native codecs omitted (`npm install vecline --omit=optional`), and the package is `"sideEffects": false`, so a bundler drops everything you never import. `vecline/core` is the vectorisation and measurement engine with **zero dependencies and no Node built-ins**. It takes a plain `{ width, height, data }` — byte-for-byte the layout of the browser's `ImageData` — so canvas pixels go straight in:

```js
import { vectorizeExact } from 'vecline/core';

const { data, width, height } = ctx.getImageData(0, 0, canvas.width, canvas.height);
const { svg } = vectorizeExact({ width, height, data });   // bit-exact, no codec needed
```

**The zero-dependency claim is CI-asserted, not stated.** Every commit bundles `vecline/core`