bc-model-viewer

A dgz(gltf) model viewer

#container {
  position: relative;
  overflow: hidden;
  width: 100px;
  height: 100px;
}

<div id="container"></div>

// 导入文件
import { Viewer } from 'bc-model-viewer'

// 实例化
const viewer = new Viewer(
  // 加载的容器 需要指定宽度 高度
  document.getElementById('container'),
  // 初始化配置选项
  {
    // ...更多配置
  })

// 异步加载dgz文件 
viewer.loadZipAsync(
  // dgz文件地址
  '/xxx.dgz',
  // 进度信息 
  process => {
    console.log(process);
  }
)

Viewer 配置文档

本文档描述了 3D 查看器的配置选项及其功能说明。

配置结构概览

interface ViewerConfig {
  cache: CacheConfig;
  ktx2: KTX2Config;
  draco: DracoConfig;
  style: StyleConfig;
  display: DisplayConfig;
  control: ControlConfig;
  camera: CameraConfig;
  light: LightConfig;
  measure: MeasureConfig;
  render: RenderConfig;
}

2. 编解码器配置

KTX2 配置 (ktx2)

{
  url: '/ktx2/' // KTX2 解码器路径
}

• url: string
  KTX2 纹理解码器的加载路径

Draco 配置 (draco)

{
  url: '/draco/' // Draco 解码器路径
}

• url: string
  Draco 压缩模型解码器的加载路径

3. 视觉样式 (style)

{
  type: 1,                // 样式类型
  background: {           // 背景配置
    color: '#DBDBDE'      // 背景颜色
  },
  sky: {                  // 天空盒配置
    enabled: false,       // 是否启用天空盒
    turbidity: 0,         // 大气浑浊度 (0-10)
    // ...其他天空物理参数
  },
  edge: { modal: 0 },     // 边缘高亮模式
  fog: {                  // 雾效配置
    enabled: false,       // 是否启用雾效
    density: 0.0015       // 雾浓度
  },
  material: { opacity: 1 }, // 材质透明度
  axes: { display: false }  // 是否显示坐标轴
}

4. 显示配置 (display)

{
  fps: { display: false } // 是否显示 FPS 计数器
}

5. 控制配置 (control)

{
  autoRotate: false,       // 自动旋转
  orbitPoint: 'clickPoint',// 旋转中心点策略
  maxDistance: 'default',  // 最大视距
  rotateSpeed: 3,          // 旋转灵敏度 (1-10)
  clickSelected: true      // 点击选择物体
}

• orbitPoint 可选值:
  clickPoint - 以点击位置为中心
  fixed - 固定中心点

6. 相机配置 (camera)

{
  type: 'perspective',  // 相机类型
  fov: 40               // 视野角度 (度)
}

• type 可选值:
  perspective - 透视投影
  orthographic - 正交投影

7. 光照配置 (light)

{
  ambientLight: {        // 环境光
    display: true,
    intensity: 0.5       // 光照强度 (0-1)
  },
  hemiLight: {           // 半球光
    display: true,
    intensity: 2.16
  },
  directionalLight: {    // 平行光
    display: true,
    intensity: 2.00
  }
}

8. 其他配置

测量配置 (measure)

{
  unit: 'm' // 测量单位
}

GUI 配置 (gui)

{
  display: false // 是否显示调试面板
}

渲染配置 (render)

{
  enableTransition: true, // 启用过渡动画
  LODFactor: 30           // 细节层次系数
}

配置示例

// 修改背景色和启用雾效
viewerConfig.style.background.color = '#FFFFFF';
viewerConfig.style.fog.enabled = true;

// 启用调试面板
viewerConfig.gui.display = true;

请根据实际需求调整配置参数，配置修改后需重新初始化查看器生效。

viewer类实例方法

activateSceneByName

描述

通过指定的场景名称激活对应场景，可控制是否启用场景过渡效果

方法签名

activateSceneByName(name: string, enableTransition: boolean = false): void

参数

| 参数名 | 类型 | 必填 | 默认值 | 描述 | | ---------------- | ------- | ---- | ------ | -------------------------------------------------------------------- | | name | string | 是 | 无 | 要激活的场景名称，需确保该名称与已注册的场景名称完全匹配 | | enableTransition | boolean | 否 | false | 是否启用场景过渡动画。当设置为 true 时，会触发场景切换的过渡效果动画 |

返回值

• void

示例

// 激活名为 "1F" 的场景，不使用过渡效果
viewer.activateSceneByName("1F");

// 激活名为 "2F" 的场景并启用过渡动画
viewer.activateSceneByName("2F", true);

addHUDLabel

描述

在三维场景的指定坐标位置添加一个可交互的HUD标签，支持自定义样式、数据绑定和点击事件回调。适用于创建信息标注、设备标签等需要与3D空间位置绑定的交互元素。

方法签名

addHUDLabel(
  pointArray: number[], 
  options: {
    assets?: object,
    className?: string,
    click?: (label: CSS2DObject, assets: object) => void
  } = {}
): void

参数说明

空间坐标

| 参数名 | 类型 | 必填 | 描述 | | ---------- | -------- | ---- | ---------------------------- | | pointArray | number[] | 是 | 三维空间坐标数组 [x, y, z] |

配置选项

| 参数名 | 类型 | 必填 | 默认值 | 描述 | | --------- | --------------------- | ---- | ------ | -------------------------- | | assets | object | 否 | {} | 绑定到标签的自定义数据对象 | | className | string | 否 | - | 控制标签样式的CSS类名 | | click | (label, assets)=>void | 否 | - | 标签点击事件回调函数 |

代码示例

// 在坐标原点添加带数据绑定的警告标签
viewer.addHUDLabel([0, 0, 0], {
  className: 'warning-marker',
  assets: {
    deviceId: "CAM-001",
    status: "online"
  },
  click: (label, assets) => {
    console.log('激活设备:', assets.deviceId)
    showDevicePanel(assets)
  }
});

// 添加简单的位置标记
viewer.addHUDLabel([5, 2, -3], {
  className: 'position-pin'
});