xeokit-bim-viewer

• 运行演示

---

如果您对适用于您自己解决方案的即用型 3D/BIM 查看生态系统感兴趣，务必同时查看：

• xeoVision - 立即查看您的模型！
• xeoServices

---

xeokit-bim-viewer 是一款开源的 2D/3D BIM 查看器，可在浏览器中运行，并从您的文件系统加载模型。

该查看器基于**xeokit** 构建，并作为**xeokit SDK** 的一部分进行打包。

该查看器由 xeolabs 和 OpenProject 开发，目前由 Creoox AG 提供支持。它已集成到 OpenProject BIM 10.4 及更高版本中。

该查看器可用作独立的 JavaScript 应用程序。结合开源的 CLI 模型转换工具，它提供了一种低成本、高性能的方式，让您的 IFC 模型能够在 Web 上展示，使您可以自由地在自己的服务器或 GitHub 仓库上转换和托管模型。为获得最稳健且性能最佳的 IFC 转换，我们建议查看 IFC -> 二进制 glTF (GLB) cxConverter。

📜 许可与商业使用

xeokit SDK 采用 AGPLv3 许可协议，这意味着任何对 xeokit SDK 的修改或集成到项目中的行为，都必须同样以 AGPLv3 许可协议开源。

🪧 需要商业许可？ 如果您的公司需要在 专有或闭源 应用中使用采用不同许可模式的 xeokit SDK，我们提供 灵活的商业许可方案。

📩 联系我们：发送邮件至 contact@creoox.com 或访问 xeokit.io 了解更多信息。

使用方法

要使用此查看器查看您的模型，请按以下步骤操作：

方法一

1. 在 GitHub 上 Fork xeokit-bim-viewer 仓库。
2. 使用 开源 CLI 工具 转换您的 IFC STEP 文件。
3. 将转换后的模型添加到您 Fork 仓库的数据目录中。
4. 使用 GitHub Pages 部署您的 Fork 仓库。

之后，用户便可在浏览器中查看您的模型，URL 示例如下：

https://xeokit.github.io/xeokit-bim-viewer/app/index.html?projectId=OTCConferenceCenter&tab=storeys

请记得像示例中那样在 URL 中添加 projectId 参数： https://user.github.io/xeokit-bim-viewer/app/index.html?projectId=<your projectID here>

方法二

1. 从 https://nodejs.org/en 安装 NodeJS
2. 克隆或 Fork 此仓库并安装所需依赖

git clone https://github.com/xeokit/xeokit-bim-viewer
cd xeokit-bim-viewer
npm install

3. 将转换后的模型添加到 data 目录。
4. 使用以下命令在本地计算机上运行查看器：

npm run serve

5. 访问 http://localhost:8080/app/index.html?projectId=<your projectID here>

与 xeokit-sdk 的版本兼容性

从 2.6.0 版本开始，xeokit-bim-viewer 的版本号已与 xeokit-sdk 保持一致，即主版本号和次版本号相匹配。 这意味着，对于任何版本为 2.6.x 的 xeokit-sdk 发行版，相应的 xeokit-bim-viewer 发行版将采用 2.6.y 的编号方式。 请注意，两个项目之间的补丁版本号是独立管理的。例如，xeokit-bim-viewer 2.6.0 是基于 xeokit-sdk 2.6.67 构建的。

后续步骤

阅读以下文档以开始使用。

---

• 发行说明 / 变更日志
• 源代码
• API 文档
• xeokit SDK

---

目录

• 功能特性
• 演示示例
• 许可协议
• 查看器应用程序
• 模型数据库
• 查看器配置
  • 查看器状态
• 部署 XKT V7 及更早版本
• 对多部分（拆分）模型的支持
• 具有单独元数据文件的拆分模型
• 编程 API
  • 创建查看器
  • 配置查看器
  • 查询项目、模型和对象
    • 获取可用项目信息
    • 获取项目信息
    • 获取对象信息
  • 加载项目和模型
    • 加载项目
    • 加载模型
  • 控制查看器状态
  • 保存和加载 BCF 视点
• 自定义查看器样式
  • 模态加载对话框
  • 工具提示
  • 自定义 IFC 类型的外观
  • 查看器本地化
• 查看器中使用的 xeokit 组件
• 构建查看器
  • 从 NPM 安装
  • 构建二进制文件
  • 构建文档

---

功能特点

• 使用 xeokit 实现高效的模型加载与渲染。
• 支持所有主流浏览器，包括移动设备浏览器。
• 可从文件系统加载模型。
• 支持加载多个模型。
• 保存和加载 BCF 视点。
• 具备 3D 和 2D 查看模式。
• 可交互式地对对象进行透视、高亮、显示、隐藏和剖切操作。
• 提供结构、图层和楼层的树状视图。
• 全精度几何图形。
• 点云支持。
• 兼容 IFC2x3 和 IFC4 格式。
• 可通过自定义 CSS 调整查看器外观。
• 本地化支持。
• 提供用于所有查看器功能的 JavaScript 编程 API。

演示示例

点击以下链接运行演示示例。

在线演示	模型来源
双精度模型	BIMData
点云	BIMData
OTC 会议中心	详情
OTC 会议中心（Web 组件）	详情
Revit 示例项目	详情
Holter Tower	详情
West Riverside Hospital	详情
Schependomlaan	详情
Schependomlaan 底层平面图	详情
Duplex	详情

许可协议

xeokit-bim-viewer 捆绑在 xeokit SDK 中，该 SDK 采用 AGPL3 许可协议。有关定制许可选项，请参见我们的 定价 页面。

查看器应用程序

./app/index.html 页面提供了 xeokit-bim-viewer 的即用实例。从现在开始，我们简称它为“查看器”。

查看器从 ./app/data/projects 目录加载项目和模型。

要查看项目，请在 URL 中带上项目 ID 加载查看器：

https://xeokit.github.io/xeokit-bim-viewer/app/index.html?projectId=WestRiversideHospital

模型数据库

本节介绍如何将您自己的模型添加到查看器应用程序中。这些说明依赖于最新版本的 XKT（V8 或更高版本）以及转换工具，您可以在 加载器与转换器 中了解相关信息。

让我们分析一下 ./app/data/projects 目录的结构，查看器在此目录中存储其项目和模型。

下面显示的是 ./app/data/projects 目录的一部分。我们将从根目录开始向下进行描述。

在根目录中，我们为每个项目都设有一个目录，同时在 index.json 中有一个项目清单。

在项目目录中，我们为项目中的每个模型都设有一个目录，同时在 index.json 中有一个模型清单。

在模型目录中，我们有包含模型几何数据和元数据的 .XKT 文件。

.app/data/projects
  │
  ├── index.json
  │
  ├── Duplex
  │     │
  │     ├── index.json
  │     │
  │     └── models
  │           └── design
  │                   └── geometry.xkt
  │
  └── WestRiversideHospital
        │
        ├── index.json
        │
        └── models
              ├── architecture
              │       └── geometry.xkt
              ├── structure
              │       └── geometry.xkt
              └── electrical
                      └── geometry.xkt

./app/data/projects 根目录下的 index.json 如下所示。

在此文件中，每个项目的 id 与该项目子目录的名称相匹配。

{
  "projects": [
    {
      "id": "Duplex",
      "name": "Duplex"
    },
    {
      "id": "WestRiversideHospital",
      "name": "West Riverside Hospital"
    }
    //..
  ]
}

“WestRiversideHospital”项目的 index.json 如下所示。

在此文件中，每个模型的 id 与其子目录的名称相匹配。每个模型的 �KE_PH_15�` 是在查看器“模型”选项卡中显示的易读名称。

{
  "id": "WestRiversideHospital",
  "name": "West Riverside Hospital Project",
  "models": [
    {
      "id": "architectural",
      "name": "Hospital Architecture"
    },
    {
      "id": "structure",
      "name": "Hospital Structure"
    },
    {
      "id": "electrical",
      "name": "Hospital Electrical",
      "saoEnabled": false
    }
  ],
  "viewerConfigs": {
    "backgroundColor": [
      0.9,
      0.9,
      1.0
    ]
  },
  "viewerContent": {
    "modelsLoaded": [
      "structure",
      "architectural"
    ]
  },
  "viewerState": {
    "tabOpen": "models"
  }
}

可选的 viewerConfigs 部分指定了查看器在加载项目时应设置的自身配置。有关可用查看器配置的完整列表，请参见查看器配置。

可选的 viewerContent 数组指定了查看器在应用配置后最初将加载的模型 ID。

可选的 viewerState 部分指定了查看器在加载初始模型后应如何设置其 UI 的初始状态。有关可用查看器状态的完整列表，请参见查看器状态。

每个模型的 geometry.xkt 文件是使用开源 CLI 工具从 IFC 文件创建的。了解如何创建这些文件，请参阅 加载器和转换器。

查看器配置

下表列出了所有可用的配置。可以将这些视为用户偏好。这些配置可以在项目信息文件中提供给查看器（如模型数据库中所述），也可以通过 BIMViewer#setConfigs() 以编程方式在查看器上设置（如配置查看器中所述）。

属性	类型	范围	默认值	描述
"backgroundColor"	Array		[1.0,1.0,1.0]	画布背景颜色
"cameraNear"	Number	[0.01-0.1]	�KE_PH_24�`	近裁剪平面距离
"cameraFar"	Number	[1-100000000]	�KE_PH_26�`	远裁剪平面距离
"smartPivot"	Boolean		true	在相机轨道模式下，当在空白区域点击拖动时，启用更好的轴心点轨道体验。
"saoEnabled"	Boolean		true	是否启用可扩展环境光遮蔽（SAO）
"saoBias"	Number	[0.0...10.0]	�KE_PH_30�`	SAO 偏差值
"saoIntensity"	Number	[0.0...200.0]	�KE_PH_32�`	SAO 强度因子
"saoScale"	Number	[0.0...1000.0]	�KE_PH_34�`	SAO 缩放因子
"saoKernelRadius"	Number	[0.0...200.0]	�KE_PH_36�`	SAO 在检查可能的遮挡时考虑的最大区域
"saoBlur"	Boolean		true	是否为 SAO 启用高斯模糊
"edgesEnabled"	Boolean		true	是否增强对象边缘
"pbrEnabled"	Boolean		false	是否启用基于物理的渲染（PBR）
"viewFitFOV"	Number	[10.0...70.0]	�KE_PH_41�`	当将对象适配到视图时，这是对象应适配用户视野的度数
"viewFitDuration"	Number	[0..5]	�KE_PH_43�`	当通过动画过渡将对象适配到视图时，这是过渡的持续时间（以秒为单位）
"perspectiveFOV"	Number	[10.0...70.0]	�KE_PH_45�`	在透视投影模式下，这是用户看到的视野角度（以度为单位）
"objectColors"	Object		undefined	各种 IFC 类型的自定义属性映射
"externalMetadata"	Boolean		false	是否随每个 geometry.xkt 文件加载 metadata.json 文件
"xrayPickable"	Boolean		false	是否可以使用鼠标/触摸输入与 X 射线模式下的对象进行交互
"selectedGlowThrough"	Boolean		true	选中的对象是否看起来“穿透”其他对象
"highlightGlowThrough"	Boolean		true	高亮显示的对象是否看起来“穿透”其他对象
"dtxEnabled"	Boolean		false	是否启用 xeokit 的基于数据纹理（DTX）的场景表示和渲染模式。与标准的基于顶点缓冲区对象（VBO）的模式相比，此模式内存占用更低，加载速度更快，但在低规格 GPU 上可能速度较慢。
"showSpaces"	Boolean		false	是否启用 IfcSpace 元素的可见性。当此值为 �KE_PH_53�` 时，即使我们可以指示 BIMViewer 在树视图或上下文菜单中使 IfcSpaces 可见，它们也将保持不可见。此配置也由工具栏中的“显示 IfcSpaces”工具动态控制。

查看器状态

在模型数据库中，我们了解了项目如何在加载完成后立即指定查看器设置其UI初始状态的指令。下表列出了可用指令。这些指令也可以使用BIMViewer#setViewerState()在查看器上进行设置。目前，我们有：

属性	类型	范围	默认值	描述
"focusObject"	String			要聚焦的对象ID
"tabOpen"	String	"objects"、"classes"或"storeys"		要打开的资源管理器选项卡
"expandObjectsTree"	Number	[0..*]	0	"objects"树展开的深度
"expandClassesTree"	Number	[0..*]	0	"classes"树展开的深度
"expandStoreysTree"	Number	[0..*]	0	"storeys"树展开的深度
"setCamera"	{ eye: Number[], look: Number[], up: Number[] }		0	相机位置

部署XKT V7及更早版本

本节介绍如何部署使用未合并几何和元数据的旧版XKT的模型。对于这些旧版本， 我们需要一些额外的处理来为每个模型部署一个额外的JSON元数据文件。

上一节介绍了如何部署使用XKT V8及更高版本的模型。XKT V8+格式将几何和元数据合并到同一个XKT文件中，是在xeokit v1.9版本中引入的。

V8之前的XKT版本仅包含几何数据，需要一个包含模型IFC元数据的JSON文件与之配合。在本节中，我们将介绍如何部署使用V8之前版本XKT的模型。

假设我们要使用XKT V7部署Duplex和West Riverside Hospital项目。对于数据库中的每个模型，我们将部署一个geometry.xkt（包含模型几何数据的XKT V7文件）和一个�KE_PH_56�`（包含模型IFC元数据的文件）。

我们假设您已经拥有这些文件，并且暂时不准备将其原始IFC文件转换为XKT V8+格式。

以下是我们的数据库文件，这次包含XKT V7及配套的元数据文件：

.app/data/projects
  │
  ├── index.json
  │
  ├── Duplex
  │     │
  │     ├── index.json
  │     │
  │     └── models
  │           └── design
  │                   ├── geometry.xkt
  │                   └── metadata.json
  │
  └── WestRiversideHospital
        │
        ├── index.json
        │
        └── models
              ├── architecture
              │       ├── geometry.xkt
              │       └── metadata.json
              ├── structure
              │       ├── geometry.xkt
              │       └── metadata.json
              └── electrical
                      ├── geometry.xkt
                      └── metadata.json

为了让 BIMViewer 加载每个模型的 geometry.xkt 和 �KE_PH_59� 文件，我们需要在项目的 ````index.json```` 文件中，为 �KE_PH_61� 添加一个新的 externalMetadata: true 配置：

{
  "id": "WestRiversideHospital",
  "name": "West Riverside Hospital",
  "models": [
    {
      "id": "architectural",
      "name": "Hospital Architecture"
    },
    {
      "id": "structure",
      "name": "Hospital Structure"
    },
    {
      "id": "electrical",
      "name": "Hospital Electrical",
      "saoEnabled": false
    }
  ],
  "viewerConfigs": {
    "externalMetadata": true, // <<------------ ADD THIS
    "backgroundColor": [
      0.9,
      0.9,
      1.0
    ]
  },
  "viewerContent": {
    "modelsLoaded": [
      "structure",
      "architectural"
    ]
  },
  "viewerState": {
    "tabOpen": "models"
  }
}

对多部分（拆分）模型的支持

从 xeokit-bim-viewer 2.4 版本开始，我们可以部署拆分为多个 XKT 文件（可包含外部 JSON 元数据文件）的模型。

Creoox 提供的 ifc2gltf 工具可将 IFC 文件转换为 glTF 几何文件和 JSON 元数据文件，该工具支持将输出内容拆分为多对 glTF 和 JSON 文件，并附带一个列出这些文件的 JSON 清单文件。

为了适配这一功能，用于将 glTF 几何文件和 JSON 元数据文件转换为 XKT 文件的 convert2xkt 工具也支持通过一次调用，对清单文件中的 glTF+JSON 文件进行批量转换。

使用此选项时，convert2xkt 将输出一系列 XKT 文件，以及一个列出这些 XKT 文件的 JSON 清单文件。

此功能为 BIMViewer 扩展了加载由多个 XKT 文件组成的模型的选项，可将这些 XKT 文件合并到每个模型的单个树视图中，并支持通过卸载模型一次性卸载其所有 XKT 文件。换句话说，我们现在可以将多个 XKT 文件组合在一起，使其在 BIMViewer 中表现为一个模型，而不是每个 XKT 文件对应一个单独的模型和树视图。

要了解有关将 IFC 模型转换为多个 XKT 文件的更多信息，请参阅本教程。

为了展示如何在 BIMViewer 中部署此类多 XKT 模型，让我们以 Karhumaki 项目为例进行说明。

---

• 在 BIMViewer 中加载 Karhumaki 项目

---

.app/data/projects
  │
  ├── index.json
  │
  └── Karhumaki
        │
        ├── index.json
        │
        └── models
              └──  KarhumakiBridge
                      ├── manifest.json
                      ├── model.xkt
                      ├── model_1.xkt
                      ├── model_2.xkt
                      ├── model_3.xkt
                      ├── model_4.xkt
                      ├── model_5.xkt
                      ├── model_6.xkt
                      ├── model_7.xkt
                      ├── model_8.xkt
                      └── model_9.xkt

manifest.json XKT 清单如下所示：

{
  "xktFiles": [
    "model.xkt",
    "model_1.xkt",
    "model_2.xkt",
    "model_3.xkt",
    "model_4.xkt",
    "model_5.xkt",
    "model_6.xkt",
    "model_7.xkt",
    "model_8.xkt",
    "model_9.xkt"
  ]
}

“Karhumaki”项目的 index.json 如下所示。

在此文件中，与往常一样，每个模型的 id 与该模型子目录的名称相匹配。每个模型的 �KE_PH_68�` 是在查看器“模型”选项卡中显示的易读名称。

为了表明该模型是包含多个 XKT 的多部分模型，模型条目会包含一个 manifest 属性，该属性包含我们 manifest.json 文件的文件名。

在 viewerContent 中，我们指定多部分模型会在项目加载后立即加载。

{
  "id": "Karhumaki",
  "name": "Karhumaki",
  "models": [
    {
      "id": "Karhumaki-Bridge",
      "name": "Karhumaki Bridge",
      "manifest": "manifest.json"
    }
  ],
  "viewerConfigs": {
    "backgroundColor": [
      0.9,
      0.9,
      1.0
    ]
  },
  "viewerContent": {
    "modelsLoaded": [
      "Karhumaki-Bridge"
    ]
  },
  "viewerState": {
    "tabOpen": "models"
  }
}

使用单独元数据文件拆分模型

在 xeokit 的最新版本中，为简化流程，我们将几何数据和元数据合并到了 XKT 文件中，如上述示例所示。

正如前面所提到的，在早期版本的 XKT 中，元数据存储在单独的 JSON 文件中，因此每个 XKT 文件仅包含几何数据，并配有一个包含其 IFC 元数据的 JSON 文件。

BIMViewer 以及 xeokit SDK 的其他部分仍向后兼容这种 XKT 与 JSON 分离的模式。拆分模型加载功能同样保持向后兼容，如下文所述的 “WestRiversideHospital_Combined” 示例项目所示。

---

• 在 BIMViewer 中加载 WestRiversideHospital_Combined 项目

---

我们在 models 目录中存放了分离的 XKT 和 JSON 元数据文件：

.app/data/projects
  │
  ├── index.json
  │
  └── WestRiversideHospital_Combined
    ├── index.json
    │
    └── models
        │
        └── WestRiversideHospital
            ├── architectural.json
            ├── architectural.xkt
            ├── electrical.json
            ├── electrical.xkt
            ├── fireAlarms.json
            ├── fireAlarms.xkt
            ├── manifest.json
            ├── mechanical.json
            ├── mechanical.xkt
            ├── plumbing.json
            ├── plumbing.xkt
            ├── sprinklers.json
            ├── sprinklers.xkt
            ├── structure.json
            └── structure.xkt

manifest.json XKT 清单如下所示。注意其中新增的 metaModelFiles 属性，该属性列出了构成“WestRiversideHospital”模型元模型的 JSON 文件：

{
  "xktFiles": [
    "architectural.xkt",
    "electrical.xkt",
    "fireAlarms.xkt",
    "mechanical.xkt",
    "plumbing.xkt",
    "sprinklers.xkt",
    "structure.xkt"
  ],
  "metaModelFiles": [
    "architectural.json",
    "electrical.json",
    "fireAlarms.json",
    "mechanical.json",
    "plumbing.json",
    "sprinklers.json",
    "structure.json"
  ]
}

最后，“WestRiversideHospital_Combined”项目的 index.json 如下所示。

在此文件中，与之前一样，每个模型的 id 与其子目录名称相匹配，每个模型的 �KE_PH_75�` 是在查看器“模型”选项卡中显示的易读名称。

同样，为了表明该模型是包含多个 XKT 的多部分模型，模型条目会包含一个 manifest 属性，其中包含我们 manifest.json 文件的文件名。

在 viewerContent 中，我们指定多部分模型在项目加载后立即加载。

{
    "id": "WestRiversideHospital_Combined",
    "name": "West Riverside Hospital",
    "models": [
        {
            "id": "WestRiversideHospital",
            "name": "West Riverside Hospital",
            "saoEnabled": true,
            "manifest": "manifest.json"
        }
    ],
    "viewerConfigs": {
        "backgroundColor": [0.9, 0.9, 1.0],
        "externalMetadata": true
    },
    "viewerContent": {
        "modelsLoaded": [
            "WestRiversideHospital"
        ]
    },
    "viewerState": {
        "viewCubeEnabled": true,
        "threeDEnabled": true,
        "tabOpen": "models"
    }
}

编程 API

本节将深入介绍查看器，说明如何实例化查看器以及如何使用其 JavaScript 编程 API。

查看器由 JavaScript BIMViewer 类实现，该类提供了一整套用于以编程方式控制查看器的方法。

使用这些方法，我们可以：

• 创建并配置查看器，
• 查询可用模型，
• 加载项目和模型，
• 与 3D 视图进行交互，
• 保存和加载 BCF 视点，
• 控制各种查看器工具，以及
• 驱动查看器 UI 的状态。

创建查看器

在下面的示例中，我们将创建一个 BIMViewer，并通过 �KE_PH_80�` 从文件系统加载项目和模型。

我们将把 Server 配置为从 �KE_PH_82�` 目录加载数据。

我们还将为 BimViewer 配置 DOM 元素，以容纳其 UI 的四个部分，分别是：

1. 3D 画布，
2. 包含树视图的资源管理器面板，
3. 工具栏，
4. NavCube，以及
5. “背景”元素，当查看器正忙于加载模型时，该元素会覆盖 UI 中的所有内容以防止交互。

const server = new Server({
    dataDir: "./data"
});

const myBIMViewer = new BIMViewer(server, {
    canvasElement: document.getElementById("myCanvas"),                // The 3D WebGL canvas
    explorerElement: document.getElementById("myExplorer"),            // Container for the explorer panel
    toolbarElement: document.getElementById("myToolbar"),              // Container for the toolbar
    navCubeCanvasElement: document.getElementById("myNavCubeCanvas"),  // Canvas for the NavCube
    busyModelBackdropElement: document.querySelector(".xeokit-busy-modal-backdrop") // Busy modal dialog backdrop element
});

通过在文档中为 BIMViewer 的各个部分配置独立位置，我们可以将其更灵活地集成到网页中。

在我们的 app/index.html 页面中，HTML 元素如下所示：

<div id="myViewer" class="xeokit-busy-modal-backdrop">
    <div id="myExplorer" class="active"></div>
    <div id="myContent">
        <div id="myToolbar"></div>
        <canvas id="myCanvas"></canvas>
    </div>
</div>
<canvas id="myNavCubeCanvas"></canvas>

有关我们如何设置这些元素样式的信息，请参见app/css/style.css。

另请参见dist/xeokit-bim-viewer.css，了解BIMViewer应用于其内部创建元素的CSS样式。

配置查看器

创建查看器后，我们使用BIMViewer#setConfigs()对其进行配置。

我们只需将画布背景颜色设置为白色：

myBIMViewer.setConfigs({
    "backgroundColor": [1.0, 1.0, 1.0]
});

有关可用配置的列表，请参见查看器配置。

查询项目、模型和对象

创建并配置好查看器后，让我们了解一下有哪些可用内容。

获取可用项目的信息

让我们查询有哪些可用项目。

myBIMViewer.getProjectsInfo((projectsInfo) => {
    console.log(JSON.stringify(projectsInfo, null, "\t"));
});

在内部，查看器将调用Server#getProjects()来获取项目信息。

如前面在模型数据库中所述，项目信息是./app/data/projects/index.json中的JSON数据。我们只需将该信息记录到控制台即可。

项目信息大致如下：

{
  "projects": [
    {
      "id": "Duplex",
      "name": "Duplex"
    },
    {
      "id": "Schependomlaan",
      "name": "Schependomlaan"
    },
    {
      "id": "WestRiversideHospital",
      "name": "West Riverside Hospital"
    }
  ]
}

获取项目信息

现在我们知道有哪些项目可用，接下来我们将获取其中一个项目的信息。

myBIMViewer.getProjectInfo("WestRiversideHospital", (projectInfo) => {
    console.log(JSON.stringify(projectInfo, null, "\t"));
});

在内部，查看器将调用Server#getProject()来获取该项目信息。和之前一样，我们只需将其记录到控制台即可。

项目信息将是./app/data/projects/WestRiversideHospital/index.json的内容。

项目信息将类似于：

{
  "id": "WestRiversideHospital",
  "name": "West Riverside Hospital",
  "models": [
    {
      "id": "architectural",
      "name": "Hospital Architecture"
    },
    {
      "id": "structure",
      "name": "Hospital Structure"
    },
    {
      "id": "electrical",
      "name": "Hospital Electrical",
      "saoEnabled": false
    }
  ],
  "viewerConfigs": {
    "backgroundColor": [
      0.9,
      0.9,
      1.0
    ],
    "saoEnabled": true
  },
  "viewerContent": {
    "modelsLoaded": [
      "structure",
      "architectural"
    ]
  },
  "viewerState": {
    "tabOpen": "models"
  }
}

在此项目信息中，我们包含以下内容：

• id - 项目的 ID，
• name - 项目的人类可读名称，
• models - 此项目中每个模型的信息，
• viewerConfigs - 查看器在加载项目时应用的配置，
• viewerContent - 查看器在加载项目时应立即加载哪些模型，以及
• viewerState - 查看器在加载项目后应如何设置其 UI。

当我们稍后在加载项目部分加载项目时，查看器将把 viewerConfigs 传递给 �KE_PH_107�`，这一点我们在前面的配置查看器部分已经介绍过。

在 viewerConfigs 中，我们启用了查看器的可扩展环境光遮蔽（Scalable Ambient Obscurance）效果，该效果将在模型的缝隙处创建环境阴影。此效果对查看器的渲染性能要求较高，因此我们为“电气”模型禁用了该效果，因为该模型包含许多细长的导线对象，这些对象无法很好地显示 SAO 效果。

获取对象信息

让我们尝试获取项目模型中某个对象的一些信息。

我们说“尝试”是因为，能否找到该信息取决于 Server，该信息可能并不存在。

在内部，查看器将调用 Server#getObjectInfo()，该方法将尝试从文件加载对象信息。

如果您想用自己的实现替换 Server，您的实现可以从数据存储（例如关系数据库）中获取该信息，该数据存储中填充了项目模型中所有对象的元数据，并按其 ID 进行键控。

我们将继续假设我们的 Server 拥有某个对象的信息。

myViewer.getObjectInfo("WestRiversideHospital", "architectural", "2HaS6zNOX8xOGjmaNi_r6b",
    (objectInfo) => {
        console.log(JSON.stringify(objectInfo, null, "\t"));
    },
    (errMsg) => {
        console.log("Oops! There was an error getting info for this object: " + errMsg);
    });

如果指定项目和模型中不存在该对象，此方法将调用其错误回调函数。

我们的文件系统数据库中确实存有该对象的信息，存储路径为./app/data/projects/WestRiversideHospital/models/architectural/objects/2HaS6zNOX8xOGjmaNi_r6b.json。

由于对象信息存在，我们将得到类似如下的结果：

{
  "id": "2HaS6zNOX8xOGjmaNi_r6b",
  "projectId": "WestRiversideHospital",
  "modelId": "architectural",
  "name": "Basic Wall:Exterior - Metal Panel on Mtl. Stud:187578",
  "type": "IfcWall",
  "parent": "2hExBg8jj4NRG6zzD0RZML"
}

到目前为止，您可能已经注意到，我们的文件系统数据库的结构支持 RESTful URI，这些 URI 由我们的 Server 根据提供给查看器查询方法的项目、模型和对象 ID 构建而成。

加载项目和模型

现在让我们加载上一节中查询到的一些项目和模型。

加载项目

首先，让我们加载刚刚查询过信息的项目。

myBIMViewer.loadProject("WestRiversideHospital",
    () => {
        console.log("Nice! The project loaded successfully.");
    },
    (errMsg) => {
        console.log("Oops! There was an error loading this project: " + errMsg);
    });

如果成功，查看器现在将加载两个模型："architectural" 和 �KE_PH_119�`，因为这些是在项目信息的 viewerContent 中指定的。

查看器还将启用可扩展环境光遮蔽（Scalable Ambient Obscurance），因为这是由 viewerConfigs 中的 �KE_PH_122�` 属性指定的。查看器还会根据该部分中的指定，为自身设置各种其他配置。

借助项目信息 viewerState 部分中的 �KE_PH_124�` 属性，查看器还将打开其“模型”选项卡。

我们可以通过查询查看器中当前加载的模型 ID 来确认这两个模型已加载：

const modelIds = myBIMViewer.getModelLoadedIds();

console.log(modelIds);

结果如下：

[
  "architectural",
  "structure"
]

加载模型

在项目加载完成后，我们来加载该项目中的另一个模型。

我们可以先获取项目中所有模型的 ID，以确保要加载的模型是可用的：

const modelIds = myBIMViewer.getModelIds();

console.log(modelIds);

结果如下：

[
  "architectural",
  "structure",
  "electrical"
]

加载模型的方法：

myBIMViewer.loadModel("electrical",
    () => {
        console.log("Nice! The model loaded successfully.");
    },
    (errMsg) => {
        console.log("Oops! There was an error loading this model: " + errMsg);
    });

如果我们不再需要该模型，可以再次卸载它：

myBIMViewer.unloadModel("electrical");

当我们不再需要该项目时，可按如下方式卸载：

myBIMViewer.unloadProject();

请注意，我们一次只能加载一个项目。

控制查看器状态

BIMViewer 提供了多种方法，可通过编程方式控制其 UI 状态。

让我们快速了解其中一些方法，了解可以通过它们控制哪些类型的 UI 状态。这并非详尽指南——有关完整列表，请参阅 BIMViewer 类文档。

在前面的部分中加载了几个模型后，让我们打开查看器的“对象”选项卡，其中包含这些模型中对象的包含层次结构的树状视图：

myBIMViewer.openTab("objects");

要确认当前打开的是哪个标签页：

const tabId = myBIMViewer.getOpenTab();

console.log("Currently open tab: '" + tabId + "'"); // "objects"

现在让我们调整相机以将对象完整显示在视图中：

myBIMViewer.flyToObject("1fOVjSd7T40PyRtVEklS6X", () => { /* Done */
});

TODO: 待 API 方法最终确定后，完成此部分

保存和加载 BCF 视点

BIM 协作格式（BCF）是一种用于管理 BIM 项目问题的格式。BCF 记录会捕获 BIM 查看器的视觉状态，包括相机位置、对象的可见性和选择状态，以及当前处于活动状态的任何剖面平面。

从一个 BIM 查看器保存的 BCF 记录可以加载到另一个查看器中，以同步两个查看器的视觉状态。

请注意，BCF 视点不会记录当前加载了哪些模型。假设源查看器和目标查看器都加载了相同的模型。

使用 BIMViewer#saveBCFViewpoint() 保存当前视图的 JSON 格式 BCF 记录：

const viewpoint = bimViewer.saveBCFViewpoint({
    // Options - see BIMViewer#saveBCFViewpoint() documentation for details
});

我们的视点 JSON 将如下所示。在保存此视点之前，我们已隐藏了一个对象，选择了另一个对象，并创建了剖面平面来剖切模型。该视点还包含查看器画布的 PNG 快照，为简洁起见，此处我们对其进行了截断。

{
    perspective_camera: {
        camera_view_point: { x: 0.0, y: 0.0, z: 0.0 },
        camera_direction: { x: 1.0, y: 1.0, z: 2.0 },
        camera_up_vector: { x: 0.0, y: 0.0, z: 1.0 },
        field_of_view: 90.0
    },
    lines: [],
    clipping_planes: [{
        location: { x: 0.5, y: 0.5, z: 0.5 },
        direction: { x: 1.0, y: 0.0, z: 0.0 }
    }],
    bitmaps: [],
    snapshot: {
        snapshot_type: png,
        snapshot_data: "data:image/png;base64,......"
    },
    components: {
        visibility: {
            default_visibility: false,
            exceptions: [{
                ifc_guid: 4$cshxZO9AJBebsni$z9Yk,
                originating_system: xeokit.io,
                authoring_tool_id: xeokit/v1.0
            }]
       },
        selection: [{
           ifc_guid: "4$cshxZO9AJBebsni$z9Yk",
        }]
    }
}

使用 BIMViewer#loadBCFViewpoint() 加载 JSON 格式的 BCF 记录：

bimViewer.loadBCFViewpoint(viewpoint, {
    // Options - see BIMViewer#loadBCFViewpoint() documentation for details
});

自定义查看器样式

独立查看器的 app/index.html 文件包含各种查看器元素的 CSS 规则，您可以根据需要进行修改。

模态加载对话框

每当我们加载模型时，查看器都会显示一个模态对话框。该对话框有一个背景元素，用于覆盖查看器。当对话框可见时，背景将阻止查看器用户界面上的交互事件。

在我们的 app/index.html 页面中，主 �KE_PH_144�` 就是背景元素：

<div id="myBIMViewer" class="xeokit-busy-modal-backdrop">
    <div id="myExplorer" class="active"></div>
    <div id="myContent">
        <div id="myToolbar"></div>
        <canvas id="myCanvas"></canvas>
    </div>
</div>
<canvas id="myNavCubeCanvas"></canvas>

如 css/BIMViewer.css 中所定义，背景将应用以下样式，以允许对话框在背景内正确定位：

.xeokit-busy-modal-backdrop {
    position: relative;
}

如果需要调整与对话框相关的 CSS，请在 css/BIMViewer.css 中搜索 "xeokit-busy-dialog"。

工具提示

工具提示不属于查看器的核心 JavaScript。相反，查看器的 HTML 元素会标记 data-tippy-content 属性，这些属性提供要在其工具提示中显示的字符串。

例如，“切换 2D/3D”按钮的元素如下所示：

<button type="button" class="xeokit-threeD xeokit-btn fa fa-cube fa-2x" data-tippy-content="Toggle 2D/3D"></button>

在独立查看器的 app/index.html 文件中，我们使用了 tippy.js，它会自动为这些元素创建工具提示。

自定义 IFC 类型的外观

默认情况下，BIMViewer 会加载 XKT 模型文件中的对象颜色和透明度，而不做任何更改。然而，有时某些类型的对象可能因为颜色问题而难以查看模型。

例如，在某些 IFC 模型中，IfcPlate 类型可能用于表示窗户，而这些类型通常被赋予不透明的颜色。这会导致模型中的窗户变为不透明。对于这个示例，我们可以通过为 BIMViewer 或特定模型配置 IfcPlate 类型的自定义颜色或透明度，使窗户变得透明。这样所有 IfcPlate 类型都会重新变为透明。我们有两种实现方式——通过 BIMViewer.setConfigs 以编程方式，或者通过项目的 index.json 文件为每个项目单独配置。

在下面的代码中，我们将把所有 IfcSpace、IfcWindow、IfcOpeningElement 和 IfcPlate 类型配置为透明，同时将 IfcWindow 类型始终设为蓝色。注意所有值的范围都是 [0..1]。

---

请注意，在 v2.4 版本之前，BIMViewer 默认会更改 IfcOpening、IfcSpace、IfcWindow 和 IfcPlate 的颜色和透明度。我们在 v2.4 中移除了这一功能，因为它容易引起混淆，用户会疑惑为什么这些对象类型没有使用模型中为它们定义的颜色/透明度。

---

// In case the model has opaque colors for IfcSpace, IfcWindow, IfcOpeningElement and IfcPlate
// objects, let's make those objects always transparent. To make the model look extra nice,
// let's force IfcWindows to always be blue, while we're at it. This will apply to all models,
// except where we override the settings per-project, as shown next.

bimViewer.setConfigs({
      "objectColors": {
            "IfcSpace": {
                "opacity": 0.3
            },
            "IfcWindow": {
                "opacity": 0.4,
                "color": [0, 0, 1]
            },
            "IfcOpeningElement": {
                "opacity": 0.3
            },
            "IfcPlate": {
                "opacity": 0.3
            }
        }
});

设置这些颜色/透明度自定义的另一种方式是按项目进行，在项目 index.json 文件的 viewerConfigs 部分中设置。如果我们也通过 BIMViewer.setConFigs 设置了这些值，那么此处的设置将覆盖通过该方法设置的值。

例如，我们已为 OTCConferenceCenter 演示模型执行了此操作，否则该模型的窗户将是不透明的，这会使我们难以在模型中导航。因此，我们通过该模型的项目 index.json 中的 viewerConfigs 为某些 IFC 类型提供了自定义的颜色和透明度映射，如下所示（参见 该模型的项目 index.json）。

{
    "id": "otcConferenceCenter",
    "name": "OTC Conference Center",
    "models": [
        {
            "id": "design",
            "name": "OTC Conference Center Design"
        }
    ],
    "viewerConfigs": {
        "backgroundColor": [
            0.95,
            0.95,
            1.0
        ],
        "objectColors": {
            "IfcSpace": {
                "opacity": 0.3
            },
            "IfcWindow": {
                "opacity": 0.4
            },
            "IfcOpeningElement": {
                "opacity": 0.3
            },
            "IfcPlate": {
                "opacity": 0.3
            }
        }
    },
    "viewerContent": {
        "modelsLoaded": [
            "design"
        ]
    },
    "viewerState": {
        "tabOpen": "objects",
        "expandObjectsTree": 3,
        "expandClassesTree": 1,
        "expandStoreysTree": 1
    }
}

本地化查看器

对 BIMViewer 进行本地化最简单的方法是将翻译字符串加载到其区域设置服务中，该服务由 xeokit 的 LocaleService 实现。

下面的代码片段展示了具体的实现方式，其中使用了 BIMViewer 组件所需的部分翻译字符串。这里仅展示导航立方体各面的翻译。我们将直接内联加载这些翻译，而不是像实际应用中那样从单独的 JSON 文件获取。

我们将翻译内容称为“messages”。我们的比喻是，用户界面会“向用户传达信息”。

要查看 BIMViewer 所需的所有翻译内容，请查看我们为捆绑的 BIMViewer 演示应用程序配置的翻译：/app/locales/messages.js。

myBIMViewer.localeService.loadMessages({
    "en": { // English
        "NavCube": {
            "front": "Front",
            "back": "Back",
            "top": "Top",
            "bottom": "Bottom",
            "left": "Left",
            "right": "Right"
        },
        //..
    },
    "mi": { // Māori
        "NavCube": {
            "front": "Mua",
            "back": "Tuarā",
            "top": "Runga",
            "bottom": "Raro",
            "left": "Mauī",
            "right": "Tika"
        },
        //..
    },
    "fr": { // French
        "NavCube": {
            "front": "Avant",
            "back": "Arrière",
            "top": "Supérieur",
            "bottom": "Inférieur",
            "left": "Gauche",
            "right": "Droit"
        },
        //..
    },
    "jp": { // Japanese
        "NavCube": {
            "front": "前部",
            "backLabel": "裏",
            "topLabel": "上",
            "bottomLabel": "底",
            "leftLabel": "左",
            "rightLabel": "右"
        },
        //..
    },
});

一旦加载了翻译内容，我们就可以像这样在不同语言环境之间切换 BIMViewer：

myBIMViewer.localeService.locale = "jp";

查看器中使用的 xeokit 组件

该查看器基于 xeokit SDK 的各类组件和插件构建而成，这些组件和插件旨在加速 BIM 和 CAD 可视化应用程序的开发。

下表列出了本查看器中使用的主要组件。

组件	用途
Viewer	�KE_PH_157�` 的核心，是基于 WebGL 的查看器。
XKTLoaderPlugin	加载模型几何数据和元数据。
NavCubePlugin	导航立方体小控件，允许我们旋转场景并移动相机，以便沿选定的轴或对角线查看场景。
TreeViewPlugin	在资源管理器面板中实现“对象”、“类别”和“楼层”树状视图。
SectionPlanesPlugin	管理交互式剖面平面，用于剖切对象以显示内部结构。
BCFViewpointsPlugin	保存和加载 BCF 视点。
ContextMenu	为资源管理器树状视图和 3D 画布实现上下文菜单。

构建查看器

从 NPM 安装

如需安装 npm 包：

npm i @xeokit/xeokit-bim-viewer

构建二进制文件

运行以下命令，在 /dist/xeokit-bim-viewer.es.js 中构建 ES6 模块。

npm run build

构建文档

要在 /docs/ 中构建 API 文档：

npm run docs