printbench 0.8.3 → 0.8.6

package/README.md

@@ -59,6 +59,7 @@ function onExported(payload: PrintBenchExportedPayload) {
   // payload.longestEdgeMm — 若导出时指定了目标边长缩放
   // payload.scaleAxis — 若按 X/Y/Z 轴缩放（最长边模式不带此字段）
   // payload.partIds / modelSize — 分件导出时带回写出的零件与缩放后整模尺寸
+  // payload.groundCenter — 若导出时置于地面中心
 }
 </script>
 
@@ -89,14 +90,15 @@ function onExported(payload: PrintBenchExportedPayload) {
 | `modelUrl`        | `string`                                              | —         | 挂载后按 URL 自动导入模型（需 CORS）                                                                              |
 | `uploadUrl`       | `string`                                              | —         | 「一键上传」的 POST 地址；未设则无法上传                                                                              |
 | `customExport`    | `boolean`                                             | `false`   | 为 `true` 时，下载 / 一键上传只生成文件并触发 `exported` 或 `snapshot`（用 `action` 区分），不本地下载、不 POST                    |
-| `mode`            | `'edit' | 'preview'`                                  | `'edit'`  | `preview` 为嵌入几何只读：隐藏工作台壳，画布可旋转与点选零件，不能改网格。画布左上角默认提供灯光模式下拉（标准照明 / 摄影棚 / 环境光照 / 跟随头灯），可用 `features.hidePreviewLighting` 隐藏 |
+| `mode`            | `'edit' | 'preview'`                                  | `'edit'`  | `preview` 为嵌入几何只读：隐藏工作台壳，画布可旋转与点选零件，不能改网格。画布左上角默认提供灯光模式下拉（标准照明 / 摄影棚 / 环境光照 / 展台照明 / 跟随头灯），可用 `features.hidePreviewLighting` 隐藏 |
 | `selectedPartIds` | `string[]`                                            | —         | 受控选中。传入后画布点击只触发 `select-part`，由宿主回写                                                                  |
 | `partColors`      | `Record<string, string>`                              | —         | 受控零件色，`#RRGGBB`，key 为零件 `id`                                                                         |
-| `bedSizeMm`       | `{ x, y, z }`                                         | —         | 宿主默认打印床体积（mm：X/Z 床面，Y 高度）。挂载时写入设置一次，之后仍可在布局区/设置中修改                                   |
+| `upAxis`          | `'z-up' \| 'y-up'`                                    | —         | 宿主默认世界坐标系（新安装默认 `z-up`）。挂载时写入设置一次；之后可在设置中切换（需确认，会重定向已加载模型） |
+| `bedSizeMm`       | `{ x, y, z }`                                         | —         | 宿主默认打印床体积（mm：高度为 up 轴分量，Z-up 时 z 为高、xy 为床面）。挂载时写入设置一次，之后仍可在布局区/设置中修改 |
 | `showBedVolume`   | `boolean`                                             | —         | 宿主默认是否显示打印床线框。挂载时写入设置一次，之后仍可开关（未传时默认隐藏）                                            |
 | `showGrid`        | `boolean`                                             | `true`    | 宿主默认是否显示地面网格。挂载时写入设置一次                                                          |
 | `gridAutoFit`     | `boolean`                                             | —         | 宿主默认网格是否随模型包围盒放大（设置默认 `true`）。挂载时若传入则写入一次；固定尺寸时请设 `false`                              |
-| `gridSizeMm`      | `{ x, y, z }`                                         | —         | 宿主默认固定网格尺寸（mm，边长取 max(X,Z)，20 格）。挂载时写入一次；若未同时传 `gridAutoFit`，会自动设为固定尺寸（`gridAutoFit: false`） |
+| `gridSizeMm`      | `{ x, y, z }`                                         | —         | 宿主默认固定网格尺寸（mm，边长取床面两轴 max，20 格）。挂载时写入一次；若未同时传 `gridAutoFit`，会自动设为固定尺寸（`gridAutoFit: false`） |
 | `diagnosisZIndex` | `number`                                              | `100`     | 诊断浮层 `z-index`。也可在外层设 CSS 变量 `--printbench-diagnosis-z`                                         |
 | `annotations`     | `Annotation[]` \| `AnnotationDocument` \| `string`     | —         | 模型批注（世界坐标 mm）。需同时打开 `features.annotations` 才能编辑；详见下方「批注」           |
 | `features`        | `{ numeric?, primitives?, split?, autoSplit?, drafts?, extras?, restore?, layout?, importUnit?, hideEmpty?, hideTour?, hideStatusBar?, hidePanelModeToggle?, hidePreviewLighting?, annotations?, … }` | 能力项默认 `false` | 进阶能力。缺省精简：左栏仅导入 / 零件 / 导出 / 快照。未开 `drafts` 时不读不写自动草稿。导入单位优先用文件声明，否则按包围盒尺寸推测 mm/cm/m 再换算到内部毫米；开 `importUnit` 时可再确认。`split` 为切面拆件；`autoSplit` 为「自动拆件」按钮（默认隐藏，需显式打开）。`restore` 为「复原到导入状态」按钮（默认隐藏，宿主需显式打开；完整工作台预设已开启）。`layout` 打开贴地 / 镜像 / 目标尺寸缩放 / 选面朝下与打印床体积。`annotations` 打开模型批注（默认关闭，`PRINTBENCH_FULL_FEATURES` 也不含该项）。`hideEmpty` / `hideTour` / `hideStatusBar` / `hidePanelModeToggle` / `hidePreviewLighting` 为 `true` 时分别隐藏空画布提示、首次引导 Tour（可与 `extras` 同开）、底栏状态条、零件栏悬浮/通栏切换按钮、预览模式左上角灯光模式控件（默认显示）。 |
@@ -173,7 +175,7 @@ async function upload() {
 </template>
 ```
 
-`mode="preview"` 时插件不显示导出 / 快照按钮。宿主用 `ref.exportFile()` / `ref.exportSnapshot()` 只要文件：`customExport` 为 true 时不本地下载、不 POST，返回 `blob` 后由宿主保存或上传。工作台左栏导出与快照仍可用 `uploadUrl` 走插件上传。预览画布左上角默认显示灯光模式（与设置中同一套：`neutral` 标准照明、`studio` 摄影棚、`ibl` 环境光照、`headlamp` 跟随头灯）；宿主可设 `:features="{ hidePreviewLighting: true }"` 隐藏该控件。
+`mode="preview"` 时插件不显示导出 / 快照按钮。宿主用 `ref.exportFile()` / `ref.exportSnapshot()` 只要文件：`customExport` 为 true 时不本地下载、不 POST，返回 `blob` 后由宿主保存或上传。工作台左栏导出与快照仍可用 `uploadUrl` 走插件上传。预览画布左上角默认显示灯光模式（与设置中同一套：`neutral` 标准照明、`studio` 摄影棚、`ibl` 环境光照、`sandbox` 展台照明、`headlamp` 跟随头灯）以及「原始法线」开关；宿主可设 `:features="{ hidePreviewLighting: true }"` 隐藏该控件。`sandbox`（展台照明）为蓝灰全景背景 + IBL，低仰角暖主光与冷轮廓光，环境光只做补光，适合验收预览。「原始法线」（设置项 `useAuthorNormals`，默认关闭）与灯光模式独立：开启时优先用导入的平滑法线做预览，无可用法线时静默回退重算，不影响打印。
 
 `exportFile` 的 `longestEdgeMm` 与导出对话框「目标边长」一致：按内部毫米将参考边（默认最长边，或 `scaleAxis` 指定的 X/Y/Z）缩到该值后再换算 `unit` 写出。省略则不缩放。默认 `scaleBasis: 'model'`（按整模 AABB 算统一比例）；`partIds` 只过滤写出内容，不改变比例，分件后仍可组装。`scaleBasis: 'exportSet'` 则按写出集合自身 AABB 缩放。
 
@@ -188,11 +190,11 @@ async function upload() {
 | -------------------- | ------------------------------------------------- | -------------------------------------------------- |
 | `ready`              | —                                                 | 几何内核就绪                                             |
 | `error`              | `string`                                          | 可展示错误                                              |
-| `exported`           | `{ action, format, fileName, blob, unit, size, longestEdgeMm?, scaleAxis?, scaleBasis?, partIds?, modelSize?, axis? }` | 网格导出完成。`size` 为本次 blob 内网格包围盒；分件且按整模缩放时带 `modelSize`；`partIds` 为实际写出的零件 |
+| `exported`           | `{ action, format, fileName, blob, unit, size, longestEdgeMm?, scaleAxis?, scaleBasis?, partIds?, modelSize?, groundCenter?, axis }` | 网格导出完成。`size` 为本次 blob 内网格包围盒；`axis` 为当前世界 up（`z-up`/`y-up`）；分件且按整模缩放时带 `modelSize`；`groundCenter: true` 表示已贴地居中 |
 | `snapshot`           | `{ action, format, fileName, blob, mime, width, height }` | 模型快照完成。`format` 为 `'png'` \| `'jpeg'` |
 | `report`             | 审核报告对象                                            | 下载 JSON / HTML 审核报告时触发                             |
 | `parts`              | `{ id, index, name, initialSize, size, unit }[]`  | 零件列表；`size` 为当前尺寸，`initialSize` 为导入时尺寸（无则为 `null`） |
-| `bbox`               | `{ min, max, size, initialSize, unit, parts }`    | 整模包围盒（含 `initialSize`）并附带同上的 `parts`            |
+| `bbox`               | `{ min, max, size, initialSize, unit, axis, parts }` | 整模包围盒（含 `initialSize`）并附带同上的 `parts`；`axis` 为当前世界 up（`z-up`/`y-up`），`size` 始终为世界 XYZ |
 | `select-part`        | `{ id, index, additive }`                         | 画布或零件树点选                                           |
 | `part-colors-change` | `Record<string, string>`                          | 工作台内改色时抛出（嵌入预览以 `partColors` 为准）                   |
 | `annotations-change` | `{ schema, version, unit, coordinateSpace, fileName?, generatedAt, annotations, reason }` | 批注新增 / 修改 / 删除时抛出（`reason`: `add` \| `update` \| `remove`）。仅在 `features.annotations` 开启时触发 |
@@ -207,11 +209,11 @@ async function upload() {
 
 | 方法                     | 说明                                                                                                                                                                |
 | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `exportFile(options?)` | 不打开插件对话框。`action` / `format` / `unit` 同上；`longestEdgeMm` + `scaleAxis?` 等比缩放；`scaleBasis`: `'model'`（默认，整模比例）\| `'exportSet'`；`partIds` 只导出指定零件；`silent: true` 跳过确认。成功返回与 `exported` 相同的 payload。 |
+| `exportFile(options?)` | 不打开插件对话框。`action` / `format` / `unit` 同上；`longestEdgeMm` + `scaleAxis?` 等比缩放；`scaleBasis`: `'model'`（默认，整模比例）\| `'exportSet'`；`partIds` 只导出指定零件；`groundCenter: true` 导出时贴地且床面居中于原点（不改工作台）；坐标帧跟随当前 `upAxis`（payload 含 `axis`）；`silent: true` 跳过确认。成功返回与 `exported` 相同的 payload。 |
 | `exportSnapshot(options?)` | 按当前视角截取模型图（不含网格、手柄、切面）。`action`: `'download'` \| `'upload'`；`format`: `'png'`（默认）\| `'jpeg'`；`quality` 仅 JPEG。成功返回与 `snapshot` 相同的 payload。`customExport` 时不本地下载、不 POST。 |
 | `autoSplit(options?)` | 多零件接触面自动装配（≥2 件）。检测接触后一端保留凸起、一端挖槽，再加卡扣。`connector`: `'ballSnap'` \| `'sphere'` \| `'square'`（默认 `ballSnap` 爪扣）；`connectorSize` 可选；`silent: true` 时不弹修复确认，未封闭则返回 `{ ok: false, needsRepair: true, repairPartNames }`。成功 `{ ok: true }`。 |
 | `getPartBounds()` | 同步返回与 `@parts` 相同结构的零件列表（含 `initialSize` / `size`）。无模型时为 `[]`。 |
-| `getBBox()` | 同步返回与 `@bbox` 相同结构的整模载荷（含 `parts`）。尚无诊断包围盒时为 `null`。 |
+| `getBBox()` | 同步返回与 `@bbox` 相同结构的整模载荷（含 `parts` / `axis`）。尚无诊断包围盒时为 `null`。 |
 | `getAnnotations()` | 返回 `AnnotationDocument`（`schema: 'printbench.annotations'`）。功能关闭时仍会规范化 `annotations` prop 后返回，便于宿主随时开启。 |
 | `exportAnnotations()` | 上面文档的格式化 JSON 字符串。 |
 | `setAnnotations(input)` | 用数组 / 文档 / JSON 字符串替换批注列表。 |
@@ -231,7 +233,7 @@ async function upload() {
 
 开启后右栏出现「检查」页签（诊断 / 批注），可点「放置批注」后在模型表面点上标注，支持级别、标题、说明与已解决标记。
 
-锚点使用**内部毫米世界坐标**（Y 轴向上）加 `partId`、命中面法线；零件被移动 / 旋转 / 镜像后仍可按 `partId` 重新挂接，`partId` 消失（拆件 / 布尔 / 合并）时标记为 `orphaned` 并保留原位置显示。
+锚点使用**内部毫米世界坐标**（与当前 `upAxis` 一致，默认 Z 轴向上）加 `partId`、命中面法线；零件被移动 / 旋转 / 镜像后仍可按 `partId` 重新挂接，`partId` 消失（拆件 / 布尔 / 合并）时标记为 `orphaned` 并保留原位置显示。
 
 JSON 结构：
 
@@ -247,7 +249,7 @@ JSON 结构：
     {
       "id": "note_ab12cd34",
       "position": [12.5, 8.0, -3.25],
-      "normal": [0, 1, 0],
+      "normal": [0, 0, 1],
       "partId": "mesh_xxx",
       "partName": "外壳",
       "title": "批注 1",
@@ -299,7 +301,7 @@ JSON 结构：
 - **STL**：二进制；无单位字段，切片软件需与导出单位一致（推荐毫米）。单零件 `.stl`，多零件 `.zip`（每件一个 STL）。不含颜色。
 - **3MF**：自带毫米单位；每零件单独 object，并写入 `displaycolor`（零件打印色）
 - **GLB**：单文件多网格；零件打印色写入材质。无打印单位字段，坐标按导出单位解释。
-- **目标边长缩放**：导出对话框可选参考轴（最长边 / X / Y / Z）、缩放基准（整模 / 仅导出零件）并填「目标边长 mm」；可勾选「仅导出选中」。宿主：`exportFile({ longestEdgeMm, scaleAxis?, scaleBasis?, partIds? })`。先按毫米等比缩放，再按所选 `unit` 写出。按件循环且需可组装时用默认 `scaleBasis: 'model'`。
+- **目标边长缩放**：导出对话框可选参考轴（最长边 / X / Y / Z）、缩放基准（整模 / 仅导出零件）并填「目标边长 mm」；可勾选「仅导出选中」「置于地面中心」。宿主：`exportFile({ longestEdgeMm, scaleAxis?, scaleBasis?, partIds?, groundCenter? })`。先按毫米等比缩放，再按 `partIds` 过滤，再可选贴地居中（相对**本次写出集合**的 AABB），再按所选 `unit` 写出。按件循环时 `groundCenter: true` 会把每件单独放到地面中心；缩放比例仍可用默认 `scaleBasis: 'model'` 保持可组装尺寸。
 - **快照**：PNG / JPEG。按当前相机截取模型，不含工作台网格、变换手柄、拆件切面与测量。下载或一键上传（同 `uploadUrl` / `customExport`）。嵌入预览用 `exportSnapshot()`。
 
 ### 快捷键
@@ -317,9 +319,9 @@ JSON 结构：
 | Ctrl            | 多选、框选                         |
 
 
-草稿保存在浏览器本地，仅当 `features.drafts` 为 true 时读写并提示恢复。设置含默认导入单位、默认导出格式、场景光照开关、灯光模式（标准照明 / 摄影棚 / 环境光照 / 跟随头灯，默认标准照明）、最小壁厚、打印床尺寸（默认 220×220×250 mm，Y 为高度）。地面网格默认开启，初始 200 mm / 20 格并随模型包围盒放大（`showGrid` / `gridAutoFit` 默认 `true`）；勾选「自定义网格尺寸」或宿主传 `gridSizeMm` 后可填 XYZ（边长取 max(X,Z)）且不再随模型放大。打印床线框默认隐藏，可在布局区或设置中打开；宿主可用 props `bedSizeMm` / `showBedVolume` / `showGrid` / `gridAutoFit` / `gridSizeMm` 提供初始默认值（只写入一次，不锁定控件）。
+草稿保存在浏览器本地，仅当 `features.drafts` 为 true 时读写并提示恢复。设置含**坐标系**（默认 **Z-up**，可切回 Y-up；切换前确认并对已加载模型做坐标重定向）、默认导入单位、默认导出格式、场景光照开关、灯光模式（标准照明 / 摄影棚 / 环境光照 / 展台照明 / 跟随头灯，默认标准照明）、原始法线预览开关（默认关）、最小壁厚、打印床尺寸（默认 220×220×250 mm，Z-up 时 Z 为高度）。地面网格默认开启，初始 200 mm / 20 格并随模型包围盒放大（`showGrid` / `gridAutoFit` 默认 `true`）；勾选「自定义网格尺寸」或宿主传 `gridSizeMm` 后可填 XYZ（边长取床面两轴 max）且不再随模型放大。打印床线框默认隐藏，可在布局区或设置中打开；宿主可用 props `upAxis` / `bedSizeMm` / `showBedVolume` / `showGrid` / `gridAutoFit` / `gridSizeMm` 提供初始默认值（只写入一次，不锁定控件）。旧版无 `upAxis` 的本地设置按 **Y-up** 兼容，避免升级后草稿静默错位。
 
-开启 `features.layout` 后：贴地将零件落到 Y=0；镜像相对包围盒中心；「缩放到」按最长边或指定轴等比缩放并自动贴地；「选面朝下」点击表面使该面朝下并贴地。超出打印床时底栏提示；显示床线框时超界会变为警示色。
+开启 `features.layout` 后：贴地将零件落到 up=0；镜像相对包围盒中心；「缩放到」按最长边或指定轴等比缩放并自动贴地；「选面朝下」点击表面使该面朝下并贴地。超出打印床时底栏提示；显示床线框时超界会变为警示色。
 
 ## 开发本仓库