@jspatrick/xb-three-box

XBTHRREBOX

version:1.2.x

更新说明

1.1.x

1. 更新了上图方式,isByMercator
2. 配置项增加了static,用于优化内存

1.2.x

1. 更新了加载状态的的触发,不再耦合eventbus
2. 增加TexturesUnUsed、ModelsUnUsed字段，找出项目中未被使用的模型和贴图文件

解决问题

这是一个同步使用mapbox和three两者的物质信息保持统一的插件

特性说明

1. 有些three原型里的方法,因为我们项目混合了mapbox这个特性.所以必须要修改.所以我们会有特殊的lib库,是对原生threelib的兼容修改
2. 相对three,多一个wrold的概念,wrold类似原生sence的概念.threebox是对world进行包装.适配gis与3d,可以用作同一个world的物体整体切换.同时也导致了需要添加到scene的模型的scale和position被托管.直接设置会无效(group内的scale,postion是有效的)
3. three世界的原点在北极附近,左右thtree世界的坐标对于业务开发意义不大,尽可能通过经纬度来处理距离问题,推荐show(对标原生的add)的时候用lnglat来定位.偏移的时候可以用lngLat也可以用xyz.这个时候是真实世界的米为单位.

总结:具体位置用lnglat,偏移用offset,后期处理切换scene用world,一些集成好的方法进包里找.

使用方法

0. 引用npm,XbThreeBox用于实现,Module用于继承,包内的一些封装需要去包内引入.
1. 初始化threebox单例
2. 配置conf文件
3. 把conf配置传递给threebox单例初始化
4. 继承module写模块,threebox单例装载该模块
5. 模块中声明依赖的模型,纹理,和别的模块(控制台打印了一定的模块加载信息)
6. 通过模块提供的show,change,del来处理模型动态(add到world的元素需要通过show,元素内部可以用原生的postion,scale等方法),dispatch/on来和外界互动
7. 模块init处理初始化代码,render处理每一帧代码
8. 框架包含一些修改适配过的外部包和内部gl封装.按需引入.并未直接暴露

示例

初始化

    import XbThreeBox from "@jspatrick/xb-three-box";
    let xxx = new XbThreeBox();

继承

    import {Module} from '@jspatrick/xb-three-box';
    class Xxx extends module{}

引用封装

    import {MathUtil} from "@jspatrick/xb-three-box/src/gl/MathUtil";

API文档

XbThreeBox.XbThreeBox 类

做成插件后,返回单例,全局使用

属性	类型	说明
scene	three.scene	three的场景,threebox会对世界有封装,不建议直接使用
world	three.group	统一的mesh存在group.在这里统一做矩阵变化
camera	three.camera
width	Number	容器宽度
height	Number	容器高度
pause	Boolean	是否暂停
renderer	three.renderer

方法	参数	返回值	说明
init	map:Mapbox,modelConf:Array,textureConf:Array,module:Array		做成插件后,直接返回单例,该方法丢弃
on	eventName:String,callback:Function		通过单例监听一个自定义事件
dispatch	eventName:String,everyThing		触发一个自定义事件
getOffset	lngLat:Array	xyz:three.Vector3	xyz三个元素的数组,相对地图中点的xy偏移量,单位是mapbox地图上的米(为了妥协,换算是用赤道换算的,上图isByMercator要设置true)
getXy	lngLat:Array	xyz:three.Vector3	xyz三个元素的数组,在3d世界的xy的值(不推荐使用,xyz实用没意义)
getLngLat	xyz:Array	lnglat:Array	数组形式的经纬度(不推荐使用)
createWorld		worldId:Int	创造一个新world,约等于scene概念.返回的id,show方法和render函数中,填写指定的world,可以只渲染该world里面的show到该world里面的物体

modelConf.element	类型	说明
name	String	模型名,期望唯一
path	String	模型的地址
type	String	模型的类型
index	Number	加载顺序(暂不支持)
static	Boolean	设置为true,改模型会在内存中被释放.节约内存(白膜等模型很需要),但是del后会无法再次上图(visible无影响)

textureConf.element	类型	说明
name	String	纹理名,期望唯一
path	String	纹理的地址

事件	参数	说明
onLoaded		加载完所有的模型和模块后,会触发
onLoading	type:Enum ,info:String, progress:Number	每加载成功一个,会触发
onLoadStart		刚开始加载时触发
onModuleComplete		当模块init完成(废弃,请用onLoaded)

XbThreeBox.module 类

项目代码写成模块,模块方法继承此基类

成员	类型	说明
threebox	XbThreeBox	XbThreeBox实例对象
name	String	模块的名字,用于被依赖

方法	参数	返回值	说明
show	meshInfos:Array		出场方法,lnglat不穿,默认map的center
change	meshInfos:Array		改变模型的位置大小
del	meshInfos:Array		删除模型(remove+dispose),对静态模型(conf中static不为false的)来说.del方法意味着再也无法show.因为静态模型内存中已经清除.

接口	参数	返回值	说明
getName		String	申明模块的名字,用于别的模块依赖
dependencyModels		Array	申明依赖的模型资源
dependencyTextures		Array	申明依赖的贴图资源
render		compserList	每一帧要执行的代码,如果自己有compser,返回一个compserlist.
init	meshes:Object,textures:Object,module:Object	everything	执行模块函数,这三个参数会传递依赖的模型,纹理,模块,如果有需要提供给别人的资源,return任意.别的模块即可拿到

compserList.element	类型	缺省值	说明
composer	three.composer
world	Number	0	该composer需要用第几个world显示(别的world隐藏)
before	Function		该composerRender前调用
after	Function		该composerRender后调用

meshInfos.element	类型	缺省值	说明
mesh	three.mesh/three.group		模型
lngLat	Array		三个元素数组,mesh的经纬度,第三个值是z值,默认为0
scale	Array		三个元素数组,第二,第三个元素的缺省值是第一个元素的值,mesh的缩放
offset	Array		三个元素数组,第二,第三个元素的缺省值是0,xyz的相对偏移量,单位是mapbox地图上的米,
xyz	Array		三个元素数组,mesh的xyz坐标(不推荐使用,xyz实用没意义)
isByMercator	Boolean	false	是否是通过Mercator的值建模,影响模型的scale,Mercator的值建模上图是不需要考虑纬度投影畸变的
world	Number	0	在第几个world

部分示例

1. 找出未被使用的模型，需要保证模型和贴图文件部署在public/model文件夹下， 运行命令node node_modules/@jspatrick/xb-three-box/bin/UnUsedFileChecker.js来生成 对应的临时文件，启动项目后控制台打印xbThreebox.resourcesManager.ModelsUnUsed

项目结构

xbThreeBox                    //module基类,和xbthreebox类
  └─src                       //框架代码
      ├─prototype             //框架基础代码
      ├─lib                   //框架整合的需要修改的外部文件(项目按需引入)
      ├─gl                    //框架整合的webgl封装(项目按需引入)
      ├─indexDB               //框架indexDB相关
      ├─Loader                //框架indexDB相关
      ├─custom                //根据用户项目生成的临时文件
      └─worker                //框架indexDB相关
        

问题清单

• 模型大小 三维空间 真实空间 导致 原生position scale 用户搞不清楚 该不该用
• 物体的世界坐标在变化
• three的scan
• 一个gl下 透明度混合有问题 (兼容性)

功能展望

• 模块render函数,提供delta时间
• 变成npm包
• dispatch 语义的正确性

依赖