png-to-svg-converter

A TypeScript library for converting PNG images to SVG vector graphics using advanced tracing algorithms.

Features

• 🚀 High Performance: Fast PNG to SVG conversion using ImageTracer.js
• 🛠️ TypeScript: Full TypeScript support with type definitions
• 🖥️ CLI Tool: Command-line interface for batch processing
• 🌐 Browser Support: Works in browsers and Node.js
• ⚙️ Customizable: Extensive options for fine-tuning conversion quality
• 🧪 Well Tested: Comprehensive test suite with Jest
• 📦 ESM & CJS: Dual package support for maximum compatibility

Installation

npm install png-to-svg-converter

Quick Start

Node.js

import { convertPNGToSVG } from 'png-to-svg-converter';

// Convert from file path
const fs = require('fs');
const pngBuffer = fs.readFileSync('image.png');
const result = await convertPNGToSVG(pngBuffer);

console.log(result.svg); // SVG string
console.log(`Processing time: ${result.processingTime}ms`);

Browser

<script src="https://unpkg.com/png-to-svg-converter"></script>
<script>
  // png-to-svg-converter is available globally
  const fileInput = document.getElementById('fileInput');

  fileInput.addEventListener('change', async (e) => {
    const file = e.target.files[0];
    const arrayBuffer = await file.arrayBuffer();
    const result = await png-to-svg-converter.convertPNGToSVG(arrayBuffer);
    console.log(result.svg);
  });
</script>

CLI

# Convert single file
png2svg image.png

# Convert with custom output
png2svg image.png -o vector.svg

# Adjust conversion settings
png2svg image.png --colors 16 --scale 2 --pathomit 4

API Reference

convertPNGToSVG(input, options?)

Converts PNG input to SVG.

Parameters

• input: string | ArrayBuffer | Uint8Array | HTMLImageElement - The PNG input
• options: ConversionOptions (optional) - Conversion options

Returns

{
  svg: string;        // The SVG string
  width: number;      // Original image width
  height: number;     // Original image height
  processingTime: number; // Processing time in milliseconds
}

convertImageToSVG(imageElement, options?)

Synchronous version for HTMLImageElement inputs.

Parameters

• imageElement: HTMLImageElement - Loaded image element
• options: ConversionOptions (optional) - Conversion options

Returns

Same as convertPNGToSVG

Conversion Options

interface ConversionOptions {
  ltres?: number;           // Line threshold (0.5-2.0)
  qtres?: number;           // Quadratic spline threshold (0.5-2.0)
  pathomit?: number;        // Path omit threshold (0-16)
  rightangleenhance?: boolean; // Right angle enhancement
  colorsampling?: number;   // Color sampling mode (0-4)
  numberofcolors?: number;  // Number of colors (2-256)
  mincolorratio?: number;   // Minimum color ratio (0-1)
  colorquantcycles?: number; // Color quantization cycles (1-10)
  scale?: number;           // Scale factor (0.1-10.0)
  roundcoords?: number;     // Round coordinates (0-5)
  viewbox?: boolean;        // Enable viewBox
  desc?: boolean;           // Add description
  id?: boolean;             // Add ID
}

CLI Usage

png2svg <input.png> [options]

Options:
  -o, --output <file>     Output file path (default: input.svg)
  --ltres <number>        Line threshold (0.5-2.0, default: 1)
  --qtres <number>        Quadratic spline threshold (0.5-2.0, default: 1)
  --pathomit <number>     Path omit threshold (0-16, default: 6)
  --colors <number>       Number of colors (2-256, default: 8)
  --scale <number>        Scale factor (0.1-10.0, default: 1)
  -h, --help              Show help message
  -v, --version           Show version number

Examples

Basic Conversion

import { convertPNGToSVG } from 'png-to-svg-converter';

const pngData = await fetch('image.png').then(r => r.arrayBuffer());
const result = await convertPNGToSVG(pngData);

document.getElementById('output').innerHTML = result.svg;

Custom Options

import { convertPNGToSVG } from 'png-to-svg-converter';

const result = await convertPNGToSVG(pngBuffer, {
  numberofcolors: 16,    // More colors for better quality
  pathomit: 4,           // Higher detail
  scale: 2,              // Double size
  viewbox: true          // Enable viewBox
});

Browser File Upload

<input type="file" id="fileInput" accept="image/png">
<div id="preview"></div>

<script type="module">
  import { convertPNGToSVG } from 'png-to-svg-converter';

  document.getElementById('fileInput').addEventListener('change', async (e) => {
    const file = e.target.files[0];
    const buffer = await file.arrayBuffer();
    const result = await convertPNGToSVG(buffer);
    document.getElementById('preview').innerHTML = result.svg;
  });
</script>

Development

# Install dependencies
npm install

# Build the library
npm run build

# Run tests
npm test

# Run demo
npm run demo

# Development with watch mode
npm run dev

Browser Demo

Try the library in your browser: Demo

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Kyle Buzbee

Credits

• Built on top of ImageTracer.js by András Jankovics
• Inspired by various PNG to SVG conversion tools

Related

• ImageTracer.js - The core tracing library
• svg2png - SVG to PNG conversion