@caojinyu111/vue-bim-viewer 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (9) hide show
  1. package/API.md +78 -60
  2. package/README.md +17 -8
  3. package/dist/gis-imagery.d.ts +1 -1
  4. package/dist/gis.d.ts +2 -2
  5. package/dist/index.cjs +23 -2
  6. package/dist/index.js +1725 -1272
  7. package/dist/style.css +1 -1
  8. package/dist/types.d.ts +7 -5
  9. package/package.json +3 -3
package/API.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # API 与集成指南
2
2
 
3
- 适用版本：**0.3.2**。本文面向在 Vue 3 应用中集成 `@caojinyu111/vue-bim-viewer` 的开发者，说明模型资源约定、组件接口、业务接入方式及使用限制。
3
+ 适用版本：**0.3.3**。本文面向在 Vue 3 应用中集成 `@caojinyu111/vue-bim-viewer` 的开发者，说明模型资源约定、组件接口、业务接入方式及使用限制。
4
4
 
5
5
  SDK 使用 JavaScript 实现，同时提供独立的 TypeScript 类型声明。除 TypeScript 接入章节外，组件与业务示例均使用 JavaScript。快速安装见 [README](./README.md)；参数字段和可选性可结合发布包中的声明文件查阅。
6
6
 
@@ -27,30 +27,30 @@ SDK 使用 JavaScript 实现，同时提供独立的 TypeScript 类型声明。
27
27
 
28
28
  ### 1.1 功能清单
29
29
 
30
- | 能力 | 当前支持内容 | 使用入口 |
31
- | ---------- | --------------------------------------------------------------- | --------------------------------------- |
32
- | 模型加载 | 通过 Manifest 加载 GLB/glTF，处理外部 buffer/image 和可选元数据 | `MineViewer`、`modelSource` |
33
- | 三维浏览 | 拖动旋转、滚轮缩放、右键平移、容器尺寸适配、初始全模型视角 | `initialView`、`resetView()` |
34
- | 视角导航 | Home、26 方向骰子、六个标准方向方法及实时显隐 | `navigation`、`setViewDirection()` |
35
- | 构件树 | 完整父子结构、空节点、元数据、包围盒和资源版本 | `getComponentTree()` |
36
- | 场景查询 | 源场景结构快照、活的 Three.js 根节点、对象对应 ID | `getSceneTree()` 等 |
37
- | 构件交互 | 三维拾取、按 ID 选择、选择轮廓、相机定位、清除选择 | `selectComponent()`、`focusComponent()` |
38
- | 锚点查询 | 对象原点、包围盒中心、包围盒 Y 轴顶部 | `getComponentAnchor()` |
39
- | 外观控制 | 显隐、透明度、颜色、批量设置及父子继承 | `setComponentAppearance()` 等 |
40
- | 差异与恢复 | 当前净差异、合并导入、恢复单节点或全部覆盖 | `getAppearanceChanges()` 等 |
41
- | 标签 | 原始模型坐标点、构件锚点、模型偏移、屏幕偏移 | `markers` |
42
- | 弹窗与模板 | 默认标签/弹窗、自定义插槽、点击切换和关闭 | `marker`、`marker-popup` |
43
- | GIS 配准 | 三点或多点水平配准、可选高程、ENU/ECEF 矩阵、误差报告 | `createGisPlacement()` |
44
- | 地图影像 | 有限范围天地图影像、透明度、独立加载状态 | `gis`、`gis-status` |
45
- | DEM 地形 | 相对预览、真实高程转换、缺测回退及独立准备状态 | `gis.terrain`、`terrain-status` |
46
- | 场景背景 | 纯色或普通静态图片，居中 cover，可响应式更新 | `background`、`background-error` |
47
- | 树展开工具 | 按源顺序深度优先展开构件树 | `flattenComponentTree()` |
30
+ | 能力 | 当前支持内容 | 使用入口 |
31
+ | ---------- | --------------------------------------------------------------- | ------------------------------------------------ |
32
+ | 模型加载 | 通过 Manifest 加载 GLB/glTF，处理外部 buffer/image 和可选元数据 | `MineViewer`、`modelSource` |
33
+ | 三维浏览 | 拖动旋转、滚轮缩放、右键平移、容器尺寸适配、初始全模型视角 | `initialView`、`resetView()` |
34
+ | 视角导航 | Home、26 方向骰子、六个标准方向方法及实时显隐 | `navigation`、`setViewDirection()` |
35
+ | 构件树 | 内置目录、名称搜索、分支显隐、选中定位及完整树查询 | `navigation.componentTree`、`getComponentTree()` |
36
+ | 场景查询 | 源场景结构快照、活的 Three.js 根节点、对象对应 ID | `getSceneTree()` 等 |
37
+ | 构件交互 | 三维拾取、按 ID 选择、青绿色高亮与细轮廓、相机定位、清除选择 | `selectComponent()`、`focusComponent()` |
38
+ | 锚点查询 | 对象原点、包围盒中心、包围盒 Y 轴顶部 | `getComponentAnchor()` |
39
+ | 外观控制 | 显隐、透明度、颜色、批量设置及父子继承 | `setComponentAppearance()` 等 |
40
+ | 差异与恢复 | 当前净差异、合并导入、恢复单节点或全部覆盖 | `getAppearanceChanges()` 等 |
41
+ | 标签 | 原始模型坐标点、构件锚点、模型偏移、屏幕偏移 | `markers` |
42
+ | 弹窗与模板 | 默认标签/弹窗、自定义插槽、点击切换和关闭 | `marker`、`marker-popup` |
43
+ | GIS 配准 | 三点或多点水平配准、可选高程、ENU/ECEF 矩阵、误差报告 | `createGisPlacement()` |
44
+ | 地图影像 | 有限范围天地图影像、透明度、独立加载状态 | `gis`、`gis-status` |
45
+ | DEM 地形 | 相对预览、真实高程转换、缺测回退及独立准备状态 | `gis.terrain`、`terrain-status` |
46
+ | 场景背景 | 纯色或普通静态图片，居中 cover，可响应式更新 | `background`、`background-error` |
47
+ | 树展开工具 | 按源顺序深度优先展开构件树 | `flattenComponentTree()` |
48
48
 
49
49
  ### 1.2 SDK 与宿主的分工
50
50
 
51
51
  SDK 管理模型加载、渲染、构件索引、外观运行状态、选择、标签投影和资源清理。宿主通过参数、事件及公开方法接入业务。
52
52
 
53
- 以下由宿主负责：模型 URL 与访问权限、构件树界面和搜索、业务按钮、标签内容、localStorage/服务端保存、JSON 文件选择与下载、地图服务密钥、控制点及真实高程基准转换。SDK 通过 `gis` 属性接入可选影像与 DEM；构件树与外观操作面板由应用自行实现，SDK 不依赖业务 UI 组件库。
53
+ 以下由宿主负责：模型 URL 与访问权限、业务按钮、标签内容、localStorage/服务端保存、JSON 文件选择与下载、地图服务密钥、控制点及真实高程基准转换。SDK 内置构件目录与名称搜索，通过 `gis` 属性接入可选影像与 DEM。宿主可通过公开查询与外观方法自建扩展面板；SDK 不依赖业务 UI 组件库。
54
54
 
55
55
  当前包的运行时命名导出只有：
56
56
 
@@ -70,10 +70,10 @@ import '@caojinyu111/vue-bim-viewer/style.css'
70
70
  在 Vue 应用中安装 SDK：
71
71
 
72
72
  ```sh
73
- npm install @caojinyu111/vue-bim-viewer@0.3.2
73
+ npm install @caojinyu111/vue-bim-viewer@0.3.3
74
74
  ```
75
75
 
76
- 运行环境要求 Vue **3.5.43**、Three.js **0.183.1** 和支持 WebGL2 的浏览器。Vue 与 Three.js 为精确版本的共享 peerDependencies，npm 7+ 会补齐尚未安装的 peer；已有不兼容版本的宿主先执行 `npm install vue@3.5.43 three@0.183.1`。three-tile **0.12.2** 与 Proj4js 随 SDK 安装，three-tile 随 SDK 构建。地图请求还需要 `fetch`、`createImageBitmap`、`AbortSignal.any/timeout`；DEM 解压需要 `DecompressionStream`。
76
+ 运行环境要求 Vue **3.5.43**、Three.js **0.183.1** 和支持 WebGL2 的浏览器。Vue 与 Three.js 为精确版本的共享 peerDependencies，npm 7+ 会补齐尚未安装的 peer；已有不兼容版本的宿主先执行 `npm install vue@3.5.43 three@0.183.1`。three-tile **0.12.2** 与 Proj4js 随 SDK 安装，three-tile 随 SDK 构建。启用 GIS 地图还需要 `fetch`、`createImageBitmap`、`AbortSignal.any`、`AbortSignal.timeout` 和 `OffscreenCanvas`；启用 DEM 额外需要 `DecompressionStream`。SSR 只能在客户端挂载组件。
77
77
 
78
78
  TypeScript 应用额外安装 Three.js 类型声明：
79
79
 
@@ -316,15 +316,15 @@ async function refreshModel() {
316
316
 
317
317
  ## 4. 组件参数
318
318
 
319
- | Prop | 类型 | 默认值 | 生效方式 |
320
- | ------------------ | ------------------------- | ---------------------------- | ---------------------------------------------- |
321
- | `modelSource` | `ModelSource` | 必填 | 监听 `manifestUrl` 字符串变化，自动加载/重载 |
322
- | `markers` | `Marker[]` | `[]` | 深度监听响应式标签数据，更新标签投影和显示 |
323
- | `initialView` | `InitialView` | `{}` | 成功展示模型时交给渲染器，用于全模型适配与重置 |
324
- | `cameraTransition` | `CameraTransitionOptions` | `{ duration: 800 }` | 定位和重置时读取，设置默认过渡时长 |
325
- | `gis` | `GisOptions` | 不加载地图 | 可选天地图影像及 DEM，见 9.9、9.11 |
326
- | `background` | `BackgroundOptions` | `{ color: '#f4f7fb' }` | 深度监听，实时更新背景，不重载模型 |
327
- | `navigation` | `NavigationOptions` | `{ home: true, cube: true }` | Home 与 26 方向骰子分别实时显隐，不重载模型 |
319
+ | Prop | 类型 | 默认值 | 生效方式 |
320
+ | ------------------ | ------------------------- | ------------------------------------------------- | ------------------------------------------------- |
321
+ | `modelSource` | `ModelSource` | 必填 | 监听 `manifestUrl` 字符串变化，自动加载/重载 |
322
+ | `markers` | `Marker[]` | `[]` | 深度监听响应式标签数据，更新标签投影和显示 |
323
+ | `initialView` | `InitialView` | `{}` | 成功展示模型时交给渲染器，用于全模型适配与重置 |
324
+ | `cameraTransition` | `CameraTransitionOptions` | `{ duration: 800 }` | 定位和重置时读取，设置默认过渡时长 |
325
+ | `gis` | `GisOptions` | 不加载地图 | 可选天地图影像及 DEM，见 9.9、9.11 |
326
+ | `background` | `BackgroundOptions` | `{ color: '#f4f7fb' }` | 深度监听，实时更新背景，不重载模型 |
327
+ | `navigation` | `NavigationOptions` | `{ home: true, cube: true, componentTree: true }` | 构件目录、Home 与方向骰子分别实时显隐，不重载模型 |
328
328
 
329
329
  Vue 模板中分别使用 `:model-source`、`:markers`、`:initial-view`、`:camera-transition`、`:gis`、`:background` 和 `:navigation`。
330
330
 
@@ -339,16 +339,17 @@ Vue 模板中分别使用 `:model-source`、`:markers`、`:initial-view`、`:cam
339
339
 
340
340
  <a id="navigation"></a>
341
341
 
342
- ### 4.1 Home 与 26 方向导航骰子
342
+ ### 4.1 构件目录、Home 与 26 方向导航骰子
343
343
 
344
- `NavigationOptions` 仅包含 `home?: boolean` 和 `cube?: boolean`，未提供的字段均为 `true`。可以替换整个配置，也可修改响应式对象的字段；界面立即生效，不重载模型、不改变当前相机。
344
+ `NavigationOptions` 包含 `home?: boolean`、`cube?: boolean` 和 `componentTree?: boolean`，未提供的字段均为 `true`。可以替换整个配置，也可修改响应式对象的字段；界面立即生效，不重载模型、不改变当前相机。
345
345
 
346
- | 配置 | 导航显示 |
347
- | ------------------------------ | ---------------------------------- |
348
- | 不传、`{}` | Home 与骰子均显示 |
349
- | `{ home: false }` | 仅骰子 |
350
- | `{ cube: false }` | 仅 Home，收缩为 44px 按钮 |
351
- | `{ home: false, cube: false }` | 全部隐藏，不占位；实例方法仍可使用 |
346
+ | 配置 | 导航显示 |
347
+ | ---------------------------------------------------- | ------------------------------------------- |
348
+ | 不传、`{}` | 构件目录按钮、Home 与骰子均显示 |
349
+ | `{ home: false }` | 构件目录按钮与骰子 |
350
+ | `{ cube: false }` | 构件目录按钮与 Home，右上角收缩为 44px 按钮 |
351
+ | `{ componentTree: false }` | Home 与骰子，构件目录关闭并隐藏 |
352
+ | `{ home: false, cube: false, componentTree: false }` | 全部隐藏，不占位；实例方法仍可使用 |
352
353
 
353
354
  ```vue
354
355
  <script setup>
@@ -357,19 +358,30 @@ import { MineViewer } from '@caojinyu111/vue-bim-viewer'
357
358
  import '@caojinyu111/vue-bim-viewer/style.css'
358
359
  const viewer = shallowRef(null)
359
360
  const source = { manifestUrl: '/models/manifest.json' }
360
- const navigation = reactive({ home: true, cube: true })
361
+ const navigation = reactive({ home: true, cube: true, componentTree: true })
361
362
  </script>
362
363
 
363
364
  <template>
364
365
  <label><input v-model="navigation.home" type="checkbox" />Home</label>
365
366
  <label><input v-model="navigation.cube" type="checkbox" />方向骰子</label>
367
+ <label><input v-model="navigation.componentTree" type="checkbox" />构件目录</label>
366
368
  <div style="height: 600px">
367
369
  <MineViewer ref="viewer" :model-source="source" :navigation="navigation" />
368
370
  </div>
369
371
  </template>
370
372
  ```
371
373
 
372
- 导航位于右上角，距顶、右各 16px；骰子区域为 150×150px，Home 图标约 24px、命中区域 44px。切角骰子和房屋图标使用本地 SVG 和 Three.js 数学计算绘制，不请求远程素材。GIS 署名自动排列在导航下方，标记弹窗避开导航区域。
374
+ 构件目录按钮位于左上角，距顶、左各 16px，命中区域 45px。面板默认关闭；打开后隐藏按钮，首次打开时面板左上角与按钮原位置重合。面板宽最多 320px、高最多 560px，尺寸受场景容器宽高减去 32px 的可用空间约束，列表独立滚动。模型就绪后默认展开根节点，仅呈现源模型实际层级，不含空间分类、地图、DEM 或标签。
375
+
376
+ 标题文字及空白处显示四向移动光标，按住可用鼠标或触屏拖动面板；关闭按钮显示手形光标，不启动拖动。面板限制在场景内，四周保留 16px；打开和场景尺寸变化时自动修正并保存越界位置。关闭后按钮恢复原位，再次打开保留关闭前的位置。同一组件实例内，关闭、配置隐藏及模型重载均保留位置；重新挂载或刷新页面后恢复初始位置，不使用本地存储。搜索框和列表不作为拖动区域，拖动不触发模型旋转、平移或拾取。
377
+
378
+ 目录搜索忽略名称大小写，保留匹配节点与祖先路径并自动展开；清除搜索恢复普通浏览的展开状态。搜索只过滤目录，不改变场景或复选框的操作范围。分支复选框按完整子树的几何体有效显隐显示全选、半选或未选，与颜色、透明度无关；没有几何后代的分支禁用复选框。取消勾选隐藏整组，勾选显示整组及此前单独隐藏的后代。单独显示隐藏祖先下的子构件会开启必要祖先，保留其他分支的隐藏状态。一次操作批量写入现有外观状态，沿用 `appearance-change`（`source: 'api'`）及外观保存、导入和恢复机制。
379
+
380
+ 点击名称组合执行选择与定位：沿当前观察方向适配该分支的包围盒，沿用 `cameraTransition`，不自动寻找无遮挡方向。隐藏构件保持隐藏，只更新选择并定位；没有可定位几何时只选择并显示提示，相机不移动。公开 `selectComponent()` 和 `focusComponent()` 各自的行为保持独立。
381
+
382
+ 三维拾取与宿主 API 选择会同步目录，面板打开时展开选中节点的祖先并滚动定位；选中项被当前搜索排除时保留搜索并提示。关闭面板或隐藏按钮保留显隐、选择及相机状态。成功切换模型后重置搜索、展开和选择；加载失败保留原模型与目录状态。目录不监听自定义键盘快捷键，Esc 不关闭面板；搜索框正常输入，展开按钮、复选框和名称按钮按原生焦点顺序及键盘行为工作。点击关闭后焦点返回目录按钮。目录鼠标操作不触发场景拾取或缩放。
383
+
384
+ 视角导航位于右上角，距顶、右各 16px；骰子区域为 150×150px，Home 图标约 24px、命中区域 44px。切角骰子和房屋图标使用本地 SVG 和 Three.js 数学计算绘制，不请求远程素材。GIS 署名自动排列在右侧导航下方，标记弹窗避开右侧导航区域。
373
385
 
374
386
  Home 等同于 `resetView()`：按 `initialView` 恢复方向，并重新适配整个模型，不清除选择、外观修改或标记。骰子随主相机旋转，六个面、十二条边、八个角均可点击；方向切换保留当前观察目标与距离，因此构件定位后仍围绕该构件观察。
375
387
 
@@ -478,7 +490,7 @@ function onBackgroundError(error) {
478
490
  | `setComponentAppearances(updates)` | `{ id, patch }[]` | `OperationResult` | 有效项应用，非法项跳过；不是整批回滚 |
479
491
  | `getAppearanceChanges()` | 无 | `AppearanceChangeSet \| null` | 未就绪为 `null`；就绪但无修改时 `overrides: []` |
480
492
  | `applyAppearanceChanges(value)` | 已解析的差异对象，不是 JSON 字符串 | `OperationResult` | 格式、版本、字段校验失败时不应用；未知 ID 单独报告 |
481
- | `restoreComponent(id)` | ID | `OperationResult` | 只取消该节点自身覆盖，保留后代独立覆盖和祖先影响 |
493
+ | `restoreComponent(id)` | 当前模型中的构件 ID | `OperationResult` | 只取消该节点自身覆盖；无效 ID 返回错误或 `unknownIds`，不修改外观 |
482
494
  | `restoreAllComponents()` | 无 | `OperationResult` | 删除所有自身覆盖；未就绪返回 `error` |
483
495
  | `selectComponent(id)` | ID 或 `null` | `boolean` | 有效选择/清空成功为 `true`；未知 ID/未就绪为 `false` |
484
496
  | `focusComponent(id, options?)` | ID；可选 `{ duration }`，毫秒 | `boolean` | 接受定位为 `true`；未知 ID/未就绪/非法时长为 `false`；不自动选择 |
@@ -537,7 +549,7 @@ function inspectComponents(api) {
537
549
 
538
550
  ### 5.4 模型坐标和锚点
539
551
 
540
- SDK 使用加载后源场景的模型坐标，展示居中通过外层 wrapper 实现，不改写节点数据。正常 glTF 以米为单位；若上游数据并非米制，SDK 不会根据尺寸自动猜测或换算单位。
552
+ SDK 使用加载后源场景的模型坐标，展示居中通过外层 wrapper 实现，不改写节点数据。模型点和节点坐标沿用源模型单位；glTF 通常以米为单位，但 SDK 不会根据尺寸自动猜测或换算单位。需要进行 GIS 配准时，通过 `metersPerUnit` 声明一个模型单位对应多少米。
541
553
 
542
554
  | anchor | 返回位置 | 注意事项 |
543
555
  | -------------- | --------------------------- | ----------------------------------------------------- |
@@ -558,7 +570,11 @@ function readAnchors(api, componentId) {
558
570
 
559
571
  ### 5.5 选择、定位与高级场景读取
560
572
 
561
- `selectComponent(id)` 设置选择轮廓并发出 `component-select`，不会自动移动相机；`focusComponent(id)` 调整视野但不会自动选择。空节点定位会围绕其原点给出局部视野。选择不计入外观差异。
573
+ `selectComponent(id)` 设置选择效果并发出 `component-select`，不会自动移动相机；`focusComponent(id)` 调整视野但不会自动选择。空节点定位会围绕其原点给出局部视野。
574
+
575
+ 选择样式由 SDK 内置：青绿色表面高亮与浅绿色细轮廓，保留纹理、明暗和原有透明度，遵循场景遮挡，不显示穿透轮廓、不闪烁，也不自动创建标签。选择父节点时作用于其可见且非完全透明的子网格；隐藏构件不显示高亮。三维点击、构件树调用及 API 选择使用同一效果，不提供样式修改或禁用参数。
576
+
577
+ 切换选择或传入 `null` 清空时恢复构件当前外观。选中期间修改颜色、透明度、显隐或导入、恢复外观，均继续生效；临时高亮不修改共享源材质、不计入外观差异、不触发 `appearance-change`。业务标签保持独立，地图与 DEM 不参与构件选择。
562
578
 
563
579
  定位和重置默认使用 800 毫秒缓入缓出动画。通过组件 `:camera-transition="{ duration: 1000 }"` 设置统一时长，单次调用优先使用传入的 `duration`：
564
580
 
@@ -641,7 +657,7 @@ function restoreEverything(api) {
641
657
  }
642
658
  ```
643
659
 
644
- **调用约束：`restoreComponent` 必须传入当前模型中的有效构件 ID。漏传参数或传入 `undefined` 会进入全部恢复分支，清除全部外观覆盖。调用前应校验非空字符串及构件存在性；全部恢复应显式调用 `restoreAllComponents()`。**
660
+ **调用约束：`restoreComponent` 必须传入当前模型中的有效构件 ID。漏传参数、传入 `undefined`、`null` 或空字符串会返回 `error`，不会修改任何外观；格式正确但不存在的 ID 会进入 `unknownIds`。需要恢复全部覆盖时，必须显式调用 `restoreAllComponents()`。**
645
661
 
646
662
  `restoreComponent(id)` 在传入有效 ID 时不递归删除后代独立覆盖；需要全部恢复时使用 `restoreAllComponents()`。重复设置相同值或设置回逻辑初值可能不会产生新的差异。
647
663
 
@@ -921,7 +937,7 @@ function onAppearanceChange(event) {
921
937
 
922
938
  ### 9.1 用途与基本流程
923
939
 
924
- `createGisPlacement(options)` 是独立函数，无需先挂载 `MineViewer`。输入三个或更多水平不共线的“原始模型点 ↔ 现实坐标”对应关系，保持模型尺寸和竖直方向，求水平旋转和平移；有高程时再拟合整体竖直偏移。
940
+ `createGisPlacement(options)` 是独立函数，无需先挂载 `MineViewer`。默认 `least-squares` 模式输入三个或更多在水平面上分散且不共线的“原始模型点 ↔ 现实坐标”对应关系，保持模型尺寸和竖直方向，求水平旋转和平移；有高程时再拟合整体竖直偏移。使用 `first-point` 模式时，首个控制点固定水平位置，其余控制点用于确定方向，不要求满足最小二乘模式的分布条件，但不能与首点水平重合，且方向不能互相抵消。
925
941
 
926
942
  推荐流程：确认现实坐标系和模型单位/竖直轴，选取分散的对应点，调用方法，检查逐点误差，再用未参与拟合的独立点复核，最后由宿主将结果接到 GIS 模型图层。
927
943
 
@@ -947,22 +963,22 @@ function onAppearanceChange(event) {
947
963
  | `EPSG:4490` | `{ longitude, latitude, height? }` | CGCS2000，经度、纬度均为度 |
948
964
  | `EPSG:4326` | `{ longitude, latitude, height? }` | WGS84，经度、纬度均为度 |
949
965
 
950
- 模型点始终为 `{ x, y, z }`，即使暂不做高程配准也要提供完整模型点；可省略的是地图点的 `height`。经纬度不是平面米制坐标，测量 X/Y 也不能直接填入 `longitude/latitude`。
966
+ 模型点始终为 `{ x, y, z }`，坐标单位沿用源模型单位；SDK 不会自动判断或换算米、毫米等单位。`metersPerUnit` 用于声明一个模型单位对应多少米。即使暂不做高程配准也要提供完整模型点；可省略的是地图点的 `height`。经纬度不是平面米制坐标，测量 X/Y 也不能直接填入 `longitude/latitude`。
951
967
 
952
- ### 9.3 三个井口测量坐标示例
968
+ ### 9.3 测量控制点接入示例
953
969
 
954
- 本例以测量人员**已确认 EPSG:4529** 为使用前提，并不根据坐标数字判定实际项目一定属于该坐标系。三个井口的模型对应点由宿主从实际模型中取得；对象原点、包围盒中心或顶部不一定就是井口中心。
970
+ 本例以测量人员**已确认 EPSG:4529** 为使用前提。表中坐标仅用于说明数据结构，实际接入时必须替换为项目测量结果；不能根据数字推断坐标系。三个控制点的模型对应点须从原始模型中取得，并与实际测量点一一对应，不能直接用对象原点或包围盒中心代替。
955
971
 
956
972
  ```js
957
973
  import { createGisPlacement } from '@caojinyu111/vue-bim-viewer'
958
974
 
959
975
  // modelPoints 的三项均须为真实原始模型坐标 { x, y, z }。
960
976
  // ellipsoidHeights 为可选椭球高对象，键名与 modelPoints 一致。
961
- function locateMine(modelPoints, ellipsoidHeights = {}) {
977
+ function locateModel(modelPoints, ellipsoidHeights = {}) {
962
978
  const surveys = [
963
- ['auxiliaryShaft', 4553676.771, 41508910.967],
964
- ['southAirShaft', 4552712.1, 41509748.6],
965
- ['northAirShaft', 4554618, 41508365],
979
+ ['controlA', 4500000, 41500000],
980
+ ['controlB', 4500000, 41500100],
981
+ ['controlC', 4500100, 41500000],
966
982
  ]
967
983
  const controlPoints = surveys.map(([key, northing, easting]) => ({
968
984
  model: modelPoints[key],
@@ -982,12 +998,12 @@ function locateMine(modelPoints, ellipsoidHeights = {}) {
982
998
  })
983
999
  }
984
1000
 
985
- function inspectMinePlacement(modelPoints, ellipsoidHeights) {
986
- const placement = locateMine(modelPoints, ellipsoidHeights)
1001
+ function inspectPlacement(modelPoints, ellipsoidHeights) {
1002
+ const placement = locateModel(modelPoints, ellipsoidHeights)
987
1003
  console.log('模型原点位置', placement.position)
988
1004
  console.log('水平角度', placement.rotationDegrees)
989
1005
  console.table(placement.residuals)
990
- return placement.toGeographic(modelPoints.auxiliaryShaft)
1006
+ return placement.toGeographic(modelPoints.controlA)
991
1007
  }
992
1008
  ```
993
1009
 
@@ -1090,7 +1106,8 @@ ENU 的轴顺序为东、北、上。Y 向上的模型在水平旋转前按 `(x,
1090
1106
  | 少于 3 个点、缺模型/地图坐标 | 抛错，补全对应关系 |
1091
1107
  | 未支持的 CRS 或不合法的 `modelUpAxis` | 抛错，明确坐标系及 Y/Z 竖直轴 |
1092
1108
  | 非有限数字、超范围经纬度、非法单位比例 | 抛错，检查数字类型和单位 |
1093
- | 模型/地图水平点重合、共线或过于接近共线 | 抛错，重新选择分散点位 |
1109
+ | `least-squares` 模式的模型或地图水平点共线、重合或过于接近共线 | 抛错，重新选择水平分散的点位 |
1110
+ | `first-point` 模式的其他控制点与首点水平重合 | 抛错，选择能够确定水平方向的点位 |
1094
1111
  | EPSG:4529 的 easting 缺少 41 带号或轴序颠倒 | 抛错，按测量 X/Y 正确填 northing/easting |
1095
1112
  | 不能确定一致的水平旋转 | 抛错，核对对应点 |
1096
1113
  | 水平误差超过 `maxErrorMeters` | 抛错，排查点位/单位/坐标系；不设阈值时通过结果报告误差 |
@@ -1240,7 +1257,7 @@ const terrain = {
1240
1257
  }
1241
1258
  ```
1242
1259
 
1243
- 输入 `height` 是天地图 DEM 原始米制高程，返回值必须是与配准一致的有限椭球高（米）。只有确认基准一致时才能直接返回 height；正常高需要可靠的大地水准面/似大地水准面转换。SDK 不推断基准，也不将人工常数偏移当作通用转换。配置缺失、回调抛错或返回非有限值时报告错误并保留相应平面影像，不悄悄切换相对模式。真实模式使用完整 ECEF → ENU → 配准逆变换 → 展示偏移；模型和 Marker 坐标始终不变。
1260
+ 输入 `height` 是天地图 DEM 原始米制高程，返回值必须是与配准一致的有限 `number` 椭球高（米），不能返回 `null`、布尔值、字符串或 Promise。只有确认基准一致时才能直接返回 height；正常高需要可靠的大地水准面/似大地水准面转换。SDK 不推断基准，也不将人工常数偏移当作通用转换。配置缺失、回调抛错、返回非数字或非有限值时报告错误并保留相应平面影像，不悄悄切换相对模式。真实模式使用完整 ECEF → ENU → 配准逆变换 → 展示偏移；模型和 Marker 坐标始终不变。
1244
1261
 
1245
1262
  SDK 的天地图 `elv_c` 适配器支持 zlib 压缩的 150×150 小端 UInt16 高程栅格，采用独立的地理 c 瓦片矩阵和三角插值，不直接复用影像 w 矩阵行列。DEM 数据级别取影像级别与 12 的较小值，影像级别 6 以下报告不支持地形；这是 SDK 的数据级别限制，不保证服务在所有区域和级别均有有效数据。每张影像生成 33×33 地表顶点及独立向下裙边，共享边缘取样一致。缺测值不伪造成零，相机缩放不改变瓦片级别，不支持地形碰撞或自动贴地，模型地表构件不会自动隐藏。
1246
1263
 
@@ -1278,7 +1295,7 @@ SDK 的天地图 `elv_c` 适配器支持 zlib 压缩的 150×150 小端 UInt16
1278
1295
  | `MarkerOverlay` | 投影标签数组、issues、视口宽高；内部布局数据的公开类型，无独立查询方法 | [标签](#markers) |
1279
1296
  | `ModelInfo` | 模型身份、名称、URL、统计、warnings | [加载事件](#model-loading) |
1280
1297
  | `SceneAssociation` | 可选 `nodes` 源节点索引，Loader 关联辅助类型，无独立查询方法 | [场景读取](#viewer-api) |
1281
- | `NavigationOptions` | `home?`、`cube?`，均默认 true | [导航](#navigation) |
1298
+ | `NavigationOptions` | `home?`、`cube?`、`componentTree?`，均默认 true | [导航](#navigation) |
1282
1299
  | `ViewDirection` | 六个标准观察方向 | [导航](#navigation) |
1283
1300
  | `ViewerApi` | 组件 ref 暴露的 18 个方法 | [实例方法](#viewer-api) |
1284
1301
  | `GeographicCoordinate` | `longitude`、`latitude`、`height?` | [GIS](#gis) |
@@ -1334,6 +1351,7 @@ const {
1334
1351
  | 现象 | 优先检查 |
1335
1352
  | ----------------------------- | ---------------------------------------------------------------------------------- |
1336
1353
  | 页面没有三维内容 | 父容器是否有非零宽高、是否引入样式、浏览器 WebGL2 是否可用、model-error 内容 |
1354
+ | 地图没有加载 | GIS 是否启用、浏览器是否支持 `fetch`、`createImageBitmap`、`AbortSignal.any`、`AbortSignal.timeout` 和 `OffscreenCanvas` |
1337
1355
  | 模型加载失败 | Manifest version、entry 后缀、HTTP 状态、CORS、地址是否实际返回 HTML、外部资源路径 |
1338
1356
  | 模型能显示但属性缺失 | model-loaded.warnings、元数据格式、源名称是否唯一、源节点关联是否存在 |
1339
1357
  | ref 有值但查询为 null | 模型尚未成功就绪；在 component-tree-ready 后查询 |
@@ -1367,7 +1385,7 @@ GIS 仅接受 EPSG:4529、4490、4326，采用局部水平刚性配准和已知
1367
1385
 
1368
1386
  | 项目 | 影响与建议 |
1369
1387
  | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
1370
- | 恢复构件的参数 | `restoreComponent(undefined)` 会清除全部覆盖。调用前检查有效 ID，全部恢复使用 `restoreAllComponents()`。 |
1388
+ | 恢复构件的参数 | `restoreComponent` 必须传入当前模型中的有效 ID；漏传或空 ID 返回 `error`，未知 ID 返回 `unknownIds`，全部恢复使用 `restoreAllComponents()`。 |
1371
1389
  | 特殊对象的资源释放 | 释放以 Mesh 为主，Line/Points、Skeleton 骨骼纹理及 InstancedMesh 自身资源的 dispose 钩子覆盖不完整。反复加载此类模型可能累积 GPU 资源。 |
1372
1390
  | Line/Points 外观 | 状态更新可能返回成功，但颜色、透明度及包围盒不具备完整支持；应使用静态 Mesh 模型。 |
1373
1391
  | 外观更新成本 | 每次修改会同步扫描节点，已克隆材质可能重复更新；大模型和高频批量修改需结合实际业务压测。 |
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @caojinyu111/vue-bim-viewer
2
2
 
3
- 基于 Vue 3 与 Three.js 的 JavaScript BIM 模型浏览 SDK。当前版本 **0.3.2**，提供 ESM、CommonJS、独立样式与 TypeScript 类型声明。
3
+ 基于 Vue 3 与 Three.js 的 JavaScript BIM 模型浏览 SDK。当前版本 **0.3.3**，提供 ESM、CommonJS、独立样式与 TypeScript 类型声明。
4
4
 
5
5
  适用于将静态 GLB/glTF 模型嵌入业务系统，通过组件参数、事件和实例方法实现构件查询、选择、外观控制及业务标记。
6
6
 
@@ -9,6 +9,8 @@
9
9
  - **模型浏览**：Manifest 资源加载、旋转、缩放、平移、构件定位与平滑视角过渡。
10
10
  - **视角导航**：Home 与切角骰子，支持面、边、角共 26 个方向，宿主可分别控制显隐。
11
11
  - **构件访问**：保留源场景父子结构，查询构件树、元数据、包围盒和模型空间锚点。
12
+ - **构件目录**：左上角内置可搜索构件树，支持整组显隐、选中定位及与宿主外观同步。
13
+ - **构件选择**：内置青绿色表面高亮与浅绿色细轮廓，支持三维点击、构件树及 API 选择；不需要宿主配置。
12
14
  - **外观管理**：显隐、颜色、透明度、批量修改，以及外观差异的导出、合并导入和恢复。
13
15
  - **业务标记**：模型坐标或构件锚点定位，支持自定义标签与弹窗插槽。
14
16
  - **场景背景**：响应式背景颜色与静态图片，居中等比裁剪，加载失败回退纯色。
@@ -18,7 +20,7 @@
18
20
  ## 安装
19
21
 
20
22
  ```sh
21
- npm install @caojinyu111/vue-bim-viewer@0.3.2
23
+ npm install @caojinyu111/vue-bim-viewer@0.3.3
22
24
  ```
23
25
 
24
26
  Vue **3.5.43** 和 Three.js **0.183.1** 是精确版本的共享 peerDependencies；npm 7+ 在宿主未安装时会自动补齐，保持单实例。three-tile **0.12.2** 与 GIS 投影依赖随 SDK 安装，three-tile 随 SDK 构建。
@@ -95,16 +97,17 @@ function focusFirst() {
95
97
 
96
98
  模型入口相对于 Manifest 地址解析；glTF 外部资源相对于模型地址解析。资源必须可通过 HTTP/HTTPS 访问，跨域服务器需要配置 CORS。
97
99
 
98
- ## Home 与方向骰子
100
+ ## 构件目录、Home 与方向骰子
99
101
 
100
- 右上角默认显示 Home 和导航骰子。宿主传入响应式配置即可实时调整，不重载模型：
102
+ 左上角默认显示构件目录按钮，右上角显示 Home 和导航骰子。宿主传入响应式配置即可分别调整显隐，不重载模型：
101
103
 
102
104
  ```vue
103
105
  <script setup>
104
106
  import { reactive } from 'vue'
105
- const navigation = reactive({ home: true, cube: true })
107
+ const navigation = reactive({ home: true, cube: true, componentTree: true })
106
108
  // navigation.home = false // 隐藏 Home
107
- // navigation.cube = false // 隐藏骰子；两项均 false 时不占位
109
+ // navigation.cube = false // 隐藏骰子
110
+ // navigation.componentTree = false // 隐藏构件目录按钮并关闭面板
108
111
  </script>
109
112
 
110
113
  <template>
@@ -114,6 +117,10 @@ const navigation = reactive({ home: true, cube: true })
114
117
 
115
118
  未传配置或字段时默认显示。Home 调用 `resetView()`，按 `initialView` 恢复全模型视角；骰子跟随主相机旋转，点击六面、十二条边或八个角时保留当前观察中心及距离。宿主也可调用 `viewer.value.setViewDirection('top', { duration: 400 })` 切换六个标准方向。方向切换默认沿用 `cameraTransition`；`duration: 0` 为立即切换。
116
119
 
120
+ 构件目录默认收起，仅显示模型的实际构件层级。搜索名称会保留匹配路径，不改变场景显隐。复选框作用于完整分支：取消勾选隐藏整组，勾选显示整组及此前单独隐藏的子构件；部分显示时呈半选状态。点击名称使用内置效果选中并按当前观察方向定位；隐藏构件保持隐藏，空节点只选中并提示没有可定位几何。目录显隐修改沿用 `appearance-change` 事件和外观差异保存机制。
121
+
122
+ 打开目录时按钮隐藏，首次打开的面板左上角与按钮原位置对齐，距场景顶部、左侧各 16px。按住标题文字或标题栏空白处可在场景内拖动，关闭按钮显示手形光标且不启动拖动。关闭后按钮恢复原位，再次打开保留关闭前的位置；同一组件实例内隐藏目录或重载模型也保留位置，刷新页面或重新挂载后恢复初始位置。打开和场景尺寸变化时自动修正越界位置。目录不设置自定义键盘快捷键，搜索输入及原生控件键盘行为正常保留；拖动不会操作模型，列表仍可独立滚动。
123
+
117
124
  导航为包内独立封装，不额外导出组件，不依赖其他地图或 BIM 平台 SDK。更多方向约定与边界见 [API 导航说明](./API.md#navigation)。
118
125
 
119
126
  ## 天地图影像与 DEM
@@ -131,6 +138,8 @@ const gis = {
131
138
  // <MineViewer :model-source="modelSource" :gis="gis" @terrain-status="onTerrain" />
132
139
  ```
133
140
 
141
+ 配准控制点中的模型坐标沿用源模型单位，SDK 不会自动判断米或毫米；通过 `metersPerUnit` 声明一个模型单位对应多少米。默认最小二乘模式需要水平分散且不共线的控制点，`first-point` 模式由首点确定位置、其余点确定方向。
142
+
134
143
  地图默认关闭。开启地图但省略 `terrain` 时显示平面影像；开启 DEM 后默认使用 `relative` 相对预览，以配准参考点的 DEM 高程为基准显示地形起伏。`absolute` 真实高程模式要求 `placement.heightResolved === true`，并提供将 DEM 原始高程转换为配准所用椭球高的 `toEllipsoidHeight` 函数。相对预览不能作为真实地表对齐或测量依据。
135
144
 
136
145
  影像与地形分别通过 `gis-status`、`terrain-status` 报告加载结果，DEM 缺测瓦片保留平面影像。地图覆盖模型水平范围外扩 1000 米后的瓦片区域，优先 16 级、最多 256 张，不随相机缩放切换精度，不支持无限漫游、注记或地形碰撞。完整配置和服务限制见 [API 地图说明](./API.md#gis-terrain)。
@@ -141,12 +150,12 @@ const gis = {
141
150
  | -------- | ----------------------------------- |
142
151
  | Vue | 精确 3.5.43 |
143
152
  | Three.js | 精确 0.183.1 |
144
- | 浏览器 | 支持 WebGL2 |
153
+ | 浏览器 | 基础模型显示支持 WebGL2；GIS 需要额外浏览器 API |
145
154
  | 布局 | 显式导入样式，容器宽高均非零 |
146
155
  | SSR | 在客户端挂载组件 |
147
156
  | 模型 | 静态 GLB/glTF，未配置额外压缩解码器 |
148
157
 
149
- IFC、RVT 等源 BIM 文件需先转换为支持的 GLB/glTF。地图请求需要浏览器支持 `fetch`、`createImageBitmap`、`AbortSignal.any/timeout`；DEM 还需要 `DecompressionStream`。动画播放、测量、剖切和模型编辑不属于公开能力。具体兼容边界及已知问题见 [使用限制](./API.md#troubleshooting)。
158
+ IFC、RVT 等源 BIM 文件需先转换为支持的 GLB/glTF。基础模型显示需要 WebGL2；启用 GIS 地图还需要 `fetch`、`createImageBitmap`、`AbortSignal.any`、`AbortSignal.timeout` 和 `OffscreenCanvas`；启用 DEM 还需要 `DecompressionStream`。这些是地图和地形的附加要求，基础模型显示不一定需要全部能力。SSR 只能在客户端挂载组件。动画播放、测量、剖切和模型编辑不属于公开能力。具体兼容边界及已知问题见 [使用限制](./API.md#troubleshooting)。
150
159
 
151
160
  ## 文档
152
161
 
package/dist/gis-imagery.d.ts CHANGED
@@ -20,7 +20,7 @@ export type TerrainOptions = {
20
20
  | { mode?: 'relative' }
21
21
  | {
22
22
  mode: 'absolute'
23
- /** DEM 原始高程（米）转换为配准所用基准的椭球高（米）；必须同步返回有限数值。 */
23
+ /** DEM 原始高程（米）转换为配准所用基准的椭球高（米）；必须同步返回有限 number，不接受类型转换。 */
24
24
  toEllipsoidHeight: (point: Required<GeographicCoordinate>) => number
25
25
  }
26
26
  )
package/dist/gis.d.ts CHANGED
@@ -13,12 +13,12 @@ export interface SurveyCoordinate {
13
13
  height?: number
14
14
  }
15
15
  export interface GisControlPoint<T = GeographicCoordinate> {
16
- /** 原始模型坐标，与 getComponentAnchor 使用相同空间，不含展示居中偏移。 */
16
+ /** 原始模型坐标，单位沿用源模型，与 getComponentAnchor 使用相同空间，不含展示居中偏移。 */
17
17
  model: Point3
18
18
  map: T
19
19
  }
20
20
  export type GisPlacementOptions = {
21
- /** 默认最小二乘；first-point 固定首点，其他点只等权确定方向，不拟合比例。 */
21
+ /** 默认最小二乘要求点分散且不共线；first-point 固定首点，其他点只等权确定方向，不拟合比例。 */
22
22
  horizontalAlignment?: 'least-squares' | 'first-point'
23
23
  /** glTF 通常 Y 向上；原始 Z 向上模型须显式指定 z。 */
24
24
  modelUpAxis?: 'y' | 'z'