1.1.3 • Published 9 months ago
nsymodel v1.1.3
什么是 nsyModel
nsyModel 是一款基于threejs的模型加载工具库,对threejs等插件进行多种常用方法的ts封装,同时融入了天气、水面和喷淋系统,经过简单的配置项即可实现想要的功能。
安装nsyModel
使用yarn add nsymodel
或者npm install nsymodel
开始使用
import nsyModel from "nsyModel/index.js"
let modelView: any = null;
onMounted(() => {
modelView = new nsyModel(option);
modelView.init();
})
初始化配置项说明(option)
总览
{
loading?: Loading,
dom: HTMLElement//注意:此dom宽高不为0!
sceneOpt: sceneOpt,
renderOpt?: renderOpt,
cameraOpt?: cameraOpt,
listenerSizeChange?: boolean,
lights: lightsOpt,
models: Array<modelsOpt>,
onModelsLoaded?: Function,
control?: controlOpt,
debug?: boolean,
onClick?: Function,
ondblClick?: Function,
weather?: weatherOpt,
}
详细
- loading 加载进度
{
open: boolean,//是否启用loading
apBody?: boolean//是否将生成的loading插入到body
}
- dom 场景容器的dom 注意:此dom宽高不为0!
- sceneOpt 场景配置项
{
background?: any,//背景 注意:在backgroundType 为 cube时,background代表全景图六个面图片所在的文件夹地址!
environment?: any,//环境
format?:string,//在backgroundType 为 cube时,format代表全景图格式的后缀
castShadow?: boolean,//是否包含阴影
backgroundType: 'exr' | 'color' | 'cube'|'test',//背景类型:'exr'全景\纯色背景\天空盒全景\测试
dataBase?:{
id: number,//模型id
version: string,//模型版本号
name: string,//模型名称
} //浏览器indexDB的模型参数说明
}
- renderOpt 渲染器配置项
{
antialias?: boolean,//是否执行抗锯齿。默认为false.
alpha?: boolean,//控制默认的清除alpha值。当设置为true时,该值为0。否则是1。默认值为false。
canvas?: HTMLElement,//一个供渲染器绘制其输出的canvas 它和下面的domElement属性对应。 如果没有传这个参数,会创建一个新canvas
context?: any,//可用于将渲染器附加到已有的渲染环境(RenderingContext)中。默认值是null
precision?: string,//着色器精度. 可以是 "highp", "mediump" 或者 "lowp". 如果设备支持,默认为"highp"
premultipliedAlpha?: boolean,//renderer是否假设颜色有 premultiplied alpha. 默认为true
stencil?: boolean, //绘图缓存是否有一个至少8位的模板缓存(stencil buffer)。默认为true
preserveDrawingBuffer?: boolean, //是否保留缓直到手动清除或被覆盖。 默认false.
powerPreference?: string, // 提示用户代理怎样的配置更适用于当前WebGL环境。 可能是"high-performance", "low-power" 或 "default"。默认是"default".
failIfMajorPerformanceCaveat?: boolean,//检测渲染器是否会因性能过差而创建失败。默认为false
depth?: boolean, // 绘图缓存是否有一个至少6位的深度缓存(depth buffer )。 默认是true.
logarithmicDepthBuffer?: boolean, //是否使用对数深度缓存。如果要在单个场景中处理巨大的比例差异,就有必要使用。 默认是false
shadowMapEnabled?: boolean,//是否启用阴影
}
- cameraOpt 相机配置项
{
fov?: number, // 摄像机视锥体垂直视野角度
aspect?: number, // 摄像机视锥体长宽比
near?: number, // 摄像机视锥体近端面
far?: number, // 摄像机视锥体远端面
position?: normalPos,//摄像机位置
target?: normalPos,//摄像机焦点
}
- listenerSizeChange 是否监听容器尺寸改变true/false
- lights 光源配置项
{
ambientLight?: { //环境光配置
color?: any,//颜色的rgb数值。缺省值为 0xffffff。
intensity?: number,//光照的强度。缺省值为 1。
},
directionalLights?: [{//方向光配置,可多个
color?: any,//颜色的rgb数值。缺省值为 0xffffff。
intensity?: number,//光照的强度。缺省值为 1。
castShadow?: boolean,//如果设置为 true 该平行光会产生动态阴影。
position?: any,//位置:假如这个值设置等于 (0, 1, 0),那么光线将会从上往下照射。
target?: any
// shadow?:any,
}],
pointLights?: [{//点光源配置,可多个
color?: any,//颜色的rgb数值。缺省值为 0xffffff。
intensity?: number,//光照的强度。缺省值为 1。
distance?: number,// 这个距离表示从光源到光照强度为0的位置。 当设置为0时,光永远不会消失(距离无穷大)。缺省值 0.
decay?: number, // 沿着光照距离的衰退量。缺省值 2。
castShadow?: boolean,//如果设置为 true 该平行光会产生动态阴影。
position?: any,//位置:假如这个值设置等于 (0, 1, 0),那么光线将会从上往下照射。
}],
hemisphereLight?: {//环境光配置
skyColor?: any, // (可选参数) 天空中发出光线的颜色。 缺省值 0xffffff。
groundColor?: any, //(可选参数) 地面发出光线的颜色。 缺省值 0xffffff。
intensity?: number, // (可选参数) 光照强度。 缺省值 1。
position?: any,//位置:假如这个值设置等于(0, 1, 0),那么光线将会从上往下照射。
},
spotLights?: [{//聚光灯配置,可多个
color?: any,//颜色的rgb数值。缺省值为 0xffffff。
intensity: number, //(可选参数) 光照强度。 缺省值 1。
distance: number,// 这个距离表示从光源到光照强度为0的位置。 当设置为0时,光永远不会消失(距离无穷大)。缺省值 0.
angle: any, // 光线散射角度,最大为Math.PI/2。
penumbra: number, // 聚光锥的半影衰减百分比。在0和1之间的值。默认为0。
decay?: number, //沿着光照距离的衰减量。
castShadow?: boolean,//如果设置为 true 该平行光会产生动态阴影。
position?: any,//位置:假如这个值设置等于(0, 1, 0),那么光线将会从上往下照射。
}]
}
- models 模型列表配置 array类型
{
url: string,//模型地址
modelType: 'gltf' | 'glb' | 'json', // 加载类型
active?: boolean,// 是否显示 默认false不显示
draco: boolean,// 模型文件是否采用了draco压缩
loaderUrl?: string, //模型对应的解码器地址 默认为:nsyModel/model/draco/gltf/
onLoaded?: Function, // 当前模型加载完毕后的回调函数
specilMember?: any, // 特殊构件设置
globalMember?: any,// 模型全局构件设置
dataBase?: {
id: number,
version: string,
name: string,
},//indexDB配置
name?: string,// 模型名称(会覆盖原先模型中的name字段)
version?: string, // 模型版本号
CameraPosition?:{ // 普通xyz坐标
x: number,
y: number,
z: number
}, // 调整到该模型时,相机位置
TargetPosition?:{ // 普通xyz坐标
x: number,
y: number,
z: number
},// 调整到该模型时,相机聚焦中心点位置
}
- onModelsLoaded 所有模型加载完成后的回调函数
- control 轨道控制器配置项
{
//自动旋转
autoRotate?: boolean,
// 自动旋转速度
autoRotateSpeed?: number,
// 使动画循环使用时阻尼或自转 意思是否有惯性
enableDamping?:boolean,
// 动态阻尼系数 就是鼠标拖拽旋转灵敏度
dampingFactor?: number,
// 是否可以旋转
enableRotate?: boolean,
// 是否可以缩放与缩小
enableZoom?: boolean,
// 上下旋转范围
minPolarAngle?:number,
maxPolarAngle?: number,
// 左右旋转范围
minAzimuthAngle ?:number,
maxAzimuthAngle ?: number,
// 设置相机距离原点的最近距离
minDistance ?: number,
// 设置相机距离原点的最远距离
maxDistance ?:number,
// 是否开启右键拖拽
enablePan?: boolean,
// 是否开启监听->在控件状态改变的过程中时
onChange?:Function,
// 是否开启监听->在控件状态改变的开始时
onStart?:Function,
// 是否开启监听->在控件状态改变的结束时
onEnd?:Function,
}
- debug 是否开启debug模式 true/false
- onClick 点击事件 Function
- ondblClick 双击时间 Function
- weather 天气系统配置项
{
open: boolean,// 是否默认展示
use:boolean, // 是否启用天气系统
rainSize?: number,//雨点大小
rainSpeed: number, //雨下落速度
rainDrops?: number, //雨量
imgSrc?: string,//雨雪图片的src地址
autoRotate?: boolean,//是否开启自动旋转雨/雪场
rainRange?: normalPos, //雨点下落范围
rainPosition?: normalPos //雨场的位置
rotaSpeed?:number,//旋转速度
}
方法
标签相关
- addSpriteLabel 添加精灵标签(此类标签将始终保持正对相机)
let dom = '<div id="demo-1"><table><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr></table></div><div id="demo-2"><table><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr></table></div><div id="demo-3"><table><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444455544</td></tr></table></div>';
let option = [{
id: 'demo-1',//该标签对应的dom字符串中的标签id
position: { // 点击该标签位置
"x": -4.4712443188537,
"y": 3,
"z": -2.879555675256142
},
scale: { x: 5, y: 3, z: 4 },//标签缩放
closeBtn: {// 标签关闭按钮
url: 'images/close_label.png',//按钮贴图位置
center: { x: 0, y: -4.5, z: 0 },//按钮中心点
scale: { x: 0.35, y: 0.35, z: 0.35 },//按钮缩放
},
openBtn: {// 标签打开按钮
url: 'images/notice.png',//按钮贴图位置
position: {//按钮位置
"x": -4.4712443188537,
"y": 1.5,
"z": -2.879555675256142
},
scale: { x: 0.5, y: 0.5, z: 0.5 },//按钮缩放
},
cameraPosition: {//点击该标签后,相机转到的位置
"x": -3.6881199024404516,
"y": 5.283624006440176,
"z": 8.426587973482047
}
},
{
id:'demo-2',
position:{x:0,y:3,z:0},
scale:{x:5,y:3,z:4}
},{
id:'demo-3',
position:{x:0,y:3,z:-2},
scale:{x:5,y:3,z:4}
}]
//m代表在模型实例化的对象,dom代表label的dom字符串,option是上方的配置项;
modelView.addSpriteLabel(m, dom, option);
- updateSpriteLabel 更新对应的精灵标签
let obj = {
id: 'demo-1',//标签配置时的标签id
dom:'<div id="demo-1"><table><tr><td>1一一一一</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr></table></div><div id="demo-2"><table><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr></table></div><div id="demo-3"><table><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444444</td></tr><tr><td>111</td><td>222</td><td>333</td><td>444455544</td></tr></table></div>'
}//新的dom字符串
let data = [obj]//array,可更新多个
modelView.updateSpriteLabel(data);
模型操作
- changeActModelByName 通过模型的name字段(初始化配置项中的name),改变场景中显示的模型
//通过模型name改变场景中显示的模型(name:模型名称;focus:显示后是否聚焦,当为true时,需要配置该模型的CameraPosition和TargetPosition)
modelView.changeActModelByName("stlsysxt", true)
- showAllModels 显示所有模型
- hideAllModels 隐藏所有模型
- changeMeshEnvMap 改变网格体的环境贴图
modelView.changeMeshEnvMap();//测试修改环境贴图,注意:需要再此之前先修改场景环境
- changeBackground 改变模型背景 (目前仅支持cube类型的环境背景)
modelView.changeBackground('images/sky/rain/');
//参数为新的环境图位置文件夹,为了统一命名规范,六张图片命名为"px", "nx", "py", "ny", "pz", "nz"
- changeMeshOpc 改变网格体的透明度
modelView.changeMeshOpc(mesh, 0.35);//参数1为网格体,参数2是透明度
- toggleTargetMesh 显示/隐藏mesh
modelView.toggleTargetMesh(mesh, false);//参数1为网格体,参数2是状态
天气系统
- nsyWeather.changeTexture 改变雨雪的贴图(修改天气)
modelView.nsyWeather.changeTexture("/images/snow.png");//参数为天气贴图的url:雨滴 雪片
- nsyWeather.changeRSpeed 修改雨下的速度
modelView.nsyWeather.changeRSpeed(0.00001);//参数为速度值
- nsyWeather.changeRDrops 修改雨/雪量
modelView.nsyWeather.changeRDrops(300);//修改雨/雪量,参数越大 ,雨雪越多
- nsyWeather.changeRSize 修改雨/雪大小
modelView.nsyWeather.changeRSize(1)//修改雨/雪大小
局部构件操作
- rotateProduct 构件旋转
//调用示例
modelView.rotateProduct("name", "Rectangle204",'x',180,1);
//参数说明
/**
* @description: 旋转构件
* @param {string} propName 必选:构件userData中定义的字段key
* @param {any} value 必选:构件userData中定义的字段value
* @param {string} axis 必选:可选值为'x','y','z'
* @param {number} rotate 必选:旋转角度
* @param {number} step 步长,默认为0.1
* @param {Function} callback 回调函数
* @return {*}
*/
rotateProduct(propName: string, value: any, axis: string, rotate: number,step:number=0.1, callback?: Function)
- moveProduct 构件移动
//调用示例
modelView.moveProduct("name", "Rectangle204",{x:0,y:0,z:0},3000);
//参数说明
/**
* @description: 移动构件
* @param {string} propName 必选:构件userData中定义的字段key
* @param {any} value 必选:构件userData中定义的字段value
* @param {normalPos} position 必选:构件目标位置
* @param {number} time 可选:过程动画的时间
* @param {Function} callback 可选:移动完成后的回调函数
* @return {*}
*/
moveProduct(propName: string, value: any, position: normalPos, time: number = 2000, callback?: Function)
- setProductNotice 测试告警
//调用示例
modelView.setProductNotice("name", "Rectangle204",'#f05',300,false);
//参数说明
/**
* @description: 设置构建告警
* @param {string} propName 必选:构件userData中定义的字段key
* @param {any} value 必选:构件userData中定义的字段value
* @param {string} color 告警颜色,默认为#f05
* @param {number} time 闪烁频率
* @param {boolean} depthTest 是否开启深度测试 默认开启,关闭后构件将不被遮挡
* @return {*}
*/
setProductNotice(propName: string, value: any,color:string='#f05',time:number=800,depthTest:boolean=true)
- resetProductNotice 还原构件状态,消除告警状态
//调用示例
modelView.setProductNotice("name", "Rectangle204",'#f05',300,false);
//参数说明
/**
* @description: 消除构建告警
* @param {string} propName 必选:构件userData中定义的字段key
* @param {any} value 必选:构件userData中定义的字段value
* @return {*}
*/
resetProductNotice(propName: string, value: any)
插件
水面插件
使用
//引入
import { water } from "nsyModel/import/waterFace"
// 示例
let ms = water({
waterNormalsUrl: 'nsymodel/import/waterFace/waternormals.jpg', size: {
width: 20,
height: 32
},
distortionScale: 3.7,
position: {
x: -1.2,
z: 4,
y: -1.7
}
});
m.add(ms);//将水面添加进场景。 m 为场景或者模型容器
setInterval(() => { // 此处作用是为了让水面产生流动效果
ms.material.uniforms['time'].value += 0.15 / 60.0;
}, 10);
参数说明
{// 配置项
textureWidth?:number;//贴图宽
textureHeight?:number;//贴图高
waterNormalsUrl?:string;//贴图url
alpha?:number;//水面透明度
sunColor?:Color;//阳光颜色
waterColor?:Color;//水面颜色
distortionScale?:number;//失真比例
position?:{x:number,y:number,z:number};//水面位置
size:{
width:number,//水面宽度
height:number//水面高度
}
}
喷淋头效果(模拟六个等级的降雨0到5,雨量递增)
使用
//引入
import Spray from "nsyModel/import/particle"
// 示例
sp = new Spray({
level: 2,
sprayHeight: 5.2,
sprayItems: spraylist//spraylist为每个喷淋头的配置
});
let group = sp.initSpray();// 初始化生成喷淋组group
m.add(group);//将喷淋组添加进场景。 m 为场景或者模型容器
sp.sprayAnimateStart();//开始喷淋动画
参数说明
sprayOpt{
level:number;//雨量等级0-5
sprayHeight:number;//从喷淋头顶部算起,到水滴滴落的高度
sprayItems:{
color:string;//水滴颜色,默认白色
size:number;//水滴尺寸
positions:any;//喷淋头位置
}
}
方法
- initSpray 初始化方法,返回喷淋头group
- sprayAnimateStart 开启喷淋动画
- sprayAnimateStop 暂停喷淋动画
- sprayRemove 删除喷淋头和雨滴
- spraySetLevel 改变雨量等级0-5