roofHip — CGA.js Function Library

CityEngine 官方语法

roofHip(angle)
roofHip(angle, overhang)
roofHip(angle, overhang, even)
roofHip(valueType, value)
roofHip(valueType, value, overhang)
roofHip(valueType, value, overhang, even)

参数说明

参数	类型	默认值	说明
`angle`	float	—	屋顶斜面与水平面的夹角（度）。byAngle 模式下使用。
`overhang`	float	0	屋檐伸出距离。在屋顶平面上垂直于屋脊测量。
`even`	bool	false	是否强制屋脊水平。为 true 时会产生非平面的屋顶面。
`valueType`	selector	byAngle	Roof 生成模式：`byAngle`（按角度）或 `byHeight`（按绝对高度）。
`value`	float	—	根据 valueType 指定为角度或高度。

描述

从当前形状的每个面垂直向上生成斜面，所有斜面相互切割形成 hip roof（四坡屋顶）面。

如果设置了 overhang，屋顶面会超出原始形状该距离。如果 even 为 true，屋脊边会被强制水平，此时会产生非平面的屋顶面。

结果的 scope 会自动调整为紧密包裹生成的几何体。

组件标签：操作自动为结果面添加语义标签："roof.bottom"（原始面）、"roof.top"（屋顶面）。

官方示例 — Simple Hip Roof

在拉伸后的 L-lot 上生成一个基本的四坡屋顶，坡度 30°，屋檐伸出 2。

@StartRule
Lot  --> extrude(10) Mass

Mass --> comp(f) { top : Top | all : X }

Top  --> roofHip(30, 2) Roof

组件分割后，每个屋顶面包含 trim plane，用于在插入时切割砖块。默认情况下屋脊处没有水平 trim plane，可通过 set(trim.horizontal, true) 启用：

Roof --> set(trim.horizontal, true)
         comp(f) { all : X }

官方示例 — Even Hip Roof

在梯形 lot 上对比标准四坡屋顶与 even 四坡屋顶。坡度 45°，屋檐伸出 1。

标准（uneven）屋脊

Top --> roofHip(45, 1, false) Roof

Even 屋脊（水平）

Top --> roofHip(45, 1, true) Roof

even = true 时，屋脊顶点被设为平均高度，使屋脊水平。此时屋顶面变为非平面。对于许多形状，屋脊本来就隐含水平，因此 even 选项不会带来明显变化。

官方示例 — byHeight 模式

使用绝对高度而不是角度来生成屋顶：

Top --> roofHip(byHeight, 5, 1) Roof

实现说明

CGA.js 中的 roofHip 实现基于 CityEngine 2025.1 官方文档，支持全部 6 种参数重载。

几何算法

提取 footprint 顶点的包围盒（bbox），计算宽 w 和深 d。
屋脊方向平行于较长边（w ≥ d 时沿 X 轴，否则沿 Z 轴）。
屋脊长度公式：|w - d|，与角度无关（矩形 footprint 的数学正确解）。
正方形 footprint 时，强制保留最小屋脊长度 = 短边的 30%，确保小角度下屋脊仍然可见（不塌陷为金字塔）。
通过 byHeight 模式时，根据 footprint 半跨距自动换算为等效角度：angle = atan(height / halfSpan) * 180/π。

代码编辑器自动补全

枚举值自动补全：在代码编辑器中输入 roofHip( 或 roofGable( 等时，补全列表会显示带具体枚举值的条目，可直接选择：
byAnglebyHeight
例如选择 roofHip(byAngle, value) 后，只需修改数值即可。

支持的参数组合

roofHip(30) roofHip(30, 2) roofHip(30, 2, false) roofHip(byAngle, 30) roofHip(byAngle, 30, 2) roofHip(byAngle, 30, 2, false) roofHip(byHeight, 5) roofHip(byHeight, 5, 1) roofHip(byHeight, 5, 1, true)

🎨 3D 预览 — 四坡屋顶

@StartRule
Lot --> primitiveCube(6, 4, 6)
        extrude(5)
        comp(f) { top: Roof | side: Wall }

Roof --> roofHip(30)
         color(0.5, 0.25, 0.15)

Wall --> color(0.75, 0.72, 0.68)