永安市建设局网站参考消息网国内新闻

3dconvert-viewer.js SDK API使用指南​

概述​

3dconvert-viewer.js SDK 是3dconvert平台提供的3D模型web端预览组件。

这款SDK的设计以文件资源为核心。当您在3dconvert平台上传3D模型后，平台会为您的模型分配一个唯一的ID（fileId）。要查看这个fileId，您可以登录3dconvert平台，进入我的工作空间，然后点击我的上传，在相应的文件信息中找到fileId字段。

使用SDK加载与fileId对应的3D模型非常简单，只需编写少量代码（请参考示例代码）。如果您希望调整模型的展示效果或实现更个性化的功能，请查阅详细的API文档。

主要功能与特性​

1. 模型加载：通过指定模型资源fild，加载并显示3D模型。
2. 交互控制：支持旋转、缩放、平移等基本视图控制，以及光照、视角、剖切、模型选择等高级设置。
3. 扩展性良好：支持多种3D模型格式，可根据项目需求定制拓展功能。

快速开始​

• 安装：引入3dconvert-viewer.js SDK到项目中。
• 初始化：在页面中创建Viewer实例，并设置必要参数。
• 加载模型：使用SDK提供的方法加载3D模型。
• 事件监听：注册相关事件监听器，处理用户交互或模型加载状态变更等。

示例代码

html

<!--html 示例-->
...<div id="viewer-container"></div>
...

javascript

// js示例
// 引入3dconvert-viewer SDK
import Viewer from 'nsdt-3dconvert-viewer';async function load3dModal() {// 创建Viewer实例，初始化参数为 Dom id 或者 HTMLElementconst viewer = new Viewer('viewer-container');// 初始化await viewer.init();// 文件idconst fileId = '687e6d1ec0'// 加载模型await viewer.loadObjectByFileId(fileId,{ enableCaching: false })// 注册事件监听器viewer.on('load-progress', (e) => {console.log('模型加载进度', e);});
}load3dModal()

安装使用​

shell

npm install nsdt-3dconvert-viewer

javascript

// 引入3dconvert-viewer.js SDK
import Viewer from ' nsdt-3dconvert-viewer';

创建 Viewer 对象​

javascript

// 创建 Viewer 对象
const viewer = new Viewer(container: HTMLElement, params: ViewerParams);

• container: Viewer绑定的HTML元素

• params: ViewerParams Viewer配置

  javascript

  interface ViewerParams {showStats?: booleanenvironmentSrc?: Asset | stringverbose: boolean
  }

  • showStats: 启用/禁用viewer画布左上角的统计窗口
  • environmentSrc: 允许用户为viewer场景定义环境纹理，形式为equirectangular HDRI
  • verbose: 在控制台中显示其他信息和警告。

在开始使用viewer之前，您需要像下面这样对其进行初始化：

await viewer.init()

该函数是异步的，因为在这一步骤中，viewer要么加载所需的资产（如您可能在params中提供的HDRI），要么生成运行时资产。

事件绑定 ViewerEvent​

javascript

on(eventType: ViewerEvent, handler: (arg) => void)

• eventType : ViewerEvent

  tsx

  enum ViewerEvent {ObjectClicked = 'object-clicked',ObjectDoubleClicked = 'object-doubleclicked',DownloadComplete = 'download-complete'LoadComplete = 'load-complete',LoadProgress = 'load-progress',LoadCancelled = 'load-cancelled',UnloadComplete = 'unload-complete',UnloadAllComplete = 'unload-all-complete',Busy = 'busy',SectionBoxChanged = 'section-box-changed'SectionBoxUpdated = 'section-box-updated'
  }

• handler: 回调函数

加载和卸载模型​

Viewer通过文件id加载存储在服务端的模型

javascript

loadObject(fileId: string, {enableCaching?: boolean}): Promise<void>

• fileId: 模型对应的文件id
• enableCaching: 启用/禁用浏览器中的数据缓存。默认为true

卸载模型

tsx

unloadObject(): Promise<void>

相机控制​

控制视角​

tsx

setView(view: CanonicalView)

用于操作相机的视角

• view: CanonicalView：

  tsx

  type CanonicalView =| 'front'| 'back'| 'up'| 'top'| 'down'| 'bottom'| 'right'| 'left'| '3d'| '3D'

透视/正交相机切换​

tsx

toggleCameraProjection()

Z/Y轴向上切换​

tsx

toggleZXAxisUpFixed()

选中模型对象​

设置模型选中并且高亮

tsx

selectObjects(objects:[]<objectId>);

• objects： objectId集合

当用户在viewer中点击某个3d对象时，监听ObjectClicked或ObjectDoubleClicked事件的回调函数会收到SelectionEvent信息：

ts

type SelectionEvent = {multiple: booleanevent?: PointerEventhits: Array<{guid?: stringobject: Record<string, unknown>point: Vector3}>
}

• 当没有点击对象时，则会使用 null 作为参数触发 ObjectClicked 事件

作为一个简单的例子，在单击对象时将其高亮并且聚焦：

tsx

viewer.on(ViewerEvent.ObjectClicked, (selectionInfo: SelectionEvent) => {if (selectionInfo) {// 选中对象 并且高亮对象viewer.selectObjects([selectionInfo.hits[0].object.id])// 对象聚焦viewer.zoom([selectionInfo.hits[0].object.id ])}else {//没有点击的对象。聚焦整个场景viewer.zoom()	}
})

剖切盒​

Viewer提供了一个可配置的剪切盒功能，可用于查看场景的部分内容。

tsx

setSectionBox(box?: {min: { x: number; y: number; z: number }max: { x: number; y: number; z: number }},offset?: number
)

使用即时盒子定义设置切割盒的尺寸。

• box：切割盒尺寸的盒子定义。如果未提供此参数，则切割盒将调整为整个场景大小。
• offset：用于增加/减小切割盒的可选乘数，默认为0.05。

tsx

setSectionBoxFromObjects(objectIds: string[], offset?: number)**

根据一组对象设置切割盒的尺寸。

• objectIds：我们希望调整切割盒的对象ID。切割盒的尺寸将是其组合轴对齐边界框的结果。
• offset：用于增加/减小切割盒的可选乘数，默认为0.05。

启用切割盒。

tsx

sectionBoxOn(): void

禁用切割盒。

tsx

sectionBoxOff(): void

切换切割盒的开/关状态。

tsx

toggleSectionBox(): void

光照控制​

设置光照

tsx

setLightConfiguration(config: LightConfiguration): void

config: LightConfiguration：

tsx

interface LightConfiguration {enabled?: booleancastShadow?: booleanintensity?: numbercolor?: numberindirectLightIntensity?: number
}interface SunLightConfiguration extends LightConfiguration {elevation?: numberazimuth?: numberradius?: number
}

• enabled：启用/禁用太阳直射光
• castShadow：启用/禁用太阳光投射阴影
• intensity：太阳光的强度
• color：太阳光的颜色（以 int 类型表示）
• indirectLightIntensity：环境光强度（IBL）的强度
• elevation：太阳球面角（以弧度为单位）
• azimuth：太阳球面方位角（以弧度为单位）
• radius：从场景包围球半径的偏移距离

系统默认配置：

tsx

export const DefaultLightConfiguration = {enabled: true, // 太阳阴影是否开启castShadow: false,intensity: 3, // 太阳光强度color: 0xffffff,elevation: 1.8, // 太阳高度azimuth: 0.75, // 太阳方位角radius: 0,indirectLightIntensity: 2,shadowcatcher: false,
};

详细开发示例