roofShed 函数实现详解

本文档详细解析 cgaprocessor.js 中 roofShed 函数的实现。该函数用于生成单坡屋顶（Shed Roof / 单坡棚顶）——只有一个坡面，一侧高一侧低的简单屋顶形式。

一、函数定位

roofShed 是所有屋顶函数中最简单的一个。它不对几何体做复杂的三角网格重建，而是直接抬升现有顶点的 Y 坐标（高度），在原几何体上直接变形得到单坡效果。

二、源码实现（第 1159~1165 行）

function func_roofShed(processor, angle) {
  angle = angle || 30;
  var top = processor.top;
  var size = processor.size();
  var h = Math.tan(THREE.Math.degToRad(angle)) * (size.z || size.x || 1);
  top.vertices.forEach(v => { v.y += (v.z - top.boundingBox.min.z) / (size.z || 1) * h; });
}

三、参数说明

四、算法步骤详解

Step 1: 计算屋顶高度差

var h = Math.tan(THREE.Math.degToRad(angle)) * (size.z || size.x || 1);

计算单坡屋顶的总高度差：

• 优先取当前形状在 Z 轴方向的尺寸 size.z
• 如果 size.z 无效，退而求其次取 size.x
• 公式：h = tan(θ) × depth

Step 2: 按 Z 坐标比例抬升顶点

top.vertices.forEach(v => { v.y += (v.z - top.boundingBox.min.z) / (size.z || 1) * h; });

这是整个函数的核心逻辑，极为简洁：

1. 对每个顶点，计算其在 Z 方向上的相对位置比例：ratio = (v.z - z_min) / depth
2. 将该比例乘以总高度差 h
3. 将结果叠加到顶点的 Y 坐标上

五、关键特性

六、数学公式

对每个顶点 v，修改后的高度为：

v.y' = v.y + tan(θ) × depth × (v.z - z_min) / depth = v.y + tan(θ) × (v.z - z_min)

化简后：

v.y' = v.y + tan(θ) × (v.z - z_min)

七、使用示例

// 默认 30 度单坡屋顶
Roof --> roofShed()

// 15 度缓坡单坡屋顶
Roof --> roofShed(15)

// 典型用法：在 footprint 上先生成墙体，再应用单坡顶
Lot --> extrude(3) comp(f) { top: ShedRoof }
ShedRoof --> roofShed(25)

八、与 roofGable 的对比