索引

• 概述
• 二维
  • 基础属性
  • 样式属性
  • 管线差异
  • 吸附功能
• 三维
  • 地板类型
  • 墙面类型
  • 管道类型
  • 空间管线
  • 挖空墙面
  • 旋转功能

概述

HT提供的ht.Shape是极其强大的图元类型，其在GraphView和Graph3dView组件上都能展示出各种二维和三维的形状效果， 其扩展子类ht.Polyline可实现三维空间管道的功能，扩展子类ht.CSGShape可实现挖空等功能效果，本手册将逐一进行详细介绍。

二维

基础属性

ht.Shape类型在GraphView组件上用于呈现多边形图元，其形状主要由points和segments这两个属性描述： points为ht.List类型数组的顶点信息，顶点为{x:100, y:200}格式的对象；segments为ht.List类型的线段数组信息， 线段为1~5的整数，分别代表不同的顶点连接方式。

如果segments为空，则代表points数组中的顶点按数组顺序依次直线连接，因此直线段的类型无需设置segments参数。 segments主要用于需要绘制曲线，或者有跳跃断点的情况，其1~5的取值含义说明如下：

• 1: moveTo，占用1个点信息，代表一个新路径的起点
• 2: lineTo，占用1个点信息，代表从上次最后点连接到该点
• 3: quadraticCurveTo，占用2个点信息，第一个点作为曲线控制点，第二个点作为曲线结束点
• 4: bezierCurveTo，占用3个点信息，第一和第二个点作为曲线控制点，第三个点作为曲线结束点
• 5: closePath，不占用点信息，代表本次路径绘制结束，并闭合到路径的起始点

ht.Shape的主要属性函数：

• getPoints()和setPoints(points)获取和设置点数组，参数为Array类型则内部转换成ht.List，为空则清除所有点
• addPoint(point, index)在指定的索引位置插入新点，index为空则插入到最后
• setPoint(index, point)在指定的索引位置替换新点
• removePointAt(index)删除指定索引位置的点
• toPoints()拷贝一份新的ht.List类型顶点数组
• segments属性为Array或ht.List类型，用于描述点连接样式，数组元素为整型值:
  • 1: moveTo，占用1个点信息，代表一个新路径的起点
  • 2: lineTo，占用1个点信息，代表从上次最后点连接到该点
  • 3: quadraticCurveTo，占用2个点信息，第一个点作为曲线控制点，第二个点作为曲线结束点
  • 4: bezierCurveTo，占用3个点信息，第一和第二个点作为曲线控制点，第三个点作为曲线结束点
  • 5: closePath，不占用点信息，代表本次路径绘制结束，并闭合到路径的起始点
• isClosePath()和setClosePath(true)获取和设置多边形是否闭合，默认为false，墙面类型通过设置闭合可无缝连接起始点
• getLength(resolution)获取多边形长度，resolution为曲线微分片数，不传入则HT会采用系统默认值

ht.Shape类型的points值与width、height和position这三个大小和位置信息存在联动关系， 即修改points会影响width、height和position相应值，同理修改width、height和position值也会影响points信息。

样式属性

ht.Shape相关的style属性：

• shape.border.width边框宽度，默认值为0表示不绘制边框
• shape.border.color边框颜色
• shape.border.cap边框末端线帽的样式，可选参数为butt|round|square
• shape.border.join边框当两条线交汇时创建边角的类型，可选参数为bevel|round|miter
• shape.border.pattern显示虚线样式，Array类型，例如[5, 5]
• shape.background背景填充颜色，为null代表不填充背景
• shape.gradient渐近色类型：
  • 为空代表不绘制渐近色效果，只用shape.background纯色填充背景。
  • 支持类型：'linear.southwest','linear.southeast','linear.northwest','linear.northeast', 'linear.north','linear.south','linear.west','linear.east', 'radial.center','radial.southwest','radial.southeast','radial.northwest','radial.northeast', 'radial.north','radial.south','radial.west','radial.east', 'spread.horizontal','spread.vertical','spread.diagonal','spread.antidiagonal', 'spread.north','spread.south','spread.west','spread.east'
• shape.gradient.color背景渐近颜色
• shape.repeat.image填充重复背景的图片，注意这里的图片不支持矢量
• shape.dash是否显示虚线，默认值为false
• shape.dash.pattern虚线样式，默认值为[16, 16]
• shape.dash.offset虚线偏移，默认值为0
• shape.dash.color虚线颜色
• shape.dash.width虚线宽度，默认为空代表采用shape.border.width值
• shape.dash.3d虚线是否显示3d效果，默认值为false
• shape.dash.3d.color虚线3d效果颜色，为空采用默认白色，呈现3d效果时连线的中间部分为该颜色
• shape.dash.3d.accuracy虚线3d效果精确度，该值越小3d渐进效果越好但影响性能，一般情况无需修改

管线差异

ht.Polyline类型继承于ht.Shape，其更多表现出与ht.Edge连线类似的特性，因此ht.Polyline上 的label、note和icons等附属部分位置和方向与连线类型类似会考虑折线的角度，从以下例子可只看出两者附件摆放的差异。

从以上例子可发现ht.Polyline关闭了setRotation的旋转功能，更多差异见空间管线章节

吸附功能

ht.Node图元通过setHost(host)函数可吸附到另外一个图元上，这样host图元进行移动和旋转时都会带动attach的吸附图元。 当host图元为ht.Shape类型时，则如果attach图元设置上attach.*的相关属性，可使得图元吸附到ht.Shape的指定线段位置上。

• attach.index：默认值为-1，指定吸附到ht.Shape图元所在线段索引
• attach.offset：默认值为0，指定吸附在ht.Shape图元所在线段偏移位置
• attach.offset.relative：默认值为false，如果为true则偏移量代表所在线段长度乘以attach.offset值
• attach.offset.opposite：默认值为false，指定吸附到ht.Shape图元所在线段的正方向还是反方向偏移
• attach.gap：默认值为0，指定吸附到ht.Shape图元所在线段垂直方向的偏移
• attach.gap.relative：默认值为false，如果为true则与线段垂直方向的偏移为所ht.Shape的thickness值乘以attach.gap
• attach.thickness：默认值为空，CSGNode默认值为1.001，为正值时吸附图元height属性值由host的thickness乘该值决定

吸附到ht.Shape线段的功能目前不支持segments设置为曲线的情况，也不考虑ht.Shape设置了rotation旋转值的因素， 当图元吸附到ht.Shape线段之后，其rotation和position位置会根据ht.Shape的自动变化同步；如果设置了attach.thickness值， 则图元的height也会根据host的thickness值自动调节，这些联动属性一般不需要用户设置。

三维

地板类型

ht.Shape图元当thickness属性小于0时常用于呈现地板效果的多边形模型，这种类型下tall属性决定地板的厚度， 一般常通过floor.setElevation(floor.getTall()/2);的方式将地板设置在海平面上。

地板类型由shape3d.top.*控制顶面参数，shape3d.bottom.*控制底面参数，shape3d.*控制厚度四周参数。 对于只需要平面不需要立体效果的情况，可通过将shape3d.bottom.visible和shape3d.visible的底面和四周可见参数设置为false实现。

GraphView的二维上ht.Shape实现平铺贴图可通过shape.repeat.image属性设置，Graph3dView三维的平铺 可通过shape3d.top.uv.scale和shape3d.top.bottom.scale控制，但这种方式如果地板的大小发生变化时， 一般还需要再设置参数因此并不方便，HT提供的repeat.uv.length参数可解决这种问题，通过设置该参数， 贴图会根据图形大小自动调节平铺图片数，而且还能与shape3d.top.uv.scale和shape3d.top.bottom.scale的参数进行叠加， 当然大部分情况下如果设置了repeat.uv.length，就不需要设置shape3d.top.uv.scale和shape3d.top.bottom.scale参数。

墙面类型

ht.Shape图元当thickness属性大于0时常用于呈现墙面效果的多边形模型，这种类型下tall属性决定墙面的高度， thickness代表墙厚度，一般常通过wall.setElevation(wall.getTall()/2);的方式将墙面设置在海平面上。

处于墙面类型时，模型相当于长条的六面体，因此可通过all.*、left.*或right.*等六面体参数进行控制， 参见3D手册六面体章节

管道类型

ht.Shape图元当shape3d属性为cylinder时，图元呈现为圆筒管道的模型效果，tall和thickness决定圆筒切面的宽高值， 当tall和thickness值一样时呈现为圆形切面，管道的走向由points和segments决定。

管道由shape3d.top.*控制顶面参数，shape3d.bottom.*控制底面参数，shape3d.*控制管道走向的中间部分效果。 通过将shape3d.top.visible和shape3d.bottom.visible设置为false，可实现空心管道的效果。

空间管线

以上介绍的类型都是基于{x: 10, y: 20}的二维点信息描述图形走向，ht.Polyline继承于ht.Shape， 支持{x: 10, y: 20, e: 30}格式的三维空间点描述，如果e值为空则取elevation的海拔值， 修改ht.Polyline的elevation和tall值时，会自动调节points顶点中的e值； 同理points顶点信息变化也会同步修改ht.Polyline的elevation和tall值。

• x代表三维的x轴坐标
• y代表三维的z轴坐标，参见3D手册
• e代表三维的y轴坐标，可理解为elevation的简写，代表三维y轴的海拔高度

ht.Polyline同样支持基础属性章节介绍的segments参数，实现从二维的平面曲线延伸到了三维的空间曲线效果。 ht.Polyline关闭了 setClosePath 函数功能。

ht.Edge和ht.Polyline在展示效果上是很类似的，只不过ht.Edge的起始和结束点来自于source和target节点， ht.Edge的edge.type属性为points时，edge.points和edge.segments对应于 ht.Polyline的points和segments属性，此时edge.points的顶点信息也可为{x: 10, y: 20, e: 30}的三维顶点格式， 其中e值为空时代表0。

ht.Edge和ht.Polyline都有两种展示方式，默认显示为普通线框效果，当shape3d设置为cylinder时则显示为立体管线的效果， HT通过微分段的方式实现曲线，因此为达到更高的均分曲线效果，两种方式都可通过shape3d.resolution控制曲线微分段数。

• 普通线框效果：

  • ht.Edge通过edge.width控制宽度
  • ht.Edge通过edge.color控制颜色
  • ht.Edge通过edge.gradient.color控制颜色
  • ht.Polyline通过shape.border.width控制宽度
  • ht.Polyline通过shape.border.color控制颜色

  • ht.Polyline通过shape.border.gradient.color控制渐进色

• 立体管线的效果

  • ht.Edge通过edge.width控制宽度
  • ht.Polyline通过thickness控制宽度
  • ht.Edge和ht.Polyline都可通过shape3d.*控制颜色和贴图等其他样式参数
  • ht.Edge和ht.Polyline都可通过shape3d.side控制管道截面边数，如设置为6，则显示为六面体截面
  • ht.Edge和ht.Polyline都可通过shape3d.start.angle控制管道截面起始边的角度
  • ht.Edge和ht.Polyline都可通过shape3d.sweep.angle控制管道截面的跨越角度，默认是 2 PI
  • ht.Edge和ht.Polyline都可通过repeat.uv.length控制贴图在管道走向方向上的自动平铺次数
  • ht.Edge和ht.Polyline都通过shape3d.top.cap和shape3d.bottom.cap控制起始结束部分，可取值如下：
    • undefined：默认值，代表镂空不封闭
    • flat：代表平面进行封闭
    • round：代表圆形体进行封闭

Edge和Polyline处于普通线框效果时可实现虚线的功能，有两种虚线效果：

• 实空交替：

  • ht.Edge通过edge.pattern控制虚线模式，默认为空，设为[20, 10]代表一段长度20的实线，一段长度10的镂空，重复交替

  • ht.Polyline通过shape.border.pattern控制虚线模式，默认为空，设为[20, 10]代表一段长度20的实线，一段长度10的镂空，重复交替

• 颜色交替：

  • ht.Edge通过edge.dash控制是否启用颜色交替虚线，默认为false
  • ht.Edge通过edge.dash.pattern控制虚线模式，默认为[16, 16]代表长度16的edge.dash.color颜色，和长度16的edge.coor颜色重复交替
  • ht.Polyline通过shape.dash控制是否启用颜色交替虚线，默认为false
  • ht.Polyline通过shape.dash.pattern控制虚线模式，默认为[16, 16]代表长度16的shape.dash.color颜色，和长度16的shape.border.coor颜色重复交替

Graph3dView默认关闭虚线功能，如需启用可通过graph3dView.setDashDisabled(false)启动虚线绘制功能。

挖空墙面

吸附功能章节介绍ht.Node可吸附到ht.Shape类型线段上， 当引入ht-modeling.js的建模扩展包后， 通过继承于ht.Node的CSGNode，和继承于ht.Shape的ht.CSGShape，可实现多边形墙面挖空的效果。

以上例子将attach.thickness设置为1.001,将高度设置为了setTall(80.001)， 此处的尾数0.001是为避免js浮点数运算的误差多预留的尺寸。

CSGNode的attach.operation属性默认值为subtract，代表可对CSGNode和CSGShape类型的host图元进行裁决挖空， 上例中通过将3d.visible设置为false隐藏了用于挖空的CSGNode，但对于门窗类型的应用，除了通过门窗模型挖空外， 还需要保留门窗的模型，而门窗类型一般厚度比墙面薄些，但如果attach.thickness小于1时则无法凿穿墙厚度， 为此建模扩展包还提供了DoorWindow类型的图元， 方便用户构建门窗类型的模型，DoorWindow类型图元提供了dw.s3参数，该参数默认值为[0.999, 0.999, 0.5]， 代表真正显示在3D界面上的模型会参考dw.s3的尺寸再进行缩放，这样attach.thickness继续保持可凿穿的1.001即可。

旋转功能

以上介绍的地板类型、墙面类型和管道类型三种类型， 都通过{x: 10, y: 20}的二维点信息描述图形走向，二维y坐标映射到三维的z坐标的转换关系请参见 3D手册。 但这三种类型都支持ht.Shape的rotationX、rotationY和rotationZ的空间旋转功能，通过设置旋转参数可实现竖立的效果。

以上例子通过不断改变shape3d.uv.offset参数可实现管道水平流动和截面方向旋转等特殊效果。