@image-tracer-ts/core

@image-tracer-ts/core

Trace images into SVG.

Typescript reimplementation of imagetracer-js.

Provides ESM and CJS packages.

The core package only works with ImageData, use @image-tracer-ts/browser or @image-tracer-ts/nodejs to trace different image formats (like PNG, JPEG, etc) from different sources (files, buffers, URLs, etc).

Basic Usage

import { ImageTracer, Options } from '@image-tracer/core';
const options: Partial<Options> = {fillStyle: 'stroke'}
const tracer = new ImageTracer(options)
const svgString = tracer.traceImage(imageData, drawer)

Options

Tracing happens in four steps, each comes with several configuration options. Pass them in a configuration object, or as command line parameter, prefixed with -- (i.e. --blurRadius 5).

Step 1: Image preprocessing

Optional steps to adjust image before processing.

Option	Type	Default	Description
blurRadius	number (between 0 and 5)	0 (off)	Number of pixels (in each direction) to calculate the blurred pixel value from.
blurDelta	number (0 - 4*255)	20	Maximum allowed difference between original pixel and blurred pixel when summing up RGBA values. If a blurred pixel exceeds delta, the original pixel is used instead.
sharpen	boolean	false	Use sharpen filter
sharpenThreshold	number (0 - 4*255)	20	Maximum allowed difference between original pixel and sharpened pixel when summing up RGBA values. If a sharpened pixel exceeds threshold, the original pixel is used instead.

Step 2: Building a color index

Create a base palette and apply clustering to the pixels in the image to build color layer masks.

Option	Type	Default	Description
colorSamplingMode	generate | sample | scan | palette	scan	Select how internal palette will be generated: generate: Generate colors along the spectrum independent of image colors. Builds a grayscale palette if less than 8 colors are requested. sample: Randomly access image for colors. scan: Step through the image along a raster. palette: Manually supply colors.
palette	Array<{r:number, g:number, b:number, a?:number}>	null	Array of colors to use with colorSamplingMode=palette
numberOfColors	number	16	Number of colors to be generated.
colorClusteringCycles	number	3	Number of color clustering cycles.
colorDistanceBuffering	off | on | reasonable	reasonable	Buffers color distances during clustering. Very efficient if palette has more than 30 colors.
minColorQuota	number (between 0 and 1)	0 (off)	Threshold for color pruning during color clustering. If ratio between pixels of a color and all pixels is below the given number, the color will be replaced by a random color.

Step 3: Tracing

Create vector data from pixels.

Option	Type	Default	Description
minShapeOutline	number	0 (off)	Discard traced areas with an outline of less than the given number of points.
interpolation	off | interpolate	interpolate	Sets interpolation mode.
enhanceRightAngles	boolean	true	Do not interpolate right angles.
lineErrorMargin	number	1	Line tracer error margin. Gives the squared maximum distance a point can be off a line trajectory to be still put on it.
curveErrorMargin	number	1	Curve tracer error margin. Gives the squared maximum distance a point can be off a curved trajectory to be put on it.

Step 4: Drawing

Create SVG data from vectors.

Option	Type	Default	Description
fillStyle	fill | stroke | stroke+fill	stroke+fill	Select how color segments are colored.
strokeWidth	number	1	Stroke width written to SVG path.
scale	number	1	Multiply all coordinates by this number.
decimalPlaces	number	1	Number of decimal places in svg values.
viewBox	boolean	true	If enabled, the viewBox attribute will be set on the SVG tag element.
trim	off | ratio | all	off	Removes empty border from the image.
lineFilter	boolean	false	Do not draw lines (areas with less than 3 points).
desc	boolean	false	Write a desc attribute to SVG edges with debug output
segmentEndpointRadius	number	0 (off)	Enables control output, draws white dots with given radius at segment borders.
curveControlPointRadius	number	0 (off)	Enables control output, draws curve control points as cyan dots with given radius.

Misc

Option	Type	Default	Description
verbose	boolean	false	Write status data to console during trace.
out	string	input file name + .svg	Set output file name (in ImageTracerNodejs)
preset	see preset names below	null	Use preset from command line

Named presets

Preset configurations can be imported from the Options object:

import { Options } from '@image-tracer/core';
ImageTracerBrowser.fromUrl<OutputType = string>(url, Options.Presets.posterized1)

From command line, the --preset parameter can be used along with a preset name:

• default
• posterized1 posterized2 posterized3
• curvy
• sharp
• detailed
• smoothed
• grayscale
• fixedpalette
• randomsampling1 randomsampling2
• artistic1 artistic2 artistic3 artistic4

Overriding the SVG Generator

You can provide a custom ImageDrawer to change how output is created from traced data:

const drawer = new CustomizedImageDrawer()
const svgString = new ImageTracer(options).traceImage(imageData, drawer)