bc-model-viewer
A dgz(gltf) model viewer
``
css
#container {
position: relative;
overflow: hidden;
width: 100px;
height: 100px;
}
`
`
html
`
`
js
// 导入文件
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 查看器的配置选项及其功能说明。
---
配置结构概览
`
typescript
interface ViewerConfig {
cache: CacheConfig;
ktx2: KTX2Config;
draco: DracoConfig;
style: StyleConfig;
display: DisplayConfig;
control: ControlConfig;
camera: CameraConfig;
light: LightConfig;
measure: MeasureConfig;
render: RenderConfig;
}
`
---
2. 编解码器配置
$3
`
typescript
{
url: '/ktx2/' // KTX2 解码器路径
}
`
- url: string
KTX2 纹理解码器的加载路径
$3
`
typescript
{
url: '/draco/' // Draco 解码器路径
}
`
- url: string
Draco 压缩模型解码器的加载路径
---
3. 视觉样式 (
style
)
`
typescript
{
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
)
`
typescript
{
fps: { display: false } // 是否显示 FPS 计数器
}
`
---
5. 控制配置 (
control
)
`
typescript
{
autoRotate: false, // 自动旋转
orbitPoint: 'clickPoint',// 旋转中心点策略
maxDistance: 'default', // 最大视距
rotateSpeed: 3, // 旋转灵敏度 (1-10)
clickSelected: true // 点击选择物体
}
`
- orbitPoint 可选值:
clickPoint
- 以点击位置为中心
fixed
- 固定中心点
---
6. 相机配置 (
camera
)
`
typescript
{
type: 'perspective', // 相机类型
fov: 40 // 视野角度 (度)
}
`
- type 可选值:
perspective
- 透视投影
orthographic
- 正交投影
---
7. 光照配置 (
light
)
`
typescript
{
ambientLight: { // 环境光
display: true,
intensity: 0.5 // 光照强度 (0-1)
},
hemiLight: { // 半球光
display: true,
intensity: 2.16
},
directionalLight: { // 平行光
display: true,
intensity: 2.00
}
}
`
---
8. 其他配置
$3
`
typescript
{
unit: 'm' // 测量单位
}
`
$3
`
typescript
{
display: false // 是否显示调试面板
}
`
$3
`
typescript
{
enableTransition: true, // 启用过渡动画
LODFactor: 30 // 细节层次系数
}
`
---
配置示例
`
javascript
// 修改背景色和启用雾效
viewerConfig.style.background.color = '#FFFFFF';
viewerConfig.style.fog.enabled = true;
// 启用调试面板
viewerConfig.gui.display = true;
`
请根据实际需求调整配置参数，配置修改后需重新初始化查看器生效。
viewer类实例方法
activateSceneByName
$3
通过指定的场景名称激活对应场景，可控制是否启用场景过渡效果
$3
`
typescript
activateSceneByName(name: string, enableTransition: boolean = false): void
`
$3
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| ---------------- | ------- | ---- | ------ | -------------------------------------------------------------------- |
| name | string | 是 | 无 | 要激活的场景名称，需确保该名称与已注册的场景名称完全匹配 |
| enableTransition | boolean | 否 | false | 是否启用场景过渡动画。当设置为 true 时，会触发场景切换的过渡效果动画 |
$3
- void
$3
`
typescript
// 激活名为 "1F" 的场景，不使用过渡效果
viewer.activateSceneByName("1F");
// 激活名为 "2F" 的场景并启用过渡动画
viewer.activateSceneByName("2F", true);
`
addHUDLabel
$3
在三维场景的指定坐标位置添加一个可交互的HUD标签，支持自定义样式、数据绑定和点击事件回调。适用于创建信息标注、设备标签等需要与3D空间位置绑定的交互元素。
---
方法签名
`
typescript
addHUDLabel(
pointArray: number[],
options: {
assets?: object,
className?: string,
click?: (label: CSS2DObject, assets: object) => void
} = {}
): void
`
---
参数说明
$3
| 参数名 | 类型 | 必填 | 描述 |
| ---------- | -------- | ---- | ---------------------------- |
| pointArray | number[] | 是 | 三维空间坐标数组 [x, y, z]
|
$3
| 参数名 | 类型 | 必填 | 默认值 | 描述 |
| --------- | --------------------- | ---- | ------ | -------------------------- |
| assets | object | 否 | {} | 绑定到标签的自定义数据对象 |
| className | string | 否 | - | 控制标签样式的CSS类名 |
| click | (label, assets)=>void | 否 | - | 标签点击事件回调函数 |
---
代码示例
`
javascript
// 在坐标原点添加带数据绑定的警告标签
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'
});
``