feat: add optimization api

Author: twlite

CONTRIBUTING.md

@@ -92,10 +92,4 @@ The key words `“MUST”`, `“MUST NOT”`, `“REQUIRED”`, `“SHALL”`, `
 
 Make sure to properly format the source code, check for linter errors and test the code before pushing.
 
-## File Names
-
-1. Use `PascalCase` format if the file belongs to a class. Ex: `NobuBrowser.ts`, `ProtocolService.ts`, etc.
-2. Use `camelCase` format for the files that belong to functions. Ex: `contextMenu`, `appMenu`, etc.
-3. Use `lowercase` format for other cases.
-
 > 🎉 Happy coding!

Cargo.toml

@@ -11,8 +11,11 @@ crate-type = ["cdylib"]
 [dependencies]
 fastrand     = "2.4.1"
 image        = "0.25.10"
-napi         = "3.0.0"
+napi         = { version = "3.0.0", features = ["serde-json"] }
 napi-derive  = "3.0.0"
+oxvg_ast = { version = "0.0.5", features = ["parse", "roxmltree"] }
+oxvg_optimiser = "0.0.5"
+serde_json = "1.0"
 visioncortex = "0.8.10"
 
 [build-dependencies]

README.md

@@ -8,6 +8,18 @@ Node.js library to convert raster images to svg using [VTracer](https://github.c
 npx @neplex/vectorizer ./raster.png ./vector.svg
 ```
 
+Optimize while vectorizing:
+
+```bash
+npx @neplex/vectorizer ./raster.png ./vector.svg --optimize --multipass --multipass-iterations 5
+```
+
+Optimize an existing SVG:
+
+```bash
+npx @neplex/vectorizer optimize ./vector.svg ./vector.optimized.svg --plugin preset-default
+```
+
 Use `--help` to see all available options.
 
 ## Installation
@@ -42,112 +54,170 @@ console.log(svg); // <svg>...</svg>
 await writeFile('./vector.svg', svg);
 ```
 
-If you want to use a synchronous API, you can use `vectorizeSync` instead.
+The generated SVG string is generally quite large, so it's recommended to optimize it before use. See the [SVG Optimization section](#svg-optimization) for more details. If you want to use a synchronous API, you can use `vectorizeSync` instead. See the [API section](#api) for more details on available functions and options.
 
 ## Benchmark
 
 ```js
 yarn bench
-clk: ~5.30 GHz
+clk: ~5.32 GHz
 cpu: Intel(R) Core(TM) i7-14700K
 runtime: node 24.14.1 (x64-win32)
 
-benchmark                       avg (min … max) p75 / p99    (min … top 1%)
------------------------------------------------ -------------------------------
-@neplex/vectorizer raw sync      532.14 µs/iter 533.70 µs    ▂▇█▃▃
-                        (524.20 µs … 590.90 µs) 550.90 µs   ▂█████
-                        (  1.65 kb … 168.67 kb)   1.94 kb ▂▄███████▇▅▃▄▂▁▁▂▁▁▁▁
+benchmark                          avg (min … max) p75 / p99    (min … top 1%)
+-------------------------------------------------- -------------------------------
+@neplex/vectorizer raw sync         529.82 µs/iter 533.70 µs        ▅█▅
+                           (517.00 µs … 607.00 µs) 552.90 µs   ▅██▆▇████▄
+                           (  1.65 kb … 168.67 kb)   1.94 kb ▃███████████▆▄▃▂▁▂▂▂▁
 
-@neplex/vectorizer encoded sync  552.92 µs/iter 554.70 µs      █▄▂
-                        (544.90 µs … 613.00 µs) 569.60 µs    ▅████▆▃
-                        (  1.60 kb …  74.57 kb)   1.70 kb ▂▄████████▇▅▃▃▂▂▁▁▁▁▁
+@neplex/vectorizer encoded sync     549.19 µs/iter 552.70 µs       ▃█▆▇
+                           (534.80 µs … 597.10 µs) 573.50 µs    ▃▆▆████▆▄
+                           (  1.60 kb …  74.57 kb)   1.70 kb ▂▆██████████▆▄▂▂▂▂▂▁▁
 
-@neplex/vectorizer encoded async 617.69 µs/iter 650.90 µs  █▆
-                        (572.30 µs … 785.10 µs) 728.20 µs  ██▄▂
-                        (  2.27 kb …  76.16 kb)   2.35 kb ▅████▆▅▄▄▅▄▅██▅▃▂▁▂▁▂
+@neplex/vectorizer encoded async    585.94 µs/iter 586.00 µs   ▇█
+                           (561.70 µs … 745.10 µs) 691.10 µs   ██
+                           (  2.27 kb …  76.16 kb)   2.34 kb ▂▅███▅▃▂▂▁▁▁▁▁▁▂▁▁▁▁▁
 
-@neplex/vectorizer raw async     583.75 µs/iter 593.00 µs   █▃
-                        (551.50 µs … 721.00 µs) 677.90 µs  ████▄
-                        (  2.33 kb …  76.23 kb)   2.40 kb ▅█████▇▆▆▅▃▂▂▂▅▄▃▂▁▁▁
+@neplex/vectorizer encoded callback 684.02 µs/iter 698.80 µs    ▃▅▃▃█▂
+                           (632.30 µs … 844.90 µs) 770.60 µs  ▂▅██████▇▃
+                           (  4.27 kb …  44.40 kb)   4.48 kb ▂████████████▇▅▆▆▅▃▃▂
 
-@neplex/vectorizer raw callback  601.52 µs/iter 604.30 µs  █
-                          (561.30 µs … 1.18 ms)   1.11 ms ▇█
-                        (  5.02 kb … 217.06 kb)   5.48 kb ███▄▂▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁▁
+@neplex/vectorizer raw async        565.45 µs/iter 565.20 µs  ▂█
+                           (548.70 µs … 706.00 µs) 646.00 µs  ██▃
+                           (  2.33 kb … 186.42 kb)   2.58 kb ▂███▅▃▃▂▂▁▂▁▂▁▁▂▁▁▁▁▁
 
-imagetracerjs                      2.37 ms/iter   2.36 ms  █
-                            (2.32 ms … 2.92 ms)   2.65 ms  █▇
-                        (  1.17 mb …   6.89 mb)   4.52 mb ▆███▄▂▂▁▁▁▂▂▂▂▂▁▁▁▁▁▁
+@neplex/vectorizer raw callback     625.91 µs/iter 636.20 µs   ▃█▇
+                           (591.60 µs … 779.20 µs) 704.80 µs   ███▇
+                           (  3.98 kb … 374.13 kb)   4.62 kb ▂████████▄▅▆▅▆▄▄▃▁▂▁▂
 
-potrace trace                      3.83 ms/iter   4.72 ms     ▃█  ▅▇
-                            (1.82 ms … 7.31 ms)   6.73 ms   ▆ ██  ██▂ ▇█
-                        (175.78 kb …  12.23 mb)   2.34 mb ▄▇████▇▄███▄██▇▅▄▇▂▁▂
+imagetracerjs                         2.41 ms/iter   2.42 ms   █▇▂
+                               (2.33 ms … 2.93 ms)   2.73 ms  ████▂
+                           (  1.14 mb …   6.92 mb)   4.52 mb ▂█████▃▃▃▃▂▂▂▂▁▂▁▁▁▁▁
+
+potrace trace                         3.59 ms/iter   4.45 ms      █▅
+                               (1.70 ms … 7.43 ms)   6.36 ms  ▆▃█▂██▃ ▃▅▂  ▄
+                           (736.00  b …  11.91 mb)   2.27 mb ▃██████████████▇▃█▁▆▃
 
 summary
   @neplex/vectorizer raw sync
    1.04x faster than @neplex/vectorizer encoded sync
-   1.1x faster than @neplex/vectorizer raw async
-   1.13x faster than @neplex/vectorizer raw callback
-   1.16x faster than @neplex/vectorizer encoded async
-   4.45x faster than imagetracerjs
-   7.19x faster than potrace trace
+   1.07x faster than @neplex/vectorizer raw async
+   1.11x faster than @neplex/vectorizer encoded async
+   1.18x faster than @neplex/vectorizer raw callback
+   1.29x faster than @neplex/vectorizer encoded callback
+   4.54x faster than imagetracerjs
+   6.78x faster than potrace trace
 ```
 
 See [benchmark](https://github.com/neplextech/vectorizer/blob/main/benchmark/bench.ts) for more details.
 
 ## API
 
-### `vectorize(data: Buffer, config?: Config | Preset): Promise<string>`
+### `vectorize(data: Buffer, config?: Config | Preset, signal?: AbortSignal): Promise<string>`
 
 Takes an image buffer and returns a promise that resolves to an SVG string.
 
 ### `vectorizeSync(data: Buffer, config?: Config | Preset): string`
 
 Takes an image buffer and returns an SVG string synchronously.
 
-### `vectorizeRaw(data: Buffer, args: RawDataConfig, config?: Config | Preset): Promise<string>`
+### `vectorizeRaw(data: Buffer, args: RawDataConfig, config?: Config | Preset, signal?: AbortSignal): Promise<string>`
 
 Takes a raw pixel data buffer and returns a promise that resolves to an SVG string.
 
 ### `vectorizeRawSync(data: Buffer, args: RawDataConfig, config?: Config | Preset): string`
 
 Takes a raw pixel data buffer and returns an SVG string synchronously.
 
-### `vectorizeToCallback(data: Buffer, config: Config | Preset | null | undefined, callback: ([chunk, progress]) => void): Promise<void>`
+### `vectorizeToCallback(data: Buffer, config: Config | Preset | null | undefined, callback: (chunk: string, progress: number) => void): void`
+
+Vectorizes an image buffer and emits SVG chunks to the callback. `progress` is a number from 0 to 100 indicating how much of the vectorization has been written.
+
+### `vectorizeRawToCallback(data: Buffer, args: RawDataConfig, config: Config | Preset | null | undefined, callback: (chunk: string, progress: number) => void): void`
+
+Vectorizes raw pixel data and emits SVG chunks to the callback. `progress` is a number from 0 to 100.
+
+### `readImage(data: Buffer, args?: RawDataConfig, signal?: AbortSignal): Promise<ImageData>`
+
+Decodes an encoded image buffer, or a raw RGBA buffer when `args` is provided, and resolves image width, height, and pixels.
+
+### `readImageSync(data: Buffer, args?: RawDataConfig): ImageData`
 
-Vectorizes an image buffer and emits SVG chunks to the callback. `progress` is a number from 0–100 indicating how much of the vectorization has been written.
+Decodes an encoded image buffer, or a raw RGBA buffer when `args` is provided, synchronously.
 
-### `vectorizeRawToCallback(data: Buffer, args: RawDataConfig, config: Config | Preset | null | undefined, callback: ([chunk, progress]) => void): Promise<void>`
+### `colorExistsInImage(image: ImageData, color: Color, signal?: AbortSignal): Promise<boolean>`
 
-Vectorizes raw pixel data and emits SVG chunks to the callback. `progress` is a number from 0–100.
+Checks asynchronously whether a decoded image contains the given RGB color.
 
-### `isEOF(data: [string, number]): boolean`
+### `colorExistsInImageSync(image: ImageData, color: Color): boolean`
+
+Checks synchronously whether a decoded image contains the given RGB color.
+
+### `findUnusedColorInImage(image: ImageData, options?: InternalOptions, signal?: AbortSignal): Promise<Color>`
+
+Finds asynchronously a color that does not exist in decoded image data.
+
+### `findUnusedColorInImageSync(image: ImageData, options?: InternalOptions): Color`
+
+Finds synchronously a color that does not exist in decoded image data.
+
+### `optimize(svg: string, options?: OptimizeOptions, signal?: AbortSignal): Promise<string>`
+
+Optimizes an SVG string asynchronously. Supports the same options as `optimizeSync`.
+
+### `optimizeSync(svg: string, options?: OptimizeOptions): string`
+
+Optimizes an SVG string synchronously.
+
+`OptimizeOptions` supports:
+
+- `preset?: OptimizePreset`: `Default`, `Safe`, or `None`.
+- `plugins?: Array<string | { name: string, params?: unknown }>`: SVGO `Config["plugins"]` compatible job config. When provided, this defines the optimizer job set.
+- `omit?: string[]`: optimizer job names to skip.
+- `multipass?: boolean`: run optimization until output stops changing or the iteration limit is reached.
+- `multipassIterations?: number`: maximum multipass iterations. Defaults to `10`.
+
+### `isEOF(chunk: string, progress: number): boolean`
 
 Determines if the given chunk data indicates the end of the SVG output. Useful for callback-based vectorization to know when the final chunk has been received. Note that EOF here refers to the final chunk of svg, which is `</svg>\n`.
 
 ```js
-await vectorizeToCallback(src, config, (chunk) => {
-  if (isEOF(chunk)) {
-    console.log('SVG output complete!');
+const { promise, resolve } = Promise.withResolvers<void>();
+
+vectorizeToCallback(src, config, (chunk, progress) => {
+  if (isEOF(chunk, progress)) {
+    resolve();
   }
 });
+
+await promise; // block until all the SVG chunks have been received
+console.log('SVG output complete!');
 ```
 
 ## SVG Optimization
 
-The raw output from `vectorize` can be significantly reduced in size using optimizers like [`@oxvg/napi`](https://www.npmjs.com/package/@oxvg/napi):
+The raw output from `vectorize` can be significantly reduced in size using the built-in optimizer powered by [oxvg_optimiser](https://github.com/noahbald/oxvg):
 
 ```js
-import { vectorize } from '@neplex/vectorizer';
-import { optimise } from '@oxvg/napi';
+import { optimize, vectorize } from '@neplex/vectorizer';
 import { readFile, writeFile } from 'node:fs/promises';
 
 const src = await readFile('./input.png');
 const svg = await vectorize(src);
-const optimized = optimise(svg);
+const optimized = await optimize(
+  svg,
+  /* optional config */ {
+    plugins: ['preset-default', { name: 'removeTitle' }], // supports svgo plugin config
+    multipass: true, // enable multipass optimization
+    multipassIterations: 5, // limit multipass iterations to 5
+  },
+);
 
 await writeFile('./output.svg', optimized);
 ```
 
+> Note that the optimizer included in this library is a thin wrapper around `oxvg_optimiser` and does not intend to provide all the features of `oxvg`. For advanced needs, consider using `@oxvg/napi` directly.
+
 ## Demo
 
 Generated under the following configuration:

__test__/cli.spec.ts

@@ -0,0 +1,81 @@
+import test from 'ava';
+import { execFile } from 'node:child_process';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const cliPath = resolve('cli/index.mjs');
+const redPixel = Buffer.from([255, 0, 0, 255]);
+
+test('cli vectorizes with on-the-fly optimization', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'vectorizer-cli-'));
+  t.teardown(() => rm(dir, { recursive: true, force: true }));
+  const inputPath = join(dir, 'pixel.rgba');
+  const outputPath = join(dir, 'pixel.svg');
+
+  await writeFile(inputPath, redPixel);
+
+  const { stderr } = await execFileAsync(process.execPath, [
+    cliPath,
+    inputPath,
+    outputPath,
+    '--raw',
+    '1x1',
+    '--preset',
+    'poster',
+    '--optimize',
+    '--optimize-plugin',
+    'removeComments',
+  ]);
+
+  const svg = await readFile(outputPath, 'utf8');
+  t.true(svg.includes('<svg'));
+  t.regex(stderr, /Progress:/);
+  t.regex(stderr, /Optimized/);
+});
+
+test('cli optimize command optimizes an existing svg file', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'vectorizer-cli-'));
+  t.teardown(() => rm(dir, { recursive: true, force: true }));
+  const inputPath = join(dir, 'input.svg');
+  const outputPath = join(dir, 'output.svg');
+
+  await writeFile(inputPath, '<svg xmlns="http://www.w3.org/2000/svg"><!-- remove me --><g><path d="M0 0"/></g></svg>');
+
+  const { stderr } = await execFileAsync(process.execPath, [
+    cliPath,
+    'optimize',
+    inputPath,
+    outputPath,
+    '--plugin',
+    'removeComments',
+  ]);
+
+  const svg = await readFile(outputPath, 'utf8');
+  t.true(svg.includes('<svg'));
+  t.false(svg.includes('remove me'));
+  t.regex(stderr, /Optimized/);
+});
+
+test('cli print streams svg chunks without a progress bar', async (t) => {
+  const dir = await mkdtemp(join(tmpdir(), 'vectorizer-cli-'));
+  t.teardown(() => rm(dir, { recursive: true, force: true }));
+  const inputPath = join(dir, 'pixel.rgba');
+
+  await writeFile(inputPath, redPixel);
+
+  const { stdout, stderr } = await execFileAsync(process.execPath, [
+    cliPath,
+    inputPath,
+    '--raw',
+    '1x1',
+    '--preset',
+    'poster',
+    '--print',
+  ]);
+
+  t.true(stdout.includes('<svg'));
+  t.false(stderr.includes('Progress:'));
+});