plain-three

planThree 简易化的 ThreeJS

本插件是基于 ThreeJs 的二次封装, 可以让使用者通过API调用方式快速创建自己的Three场景, 工具库中提供了基础交互功能,更多功能持续更新中

安装

npm install plain-three -S
or 
yarn add plain-three -S
or
pnpm add plain-three

引入

import PlainThree from "plain-three"

使用文档

1. 实例化实例

代码实例

const app = PlainThree({
    elementId: "scene",
    cameraPosition:[50,50,130],
    FPS:120,
    logarithmicDepthBuffer:true,
    physicallyCorrectLights:true
});

配置说明

配置项	类型	是否必填	说明
elementId	string	是	实例挂载的HTML元素的id
cameraPosition	array[number]	否	相机的位置
FPS	number	否	模型渲染的帧率 默认10
logarithmicDepthBuffer	boolean	否	开启性能优化. 默认为 false
physicallyCorrectLights	boolean	否	开启物理光照 默认为 false

---

2. 创建场景模型

代码示例

 await app.createSceneModule({
     rootPath: "./module/",
     moduleFile: "xxx.gltf",
     userData: {
         key: "模型属性",
         key2: "模型属性2",
         ...
     },
     moduleName: "模型名称",
})

createSceneModule返回一个 promise 对象, 成功返回模型的实例对象（可用于模型实例的二次开发），失败则返回错误信息

配置项

配置项	类型	是否必填	说明
rootPath	string	是	配置路径的根目录
moduleFile	string	是	配置路径的文件
userData	object	是	自定义数据集合
moduleName	string	是	模型名称

---

3.创建物体

示例

await app.createParts({
    rootPath: "/car/",
    moduleFile: "acura-rlx-2021.quads.gltf",
    position: [0, 1, 0],
    zoom:[0,0,0]
    userData: {
        name: "车辆",
        carCode: "京B2022",
    },
    moduleName: "车辆",
});

在V1.0.4版本中，支持对模型的帧动画操作；createParts返回一个 promise 对象,成功返回对象实例和关键帧动画实例 ,失败返回报错信息。

返回示例

{
    gltf:{}, // 模型对象
	ItemAnimations:{ //动画属性
        id:'' , //生成当前该模型动画的uuid，
        example:"", // 当前的动画加载器实例
        animationAction：exampleItem.clipAction(gltf.animations[2], // 当前的动画源
    }
}

配置项

配置项	类型	是否必填	说明
rootPath	string	是	模型根目录
moduleFile	string	是	模型文件名
userData	object	是	自定义数据集合
moduleName	string	是	模型名称
position	array	是	模型位置
zoom	arrat	是	模型缩放

---

4. 查找物体

示例

app.getQuery("车辆")

配置项

配置项	类型	是否必填	说明
	string	是	查找模型的moduleName值

注意: 改方法只有在模型渲染完成后才可以调用

---

5.创建标注

示例

app.createMarker({
    name:'车辆',
    url:"图片的CDN地址,推荐使用线上的资源",
    position:[0,2,5],
    scale:[1,1,1],
    userData:{
        name:"车辆的标注"
    },
    thingData:this.app.getQuery("车辆")
})

配置项

配置项	类型	是否必填	说明
alias	string	是	标注的别名
thingData	object	是	表示标注物体父集组对象
name	string	是	需要标注的物体的名称
url	string	是	图片地址(CDN方式)
position	array[number]	是	标注的偏移量[x,y,z]
scale	array[number]	是	图片的缩放大小[x,y,z]
userData	object	否	预留属性用于存放标注的自定义属性

---

6. 隐藏标注

示例

app.clearMarker({name:this.deviceName})

参数配置

参数	类型	是否必填	说明
name	string	是	查找标注的name (标准的类型是Sprite, 位置在全局的group的children集合里面), 例如: xxx.obj.parent.name

---

7. 隐藏物体

示例

let state = app.getQuery("车辆").visible
app.hideThing("车辆",!state)

参数配置

参数	类型	是否必填	说明
name	string	是	模型的moduleName值
state	boole	是	模型是否隐藏

---

8. 清除场景

示例

app.clearScene();

---

9.注册点击事件

示例

window.addEventListener("dblclick", (event) => {
  	let result = this.app.click(event);
    console.log("点击事件", result);
});

配置项

参数	类型	是否必填	说明
event	object	是	点击是触发的HTMLDOM的event对象

返回值 eventInfo

属性名	类型	说明
obj	object	当前鼠标点击拾取物体
point	array[number]	当前鼠标点击的场景坐标[x,y,z]

---

10.外部模型的关键帧动画使用

参考第三节的创建物体后返回的实例对象

代码示例

 var botany = await this.app.createParts({
     rootPath:"./threeModule/zhizhu/",
     moduleFile: "zhizhu.glb",
     position: [-15,5,20],
     zoom:[2,2,2],
     moduleName: "蜘蛛",
})
console.log("蜘蛛模型",botany) // 此时的变量已经返回了模型实例和动画实例
//播放帧动画
let {exampleItem,ItemAnimations} = botany.animation;
ItemAnimations.animationAction = exampleItem.clipAction(this.insect.gltf.animations[index])
ItemAnimations.animationAction.play()

/*如果出去动画停止，或者切换动画时，需要调用stop()停止当前的动画*/
ItemAnimations.animationAction.stop()

11. HTML标注信息

this.app.createHtml(options)

参数

参数	类型	是否选填	描述
HTMLId	string	是	传递模型的uuid，用于html的唯一标识
Mesh	object	是	模型的实例对象
position	array[x:number,y:number]	是	用于附加HTML浮窗的位置

示例

const moduleHtmlData = []; // 用于存放每个模型的id和数据，用于HTML循环创建元素
var botany = await this.app.createParts(options) //创建外部模型
var {scene} = this.botany.gltf;
moduleHtmlData.push({
    uuid:scene.uuid,
    htmlValue:{
      title:"xxx",
      w:"xxx",
      w2:"xxx"
    }
})
this.app.createHtml({
    HTMLId:scene.uuid,
    Mesh:scene,
    position:[40,-130]
})