modelviewer 动态库-Beta

modelviewer 动态库提供了在小程序中展示 3D 模型功能,底层基于百度webVR SDK Hydreigonmodelviewer 动态库-Beta - 图1 实现。

使用方法

1. 在项目中引用动态库

使用动态库的方法参见小程序文档:使用动态库modelviewer 动态库-Beta - 图2,在 app.json 中增添一项 dynamicLib,与 pages 同级。

  1. "dynamicLib": {
  2. "myModelviewer": {
  3. "provider": "modelviewer"
  4. }
  5. },

2. 在使用到模型组件的页面配置动态库

在每个使用到模型组件的页面,配置 *.json 文件如:

  1. {
  2. "usingSwanComponents": {
  3. "modelviewer": "dynamicLib://myDynamicLib/modelviewer"
  4. }
  5. }

3. 编写 *.swan 文件

  1. <modelviewer option="{{ option }}" style="width: 100%; height: 500px; display: block"></modelviewer>

这是一种最基本的配置方式。style 也可以在 .css 中声明,需要保证 <modelviewer> 是有宽度和高度的。option.js 中绑定到页面的 data 中:

  1. const option = ...;
  2. Page({
  3. data: {
  4. option: option
  5. }
  6. });

其中,option 是一个模型展示配置项,定义了模型应该如何展示,示例如下:

  1. option = {
  2. "autoStart": true,
  3. "parent": "body",
  4. "backgroundImage": "https://bj.bcebos.com/v1/hydreigon-dev/sdk-dev/dist/assets/bg.jpg",
  5. "camera": {
  6. "fov": "65",
  7. "position": [
  8. 0,
  9. 0,
  10. 0
  11. ],
  12. "near": 1,
  13. "far": 10000
  14. },
  15. "scenes": [
  16. {
  17. "pano": {
  18. "url": "https://bj.bcebos.com/v1/hydreigon-dev/sdk-dev/dist/assets/model/bio/skybox.jpg",
  19. "radius": 800,
  20. "rotation": 0,
  21. "position": [0, 0, -0]
  22. },
  23. "scale": 1,
  24. "animationSettings": {
  25. "111": {
  26. "startAt": 0,
  27. "duration": 3.6
  28. }
  29. },
  30. "lights": [
  31. {
  32. "type": "AmbientLight",
  33. "params": {
  34. "color": 16777215,
  35. "intensity": 1
  36. }
  37. },
  38. {
  39. "type": "DirectionalLight",
  40. "params": {
  41. "color": 16777215,
  42. "intensity": 1,
  43. "position": [
  44. 1,
  45. 1,
  46. 1
  47. ]
  48. }
  49. },
  50. {
  51. "type": "SpotLight",
  52. "params": {
  53. "color": 16777215,
  54. "intensity": 1,
  55. "position": [
  56. 1,
  57. 1,
  58. 1
  59. ],
  60. "distance": 0,
  61. "angle": 1.57,
  62. "penumbra": 0.5,
  63. "decay": 1
  64. }
  65. }
  66. ],
  67. "backgroundImage": "https://bj.bcebos.com/v1/hydreigon-dev/sdk-dev/dist/assets/bg.jpg",
  68. "autoPlayAnimation": "111",
  69. "showLabels": false,
  70. "url": "https://hydreigon-publish.bj.bcebos.com/swan-hydreigon/model/new_robot/scene.gltf",
  71. "bg": "https://bj.bcebos.com/v1/hydreigon-dev/sdk-dev/dist/assets/bg.jpg",
  72. "offset": [
  73. 0,
  74. -25,
  75. 0
  76. ],
  77. "hotspots": [
  78. {
  79. "text": "右上臂",
  80. "position": [
  81. -0.7,
  82. 1.2,
  83. 0
  84. ],
  85. "parentName": "右上臂",
  86. "events": {
  87. "click": {
  88. "type": "highlight",
  89. "color": [
  90. 0.096,
  91. 0.359,
  92. 0.757
  93. ],
  94. "duration": 1000,
  95. "times": 3
  96. }
  97. }
  98. },
  99. {
  100. "text": "左下臂",
  101. "position": [
  102. 0.7,
  103. 0.6,
  104. 0
  105. ],
  106. "parentName": "左下臂",
  107. "events": {
  108. "click": {
  109. "type": "highlight",
  110. "color": [
  111. 0.096,
  112. 0.359,
  113. 0.757
  114. ],
  115. "duration": 1000,
  116. "times": 3
  117. }
  118. }
  119. },
  120. {
  121. "text": "膝盖",
  122. "position": [
  123. 0,
  124. 0.5,
  125. 0
  126. ],
  127. "parentName": "膝盖",
  128. "events": {
  129. "click": {
  130. "type": "highlight",
  131. "color": [
  132. 0.096,
  133. 0.359,
  134. 0.757
  135. ],
  136. "duration": 1000,
  137. "times": 3
  138. }
  139. }
  140. }
  141. ]
  142. }
  143. ]
  144. };

动态库配置文件详细说明

动态库属性列表

<modelviewer> 上支持的属性包括:

属性名称类型说明
optionObject配置项,参见上方参数说明列表

总配置

属性名称必填默认值说明
autoStarttrue是否
parent"body"父级容器的dom元素匹配css表达式
backgroundImage""设置全局2D背景图,该背景图设置全局有效,可被scene的配置覆盖
camera设置相机配置参数,具体设置请看camera配置表
scenes设置场景配置参数,可以配置任意数量的场景,可以通过热点进行场景切换。所有的场景只会在用到时加载自己所需资源。且在切换为新场景时,旧场景不会被销毁,从而再次进入旧场景则可以直接展示,无需用户等待。

相机配置

属性名称必填默认值说明
fov65调整透视相机fov
position{x: 0, y:0, z:0}相机初始位置坐标
near1调整相机近截面距离
far10000调整相机远截面距离

场景配置

场景是一个数组,每个数组元素都是独立的场景

属性名称必填默认值说明
panonull全景设置。该全景图会出现在场景里面,会覆盖2D背景图。
scale1模型缩放。
animationsnull用于额外修改模型动画默认参数的配置。详见动画配置
lightsnull用于设置光照,是个数组,可以配置任意数量和不同类型的光照。如果不配置则会SDK默认添加一组光照。详见光照配置
backgroundImagenull图片的url。用于设置该场景的2D背景图,该设置填写之后会覆盖全局配置
autoPlayAnimationnull是否进入该场景之后自动播放某个名称的动画
showLabelsfalse是否进入该场景后自动显示所有热点
url模型的url。为了提高展示性能以及缩短用户的等待时间,SDK只支持gltf和glb格式。并且推荐开发者的模型进行draco编码压缩。
offset{x: 0, y:0, z:0}模型默认位置的偏移量。由于绝大部分情况模型建模的原点在模型的底部,从而在展示的时候总是偏向于上方。为了更好的用户体验通常需要模型居中展示,通过次参数进行调整
hotspots[]可以配置任意数量的热点进行一些交互操作。具体的参数设置参见热点配置表

全景设置

属性名称必填默认值说明
url""如果设置则会创建球面全景图
radius800设置全景图球体的半径
rotation0全景图球体在y轴上的旋转弧度
position[0, 0, -0]全景图的位置偏移,数组长度为3,对应x,y,z坐标

动画设置

动画配置为键值对形式,通常情况无需配置,只有对某些动画需要额外处理的时候才需要配置。其中key为某个动画的名称,其value值说明如下

属性名称必填默认值说明
startAt0
durationInfinity

光照设置

光照设置是个数组,可以设置点锥形源,平行光,环境光。不同的光有不同的配置参数。如下所示:

锥形光:

属性名称必填默认值说明
typeSpotLighttype必须为SpotLight
params.color0xffffff颜色值,可以为数字,也可以为#开头的字符串,如“#FFFFFF”,也可以为颜色英文名称,如"white"
params.intensity1光照强度
params.position[1, 1, 1]光源的位置,数组长度为3,对应x,y,z坐标
distance0光的最远照射距离,0表示无穷远
angle1.57设置锥角弧度大小
decay1衰减率。离光越远,光照强度越弱。1为不衰减。取值为0到1之间

平行光:

属性名称必填默认值说明
typeDirectionalLighttype必须为DirectionalLight
params.color0xffffff颜色值,可以为数字,也可以为#开头的字符串,如“#FFFFFF”,也可以为颜色英文名称,如"white"
params.intensity1光照强度
params.position[1, 1, 1]光源的位置,数组长度为3,对应x,y,z坐标

环境光:

属性名称必填默认值说明
typeDirectionalLighttype必须为AmbientLight
params.color0xffffff颜色值,可以为数字,也可以为#开头的字符串,如“#FFFFFF”,也可以为颜色英文名称,如"white"
params.intensity1光照强度

热点配置

热点目前支持2种交互操作,一种是模型部位的高亮。一种是场景的切换跳转。整个的热点配置是个数组,数组的每个元素对应一个热点。热点是dom元素而非WebGL绘制,因此热点始终会比模型的层级更高。具体配置如下。

属性名称必填默认值说明
text用于热点显示的文本
position热点相对于3D场景挂载的模型节点的位置,数组长度为3,对应x,y,z坐标
parentName热点所挂载的模型节点的网格或组的名称
events{}用于配置热点的交互。如果是{}则不会出现任何交互操作
events.clickevents可以设置一些交互操作名称,例如click,则交互操作在click事件触发。
events.click.type取值为highlight或者jump,分别对应模型高度操作以及场景跳转操作。
events.click.color[1,1,1]模型高亮的颜色,采用的是和着色器的颜色取值,必须是0到1之间的数字
events.click.duration1000模型高亮是一种呼吸灯的忽明忽暗效果,这个是亮变暗的时间
events.click.timesInfinity呼吸灯高亮次数