search

tooolbox / node-potrace

JavaScript port of Potrace, for NodeJS
GNU General Public License v2.0
388 stars 34 forks source link

readme

node-potrace

A NodeJS-compatible fork of Potrace in JavaScript with some additions, which is in turn a port of the original Potrace — a tool for tracing bitmaps.

Node.js CI

Example and demo

Original image Potrace output Posterized output

(Example image inherited from online demo of the browser version)

Usage

Install

npm install potrace

Basic usage

var potrace = require('potrace'),
    fs = require('fs');

potrace.trace('./path/to/image.png', function(err, svg) {
  if (err) throw err;
  fs.writeFileSync('./output.svg', svg);
});

You can also provide a configuration object as a second argument.

var params = {
  background: '#49ffd2',
  color: 'blue',
  threshold: 120
};

potrace.trace('./path/to/image.png', params, function(err, svg) {
  /*...*/
});

If you want to run Potrace algorithm multiple times on the same image with different threshold setting and merge results together in a single file - posterize method does exactly that.

potrace.posterize('./path/to/image.png', { threshold: 180, steps: 4 }, function(err, svg) {
  /*...*/
});

// or if you know exactly where you want to break it on different levels

potrace.posterize('./path/to/image.png', { steps: [40, 85, 135, 180] }, function(err, svg) {
  /*...*/
});

Advanced usage and configuration

Both trace and posterize methods return instances of Potrace and Posterizer classes respectively to a callback function as third argument.

You can also instantiate these classes directly:

var potrace = require('potrace');

// Tracing

var trace = new potrace.Potrace();

// You can also pass configuration object to the constructor
trace.setParameters({
  threshold: 128,
  color: '#880000'
});

trace.loadImage('path/to/image.png', function(err) {
  if (err) throw err;

  trace.getSVG(); // returns SVG document contents
  trace.getPathTag(); // will return just <path> tag
  trace.getSymbol('traced-image'); // will return <symbol> tag with given ID
});

// Posterization

var posterizer = new potrace.Posterize();

posterizer.loadImage('path/to/image.png', function(err) {
  if (err) throw err;

  posterizer.setParameter({
    color: '#ccc',
    background: '#222',
    steps: 3,
    threshold: 200,
    fillStrategy: potrace.Posterize.FILL_MEAN
  });

  posterizer.getSVG();
  // or
  posterizer.getSymbol('posterized-image');
});

Callback function provided to loadImage methods will be executed in context of the Potrace/Posterizer instance, so if it doesn't go against your code style - you can just do

new potrace.Potrace()
  .loadImage('path/to/image.bmp', function() {
    if (err) throw err;
    this.getSymbol('foo');
  });

Jimp module is used on the back end, so first argument accepted by loadImage method could be anything Jimp can read: a Buffer, local path or a url string. Supported formats are: PNG, JPEG or BMP. It also could be a Jimp instance (provided bitmap is not modified)

Parameters

Potrace class expects following parameters:

Posterizer class has same methods as Potrace, in exception of .getPathTag(). Configuration object is extended with following properties:

Notes:

Thanks to

License

The GNU General Public License version 2 (GPLv2). Please see License File for more information.