# @gatsbyjs/potrace 中文文档

规范地址：https://npmcn.com/package/%40gatsbyjs/potrace/

版本：3\.0\.0
npm 元数据更新时间：2026-06-30T21:59:41.901Z
中文译文更新时间：2026-11-16T00:06:40.011Z
软件包许可：GPL-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gatsbyjs/potrace
原文对照：https://npmcn.com/package/%40gatsbyjs/potrace/?lang=original
项目主页：https://github.com/tooolbox/node-potrace#readme
源码仓库：https://github.com/tooolbox/node-potrace

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：97.3 kB，18 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：1 个
- 首次发布：2022-03-29T21:09:44.231Z
- 最新版本发布：2022-11-25T10:53:02.707Z
- 近 30 天下载量：78083（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

Potrace in Javascript, 用于节点JS

## 安装

```sh
npm install @gatsbyjs/potrace
```

也可以使用：`pnpm add @gatsbyjs/potrace`、`yarn add @gatsbyjs/potrace`、`bun add @gatsbyjs/potrace`

## README

# 节点-选取

节点JS兼容叉 [在 JavaScript 中的 potrace](https://github.com/kilobtye/potrace) 加上一些添加,这反过来又是一个港口 [原始波崔斯语](http://potrace.sourceforge.net/) ——追踪位图的工具.

![Node.js CI](https://github.com/tooolbox/node-potrace/workflows/Node.js%20CI/badge.svg)

## 示例和演示

| **原始图像** | **Potrace 输出** | **邮寄产出** |
| --- | --- | --- |
| ![](https://npmcn.com/package/%40gatsbyjs/potrace/test/sources/yao.jpg) | ![](https://cdn.rawgit.com/tooolbox/node-potrace/9ee822d/test/example-output.svg) | ![](https://cdn.rawgit.com/tooolbox/node-potrace/9ee822d/test/example-output-posterized.svg) |

(从 [浏览器版本的在线演示](http://kilobtye.github.io/potrace/)(中文(简体) )

## 使用量

安装

```sh
npm install potrace
```

基本用途

```js
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);
});
```

您也可以提供配置对象作为第二个参数.

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

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

如果您想在同一图像上多次运行波崔斯算法, 并设定不同的阈值, 将结果合并到一个文件中 - `posterize` 方法就是这样.

```js
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) {
  /*...*/
});
```

### 高级使用和配置

两者 `trace` 财务报告和审定财务报表 `posterize` 方法返回实例 `Potrace` 财务报告和审定财务报表 `Posterizer` 分类为第三个参数.

您也可以直接即兴上课:

```js
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');
});
```

回调函数提供给 `loadImage` 方法将结合 `Potrace`编号 :`Posterizer` 因此,如果它不违反你的代码风格 - 你可以只是做

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

[Jimp 模块](https://github.com/oliver-moran/jimp) 用于后端,所以第一个参数为 `loadImage` 方法可以是 Jimp 能读到的任何东西: a `Buffer`,本地路径或url字符串。 所支持的格式有: PNG, JPEG 或 BMP. 也可以是 Jimp 实例( 前提是位图没有修改)

### 参数

`Potrace` 类预期以下参数:

-   **转动政策** - 如何解决路径分解中的模糊问题。 可能值导出为常数 : `TURNPOLICY_BLACK`, (中文(简体) ), `TURNPOLICY_WHITE`, (中文(简体) ), `TURNPOLICY_LEFT`, (中文(简体) ), `TURNPOLICY_RIGHT`, (中文(简体) ), `TURNPOLICY_MINORITY`, (中文(简体) ), `TURNPOLICY_MAJORITY`。参见 [此文档](http://potrace.sourceforge.net/potrace.pdf) 更多信息(第4页)  
    (默认 : `TURNPOLICY_MINORITY`(中文(简体) )
-   **粪便大小** - 压制这种大小的光谱  
    (默认: 2)
-   **α-最大值** - 角阈值参数  
    (默认:1)
-   **选择调查** - 曲线优化  
    (默认:真实)
-   **选择容忍** - 曲线优化可容性  
    (违约:0.2)
-   **阈值** - 低于这个界限的颜色被视为黑色. 数字应为0.255或 `THRESHOLD_AUTO` 在此情况下,将自动使用 [多层线程算法](http://www.iis.sinica.edu.tw/page/jise/2001/200109_01.pdf)  
    (默认 : `THRESHOLD_AUTO`(中文(简体) )
-   **黑色白色** - 指定从阈值变为矢量形状的颜色  
    (默认 : `true`(中文(简体) )
-   **颜色** - 充满颜色。 导出为 < symbol> 时将被忽略( 默认 : `COLOR_AUTO`,这意味着黑色或白色,取决于 `blackOnWhite` (财产)
-   **背景情况** - 背景颜色。 导出为“ symbol” 时会被忽略 。 默认不存在( N)`COLOR_TRANSPARENT`(中文(简体) )

* * *

`Posterizer` 类方法与 `Potrace`,但 `.getPathTag()`。 。 。 . 配置对象以下列属性扩展 :

-   **填充战略** - 确定如何为每一层选择填充颜色。 可能值导出为常数 :
    -   `FILL_DOMINANT` - 范围内最常使用的颜色(默认使用),
    -   `FILL_MEAN` - 算术平均值(平均),
    -   `FILL_MEDIAN` - 中间颜色,
    -   `FILL_SPREAD` - 忽略图像的颜色信息,只是将颜色在 0. < 阈值 > (或 < 阈值 >. 255) 范围内平均分布 `blackOnWhite` 设置为 `false`, (中文(简体) ),
-   **分布范围** - 如何选择每一层的颜色停止。 如果 `steps` 是一个数组。 可能的值是:
    -   `RANGES_AUTO` - 执行自动阈值(使用 [多层线程算法](http://www.iis.sinica.edu.tw/page/jise/2001/200109_01.pdf)) (中文(简体) ). 已标注的源的可取方法,但计算出5个或更多阈值(时间复杂)需要很长时间  
        _(默认使用)_
    -   `RANGES_EQUAL` - 忽略图像的颜色信息,并将可用的颜色空间分割成等块
-   **步骤** - 在生成的图像中指定所需分层的数量。 如果提供数字 -- -- 每个层的阈值将自动按照 `rangeDistribution` 参数。 如果一个阵列提供了它,则它预期是一个阵列,每层都有预先计算出的阈值(在0.255之间)  
    (默认 : `STEPS_AUTO` 将导致 `3` 或者说 `4`,取决于 `threshold` 数值)
-   **阈值** - 将图像分解为前地和后地(而只有前地被分解为所期望的地层数). 基本上,当它成为最后一个(最不透明)层的门槛,然后 `steps - 1` 中间阈值计算. 若为 **步骤** 是一个阈值的数组,而且数组的每个值都较低(如果 **黑色白色** 参数设置为 `false`) 而不是阈值 - 阈值将被添加到数组中,否则会被忽略.  
    (默认 : `Potrace.THRESHOLD_AUTO`(中文(简体) )
-   _potrace 类接受的所有其他参数_

**注释:**

-   当数量 `steps` 大于 10 - 可以增加一层,以确保在需要时有最暗/最亮的颜色,以确保有可能非常重要的这一点细节,如阴影或线条艺术.
-   由于生成了大量地层,由于地层是如何被合成的,在渲染阶段的数学出错,整体看起来会比原作更亮.
-   默认配置 `steps`, (中文(简体) ), `threshold` 财务报告和审定财务报表 `rangeDistribution` 设置全部设置为自動,结果用上面提到的多级切入算法计算出4个阈值/颜色停止. 计算4个阈值平均需要3至5秒。 您可能想要明确限制 `steps` 至3至中度提高处理速度.

## 感谢

-   彼得·塞林格为 [原始 Potrace 工具和算法](http://potrace.sourceforge.net/)
-   @kilobtye 原创 [javascript 端口](https://github.com/kilobtye/potrace)

## 许可证

GNU通用公共许可版本2(GPLv2). 请看 [许可证文件](https://npmcn.com/package/%40gatsbyjs/potrace/LICENSE) 更多信息.

## 常见问题

### @gatsbyjs/potrace 是什么？

Potrace in Javascript, 用于节点JS

### 如何安装 @gatsbyjs/potrace？

在项目目录运行 npm install @gatsbyjs/potrace，或使用 pnpm add / yarn add / bun add。

### @gatsbyjs/potrace 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/gatsbyjs\_\_potrace 是否存在。

### @gatsbyjs/potrace 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @gatsbyjs/potrace 可以商用吗？

@gatsbyjs/potrace 使用 GPL-2\.0 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @gatsbyjs/potrace 的下载量有多少？

根据 npm 官方下载统计，@gatsbyjs/potrace 在 2026/10/16 – 2026/11/14 这 30 天内被下载 78,083 次，日均约 2,603 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @gatsbyjs/potrace 还在维护吗？

最新版本 3\.0\.0 发布于 2022/11/25（3 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2022/03/30。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

