Skip to content

wangerzi/modelbox-sdk

Repository files navigation

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

GIF

版本发布记录

注:请尽量使用最新版本的 SDK,避免隐性 BUG

版本 发布时间 CDN地址 备注
v1.0.7 2021-02-28 20:37 https://preview.mobox3d.com/modelbox-sdk/1.0.7/modelbox-sdk.js 修复bug优化体验
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场景编辑器的 交互及体验
  • 【优化】 模型转换 速度
  • 【优化】 模型转换结果缓存 以优化整体转换速度

模型处理及渲染流程

大致流程如下所示,前端仅需上传文件,然后等待模型处理完成即可,后端会自动做 压缩包解压转换模型压缩上传分发 等一系列工作

GIF

使用交流&BUG反馈

请扫描群二维码或搜索群号 『 555876154 』加群,如需商用部署请加群或直接联系 [email protected]

GIF

使用方法

方式一: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