后浪云百度小程序教程：modelviewer VR 3D 模型-beta

2022-5-23
  • modelviewer VR 3D 模型-beta
    • 使用方法
      • 1. 在项目中引用动态库
      • 2. 在使用到模型组件的页面配置动态库
      • 3. 编写 *.swan 文件
    • 动态库配置文件详细说明
      • 动态库属性列表
      • 总配置
      • 相机配置
      • 场景配置
      • 全景设置
      • 动画设置
      • 光照设置
      • 热点配置

    modelviewer VR 3D 模型-beta

    modelviewer 动态库提供了在小程序中展示 3D 模型功能，底层基于百度 webVR SDK Hydreigon 实现。

    使用方法

    1. 在项目中引用动态库

    使用动态库的方法参见小程序文档使用动态库，在app.json中增添一项dynamicLib，与pages同级。

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

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

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

    • JSON
     
 
 
      
  
  
  
    1. {
      2. 
  
  
  
    2.  "usingSwanComponents": {
      3. 
  
  
  
    3.  "modelviewer": "dynamicLib://myModelviewer/modelviewer"
      4. 
  
  
  
    4.  }
      5. 
  
  
  
    5. }
      6.

    3. 编写 *.swan 文件

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

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

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

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

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

    动态库配置文件详细说明

    动态库属性列表

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

    属性名称 类型 说明
    option Object 配置项，参见上方参数说明列表

    总配置

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

    相机配置

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

    场景配置

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

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

    全景设置

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

    动画设置

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

    属性名称 必填 默认值 说明
    startAt 否 0
    duration 否 Infinity

    光照设置

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

    锥形光

    属性名称 必填 默认值 说明
    type 是 SpotLight type 必须为 SpotLight
    params.color 否 0xffffff 颜色值，可以为数字，也可以为#开头的字符串，如#FFFFFF，也可以为颜色英文名称，如white
    params.intensity 否 1 光照强度
    params.position 否 [1, 1, 1] 光源的位置，数组长度为 3 ，对应 x，y，z 坐标
    distance 否 0 光的最远照射距离。0：无穷远
    angle 否 1.57 设置锥角弧度大小
    decay 否 1 衰减率。离光越远，光照强度越弱。1：不衰减。取值为 0 到 1 之间

    平行光

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

    环境光

    属性名称 必填 默认值 说明
    type 是 DirectionalLight type 必须为 AmbientLight
    params.color 否 0xffffff 颜色值，可以为数字，也可以为#开头的字符串，如#FFFFFF，也可以为颜色英文名称，如white
    params.intensity 否 1 光照强度

    热点配置

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

    属性名称 必填 默认值 说明
    text 是 用于热点显示的文本
    position 是 热点相对于 3D 场景挂载的模型节点的位置，数组长度为 3 ，对应 x，y，z 坐标
    parentName 是 热点所挂载的模型节点的网格或组的名称
    events 是 {} 用于配置热点的交互。如果是{}则不会出现任何交互操作
    events.click 否 events 可以设置一些交互操作名称，例如 click ，则交互操作在 click 事件触发
    events.click.type 是 取值为 highlight 或者 jump ，分别对应模型高度操作以及场景跳转操作
    events.click.color 否 [1,1,1] 模型高亮的颜色，采用的是和着色器的颜色取值，必须是 0 到 1 之间的数字
    events.click.duration 否 1000 模型高亮是一种呼吸灯的忽明忽暗效果，这个是亮变暗的时间
    events.click.times 否 Infinity 呼吸灯高亮次数
    版权声明：
    作者：后浪云
    链接：https://www.idc.net/help/186069/
    文章版权归作者所有，未经允许请勿转载。
    THE END
    IDC.NET智能小程序后浪云百度小程序
    Copyright © 2025 后浪云 网站地图