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.
This version of node-potrace supports setting up the color of an image border (stroke). You can get a coloured single line as a contour of image.
Original image | Potrace output | Posterized output |
---|---|---|
![]() |
(Example image inherited from online demo of the browser version)
Install
npm install --save https://github.com/stickerum/node-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 color for a whole image */
background: '#49ffd2',
/** Foreground color of traced image */
color: 'blue',
/** Color of traced image's border */
outline: 'red',
/** Below which color is considered black (0..255) */
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) {
/*...*/
});
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)
Potrace
class expects following parameters:
- turnPolicy - how to resolve ambiguities in path decomposition. Possible values are exported as constants:
TURNPOLICY_BLACK
,TURNPOLICY_WHITE
,TURNPOLICY_LEFT
,TURNPOLICY_RIGHT
,TURNPOLICY_MINORITY
,TURNPOLICY_MAJORITY
. Refer to this document for more information (page 4)
(default:TURNPOLICY_MINORITY
) - turdSize - suppress speckles of up to this size
(default: 2) - alphaMax - corner threshold parameter
(default: 1) - optCurve - curve optimization
(default: true) - optTolerance - curve optimization tolerance
(default: 0.2) - threshold - threshold below which color is considered black.
Should be a number in range 0..255 or
THRESHOLD_AUTO
in which case threshold will be selected automatically using Algorithm For Multilevel Thresholding
(default:THRESHOLD_AUTO
) - blackOnWhite - specifies colors by which side from threshold should be turned into vector shape
(default:true
) - color - Fill color. Will be ignored when exporting as <symbol>. (default:
COLOR_AUTO
, which means black or white, depending onblackOnWhite
property) - background - Background color. Will be ignored when exporting as <symbol>. By default is not present (
COLOR_TRANSPARENT
) - outline - Border color. (default:
VALUE_NONE
, which meansnone
)
Posterizer
class has same methods as Potrace
, in exception of .getPathTag()
.
Configuration object is extended with following properties:
- fillStrategy - determines how fill color for each layer should be selected. Possible values are exported as constants:
FILL_DOMINANT
- most frequent color in range (used by default),FILL_MEAN
- arithmetic mean (average),FILL_MEDIAN
- median color,FILL_SPREAD
- ignores color information of the image and just spreads colors equally in range 0..<threshold> (or <threshold>..255 ifblackOnWhite
is set tofalse
),
- rangeDistribution - how color stops for each layer should be selected. Ignored if
steps
is an array. Possible values are:RANGES_AUTO
- Performs automatic thresholding (using Algorithm For Multilevel Thresholding). Preferable method for already posterized sources, but takes long time to calculate 5 or more thresholds (exponential time complexity)
(used by default)RANGES_EQUAL
- Ignores color information of the image and breaks available color space into equal chunks
- steps - Specifies desired number of layers in resulting image. If a number provided - thresholds for each layer will be automatically calculated according to
rangeDistribution
parameter. If an array provided it expected to be an array with precomputed thresholds for each layer (in range 0..255)
(default:STEPS_AUTO
which will result in3
or4
, depending onthreshold
value) - threshold - Breaks image into foreground and background (and only foreground being broken into desired number of layers). Basically when provided it becomes a threshold for last (least opaque) layer and then
steps - 1
intermediate thresholds calculated. If steps is an array of thresholds and every value from the array is lower (or larger if blackOnWhite parameter set tofalse
) than threshold - threshold will be added to the array, otherwise just ignored.
(default:Potrace.THRESHOLD_AUTO
) - all other parameters that Potrace class accepts
Notes:
- When number of
steps
is greater than 10 - an extra layer could be added to ensure presence of darkest/brightest colors if needed to ensure presence of probably-important-at-this-point details like shadows or line art. - With big number of layers produced image will be looking brighter overall than original due to math error at the rendering phase because of how layers are composited.
- With default configuration
steps
,threshold
andrangeDistribution
settings all set to auto, resulting in a 4 thresholds/color stops being calculated with Multilevel Thresholding algorithm mentioned above. Calculation of 4 thresholds takes 3-5 seconds on average laptop. You may want to explicitly limit number ofsteps
to 3 to moderately improve processing speed.
- Peter Selinger for original Potrace tool and algorithm
- @kilobtye for original javascript port
The GNU General Public License version 2 (GPLv2). Please see License File for more information.