# @eyepop\.ai/eyepop-render-2d 中文文档

规范地址：https://npmcn.com/package/%40eyepop.ai/eyepop-render-2d/

版本：4\.0\.0
npm 元数据更新时间：2026-11-13T20:49:05.137Z
中文译文更新时间：2026-11-14T06:35:50.445Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：899 kB，11 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- 首次发布：2024-02-17T01:03:10.303Z
- 最新版本发布：2026-11-13T20:49:04.769Z
- 近 30 天下载量：2944（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：142（近 12 个月 50 个）

## 中文简介

节点.js / Typescript 库 2d 渲染 EyePop.ai 推论 API

## 安装

```sh
npm install @eyepop.ai/eyepop-render-2d
```

也可以使用：`pnpm add @eyepop.ai/eyepop-render-2d`、`yarn add @eyepop.ai/eyepop-render-2d`、`bun add @eyepop.ai/eyepop-render-2d`

## README

# EyePop.ai 第2d节点模块

EyePop.ai 节点模块为预测返回提供了方便的2d渲染功能 以 TypeScript 或 JavaScript 语言编写的应用程序推论 API.

模块要求 [眼球节点 SDK](https://www.npmjs.com/package/@eyepop.ai/eyepop)

## 安装

### 节点

```shell
npm install --save @eyepop.ai/eyepop @eyepop.ai/eyepop-render-2d
```

### 浏览器

```html
<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop-render-2d/dist/eyepop.render2d.min.js"></script>
```

## 用法实例

### 节点

这个 EyePop 节点模块提供了 2d 渲染,用于预测 `canvas.CanvasRenderingContext2D`。 。 。 .

```typescript
import { EyePop } from '@eyepop.ai/eyepop'
import { Render2d } from '@eyepop.ai/eyepop-render-2d'

import { createCanvas, loadImage } from 'canvas'
import { open } from 'openurl'
import { mkdtempSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { tmpdir } from 'node:os'

const example_image_path = 'examples/example.jpg'

;(async () => {
    const image = await loadImage(example_image_path)
    const canvas = createCanvas(image.width, image.height)
    const context = canvas.getContext('2d')
    const renderer = Render2d.renderer(context)

    context.drawImage(image, 0, 0)

    const endpoint = await EyePop.workerEndpoint({
        pop: {
            components: [
                {
                    type: 'inference',
                    ability: 'eyepop.person:latest',
                    categoryName: 'person',
                },
            ],
        },
    }).connect()
    try {
        let results = await endpoint.process({ source: { path: example_image_path } })
        for await (let result of results) {
            renderer.draw(result)
        }
    } finally {
        await endpoint.disconnect()
    }

    const tmp_dir = mkdtempSync(join(tmpdir(), 'ep-demo-'))
    const temp_file = join(tmp_dir, 'out.png')
    console.log(`creating temp file: ${temp_file}`)

    const buffer = canvas.toBuffer('image/png')
    writeFileSync(temp_file, buffer)

    open(`file://${temp_file}`)
})()
```

### 浏览器

```html
<!doctype html>
<html lang="en">
    <head>
        <script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop/dist/eyepop.min.js"></script>
        <script src="https://cdn.jsdelivr.net/npm/@eyepop.ai/eyepop-render-2d/dist/eyepop.render2d.min.js"></script>
    </head>
    <body>
        <!-- ... -->
        <input
            type="file"
            id="my-file-chooser"
        />
        <!-- ... -->
        <canvas id="my-canvas"></canvas>
        <!-- ... -->
        <script>
            async uploadFile(event) {
                const fileChooser = document.getElementById('my-file-chooser');
                const context = document.getElementById('my-canvas').getContext("2d");
                const renderer = Render2d.renderer(context);

                const endpoint = await EyePop.workerEndpoint({auth: {oAuth2: true}}).connect();
                await endpoint.changePop({ components: [{
                    type: 'inference',
                    model: 'eyepop.person:latest',
                    categoryName: 'person'
                }]})
                await endpoint.process({ source: {file: fileChooser.files[0]} }).then(async (results) => {
                    for await (let result of results) {
                        renderer.draw(result);
                    }
                });
                await endpoint.disconnect();
            });
        </script>
    </body>
</html>
```

### 招标规则

默认情况下, 2d 渲染器会为预测中每个顶级对象制作框和类标签. 改变此渲染行为, 在渲染规则中通过, 例如:

```javascript
// ...
Render2d.renderer(context, [Render2d.renderFace()]).draw(result)
// ...
```

每个规则都有 `render` 对象和 a `target` 属性。 所有预建课程都接受 JSONPath 表达式为 `target` 参数,用于选择哪些元素应从预测中提供. 见 [JSONPath 表达式](https://www.npmjs.com/package/jsonpath)

如下表所示,大多数预建类别提供了合理的缺省.

#### 装入相接箱和分类标签

```typescript
Render2d.renderBox({
    showClass: true,
    showConfidence: false,
    showTrackId: false,
    showNestedClasses: false,
    target: '$..objects.*',
})
```

#### 人体病变(2d或3d)

```typescript
Render2d.renderPose({
    target: '$..objects[?(@.category=="person")]',
})
```

#### 人手细节

```typescript
Render2d.renderHand({
    target: '$..objects[?(@.classLabel=="hand circumference")]',
})
```

#### 人相会

```typescript
Render2d.renderFace({
    showLabels: false,
    target: '$..objects[?(@.classLabel=="face")]',
})
```

#### 渲染文本( OCR 重叠)

```typescript
Render2d.renderText({
    target: '$..objects[?(@.classLabel=="text")]',
})
```

#### 线性分类标签

(原始内容存档于2017-10-21). Renders全相片分类标签. 显示默认 :

```typescript
Render2d.renderClasses({
    showConfidence: false,
    labelSizePercentage: 0.05,
    target: '$',
})
```

#### 渲染键

给任何携带它们的物体提供关键点。 显示默认 :

```typescript
Render2d.renderKeypoints({
    showLabels: false,
    target: '$..objects[?(@.keyPoints)]',
})
```

#### 分层罩

```typescript
Render2d.renderMask({
    target: '$..objects[?(@.mask)]',
})
```

#### 分层轮廓

```typescript
Render2d.renderContour({
    target: '$..objects[?(@.contours)]',
})
```

#### 渲染深度地图

渲染由深度估计能力(如:. `eyepop.depth.*`(中文(简体) ) 作为涡轮-彩色热图混合在相框上:相近=温暖(红色/黄色),相远=凉(蓝色). 天空像素( +无限) 除非 `renderSky` 已经设定.

```typescript
Render2d.renderDepth({
    target: '$',
    opacity: 0.5, // overlay opacity over the underlying frame
    renderSky: false, // also paint sky pixels
})
```

#### 模糊对象

```typescript
Render2d.renderBlur({
    target: '$..objects[?(@.classLabel=="face")]',
})
```

注意: 这当前在对象上画上一个固态填充, 而不是应用一个真正的模糊 .

#### 随时间推移将追踪对象拖入

```typescript
Render2d.renderTrail({
    target: '$..objects[?(@.traceId)]',
    trailLengthSeconds: 1,
})
```

默认情况下,这可以追溯到对象的边框的中点. 相反,人们也可以绘制被追踪对象的子对象或关键点的痕迹. 使用可选参数 `traceDetails` 为此. 例如追踪每个被追踪者的鼻子:

```typescript
Render2d.renderTrail({
    target: '$..objects[?(@.traceId)]',
    trailLengthSeconds: 1,
    traceDetails: '$..keyPoints[?(@.category=="3d-body-points")].points[?(@.classLabel.includes("nose"))]',
})
```

#### 自定义渲染执行

为实施自定义渲染规则,创建自定义类如下:

```typescript
import { PredictedObject, StreamTime } from '@eyepop.ai/eyepop'

export interface Render {
    target: string
    start(context: CanvasRenderingContext2D, style: Style): void
    draw(element: any, xOffset: number, yOffset: number, xScale: number, yScale: number, streamTime: StreamTime): void
}

export class RenderCustomImage implements Render {
    public target: string = "$..objects[?(@.category=='person')]"

    private context: CanvasRenderingContext2D | undefined
    private style: any

    // Optionally, add a constructor here. ie: constructor(...) { }

    // The start method sets the context and style properties.
    start(context: CanvasRenderingContext2D, style: any) {
        this.context = context
        this.style = style
    }

    // The draw method draws the image and line on the canvas based on the positions of the points in the PredictedObject.
    public draw(
        element: PredictedObject, // The object containing the keypoints
        xOffset: number, // The x offset for the drawing
        yOffset: number, // The y offset for the drawing
        xScale: number, // The x scale factor for the drawing
        yScale: number, // The y scale factor for the drawing
        streamTime: StreamTime, // The timestamp for the stream of predicted objects
    ): void {
        // Check if the context and style properties have been set
        if (!this.context || !this.style) {
            throw new Error('render() called before start()')
        }

        // Check if the keypoints are defined
        if (!element.keyPoints) return
        if (!element.keyPoints.length) return

        // Find the points of interest in the keypoints
        for (let i = 0; i < element.keyPoints.length; i++) {
            const kp = element.keyPoints[i]
            for (let j = 0; j < kp.points.length; j++) {
                const point = kp.points[j]
                if (point.classLabel === 'left eye' || point.classLabel === 'right eye') {
                    // Draw with the canvas context here
                }
            }
        }
    }
}
```

## 常见问题

### @eyepop\.ai/eyepop-render-2d 是什么？

节点\.js / Typescript 库 2d 渲染 EyePop\.ai 推论 API

### 如何安装 @eyepop\.ai/eyepop-render-2d？

在项目目录运行 npm install @eyepop\.ai/eyepop-render-2d，或使用 pnpm add / yarn add / bun add。

### @eyepop\.ai/eyepop-render-2d 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eyepop\.ai/eyepop-render-2d 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @eyepop\.ai/eyepop-render-2d 可以商用吗？

@eyepop\.ai/eyepop-render-2d 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @eyepop\.ai/eyepop-render-2d 的下载量有多少？

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

### @eyepop\.ai/eyepop-render-2d 还在维护吗？

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