modelbox-sdk
v1.0.7
Published
modelbox npm sdk.
Readme
Modelbox Browser SDK
此SDK用于简化 Modelbox 模型API的调用，仅需前端传入模型文件即可实现嵌入式的模型预览，支持 OBJ/FBX/GLTF/STL/STEP/IGES
码云地址：https://gitee.com/wangerzi/modelbox-sdk
Github地址：https://github.com/wangerzi/modelbox-sdk
npm package：https://www.npmjs.com/package/modelbox-sdk
Demo地址：https://wangerzi.gitee.io/modelbox-sdk/examples/index.html
版本发布记录
注：请尽量使用最新版本的 SDK，避免隐性 BUG
| 版本 | 发布时间 | CDN地址 | 备注 | | ------ | ---------------- | ------------------------------------------------------------ | ------------------------------ | | v1.0.6 | 2020-11-11 23:44 | https://preview.mobox3d.com/modelbox-sdk/1.0.6/modelbox-sdk.js | 更新文档优化并npm包大小 | | v1.0.5 | 2020-11-09 22:40 | https://preview.mobox3d.com/modelbox-sdk/1.0.5/modelbox-sdk.js | 全体接口https | | v1.0.4 | 2020-11-09 13:39 | https://preview.mobox3d.com/modelbox-sdk/1.0.4/modelbox-sdk.js | 修复 config 为空的问题 | | v1.0.3 | 2020-11-09 00:39 | https://preview.mobox3d.com/modelbox-sdk/1.0.3/modelbox-sdk.js | 最初版本，实现基本上传预览功能 |
已支持的能力
- 极简的 SDK 调用，仅需要传入用户选择的文件即可嵌入3D模型展示
- 多种模型类型支持，包括 OBJ/FBX/GLTF/STL/STEP/IGES
- 支持 模型压缩 ，数 Mb 的 STL 压缩到数百 Kb，更适合 Web 场景的跨平台展示
- 利用 CDN 边缘节点 的能力，加速对模型资源的上传和下载分发
- 支持 3d场景编辑器 中的全部能力，包括 模型渲染、视角控制、环境HDR、光照、动画 等
待实现的能力
- [ ] 【增强】场景编辑器 配置导出
- [ ] 【增强】支持修改已上传模型的 场景配置
- [ ] 【增强】支持模型视角切换、 X/Y/Z剖面
- [ ] 【增强】支持模型 图片纹理压缩
- [ ] 【增强】支持模型 尺寸测量、体积、表面积测量
- [ ] 【增强】支持场景编辑器中的 模型变换、组合、相机配置 等
- [ ] 【优化】场景中
- [ ] 【优化】 模型加载 等待、模型转换等待交互
- [ ] 【优化】 3D场景编辑器的 交互及体验
- [ ] 【优化】 模型转换 速度
- [ ] 【优化】 模型转换结果缓存 以优化整体转换速度
模型处理及渲染流程
大致流程如下所示，前端仅需上传文件，然后等待模型处理完成即可，后端会自动做 压缩包解压、转换、模型压缩、上传分发 等一系列工作
使用交流&BUG反馈
请扫描群二维码或搜索群号 『 555876154 』加群
使用方法
方式一：npm引入
npm install modelbox-sdk然后使用模块化的加载方式得到 SDK 对象
import MODELBOX_SDK from 'modelbox-sdk'方式二：script标签引入
可通过 CDN 的方式引用： https://preview.mobox3d.com/modelbox-sdk/1.0.5/modelbox-sdk.js ，或者下载到本地，使用 script 的方式引用即可得到 MODELBOX_SDK 全局对象
<script src="https://preview.mobox3d.com/modelbox-sdk/1.0.5/modelbox-sdk.js"></script>初始化
这里的 token 仅供测试，并不保证稳定性，如有企业需求请联系 [email protected]
MODELBOX_SDK.updateToken('5c06b6b8a548d8911e3ccdbdc518fac6');上传模型
注意：上传的文件不应该超过 100M
MODELBOX_SDK.uploadModel(file, type, config, modelConfig, function() {}, function() {} );| 参数名称 | 类型 | 备注 | | ----------- | -------- | ------------------------------------------------------------ | | file | File | 上传的单个文件对象 | | type | string | stl/stp/igs/fbx/obj/gltf，不同类型对应不同的可上传文件后缀 | | config | object | .name: 模型名称，.comment: 模型备注（预留参数，用于展示） | | modelConfig | object | 一些配置，能够完成 3d场景编辑器 上的所有效果配置，详情请参见#可选配置参数 | | success | callback | 调用成功触发此函数回调，处理成功后触发，第一个参数为响应的数据，包含嵌入式网页URL，编辑器URL，原始资源下载URL | | error | callback | 调用失败触发此函数回调，第一个参数为错误原因的字符串 |
上传模型支持文件类型如下表所示：
| 模型类型 | 支持类型 | | -------- | --------------- | | stl | .stl/.zip | | stp | .stp/.step/.zip | | igs | .igs/.iges/.zip | | fbx | .fbx/.zip | | obj | .obj/.zip | | gltf | .gltf/.glb/.zip |
示例代码如下：
// 使用 DOM API 获取到 file 对象
var file = form.querySelector('input[type="file"]');
// 将选择的 File 对象传入到 SDK 中，比如这里使用了第一个文件，索引为 0
MODELBOX_SDK.uploadModel({
file: file.files[0],
type: 'stl',
config: {
'name': name,
'comment': comment,
},
modelConfig: config,
success: function (res) {
layui.layer.close(layerIndex);
// res.iframe_url 表示嵌入网页的 url
// res.editor_url 表示编辑器网页 url
// res.source_file_url 表示源资源的下载 url
console.log(res);
},
error: function (msg) {
console.error(msg); // 错误信息
},
}); 查看模型
在上传的时候，保存好嵌入网页的url（参数：res.iframe_url）即可，使用 iframe 标签进行页面嵌入
<iframe src="https://preview.mobox3d.com/index.html#/PreviewModel/EAAYIrBA" width="600" height="400"></iframe>可选配置参数
在上传模型的接口有一个 modelConfig ，可以针对 3d场景编辑器 中的所有参数进行初始化（实时编辑功能正在骑马来的路上，参数配置生成器也在骑马来的路上）
可配置参数分为 模型渲染、视角控制、环境HDR、光照、动画 几个模块，分别对应如下几个大的配置参数
| 模块名称 | 对应配置key | | -------- | ----------- | | 模型渲染 | render | | 视角控制 | control | | 环境HDR | environment | | 光照 | lights | | 动画 | animate |
所以整个modelConfig的配置结构大体如下：
var modelConfig = {
render: {...},
control: {...},
environment: {...},
lights: {...},
animate: {...},
};
// 然后作为参数传到 SDK 中
MODELBOX_SDK.uploadModel(file, type, config, modelConfig, function() {}, function() {} );！！！ 注意：如下的配置可能有点复杂，在 实时配置生成器实现之前想要达到指定的渲染效果会比较费时间 ，如有紧急或特殊需求还请先进群或者邮件我 ！！！
render - 模型渲染配置
此模块主要控制模型场景的整体渲染效果，比如抗锯齿、色调映射、输出编码器等，其 默认配置如下：
var defaultRenderConfig = {
// webgl 的配置
glConfig: {
antialias: true, // 抗锯齿
alpha: true, // 是否包含透明缓冲区
logarithmicDepthBuffer: true, // 是否启用深度缓冲区（可能导致性能下降）
toneMapping: 0, // 色调映射，影响效果
toneMappingExposure: 0.75, // 色调映射强度调整
},
// 外部的渲染配置
outputEncoding: 3001,
gammaFactor: 2,
};control - 视角控制配置
此模块主要用于控制模型展示视角及初始配置参数，包括自由视角、锁定视角等，其默认配置如下：
var defualtControlConfig = {
type: CONTROL_TYPE_LOCK,
TrackballControls: { // 自由视角
dynamicDampingFactor: 0.12, // 阻尼强度
panSpeed: 0.3, // 平移速度
rotateSpeed: 1.5, // 旋转速度
noPan: false, // 禁止平移
noRotate: false, // 禁止旋转
noZoom: false, // 禁止缩放
zoomSpeed: 1.2, // 缩放速度
maxDistance: 9999999, // 最大距离
minDistance: 0, // 最小距离
},
OrbitControls: { // 锁定视角
enabled: true, // 允许操作
autoRotate: false, // 自动旋转
autoRotateSpeed: 2.0, // 自动旋转速度
enableDamping: true, // 允许阻尼运动
dampingFactor: 0.2, // 阻尼运动参数，越小惯性越明显
enablePan: true, // 允许平移
enableRotate: true, // 允许旋转
enableZoom: true, // 允许缩放
maxDistance: 9999999, // 最大距离
minDistance: 0, // 最小距离
minPolarAngle: -Math.PI, // 最小可查看角度
maxPolarAngle: Math.PI, // 最大可查看角度
minAzimuthAngle: -2 * Math.PI, // 最小水平旋转角度
maxAzimuthAngle: 2 * Math.PI, // 最大水平旋转角度
maxZoom: 9999999, // 最大放多远
minZoom: 0, // 最小放多远
zoomSpeed: 1, // 缩放速率
},
}environment - 环境HDR
这个部分主要用于控制环境光照和模型背景，支持 HDR、环绕图片、颜色背景，其默认参数如下：
var defaultEnvironmentConfig = {
type: 'background', // 类型
background: '#dddddd', // 背景色配置
hdr: '/static/resources/venice_sunset_1k.hdr', // 日落
env: '/static/resources/textures/Park3Med/', // 雪地
sky: {
scalar: 450000,
effectControl: {
turbidity: 10,
rayleigh: 2,
mieCoefficient: 0.005,
mieDirectionalG: 0.8,
luminance: 1,
inclination: 0.49, // elevation / inclination
azimuth: 0.25, // Facing front,
sun: true,
},
}
}lights - 光照
这个模块的配置用于控制光照，支持环境光、点光源、平行光、全局光，以及未来会增加更多的可配置项，其默认参数如下：
注：如下参数的意思是，配置五个平行光，方向分别是 (1, 1, 1)，(-1, 1, 1)，(1, 1, -1)，(-1, 1, -1)，(0, -1, 0)，如果用点光源，type 设置为点光源('piont') 并且映射每个灯光中的 point 参数，环境光(hemisphere)，全局光照(ambient) 同理
如下 配置中的 intensity 均为光强的意思，一般从 0 ~ 1，数值越大光照强度越大。
var defaultLightsConfig = {
lights: [
{
type: 'directional',
status: true,
ambient: {
color: '#ffffff',
intensity: 1,
},
point: {
color: '#ffffff',
intensity: 1,
distance: 0,
decay: 2,
position: {
x: 0,
y: 0,
z: 0,
},
},
directional: {
color: '#ffffff',
intensity: 1,
position: {
x: 1,
y: 1,
z: 1,
},
},
hemisphere: {
skyColor: '#ffffff',
groundColor: '#000000',
intensity: 0.6,
},
},
{
type: 'directional',
status: true,
ambient: {
color: '#ffffff',
intensity: 1,
},
point: {
color: '#ffffff',
intensity: 1,
distance: 0,
decay: 2,
position: {
x: 0,
y: 0,
z: 0,
},
},
directional: {
color: '#ffffff',
intensity: 1,
position: {
x: -1,
y: 1,
z: 1,
},
},
hemisphere: {
skyColor: '#ffffff',
groundColor: '#000000',
intensity: 0.6,
},
},
{
type: 'directional',
status: true,
ambient: {
color: '#ffffff',
intensity: 1,
},
point: {
color: '#ffffff',
intensity: 1,
distance: 0,
decay: 2,
position: {
x: 0,
y: 0,
z: 0,
},
},
directional: {
color: '#ffffff',
intensity: 1,
position: {
x: 1,
y: 1,
z: -1,
},
},
hemisphere: {
skyColor: '#ffffff',
groundColor: '#000000',
intensity: 0.6,
},
},
{
type: 'directional',
status: true,
ambient: {
color: '#ffffff',
intensity: 1,
},
point: {
color: '#ffffff',
intensity: 1,
distance: 0,
decay: 2,
position: {
x: 0,
y: 0,
z: 0,
},
},
directional: {
color: '#ffffff',
intensity: 1,
position: {
x: -1,
y: 1,
z: -1,
},
},
hemisphere: {
skyColor: '#ffffff',
groundColor: '#000000',
intensity: 0.6,
},
},
{
type: 'directional',
status: true,
ambient: {
color: '#ffffff',
intensity: 1,
},
point: {
color: '#ffffff',
intensity: 1,
distance: 0,
decay: 2,
position: {
x: 0,
y: 0,
z: 0,
},
},
directional: {
color: '#ffffff',
intensity: 1,
position: {
x: 0,
y: -1,
z: 0,
},
},
hemisphere: {
skyColor: '#ffffff',
groundColor: '#000000',
intensity: 0.6,
},
},
],
}animate - 动画
这个模块的配置用于播放指定的、烘焙好的动画，目前的 3D格式内，带有动画信息的格式为 FBX/GLTF，部分 FBX 由于会被转换为 GLTF，动画播放可能有异常，需与模型师多次沟通尝试，动画模块配置如下：
注：index 表示播放第几个动画
var defaultAnimateConfig = {
index: 0,
};LICENCE
MIT