Alibabacloud-tdsr-js-sdk NPM

三维重建(临云镜)SDK使用文档

1. 背景介绍

三维重建(TDSR)SDK 主要为三维重建(TDSR)提供了平台生成的三维模型的：模型播放能力、与模型进行互动的能力、以及标签标注能力。整个SDK分为PanoramaScenePlayer和PanoramaSceneEdtior两部分：

PanoramaScenePlayer提供了基本模型加载，模型交互（如场景漫游，飞入标签，多视图切换，事件监听等能力）
PanoramaSceneEditor继承了PanoramaScenePlayer对象，该对象除了提供模型加载，模型交互，还提供了标签编辑的能力，可以跟进API进行标签创建、标签删除、标签修改等操作。

该SDK与框架无关，您可在React框架中使用，也可嵌入到Angular\Vue等任何框架中使用。本文档将以嵌入React的方式演示如何利用该SDK加载三维模型以及如何与三维模型进行交互

2. 关键术语

模型: 用户将全景照片上传到三维重建(TDSR)平台，利用平台的模型重建能力创造出来的模型；用户可以通过3D交互的方式查看该模型的结构。也可以飞入到模型中以全景视角产看场景。
场景: 场景跟模型是一一对应的
子场景: 与平台子场景含义相同，一张全景图即一个子场景，用户可以在不同子场景进行漫游。
三维模式：传说中的“上帝视角“，在该模式下，用户可以较清晰看到模型结构，以及各个子场景之间的关联关系
全景模式: 子场景模型，可通过鼠标点击/SDK提供的API的操作实现场景间切换从而实现场景漫游
标签：SDK允许在编辑模式下进行图像的标注，标注后会一标签的形势存在，目前支持标注模式有图片，图像，文本，链接。

3. 快速上手

3.1 PanoramaScenePlayer 快速上手

初始化PlayerService对象, 该对象封装了前后端通信的能力，详见下一章节。这里在快速上手模块，我们先使用Mock Data能力测试

    const service = new PanoramaScenePlayerService();
    service.registerFetch(utils.mock) // NOTICE: 本地mock测试，线上不要使用

初始化播放器对象

    const player = new PanoramaScenePlayer(target.current, {
      service: service,
      mode: 'Online', // 如果想预览未发布的Tag, mode设置未Preview
    });

模型加载

await player.load(token);

基于React的完整代码如下：

import React, { Component } from 'react';
import ReactDOM from 'react-dom';
import { PanoramaScenePlayer, PanoramaScenePlayerService, utils, DefaultSceneData } from 'alibabacloud-tdsr-js-sdk';


/**
 * 加载模型
 * @param {string} token
 * @param {HTMLDivElement} target
 */
function usePlayer(token, target) {
  const init = async () => {
    const service = new PanoramaScenePlayerService();
    service.registerFetch(utils.mock) // NOTICE: 本地mock测试，线上不要使用
    const player = new PanoramaScenePlayer(target.current, {
      service: service,
      mode: '1', // 如果想预览未发布的Tag, mode设置未Preview
    });
    await player.load(token);
  };
  React.useEffect(() => {
    init();
  }, [token]);
}

function Player(props) {
  const token = '58b51071d0a446318607443bd2135d74';
  const target = React.useRef();
  usePlayer(token, target);
  const style = {
    width: '100%',
    height: 450,
    position: 'relative'
  };
  return (
    <div ref={target} style={style} />
  );
}

ReactDOM.render((
  <Player />
), mountNode);

3.2 PanoramaScenePlayer

初始化PanoramaSceneEditorService对象, 该对象封装了前后端通信的能力，详见下一章节。这里在快速上手模块，我们先使用Mock Data能力测试

    const service = new PanoramaSceneEditorService();
    service.registerFetch(utils.mock) // NOTICE: 本地mock测试，线上不要使用

初始化播放器对象

    const editor = new PanoramaSceneEditor(target.current, {
      service,
      autoSave: false,
    });

模型加载

await editor.load(token);

基于React的完整代码如下：

import React, { Component } from 'react';
import ReactDOM from 'react-dom';
import merge from 'lodash/merge';

import { PanoramaSceneEditor, PanoramaSceneEditorService, utils, DefaultSceneData } from 'alibabacloud-tdsr-js-sdk';

/**
 * 加载模型
 * @param {string} token
 * @param {HTMLDivElement} target
 */
function useEditor(token, target) {
  const init = async () => {
    const service = new PanoramaSceneEditorService();
    service.registerFetch(utils.mock) // NOTICE: 本地mock测试，线上不要使用

    const editor = new PanoramaSceneEditor(target.current, {
      service,
      autoSave: false,
    });

    await editor.load(token);
  };
  React.useEffect(() => {
    init();
  }, [token]);
}

function Editor(props) {
  const token = 'f9d19ae0541f4131bb787d8a4521d46d';
  const target = React.useRef();
  useEditor(token, target)
  const style = {
    width: '100%',
    height: 450,
    position: 'relative'
  };
  return (
    <div>
      <div ref={target} style={style} />
    </div>
  );
}

ReactDOM.render((
  <Editor />
), mountNode);

4. 通信

SDK需要依赖后端接口进行模型的加载以及标签的增删改查，考虑到安全性，需要业务方对依赖接口进行转发，其架构如下图。三维重建服务端把依赖的后端接口通过Open API的方式开放给业务方，业务方可以通过Open API SDK方式与这些接口进行交互，并通过WEB API方式转发给WEB端的播放器。播放器通过转发后的API实现三维重建服务端通信, 又能保证其安全性，以及各平台兼容性。PanoramaScenePlayerService、PanoramaSceneEditorService对象封装了通信能力，开发者可以通过 const service = new PanoramaSceneEditorService(); 和 const service = new PanoramaSceneEditorService(); `的方式创建该对象。

Mock：为了方便开发者进行本地调试，PanoramaScenePlayerService、PanoramaSceneEditorService提供了Mock数据的能力，开发者在开发前期可以通过如下的方式加载Mock数据进行本地开发

service.registerFetch(utils.mock) // NOTICE: 本地mock测试，线上不要使用

协议适配: 考虑到不同业务方前后端通信协议会有较大差异，PanoramaScenePlayerService、PanoramaSceneEditorService开发了协议转换的能力，用户可以通过registerHook接口进行协议转换。比如以下Code给URL增加前缀，同时对返回结果进行适配

service.registerHook({
	async request(method, url, data, header) {
    const prefix = '/biz'
    return [`${prefix}${url}`, data, header];
  },
  async response(result, context) {
    return {
      code: result.errorCode,
      success: result.errorCode == 0,
      message: result.errorMessage,
      data: result.data
  }
});

具体接口参数参考 /documents/interfaces/services_basicpanoramasceneservice.hook.md

5. Panorama Scene Player

PanoramaScenePlayer对象提供了基本模型加载，模型交互（如场景漫游，飞入标签，多视图切换，事件监听等能力）

5.1 Constructor

constructor(target: HTMLDivElement, protected config: IPanoramaScenePlayerConfig)

target: Player的DOM容器
config
- service: 前后端通信对象，见 4. 通信章节内容
- mode: Player的模式，支持 Preview = '2', Online = '1', 其中Preview加载已经创建，但是还没有发布的标签和已经发布的标签；Online只会加载已经发布的标签
- view: DollHouse(3D模式)\Panorama(全景模式), 默认为DollHouse模式

5.2 Load/Unload

async load(previewToken: string)

加载模型，previewToken为模型的唯一标示，可以通过OPEN API提供的接口获得，详见后端SDK

 async unload()

卸载模型

5.3 事件

注册播放器事件

registerSceneHook(hooks: IBasicPanoramaScenePlayerHooks)

hooks.onLoad: () => void; 加载完成事件
hooks.onChangeView: (type: EnumPanoramaSceneView) => void; 切换全景/3D模式事件
hooks.onChangePanorama: (panoId: string) => void; 切换子场景事件
hooks.onOrbitRotate: (quanertion: TypeQuaternion) => void; 场景旋转, 目前暂不支持三维空间旋转

注册标签事件

registerTagHook(hooks: IPanoramaScenePlayerTagHooks)

hooks.onClick: (tag: ICombinedTag) => void; 点击标签事件
hooks.onUpdatePositions: (tag: ICombinedTagWithScenePosition[]) => void; 触发标签位置更新事件

5.4 API

player.getTagList() 获得所有标签
player.getTagListByPanoramaId(panoId) 获得当前子场景下标签
player.getPanoramaList() 获得所有子场景
player.changeView(view) 切换视图，支持DollHouse(3D模式)\Panorama(全景模式),
player.flyToPanoramaById(panoId) 跳转到指定子场景
player.hideTag() 隐藏标签
player.showTag() 显示标签
player.flyToTag(tagId) 跳转到指定标签位置
player.getTagClientPosition(tagId) 获得Tag的屏幕坐标
player.getCurrentPanorama() 获得当前子场景，若在Dollhouse(3D)模式下，返回为undefined
player.isTagInViewScene(tagId) 判断标签是否当前视口可见
player.getRotateQuaternion() 获得当前场景旋转四元组
player.setRotateQuaternion(quaternion) 设置当前场景的旋转四元组

6. Panorama Scene Editor

PanoramaSceneEditor继承了PanoramaScenePlayer对象，该对象除了提供模型加载，模型交互，还提供了标签编辑的能力，可以跟进API进行标签创建、标签删除、标签修改等操作。

6.1 Constructor

constructor(target: HTMLDivElement, protected config: IPanoramaSceneEditorConfig)

target: Player的DOM容器
config
- service: 前后端通信对象，见 4. 通信章节内容
- autoSave: 是否自动保存TAG, 若autoSave为true, 模型创建、模型取消选中、模型更新、模型拖拽、
- view: DollHouse(3D模式)\Panorama(全景模式), 默认为DollHouse模式

6.2 Load/UnLoad

见 5.2

6.3 事件

注册播放器事件见 5.3.1 注册播放器事件
注册标签事件

registerTagHook(hooks: IPanoramaSceneEditorTagHooks)

hooks.onSelected: (tag: ICombinedTag) => boolean; 标签选中事件
hooks.onWillUnselected: (tag: ICombinedTag) => boolean; 标签取消选中事件
hooks.onCreating: () => ICombinedTag; 创建标签事件
hooks.onCreated: (tag: ICombinedTag) => void; 标签创建完成事件
hooks.onUpdatePositions: (tag: ICombinedTagWithScenePosition[]) => void; 标签位置更新事件
hooks.onDragStart: (tag: ICombinedTag) => void; 标签拖拽事件
hooks.onDragStop: (tag: ICombinedTag) => void; 标签拖拽事件
hooks.onDragging: (tag: ICombinedTag) => void; 标签拖拽事件

6.4 API

PanoramaSceneEditor继承了PanoramaScenePlayer所有API除此之外，PanoramaSceneEditor还提供了跟标签编辑有关的API

6.4.1 创建标签
- 通过注册onCreating事件回填标签内容

editor.registerTagHook({
	 onCreating: () => {
     const tag = {
      type: "IMAGE",
        config: {
          backgroundColor: "#000",
          images: [
            "http://s.alicdn.com/@lyj/pano_src/100070-82766/hotspot/image/4bbc-06439_LD.png",
          ],
          title: "60152892558",
          formSelectImgType: "mural",
        },
      };
      return tag;
    }, // 右箭创建标签
});

通过 createTagInView(position?: { x: number, y: number }) 接口创建标签，默认在视口中心创建

editor.createTagInView()

另外也支持通过鼠标点击方式在指定位置创建标签，开启鼠标点击交互能力

editor.setState(EnumIPanoramaSceneEditorState.ROMA) //漫游, 默认状态，允许用户进行场景漫游，场景旋转等操作
editor.setState(EnumIPanoramaSceneEditorState.EDIT) // 编辑, 允许用户创建TAG
const state = editor.getState() // 获得当前播放器状态