高级功能
EverAPI 的构造函数具有 3 个参数,其中参数 config
用于高级功能配置,各配置项说明如下:
总体配置
提示:
width 以及 height 配置已废弃, 可以使用 CSS 控制 HTML 中 API 的容器的大小,API 窗口会自适应
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
lang | String | 'zh' | 默认文字语言 |
scale | Number | 1 | 默认缩放大小 |
renderMode | String | 'flatlines' | 可选值'flatlines','flat','wireframe' |
sceneType | String | 'default' | 可选值'default','ceram' |
viewType | String | 'evercraft' | 可选值'evercraft','alias' |
highlightedOnClick | Boolean | true | 点击是否高亮 |
cache | Object | 见表 Cache 配置 | 缓存功能配置 |
progress | Object | 见表 Progress 配置 | 进度条的配置 |
background | Object | 见表 Backgroud 配置 | canvas 背景配置 |
toolbar | Object | 见表 Toolbar 配置 | 工具条配置 |
logo | Object | 见表 Logo 配置 | Logo 配置 |
annotation | Object | 见表 Annotation 配置 | 3D 标注配置 |
Cache 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | Boolean | true | 启用或禁用缓存功能 |
key | String | 'url' | indexedDB 中的 keyPath |
database | String | 'EverApi3D' | indexedDB 中的数据库名称 |
一般来说,默认配置就可以支持将加载过的模型缓存在浏览器端的 indexDB 中,正常渲染模型调用的方法如下所示:
// 省略一些快速入门中的重复代码...
const files = [{ filename: 'Proper.STL', url: './Proper.STL' }]
api.render('root', files)
// 省略一些快速入门中的重复代码...
这种配置适合每个模型对应的 url
字段始终保持不变的情况,但是如果你的模型对应的 url
是变化的话,比如从对象存储服务获取的链接,就要修改 cache
配置中的 key
字段,同时在需要加载的模型对象中添加上对应的 key
,示例如下:
// 省略一些快速入门中的重复代码...
const config = {
cache: {
enabled: true,
key: 'id',
database: 'EverAPI_Models',
},
}
// 省略一些快速入门中的重复代码...
// 此处增加的 id 字段对应上面 cache 配置中 key 指定的值,EverAPI 会将此字段用作 indexDB 中的索引
// 此处 id 可以根据业务自行设置,能够保证可以唯一标识该模型即可
const files = [{ id: '2201_1', filename: 'Proper.STL', url: './Proper.STL' }]
api.render('root', files)
Progress 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
useDefaultProgress | Boolean | true | 使用默认的进度条样式 |
onProgress | Function | functions (progress) {} | 进度回调函数,progress 为当前进度 |
onRendered | Function | functions (volume, area, box) {} | 渲染完成回调函数,volume 为体积,area 为表面积, box 为包围盒 |
Background 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
color | String | #35415E | canvas 背景颜色,用16进制表示 |
opacity | Number | 0 | canvas 背景透明度,取值范围 0~1 |
Toolbar 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示工具条 |
modules | Object | 见下列各子表 | 工具条中各模块的具体配置 |
工具条为配合三维浏览的功能条,如下图所示。
Tree 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示结构树模块 |
label | String | 结构树 | 工具条中结构树模块的标签 |
结构树功能用以列出三维模型的零件组成,如下图:
Section 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示剖切模块 |
label | String | 剖切 | 工具条中剖切模块的标签 |
title | String | 剖切面 | 剖切浮窗中的标题 |
剖切功能用以查看模型内部结构,功能包括 x、y、z 三个方向。
Measure 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示测量模块 |
editable | Boolean | false | 测量数据可编辑 |
clearAfterClose | Boolean | true | 关闭测量功能后是否清空测量值 |
label | String | 测量 | 工具条中测量模块的标签 |
title | String | 测量 | 测量浮窗的标题 |
properties | Object | 见下表 | 测量各功能的配置 |
测量功能包括体积测量、边界测量、两点距离测量、点到面距离测量、半径测量、平面夹角测量,并可切换尺寸单位。
Properties
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
volume | String | 体积 | 体积的标签 |
area | String | 表面积 | |
boundary | Object | { enabled: true, label: '边界' } |
|
thick | String | { enabled: true, label: '壁厚' } |
|
length | Object | { enabled: true, label: '棱边长' } |
|
p2p | Object | { enabled: true, label: '两点距离' } |
|
p2l | Object | { enabled: false, label: '点边距离' } |
|
p2s | Object | { enabled: true, label: '点面距离' } |
|
l2l | Object | { enabled: false, label: '两边距离' } |
|
radius | Object | { enabled: true, label: '半径' } |
|
angle | Object | { enabled: true, label: '平面夹角' } |
|
unit | String | 单位 |
View 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示视图模块 |
label | String | 视图 | 工具条中视图模块的标签 |
title | String | 切换视图 | 视图浮窗的标题 |
properties | Object | 见下表 | 视图属性配置 |
默认常用7个视图的选择切换(前后视图、左右视图、上下视图、轴测图)。
Properties
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
front | String | 前视图 | 标签 |
rear | String | 后视图 | |
left | String | 左视图 | |
right | String | 右视图 | |
top | String | 上视图 | |
bottom | String | 下视图 | |
isometric | String | 轴测图 |
Render 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示渲染模块 |
label | String | 渲染 | 工具条中渲染模块的标签 |
properties | Object | 见下表 | 渲染属性配置 |
切换模型的渲染模式:线框、着色、线框着色。
Properties
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
wireframe | String | 线框 | 标签 |
flat | String | 着色 | |
flatlines | String | 线框着色 |
Projection 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
visible | Boolean | true | 显示投影模块 |
label | String | 投影 | 工具条中投影模块的标签 |
properties | Object | 见下表 | 投影属性配置 |
切换模型的投影模式:正交投影、透视投影。
Properties
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
orthogonal | String | 正交投影 | 标签 |
perspective | String | 透视投影 |
Logo 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
top | String | 'auto' | CSS 绝对定位 top 属性 |
right | String | '8px' | CSS 绝对定位 right 属性 |
bottom | String | '8px' | CSS 绝对定位 bottom 属性 |
left | String | 'auto' | CSS 绝对定位 left 属性 |
width | String | '80px' | Logo 宽度 |
height | String | 'auto' | Logo 高度 |
src | String | EverXYZ 企业 Logo | Logo src |
href | String | 'https://evercraft.co' | Logo 跳转链接 |
Measure 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
callbacks | Object | { onAdd, onRemove, onUpdate } |
触发测量功能之后的回调函数配置 |
要输出测量数据,需要绑定以上三个回调函数。如果希望能从服务器加载测量数据,或者输出所有测量数据的话,还需要用到这两个函数,api.initMeasureList
,api.getMeasureList
,示例如下:
<!doctype html>
<html lang="en">
<head>
<meta charset='utf8'>
<title>EverAPI Demo</title>
<!-- 引入 EverAPI 脚本文件 -->
<script src="https://evercraft.co/api/everapi.js"></script>
</head>
<body>
<h1>EverAPI Demo</h1>
<div id="root"></div>
<button id="list">列出所有测量</button>
<button id="load">加载测量数据</button>
<script>
// 配置文件
const config = {
measure:{
callbacks: {
onAdd: (data) => { console.log(data) },
onRemove: (data) => { console.log(data) },
onUpdate: (data) => { console.log(data) },
}
}
}
// api 是否已经加载成够的标志位
let apiLoaded = false
// 新建 api 实例
// 构造函数的前两个参数分别是 AppID 和 AppKey,这里的参数可用于本地 localhost:9000 调试
const api = new EverAPI('<APP_ID>', '<APP_KEY>', config)
const load = document.querySelector("#load")
const list = document.querySelector("#list")
load.addEventListener("click", () => {
if (apiLoaded) {
// 此处的 data 是加载的之前导出来的数据
const data = {}
api.initMeasureList('root', data)
}
})
list.addEventListener("click", () => {
if (apiLoaded) {
const measureList = api.getMeasureList('root')
console.log(measureList)
}
})
// api 加载成功后调用 loadApi 函数
window.addEventListener('oneverapiloaded', () => {
const files = [{ filename: 'Proper.STL', url: './Proper.STL' }]
api.render('root', files)
apiLoaded = true
})
</script>
</body>
</html>
Annotation 配置
Key | 类型 | 默认值 | 描述 |
---|---|---|---|
enabled | Boolean | false | 启用 3D 标注功能 |
hasDialog | Boolean | true | 使用默认的 3D 标注窗口 |
callbacks | Object | { onAdd, onRemove, onUpdate } |
触发标注功能之后的回调函数配置 |
要使用 3D 标注功能,还需要用到以下几个方法:
api.startAnno3D
:此方法用于开始 3D 标注操作,即可以在模型上添加标注点;api.restoreSceneByPinId
:此方法可以通过标注点来恢复 3D 场景;api.getAnno3DList
:此方法可以输出场景中的标注点;api.initAnno3DPins
:此方法可以将标注点数据加载到场景中。
若 hasDialog
参数设置为 false
,可以通过以下两个方法对 3D 标注点进行操作,使用方式与上述四种方法类似:
api.savePin
:此方法可以将标注点保存在场景当中,返回值为该标注点的信息;api.cancelPin
:此方法可以取消当前未保存的标注点;
<!doctype html>
<html lang="en">
<head>
<meta charset='utf8'>
<title>EverAPI Demo</title>
<!-- 引入 EverAPI 脚本文件 -->
<script src="https://evercraft.co/api/everapi.js"></script>
</head>
<body>
<h1>EverAPI Demo</h1>
<div id="root" style="width: 800px; height: 600px;"></div>
<button id="anno">点击开始标注</button>
<button id="list">列出所有标注点</button>
<button id="restore">根据 Pin 恢复场景</button>
<button id="load">加载标注点数据</button>
<script>
// 配置文件
const config = {
annotation:{
enabled: true,
callbacks: {
onAdd: (data) => { console.log(data) },
onRemove: (data) => { console.log(data) },
onUpdate: (data) => { console.log(data) },
}
}
}
// api 是否已经加载成够的标志位
let apiLoaded = false
// 新建 api 实例
// 构造函数的前两个参数分别是 AppID 和 AppKey,这里的参数可用于本地 localhost:9000 调试
const api = new EverAPI('<APP_ID>', '<APP_KEY>', config)
const anno = document.querySelector("#anno")
const list = document.querySelector("#list")
const restore = document.querySelector("#restore")
const load = document.querySelector("#load")
let enableAnno = false
anno.addEventListener("click", () => {
if (apiLoaded) {
enableAnno = !enableAnno
api.startAnno3D('root', true)
}
})
list.addEventListener("click", () => {
if (apiLoaded) {
const pinList = api.getAnno3DList('root')
console.log(pinList)
}
})
restore.addEventListener("click", () => {
if (apiLoaded) {
// 这里应该放获取到的标注点的 uid
const uid = 1
api.restoreSceneByPinId('root', uid)
}
})
load.addEventListener("click", () => {
if (apiLoaded) {
// 这里应该放从服务器加载到的数据
const data = {}
api.initAnno3DPins('root', data)
}
})
// api 加载成功后调用 loadApi 函数
window.addEventListener('oneverapiloaded', () => {
const files = [{ filename: 'Proper.STL', url: './Proper.STL' }]
api.render('root', files)
apiLoaded = true
})
</script>
</body>
</html>
导出图片
调用 api.takePhoto
方法,可以将场景导出为图片,另外,还可以调用 api.changeTheme
方法,来改变场景的主题,示例如下:
const config = {
progress: {
onRendered: () => {
// 此处的 root 是 HTML 中 API 容器的 id
api.takePhoto('root', {
includeMeasure: true, // 包含测量信息
onFinished: (base64) => {
console.log(base64) // 图片的 base64 编码
}
})
// 第二个参数为主题名,现在支持 'light' 和 'dark' 两种主题
// 默认为 'dark' 主题
api.changeTheme('root', 'light')
}
}
}
const api = new EverAPI('<APP_ID>', '<APP_KEY>', config)
控制零件显示隐藏
调用 api.hideByName
方法和 api.showByName
方法,可以通过零件在结构树中的名字来控制该零件在场景中的显示或者隐藏,示例如下:
const config = {
progress: {
onRendered: () => {
// 此处的 root 是 HTML 中 API 容器的 id
// Part1 是该在结构树中名字为 Part1 的零件
// 此方法使这个零件在场景中不可见
api.hideByName('root', 'Part1')
// 此处的 root 是 HTML 中 API 容器的 id
// Part1 是该在结构树中名字为 Part1 的零件
// 此方法使这个零件在场景中可见
api.showByName('root', 'Part1')
}
}
}
const api = new EverAPI('<APP_ID>', '<APP_KEY>', config)
设置零件 viewType
调用 api.setViewType
方法,可以调整模型的默认显示类型,示例如下:
const config = {
progress: {
onRendered: () => {
// 此处的 root 是 HTML 中 API 容器的 id
// 此方法使这个模型的默认坐标系与 Alias 软件一致
api.setViewType('root', 'alias')
}
}
}
const api = new EverAPI('<APP_ID>', '<APP_KEY>', config)
示例
const config = {
lang: 'zh',
scale: 1,
progress: {
useDefaultProgress: true,
onProgress: function (progress) {},
onRendered: function (volume, area, box) {},
},
background: {
color: '#35415E',
opacity: 1,
},
toolbar: {
visible: true,
modules: {
tree: {
visible: true,
label: '结构树',
},
section: {
visible: true,
label: '剖切',
title: '剖切面',
},
measure: {
visible: true,
editable: true,
clearAfterClose: false,
label: '测量',
title: '测量',
properties: {
volume: '体积',
area: '表面积',
boundary: {
enabled: true,
label: '边界',
},
thick: {
enabled: true,
label: '壁厚',
},
length: {
enabled: true,
label: '棱边长',
},
p2p: {
enabled: true,
label: '两点距离',
},
p2l: {
enabled: false,
label: '点边距离',
},
p2s: {
enabled: true,
label: '点面距离',
},
l2l: {
enabled: false,
label: '两边距离',
},
radius: {
enabled: true,
label: '半径',
},
angle: {
enabled: true,
label: '平面夹角',
},
unit: '单位',
},
},
view: {
visible: true,
label: '视图',
title: '切换视图',
properties: {
front: '前视图',
rear: '后视图',
left: '左视图',
right: '右视图',
top: '上视图',
bottom: '下视图',
isometric: '轴测图',
},
},
render: {
visible: true,
label: '渲染',
properties: {
wireframe: '线框',
flat: '着色',
flatlines: '线框着色',
},
},
projection: {
visible: true,
label: '投影',
properties: {
orthogonal: '正交投影',
perspective: '透视投影',
},
},
},
},
logo: {
top: 'auto',
right: '8px',
bottom: '8px',
left: 'auto',
width: '80px',
height: 'auto',
src: 'https://www.evercraft.co/media/logo.svg',
href: 'https://evercraft.co'
},
measure: {
callbacks: {
onAdd: (data) => {},
onRemove: (data) => {},
onUpdate: (data) => {}
}
},
annotation: {
enabled: true,
hasDialog: true,
callbacks: {
onAdd: (data) => {},
onRemove: (data) => {},
onUpdate: (data) => {}
}
}
}
const api = new EverAPI(<AppID>, <AppKey>, config)