HT for Web 建模手册

索引

概述

HT for 3D Web提供了六面体、 shape3d上预定义的球体、圆柱体等多种常规三维模型， ht.Shape类型可实现墙面、管道和多边形等三维模型效果， 本手册将介绍更灵活的自定义三维模型功能，以满足不同行业设备及不同环境场景的建模需求。

自定义3D模型具有以下优点：

本手册介绍的部分扩展模型库的函数，由ht-modeling.js的建模扩展包提供。

模型基础

3D模型是由最基础的三角形面拼接合成，例如1个矩形可以由2个三角形构成，1个立方体由6个面即12个三角形构成， 以此类推更复杂的模型可以由许多的小三角形组合合成。因此3D模型定义即为对构造模型的所有三角形的描述， 而每个三角形由三个顶点vertex构成， 每个顶点vertex由x,y,z三维空间坐标决定，HT采用右手螺旋定则来确定三个顶点构造三角形面的正面。

最简单的3D模型描述方式就是由一个顶点数组来描述，例如p1-p2-p3这三个点构成的三角形， 可用数组[p1.x, p1.y, p1.z, p2.x, p2.y, p2.z, p3.x, p3.y, p3.z]来描述，更多三角形如下图所示：

以上这种描述方式格式简单较容易理解，但重复数据较多，例如上图中顶点1、2和3分别在T1、T2和T3的三角形定义中重复描述， 因此可采用顶点和三角形分离描述的方式，即用两个数组，一个数组描述顶点vertices，HT中简称vs， 一个数组描述三角形对应顶点的索引indices，HT中简称is。上图对于的索引描述方式如下：

从几何模型角度以上的定义已足够构建一个完整3D模型，界面呈现一般还需要定义颜色或贴图决定渲染效果， 采用贴图的渲染方式需要对每个顶点定义其对应的贴图位置信息， UV Mapping参见六面体章节， HT中简称为uv。如果模型只用普通颜色渲染，则可不定义该参数。

三维场景模型显示效果还取决于每个三角形面法线向量与光线的夹角，法线向量normal在HT的模型中以ns的简称代表， 一般HT可根据顶点自动计算ns信息，但有些模型为实现特殊的渲染效果，每个顶点可通过ns指定对应的法线向量值， 可参考Phong shading进行理解。

以下定义模型均采用在xzy轴大小为1范围内的立方体作为参考，[0,0,0]对应于图元的中心位置， 如果xzy轴的点坐标绝对值超过0.5则意味着超出图元size3d定义的大小。

模型注册

通过ht.Default.setShape3dModel(name, model)函数，可注册自定义3D模型：

综上所述，自定义模型的流程为：

类似2D图片不需要全局注册，可直接将内容设置的图元属性node.setImage('www.google.com/logo.png')的方式，3D也支持这种简化的方式， 将构建3D的JSON模型对象直接设置到图元属性：node.setStyle('shape3d', dragonModel)，但这种方式对于DataModel序列化数据导出是不利的， 这种方式导致相同模型的图元重复输出3D模型信息，而且3D模型信息一般数据量很大，不建议与DataModel的整体模型信息一起导出， 我们一般视3D模型信息和图片信息同为外围资源信息，建议与DataModel数据模型信息分开存储管理。

建模函数

自定义3D模型非常灵活强大，但对于复杂模型，手写顶点工作量和难度很高，为此HT抽象了几类模型，提供了函数API的便捷构建方式， 以下函数除createFrameModel如要引入ht-modeling.js扩展包外，其余都已由ht.js提供：

createBoxModel

ht.Default.createBoxModel()构建六面体模型，该模型的六个面显示的颜色和贴图都将一样

createSphereModel

ht.Default.createSphereModel(side, sideFrom, sideTo, from, to, resolution)构建球体模型

createSmoothSphereModel

ht.Default.createSmoothSphereModel(hResolution, vResolution, hStart, hArc, vStart, vArc, radius)构建光滑球体模型

createCylinderModel

ht.Default.createCylinderModel(side, sideFrom, sideTo, from, to, top, bottom)构建圆柱体模型

createSmoothCylinderModel

ht.Default.createSmoothCylinderModel(resolution, top, bottom, topRadius, bottomRadius, start, arc, height)构建光滑圆柱体模型

createConeModel

ht.Default.createConeModel(side, sideFrom, sideTo, from, to, bottom)构建圆锥体模型

createSmoothConeModel

ht.Default.createSmoothConeModel(bottom, resolution, start, arc, radius)构建光滑圆锥体模型

createTorusModel

ht.Default.createTorusModel(side, sideFrom, sideTo, from, to, radius, resolution)构建圆环体模型

createSmoothTorusModel

ht.Default.createSmoothTorusModel(radius, tubeRadius, hResolution, vResolution, start, arc)构建光滑圆环体模型

createRoundRectModel

ht.Default.createRoundRectModel(top, bottom)构建圆角矩形体模型

createStarModel

ht.Default.createStarModel(top, bottom)构建星形体模型

createRectModel

ht.Default.createRectModel(top, bottom)构建矩形体模型

createTriangleModel

ht.Default.createTriangleModel(top, bottom)构建三角形体模型

createRightTriangleModel

ht.Default.createRightTriangleModel(top, bottom)构建直角三角形体模型

createParallelogramModel

ht.Default.createParallelogramModel(top, bottom)构建平行四边形体模型

createTrapezoidModel

ht.Default.createTrapezoidModel(top, bottom)构建梯形体模型

createExtrusionModel

ht.Default.createExtrusionModel(array, segments, top, bottom, resolution, repeatUVLength, tall, elevation)根据xz平面多边形，挤压形成3D模型。

createRingModel

ht.Default.createRingModel(array, segments, resolution, top, bottom, side, sideFrom, sideTo, from, to)根据xy平面的曲线，环绕一周形成3D模型。

createSmoothRingModel

ht.Default.createSmoothRingModel(array, segments, vResolution, start, arc, hResolution)根据xy平面的曲线，环绕一周形成光滑3D模型。

createFrameModel

ht.Default.createFrameModel(dx, dy, dz, params)构建框架体模型

模型属性

除了模型基础章节介绍的构建模型顶点相关的基础属性外，模型JSON对象还可定义以下属性：

以下属性值默认取至style的相应shape3d.*，如果模型上进行设置，则模型上的定义具有更高优先级：

模型组合

较为复杂的模型往往需要多个小模型组合而成，采用目前掌握的知识可通过多个Node图元分别设置不同部位模型的shape3d属性实现， 如果需要多个部分粘在一起的效果，可通过将这些Node图元相互通过Node#setHost函数相互环状吸附在一起。 但这样的解决方案会导致对象管理的不方便，例如一把椅子可有由四条腿和一个平面组成，但从对象管理角度或用户使用角度， 更希望整个椅子就是一个Node对象，在TreeView视图上仅为一个节点，这种情况就是使用模型组合功能的最佳场合了。

组合模型的定义非常简单且灵活，以Array数组方式即可组合多个模型

ht.Default.setShape3dModel('A', modelA);
ht.Default.setShape3dModel('B', modelB);
ht.Default.setShape3dModel('C', ['A', 'B']);

以上代码分别定义了A、B和C三种模型，其中模型C为A和B两种模型的组合。

ht.Default.setShape3dModel('E', ['A', 'B', 'sphere', modelD])

组合模型的数组元素不仅可为新定义的模型名称，还可为预定义的模型名称，以及直接为模型JSON对象， 以上代码定义了新模型E，该模型由自定义的A和B模型，预定义的sphere球体，以及modelD四个模型组合而成。

ht.Default.setShape3dModel('F', [
    {
        shape3d: 'box',
        color: 'yellow'
    },
    {
        shape3d: 'box',
        s3: [0.5, 0.5, 1.1],
        color: 'red'
    }
]);

模型属性章节的属性不仅可设置在模型的JSON对象上，也可以直接在组合模型数组中的新元素对象上设置， 以上代码定义了新模型F，其由两个box模型组合而成，模型类型由shape3d的元素属性定义，还可设置color和s3等模型参数。

ht.Default.setShape3dModel('G', [
    {
        shape3d: ['cylinder', {shape3d: 'cone', color: 'green', t3: [1, 0, 0]}],
        color: 'yellow',
        t3: [-0.5, 0, -1]
    },
    {
        shape3d: 'box',
        s3: [0.3, 0.3, 0.3],
        color: 'red'
    }
]);

组合数组元素对象的shape3d属性值，依然可为数组类型，以实现无限递归的组合层次嵌套，以上代码定义的G模型呈现效果如下图：

数据绑定

详见数据绑定手册

扩展类型

HT提供了众多基础图元类型，但为快速构建房间楼宇即各种场景装饰物，在建模扩展包种增加了更多的图元类型，方便用户用API或可视化编辑工具快速搭建项目场景。

Symbol

ht.Symbol继承于ht.Node，常用于展示花盆、公告牌等装饰物的平面图片，其默认设置了all.visible为false，重载了setIcon函数， 在设置icon的同时通过addStyleIcon将图片也用于显示在Graph3dView上。使用Symbol一般只需要再构造函数或通过setIcon传入参数， 然后设置p3位置即可。

setIcon函数会返回注册的json对象，可用于再设置额外的参数，可参见3D手册图标章节

CSGNode

CSG是 Constructive Solid Geometry 建模技术的简称， 通过裁剪subtract、融合union和相交intersect的运算，组合出复杂模型效果，HT封装了ht.CSGNode和ht.CSGShape等 图元类型来支持CSG的组合功能，常用于墙面的门窗挖空凿洞的应用场景。

ht.CSGNode继承于ht.Node，当style的shape3d属性为空时显示为六面体效果，CSGNode如果通过setHost吸附到 宿主CSGNode或CSGShape后，宿主CSGNode或CSGShape可与吸附的CSGNode图元进行CSG的组合建模。

当宿主CSGNode或CSGShape进行组合生成新的模型部分的渲染由csg.*的参数来控制，与all.*等六面体的其他面的控制方式一致， 参见3D手册的六面体章节。

需要注意的是并没有csg.uv，csg.uv.scale和csg.uv.offset等贴图相关参数，csg相关表面的uv值由吸附者的六面贴图相关参数决定， 只有贴图图片参数由host的csg.image参数决定。

可以把CSG.*理解为除left/rigth/top/bottom/front/back外的第七个面

CSGBox

ht.CSGBox继承于ht.CSGNode，其除具备父类CSGNode的挖空等功能外，还可对六个面进行旋转展开关闭的操作， 因此增加了以下面相关style属性，由于六个面的参数一致，以下仅以front进行说明：

以上的front.expanded和front.angle这两个参数一般无需用户直接操作，ht.CSGBox提供了以下函数封装， 参见表单手册 Unboxing 例子

注意以上面相关参数并无all.*的对应六面统一参数，CSGBox的相关面参数只能每个面独立设置

DoorWindow

ht.DoorWindow继承于ht.CSGNode，其除具备父类CSGNode的挖空等功能外，还可进行整体的旋转展开关闭的操作， 常用于作为门或窗的业务对象，吸附于CSGNode或CSGShape的host作为墙面的图元， DoorWindow增加了以下style参数进行控制，其中dw为DoorWindow的简称：

DoorWindow类型还可以与OBJ格式的3D模型结合，显示更为逼真的门窗效果，参见OBJ手册的 门窗应用例子

CSGShape

ht.CSGShape继承于ht.Shape，目前仅支持忽略segments参数的折线墙面效果，CSGNode如果通过setHost吸附到宿主CSGShape后， CSGShape可与吸附的CSGNode图元进行CSG的组合建模。

当吸附者CSGNode设置了以上style参数后，则其会自动调节自身大小、位置和旋转角度，使其保持定位在Shape对应的线段上， 该功能不仅适用于ht.CSGShape，也适用于ht.Shape的父类图元。

CSGShape类型对ht.Shape进行了简化，除不支持segments参数外，还无效了setRotation、setRotationX和setRotationZ旋转功能。

欢迎交流 service@hightopo.com