# @chestnutlabs/gcode-model-renderer 中文文档

规范地址：https://npmcn.com/package/%40chestnutlabs/gcode-model-renderer/

版本：0\.21\.1
npm 元数据更新时间：2026-11-04T01:35:17.583Z
中文译文更新时间：2026-11-09T17:19:17.573Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40chestnutlabs/gcode-model-renderer
原文对照：https://npmcn.com/package/%40chestnutlabs/gcode-model-renderer/?lang=original
项目主页：https://github.com/ChestnutLabs/gcode-preview#readme
源码仓库：https://github.com/ChestnutLabs/gcode-preview

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

- 包体积（解压后）：167 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22
- 运行依赖：3 个
- peer 依赖：three ^0\.178\.0
- 首次发布：2026-08-24T16:58:18.502Z
- 最新版本发布：2026-11-04T01:35:17.214Z
- 近 30 天下载量：2144（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：18（近 12 个月 18 个）

## 中文简介

三.js源模型的演示文稿渲染器(STL/3MF)——干净的缩略图/卡片,不同于工具道检查(DD-018).

## 安装

```sh
npm install @chestnutlabs/gcode-model-renderer
```

也可以使用：`pnpm add @chestnutlabs/gcode-model-renderer`、`yarn add @chestnutlabs/gcode-model-renderer`、`bun add @chestnutlabs/gcode-model-renderer`

## README

# @chestnutlabs/ gcode- model- resanderer (英语)

3个J **列报** 源模型的渲染器——绘制 `.stl` 或者说 `.3mf` 网状为干净, 录音室的缩略语。 它会回答的 _"这是什么物体?"_,并且是故意的 **单独** 从 工具路径渲染器, 答案 _"这个打印/剪辑是如何运行的?"_ (设计:DD-018).

> **同伴依赖 :** `three` (支持范围) `^0.178.0`)——与这个包一起安装.

![Two presentation thumbnails: a neutral gray STL part (materials: unavailable) beside a red/amber/green three-object 3MF (materials: known)](https://raw.githubusercontent.com/ChestnutLabs/gcode-preview/dev/docs/media/model-render-stl-3mf.png)

用于文件浏览器缩略图、库卡和“文件内容”预览——图片 a 切片器显示一个部分,而不是工具路径。 检查实际移动情况(层、出行、接缝、, 颜色模式、活进度、使用 [`@chestnutlabs/gcode-renderer-three`](https://npmcn.com/package/%40chestnutlabs/gcode-renderer-three/README.md) 换句话说.

-   **STL 和 3MF** - 裸露的STL是没有申报材料的单一物体;3MF带来自己的物质 多对象结构,每个对象变换,以及每个对象/每个三角的物质颜色, 包括使用 3MF 的文件 **生产扩展** (单位:千美元)`p:path` (外部部分).
-   **生产多颜色** – 真正的 Bambu Studio / OrcaSlicer 文件用一个区域涂色 专有 `paint_color` 平面属性并保留调色板 `project_settings.config`中,没有 标准3MF材料。 渲染器解码出面绘格式( 清洁室, 见 [RR-005号](https://npmcn.com/package/docs/research/RR-005-3mf-paint-color-facet-format.md)并阅读 `filament_colour` 调色板本身,所以一个设计师的多彩模型在不切切切的情况下,以真实的颜色来制作.
-   **能力诚实颜色** 当来源声明颜色时——标准 3MF `basematerials`,或 `paint_color` + 有丝调色板——渲染器使用它们和报告 `materials: 'known'` (单位:千美元)`'approximated'` 当若干个多色的面被平整的时候。 当它宣布无时——a plain STL, 或没有调色板的油漆格式 —— 它绘制中性默认和报表 `materials: 'unavailable'`。它永远不会发明源色.
-   **固定列报形式** ——在共享渲染"相"上以3/4角度被设定 `@chestnutlabs/gcode-renderer-three`,在中性工作室轻型钻机下,透明(默认) 或可混入卡片的坚实背景.
-   **头没了** —— 说 `renderModelStill` 镜像工具端 `renderStill`: 递出字节, 拿回画布加马厩 `cacheKey` 编辑 `materials` 相信这一点。 运行在 任意铬级的WebGL2(一种 `OffscreenCanvas` 或无头的铬.
-   **交互式查看器** —— 说 `createModelViewer` 是静态的活模拟:轨道、缩放和平坦 浏览器中相同的 STL / 3MF( 包括生产多彩) `<canvas>`,带有相机预设,a 可序列相机状态, 和事件流 准备和错误.
-   **三种免费公共类型** —— 说 `ModelScene` 编号 : `ModelObject` 编号 : `MeshGeometry` 是数不清的, 所以包裹的表面不会漏出 `three`; 渲染器在内部构建出三个 meshes.

```ts
import { renderModelStill } from '@chestnutlabs/gcode-model-renderer';

// In a Worker with an OffscreenCanvas, or headless Chromium:
const { canvas, objectCount, materials, cacheKey } = await renderModelStill(
  { kind: '3mf', bytes },                        // or { kind: 'stl', bytes }
  { canvas: new OffscreenCanvas(512, 512), background: 'transparent' }
);
// materials === 'known'  → the render used colors the file declared
// materials === 'unavailable' → the file carried none; a neutral default was used (never faked)
const blob = await canvas.convertToBlob();
```

已经持有一个更正或更丰富的丝状调色板( 例如重交切出的文件) ? 过 `filamentPalette` (每以0为基数的位数)改为 `renderModelStill` 编号 : `parse3mf` 以覆盖读取的 从 `project_settings.config`. option —— 渲染器不读取文件自己的调色板.

## 交互式查看器

对于活地表面,用户可以轨道——用于源模型的"3D中的视频",相对于静态 缩略语.. `createModelViewer` 在共享相机下驱动同一场景,轨道控制 工具路径渲染器的使用 :

```ts
import { createModelViewer } from '@chestnutlabs/gcode-model-renderer';

const viewer = createModelViewer(canvas);           // a real <canvas> in the page
viewer.onEvent((e) => {
  if (e.type === 'ready') {
    // e.info.materials === 'known' | 'approximated' → showing the file's true colors
    // e.info.materials === 'unavailable'            → neutral render; don't claim "true colors"
    console.log(e.info.objectCount, e.info.materials, e.info.bounds);
  }
  if (e.type === 'renderer-unsupported') {
    // No WebGL — fall back to a renderModelStill image or a static thumbnail
  }
});

await viewer.setSource({ kind: '3mf', bytes });     // or { kind: 'stl', bytes }; parse → build → frame
viewer.setView('front');                            // 'iso' | 'top' | 'front' | 'back' | 'left' | 'right' | 'bottom'
// ...on unmount:
viewer.dispose();
```

拖入轨道,滚动到缩放,右拖至平板. `getCameraState()` 编号 : `setCameraState()` 持续和 恢复一个姿势( 相同的序列式) `CameraState` 作为工具的制造者, `resize(w, h)` 匹配一个 `ResizeObserver`,以及 `setInteractionQuality('auto')` 在轨道运行时进行关于平滑性的详细交易。 新设 源格式通过注册可查看 `ModelLoader` 用于新的 `kind`,无改动 取景器的API(设计: [DD-021号](https://npmcn.com/package/docs/design/DD-021-interactive-model-viewer.md)) (中文(简体) ).

第一个框架和 `frame()` (a"重置视图"按钮)将模型的边框与画布相接: a 宽而平的部分填满了宽的画布,仍然适合一个狭长的375px面板,以小边为中心. 在用户轨道、缩放或平板之前 `resize(w, h)` 重用模型,所以侧边栏倒塌 或窗口调整大小 永远不会离开它裁剪。 用户移动相机后, `resize` 保持他们的 视图,以及 `frame()` 手拍到观众 过 `autoFrameOnResize: false` 保留 首先设定跨大小。 这个 `camera-changed` 仅当用户手势稳定时,事件才会起火.

更喜欢自己造场景? `parseStl` 编号 : `parse3mf` 返回一个三自由 `ModelScene`,两个 仍然,观众接受一个预建 `ModelScene` 直接说.

## 框架中性准备控制器

`createModelPreviewController` 包装 `createModelViewer` 在控制器中塑造框架适配器 消耗——它是工具路径核心控制器的准备侧模拟. 在原始的观众上面 添加画布..`bindCanvas` 使用寿命周期( 重组在重载中存活; 最后一个源和任何队列控制) 操作重放在绑定上,一个单一的反应状态快照(`getState()` 编号 : `onStateChange()`),以及一个操作 队列, 因此在画布存在前的调用不会丢失 。 它背对 `/model` 伏特的后裔, React, Svelte, 和 Web 组件包; 直接使用它来构建自己的适配器.

```ts
import { createModelPreviewController } from '@chestnutlabs/gcode-model-renderer';

const controller = createModelPreviewController();
const off = controller.onStateChange((s) => {
  // s: ModelPreviewState — loading, ready, rendererSupported, objectCount, materials,
  //    instancedCount, decimationApplied, bounds, plates, hasPlates, cameraState, progress, error
});
controller.bindCanvas(canvas);                       // a real <canvas> in the page
await controller.controls.setSource({ kind: '3mf', bytes });
// ...on teardown:
off();
controller.dispose();
```

这两类合同是: `ModelPreviewControls` (单位:千美元)`setSource` 编号 : `setView` 编号 : `getCameraState` 编号 : `setCameraState` 编号 : `setBackground` 编号 : `setInteractionQuality` 编号 : `setRenderScope` 编号 : `frame` 编号 : `resize` 编号 : `capture`)和 `ModelPreviewState` 以上快照; `materials` 在那张快照里也是一样的诚实 平面和查看器报告(`'known'` 编号 : `'approximated'` 编号 : `'unavailable'`从来没有发明过).

手提式行为套装船 `/testing` 子路径 : `runModelBehavioralSuite(name, api, harness)` 运行一个共享的一套断言 针对任何适配器, 所以每个框架的 `<ModelViewer>` 对照与核心控制器相同的合同进行核查.

```ts
import { runModelBehavioralSuite } from '@chestnutlabs/gcode-model-renderer/testing';
```

见 [`docs/manual/adapters.md`](https://npmcn.com/package/docs/manual/adapters.md) "两个观众:预览和准备" 四个框架包装的跨适应器巡演.

决定主义( stills):相同的输入+相同的环境 QQ相同的输出. 跨GPU/驱动像素身份 未承诺——由返回的缓存 `cacheKey`。 。 。 .

部分 [栗子实验室 G 代码预览](https://npmcn.com/package/README.md) 麻省理工学院

## 常见问题

### @chestnutlabs/gcode-model-renderer 是什么？

三\.js源模型的演示文稿渲染器\(STL/3MF\)——干净的缩略图/卡片,不同于工具道检查\(DD-018\)\.

### 如何安装 @chestnutlabs/gcode-model-renderer？

在项目目录运行 npm install @chestnutlabs/gcode-model-renderer，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：three（^0\.178\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @chestnutlabs/gcode-model-renderer 支持 TypeScript 吗？

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

### @chestnutlabs/gcode-model-renderer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @chestnutlabs/gcode-model-renderer 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @chestnutlabs/gcode-model-renderer 可以商用吗？

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

### @chestnutlabs/gcode-model-renderer 的下载量有多少？

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

### @chestnutlabs/gcode-model-renderer 还在维护吗？

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