HT for Web (Hightopo) 使用心得（4）- 3D 場(chǎng)景 Graph3dView 與 Obj 模型

在前一篇文章《Hightopo 使用心得（3）- 吸附與錨點(diǎn)》中，我們?cè)诮Y(jié)尾處提到過(guò) HT 的 3D 場(chǎng)景。這里我們通過(guò)代碼建立一個(gè) 3D 場(chǎng)景并添加一個(gè) Obj 模型來(lái)介紹一下 HT for Web 在 3D 場(chǎng)景和模型加載方面的使用。

這是我們最終實(shí)現(xiàn)的效果：

3D坐標(biāo)系

在搭建 3D 場(chǎng)景之前，先介紹一下基本的 3D 概念。

HT for Web 在 3D 場(chǎng)景中采用的是右手坐標(biāo)系，遵循右手螺旋法則。也就是：x軸正方向朝右，y軸正方向朝上，z軸正方向朝向屏幕外。

與 2D 坐標(biāo)系（x, y）相比，這里多了一條坐標(biāo)軸，也就是高度軸。2/3D 坐標(biāo)系具體對(duì)應(yīng)關(guān)系如下：

從圖片和表格中可以看到，在右手坐標(biāo)系下，2D坐標(biāo)系中的 x,y 平面，在 3D 中對(duì)應(yīng)的是 x,z 平面，也就是地平面。而在 3D 中多出來(lái)的一條坐標(biāo)軸是高度坐標(biāo)軸，也就是 y 軸。

有了三條坐標(biāo)軸后，顯而易見(jiàn)，我們?cè)谂渲霉?jié)點(diǎn)(ht.Node)屬性時(shí)就不能使用原來(lái)的方法。為此，HT 為ht.Node 擴(kuò)展了一些新的方法。其中比較常用的有：

3D位置函數(shù)

• 設(shè)置位置（坐標(biāo)）：setPosition3d(x, y, z)|setPosition3d([x, y, z])，可傳入x, y, z三個(gè)參數(shù)，或傳入[x, y, z]的數(shù)組
• 獲取位置（坐標(biāo)）：getPosition3d()的新函數(shù)，返回[x, y, z]數(shù)組值，即[getPosition().x, getElevation(), getPosition().y]
• 設(shè)置大?。ǔ叽纾簊etSize3d(x, y, z)|setSize3d([x, y, z])，可傳入x, y, z三個(gè)參數(shù)，或傳入[x, y, z]的數(shù)組
• 獲取大?。ǔ叽纾篻etSize3d()的新函數(shù)，返回[x, y, z]數(shù)組值，即[getWidth(), getTall(), getHeight()]

3D錨點(diǎn)

3D中節(jié)點(diǎn)同樣有錨點(diǎn)的概念，同樣HT為ht.Node圖元增加了以下新函數(shù)：

-設(shè)置 3D 錨點(diǎn)： setAnchor3d(x, y, z)|setAnchor3d([x, y, z])，可傳入x, y, z三個(gè)參數(shù)，或傳入[x, y, z]的數(shù)組

-設(shè)置獲取y軸方向錨點(diǎn)： getAnchorElevation()|setAnchorElevation(elevation)

-獲取 3D 錨點(diǎn) getAnchor3d()的新函數(shù)，返回[x, y, z]數(shù)組值，即[getAnchor().x, getAnchorElevation(), getAnchor().y]

3D旋轉(zhuǎn)函數(shù)

ht.Node在2D坐標(biāo)系下由getRotation()和setRotation(rotation)函數(shù)控制旋轉(zhuǎn)，該參數(shù)對(duì)應(yīng)于3D坐標(biāo)系下沿y軸的負(fù)旋轉(zhuǎn)值。 同時(shí)3D坐標(biāo)系下增加了rotationX和rotationZ兩個(gè)分別沿著x軸和z軸的新旋轉(zhuǎn)變量，同時(shí)增加以下新函數(shù)：

• setRotationY(y)設(shè)置沿y軸旋轉(zhuǎn)弧度，相當(dāng)于setRotation(-y)
• getRotationY()獲取沿y軸旋轉(zhuǎn)弧度，相當(dāng)于getRotation()
• 設(shè)置圍繞三個(gè)坐標(biāo)軸的旋轉(zhuǎn)角度：setRotation3d(x, y, z)|setRotation3d([x, y, z])，可傳入x, y, z三個(gè)參數(shù)，或傳入[x, y, z]的數(shù)組
• 獲取當(dāng)前在三個(gè)坐標(biāo)軸的旋轉(zhuǎn)角度：getRotation3d()的新函數(shù)，返回[x, y, z]數(shù)組值，即[getRotationX(), -getRotation(), getRotationZ()]

3D場(chǎng)景搭建 - ht.graph3d.Graph3dView

在前面文章的例子中，創(chuàng)建一張 2D 圖紙，使用的是 new ht.graph.GraphView(); 而在這里，創(chuàng)建一個(gè) 3D 場(chǎng)景，我們需要使用 new ht.graph3d.Graph3dView();

與HT其他視圖組件一樣， ht.graph3d.Graph3dView也是基于于統(tǒng)一的ht.DataModel數(shù)據(jù)模型來(lái)驅(qū)動(dòng)圖形顯示。熟悉了2D圖紙的同學(xué)可能會(huì)發(fā)現(xiàn)，其在場(chǎng)景配置，節(jié)點(diǎn)配置上與 2D 相似。

使用下面的代碼，我們創(chuàng)建和配置了一個(gè) 3D 場(chǎng)景，并獲取了其對(duì)應(yīng)的數(shù)據(jù)模型（dataModel):

/*************** 創(chuàng)建一個(gè)3D場(chǎng)景，添加到body下，并配置各種屬性 ******************/

const g3d = new ht.graph3d.Graph3dView();

g3d.addToDOM(); // 添加到DOM

g3d.setGridVisible(true); // 顯示網(wǎng)格

g3d.setEye(2000, 1000, 0); // 設(shè)置相機(jī)位置

g3d.setCenter(0, 0, 0); // 設(shè)置中心點(diǎn)

g3d.setUp(0, 1, 0); // 設(shè)置相機(jī)角度；這里默認(rèn)值就是 [0, 1, 0]

g3d.setRotatable(true); // 允許旋轉(zhuǎn)，默認(rèn)值：true

g3d.setZoomable(true); // 允許滾輪縮放，默認(rèn)值：true

g3d.setPannable(true); // 允許平移，默認(rèn)值：true

g3d.setEditable(true); // 允許在場(chǎng)景中對(duì)節(jié)點(diǎn)進(jìn)行編輯

const dm = g3d.getDataModel(); // 獲取場(chǎng)景的 DataModel，簡(jiǎn)寫(xiě)形式：g3d.dm()

dm.setBackground('white'); // 同 dm.setBackground('rgba(255, 255 255, 1)'); 默認(rèn)為黑色

創(chuàng)建場(chǎng)景后，我們又讓它顯示了輔助網(wǎng)格。我們可以將這些網(wǎng)格理解成地平面。模型在網(wǎng)格上方就相當(dāng)于在地面之上。反之就是在地面下方。

相機(jī)的up坐標(biāo)

在上例中，比較特殊的一個(gè)操作是 g3d.setUp(0, 1, 0)。這里是指設(shè)置相機(jī)的 up 坐標(biāo)。在計(jì)算機(jī)圖形學(xué)中，相機(jī)的 up 坐標(biāo)通常是指相機(jī)坐標(biāo)系中的一個(gè)向量，用于定義相機(jī)的上方向。

例如在一個(gè)場(chǎng)景中，在水平面上有一棟房子，如果相機(jī)的 up 坐標(biāo)是 (0,1,0)，則相機(jī)將看到一個(gè)朝上的房子。如果相機(jī)的 up 坐標(biāo)是(1,0,0)，則相機(jī)將看到一個(gè)朝右的房子和豎直的地面（整個(gè)視角都會(huì)旋轉(zhuǎn)）。在 HT for Web 中，默認(rèn)的相機(jī) up 坐標(biāo)是 [0, 1, 0]，也就是我們會(huì)看到一個(gè)正常的朝上的房子。

OBJ模型

HT 的 3D 場(chǎng)景支持 FBX，OBJ，GLTF 等多種模型格式。這里我們選擇比較通用的 OBJ 模型來(lái)進(jìn)行舉例。

要使用 OBJ 模型，首先需要在 index.html 中引入 ht-obj.js 插件：

加載OBJ模型

通過(guò)使用 ht.Default.loadObj() 方法可以將 OBJ 模型加載到內(nèi)存中。在執(zhí)行l(wèi)oadObj() 時(shí)，需要配置 OBJ 路徑，材質(zhì)路徑以及相關(guān)參數(shù)。其中參數(shù) params 的詳細(xì)說(shuō)明可以從以下連接獲?。?/p>

它里面比較常用的幾個(gè)參數(shù)有：

/**

* 加載 obj 模型

*

* @param {*} modelName

* @return {*}

*/

function loadObj(objPath, mtlPath, modelName) {

return new Promise((resolve, reject) => {

/**

* 模型參數(shù)，具體參數(shù)參考：https://www.hightopo.com/guide/doc/global.html#LoadObjParams

*/

const params = {

center: true,

prefix: 'obj/',

shape3d: modelName,

finishFunc: (modelMap, array, rawS3) => {

resolve({modelMap, array, rawS3});

},

};

// 加載模型

ht.Default.loadObj(objPath, mtlPath, params);

});

}

其中的 shape3d 參數(shù)是一個(gè)自定義字符串，可以將該字符串理解為我們?yōu)槟Ｐ团渲昧艘粋€(gè)名字。HT 在加載完 OBJ 模型后，它會(huì)把該模型存儲(chǔ)到內(nèi)存中。存儲(chǔ)的方式就是通過(guò) ht.Default.setShape3dModel(name, model) 方法。

在上面的代碼中，我們?yōu)橐虞d的模型起了一個(gè)名字：modelName。在想使用該模型的時(shí)候，再通過(guò)ht.Default.getShape3dModel(name) 方法便可把模型從內(nèi)存中取出來(lái)。

將Obj模型添加到3D場(chǎng)景

在上面的 loadObj() 只是將 OBJ 模型添加到了內(nèi)存中。我們還需要在之后將 OBJ 模型添加到場(chǎng)景中。

由于 loadObj() 方法為異步執(zhí)行，因此其參數(shù)里面需要攜帶一個(gè) finishFunc 作為回調(diào)參數(shù)。為了減少代碼層級(jí)，我們將上面的方法封裝成了Promise 性質(zhì)。后面我們可以等待這個(gè) Promise 完成后再執(zhí)行添加動(dòng)作。

const MODELS = {

// 直升機(jī)

HELICOPTER: {

name: 'helicopter',

obj: 'obj/helicopterhspt_1002_01.obj',

mtl: 'obj/helicopterhspt_1002_01.mtl',

},

// 螺旋槳

PROPELLER: {

name: 'propeller',

obj: 'obj/helicopterhspt_1002_02.obj',

mtl: 'obj/helicopterhspt_1002_02.mtl',

},

};

/**

* 加載模型；模型初始化；創(chuàng)建模型Node; 添加模型到3D場(chǎng)景中

*

* @return {*}

*/

async function createObj(name, obj, mtl) {

const objInfo = await loadObj(obj, mtl, name); // 加載計(jì)量表模型，此處為異步

// * @param {*} modelMap 調(diào)用ht.Default.parseObj解析后的返回值，若加載或解析失敗則返回值為空

// * @param {*} array 所有材質(zhì)模型組成的數(shù)組

// * @param {*} rawS3 包含所有模型的原始尺寸

const {modelMap, array, rawS3} = objInfo;

console.log('createObj: ', objInfo);

if (!modelMap) {

return;

}

// 創(chuàng)建 Node 用來(lái)存放該模型，后續(xù)對(duì)模型的操作通過(guò)該 Node 進(jìn)行

const node = new ht.Node();

node.s({

'shape3d': name, // 對(duì)應(yīng)ht.Default.getShape3dModel(name)注冊(cè)的模型

'shape3d.scaleable': false

});

node.setSize3d(rawS3); // 存放模型在三個(gè)坐標(biāo)軸方向上的大小。簡(jiǎn)寫(xiě)：node.s3()

node.setPosition3d(0, 0, 0); // 此處可以將其放到水平面上。簡(jiǎn)寫(xiě)：node.p3()

dm.add(node);

return node;

}

const helicopterNode = await createObj(MODELS.HELICOPTER.name, MODELS.HELICOPTER.obj, MODELS.HELICOPTER.mtl);

const propellerNode = await createObj(MODELS.PROPELLER.name, MODELS.PROPELLER.obj, MODELS.PROPELLER.mtl);

直升機(jī)模型分為兩部分，分別是機(jī)體和螺旋槳。由于他們是兩個(gè)模型，因此需要分別添加。

在 loadObj 結(jié)束后，HT 會(huì)將模型通過(guò) ht.Default.setShape3dModel(name, model) 注冊(cè)到內(nèi)存中，之后會(huì)給 finishFunc 傳遞三個(gè)參數(shù)：modelMap, array, rawS3。其解釋參考上面代碼注釋。目前我們用到的只有 rawS3 參數(shù)，也就是模型尺寸（大小）。

有了模型和尺寸（大?。?，我們便可以創(chuàng)建 ht.Node 用來(lái)對(duì)模型進(jìn)行管理。將模型添加到 3D 場(chǎng)景中進(jìn)行管理的主要邏輯如下：

模型 -(綁定到)→ ht.Node -(添加到)→ dataModel -(綁定到)→ Graph3dView

這里面的一個(gè)關(guān)鍵步驟是設(shè)置 ht.Node 的 shape3d 屬性。由于在 loadObj 的時(shí)候系統(tǒng)已經(jīng)對(duì)模型進(jìn)行注冊(cè)，因此這里我們只需要通過(guò)將注冊(cè)的模型名稱賦值給 ht.Node 的 shape3d 屬性，HT 便可自動(dòng)匹配到內(nèi)存中對(duì)應(yīng)的 OBJ 模型。

需要注意的是：在加載了模型并將模型綁定到 ht.Node 后并不能使其在 3D 場(chǎng)景中顯示。只有通過(guò) dataModel.add(node) 將節(jié)點(diǎn)添加到 3D 場(chǎng)景對(duì)應(yīng)的數(shù)據(jù)模型中時(shí)，HT 才會(huì)在場(chǎng)景中將模型渲染出來(lái)。

模型位置

在上圖中我們可以發(fā)現(xiàn)，直升機(jī)和螺旋槳重合了，并且二者也不在地面上。這里我們?cè)敿?xì)解釋一下。

仔細(xì)查看代碼，在創(chuàng)建 ht.Node 時(shí)，我們執(zhí)行了下面的操作：

node.setSize3d(rawS3); // 存放模型在三個(gè)坐標(biāo)軸方向上的大小。簡(jiǎn)寫(xiě)：node.s3()

node.setPosition3d(0, 0, 0); // 此處可以將其放到水平面上。簡(jiǎn)寫(xiě)：node.p3()

這兩行命令分別是設(shè)置節(jié)點(diǎn)的大小和位置。這里的節(jié)點(diǎn)尺寸采用的是模型尺寸。而位置默認(rèn)放到的坐標(biāo)系中心點(diǎn)。

由于在 3D 場(chǎng)景中，ht.Node 的默認(rèn)錨點(diǎn)是 [0.5, 0.5, 0.5]，也就是在模型的三維中心點(diǎn)。因此其位置坐標(biāo)也要對(duì)應(yīng)到其中心點(diǎn)。這樣，模型就會(huì)有一半在網(wǎng)格上方，另一半在網(wǎng)格下方。

該如何將直升機(jī)放到地平面上呢？我們可以通過(guò)模型的高度來(lái)計(jì)算出對(duì)應(yīng)的位置從而將模型放到地平面上。具體代碼如下：

// 由于默認(rèn)創(chuàng)建 Node 的時(shí)候，其錨點(diǎn)是在 [0.5, 0.5, 0.5]，位置是在 [0, 0, 0]。導(dǎo)致模型并不在水平面以上。

let size3d = helicopterNode.getSize3d(); // 獲取直升機(jī)模型的 [長(zhǎng),寬,高]

let height = size3d[1]; // 獲取模型高度

helicopterNode.setPosition3d([0, height/2, 0]); // 將直升機(jī)放到地面上

而對(duì)于螺旋槳，情況又有些復(fù)雜。這里需要一些技巧才能將其配置到合適的位置。

我們過(guò)手動(dòng)調(diào)整螺旋槳來(lái)獲取其應(yīng)該擺放的位置和角度。這里就用到了g3d.setEditable(true)功能。打開(kāi)編輯功能后，選中模型，場(chǎng)景中會(huì)顯示坐標(biāo)軸，通過(guò)拖動(dòng)不同的坐標(biāo)軸我們可以對(duì)模型進(jìn)行移動(dòng)，旋轉(zhuǎn)和縮放。

將螺旋槳移動(dòng)到機(jī)體合適的位置后，在console中通過(guò) node.getPosition3d() 和 node.getRotation3d() 來(lái)獲取螺旋槳當(dāng)前的位置和角度：

然后配置到代碼中。與此同時(shí)，我們通過(guò) setHost() 將螺旋槳吸附到了直升機(jī)上。這樣，后面直升機(jī)移動(dòng)時(shí)會(huì)帶著螺旋槳移動(dòng)。使二者不會(huì)脫離。

propellerNode.setRotation3d([0.10506443461595279, 4.550746858974086, -0.007825951889059535]); // 讓螺旋槳水平

propellerNode.setPosition3d([0, 215, -99.00152946490829]); // 將螺旋槳放到直升機(jī)上

propellerNode.setHost(helicopterNode); // 螺旋槳吸附到直升機(jī)上

直升機(jī)動(dòng)畫(huà)

在直升機(jī)和螺旋槳都加載完成后，我們現(xiàn)在就可以為其增加相應(yīng)的動(dòng)畫(huà)。

這里的動(dòng)畫(huà)分為兩部分：

1. 螺旋槳旋轉(zhuǎn)

2. 直升機(jī)移動(dòng)

/**

* 循環(huán)前進(jìn)與后退

*

* @param {*} node

*/

function startAnim(node) {

const p1 = node.p3(); // 原始位置

const p2 = [p1[0], p1[1], p1[2] - 400]; // 目標(biāo)位置，

const forwardParams = {

duration: 3 * 1000, // 動(dòng)畫(huà)幀數(shù)

easing: (t) => { return t; }, // 動(dòng)畫(huà)緩動(dòng)函數(shù)，默認(rèn)采用`ht.Default.animEasing`

finishFunc: () => {

ht.Default.startAnim(backwardParams);// 循環(huán)播放該動(dòng)畫(huà)

}, // 動(dòng)畫(huà)結(jié)束后調(diào)用的函數(shù)。

action: (v, t) => { // action函數(shù)必須提供，實(shí)現(xiàn)動(dòng)畫(huà)過(guò)程中的屬性變化。

node.setPosition3d( // 此例子展示將節(jié)點(diǎn)`node`從位置`p1`動(dòng)畫(huà)到位置`p2`。

p1[0] + (p2[0] - p1[0]) * v,

p1[1] + (p2[1] - p1[1]) * v,

p1[2] + (p2[2] - p1[2]) * v,

);

}

};

const backwardParams = {

duration: 3 * 1000, // 動(dòng)畫(huà)幀數(shù)

easing: (t) => { return t; }, // 動(dòng)畫(huà)緩動(dòng)函數(shù)，默認(rèn)采用`ht.Default.animEasing`

finishFunc: () => {

ht.Default.startAnim(forwardParams);// 循環(huán)播放該動(dòng)畫(huà)

}, // 動(dòng)畫(huà)結(jié)束后調(diào)用的函數(shù)。

action: (v, t) => { // action函數(shù)必須提供，實(shí)現(xiàn)動(dòng)畫(huà)過(guò)程中的屬性變化。

node.setPosition3d( // 此例子展示將節(jié)點(diǎn)`node`從位置`p1`動(dòng)畫(huà)到位置`p2`。

p2[0] + (p1[0] - p2[0]) * v,

p2[1] + (p1[1] - p2[1]) * v,

p2[2] + (p1[2] - p2[2]) * v,

);

}

};

ht.Default.startAnim(forwardParams);

}

/**

* 螺旋槳旋轉(zhuǎn)動(dòng)畫(huà)

*

*/

function startPropellerAnim(node) {

setInterval(() => {

const r3 = node.getRotation3d();

node.setRotation3d([r3[0], r3[1] + 0.4, r3[2]]); // 繞 Y 軸旋轉(zhuǎn)。單位：弧度

}, 20);

}

螺旋槳旋轉(zhuǎn)動(dòng)畫(huà)比較簡(jiǎn)單。我們只需要讓其繞著 y 軸轉(zhuǎn)動(dòng)就可以了。這里我們利用 setInterval() 起一個(gè)定時(shí)器，每隔 20 毫秒讓其沿著 y 軸旋轉(zhuǎn) 0.4°。

關(guān)于直升機(jī)動(dòng)畫(huà)，我們?yōu)槠湔伊藘蓚€(gè)點(diǎn)，讓它在這兩點(diǎn)之間來(lái)回移動(dòng)。在動(dòng)畫(huà)的實(shí)現(xiàn)上，我們依然采用前幾篇文章提到的 ht.Default.startAnim() 方法。具體實(shí)現(xiàn)見(jiàn)上面代碼部分。

總結(jié)

這篇文章介紹了如何使用 HT for Web 的 Graph3dView 和 OBJ 模型來(lái)創(chuàng)建 3D 場(chǎng)景。里面介紹了 3D 的一些基本概念以及 3D 場(chǎng)景的基本搭建與配置。另外，除了 3D 場(chǎng)景，我這里還重點(diǎn)描述了如何加載 OBJ 文件，如何添加模型節(jié)點(diǎn)到 3D 場(chǎng)景中，以及如何為節(jié)點(diǎn)添加動(dòng)畫(huà)。希望這些基本知識(shí)能對(duì)大家有所幫助。

審核編輯 黃宇