roofHip 函数实现详解

本文档详细解析 cgaprocessor.js 中 roofHip 函数的实现。该函数用于生成四坡屋顶（Hip Roof / 庑殿顶）——四面都有坡度的屋顶形式，顶部有一条屋脊线，四角有斜脊（hip line）。

一、函数定位与特点

roofHip 是屋顶函数中最复杂的一个。它采用矩形近似算法：将 footprint 投影到2D平面后，用其包围盒的长宽比来近似生成四坡屋顶。当 footprint 接近正方形时会自动退化为金字塔顶。

二、源码实现（第 1185~1420 行）

2.1 参数与预处理

function func_roofHip(processor, angle) {
  angle = angle || 30;
  var top = processor.top;
  if (!top.faces.length) return;

  top.mergeVertices();
  top.computeFaceNormals();

  var normal = top.faces[0].normal.clone().normalize();
  if (!normal.length()) throw 'roofHip needs a non-degenerate face normal';

  var center = new THREE.Vector3();
  top.vertices.forEach(v => center.add(v));
  center.divideScalar(top.vertices.length);

  // Project vertices to 2D plane
  var projected = top.vertices.map(v => v.clone().sub(center));
  var xaxis = projected[1] ? projected[1].clone().sub(projected[0]) : new THREE.Vector3(1,0,0);
  xaxis.sub(normal.clone().multiplyScalar(xaxis.dot(normal)));
  if (xaxis.length() < 0.0001) xaxis = new THREE.Vector3(1,0,0).cross(normal);
  if (xaxis.length() < 0.0001) xaxis = new THREE.Vector3(0,1,0).cross(normal);
  xaxis.normalize();

  var yaxis = new THREE.Vector3().crossVectors(normal, xaxis).normalize();

  var pts2d = top.vertices.map(v => {
    var d = v.clone().sub(center);
    return { x: d.dot(xaxis), y: d.dot(yaxis), vertex: v };
  });

  // Sort CCW
  var c2 = pts2d.reduce((a, p) => { a.x += p.x; a.y += p.y; return a; }, {x:0,y:0});
  c2.x /= pts2d.length; c2.y /= pts2d.length;
  pts2d.sort((a,b) => Math.atan2(a.y-c2.y, a.x-c2.x) - Math.atan2(b.y-c2.y, b.x-c2.x));

  // Compute bounding box to determine orientation
  var minX = Infinity, maxX = -Infinity, minY = Infinity, maxY = -Infinity;
  pts2d.forEach(p => {
    minX = Math.min(minX, p.x); maxX = Math.max(maxX, p.x);
    minY = Math.min(minY, p.y); maxY = Math.max(maxY, p.y);
  });
  var W = maxX - minX, D = maxY - minY;

2.2 退化判断

  // Near-square → pyramid (correct degeneracy)
  if (Math.min(W,D) / Math.max(W,D) > 0.85) {
    func_roofPyramid(processor, angle);
    return;
  }

  // ...
  var h = Math.tan(THREE.Math.degToRad(angle)) * shortSize / 2;
  var hipRun = h / Math.tan(THREE.Math.degToRad(angle));
  if (hipRun > shortSize / 2 + 0.0001) {
    func_roofPyramid(processor, angle);
    return;
  }

2.3 顶点生成与面片构建

  var ridgeHalfShort = shortSize / 2 - hipRun;
  var ridgeHalfLong = longSize / 2;

  // ... corners and roofBase definitions ...

  var ridgeLeft  = center.clone().add(longAxis.clone().multiplyScalar(-ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar(0)).add(normal.clone().multiplyScalar(h));
  var ridgeRight = center.clone().add(longAxis.clone().multiplyScalar( ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar(0)).add(normal.clone().multiplyScalar(h));

  // Footprint corners (ground level)
  var fl = center.clone().add(longAxis.clone().multiplyScalar(-halfW))
    .add(shortAxis.clone().multiplyScalar(-halfD));
  var fr = center.clone().add(longAxis.clone().multiplyScalar( halfW))
    .add(shortAxis.clone().multiplyScalar(-halfD));
  var br = center.clone().add(longAxis.clone().multiplyScalar( halfW))
    .add(shortAxis.clone().multiplyScalar( halfD));
  var bl = center.clone().add(longAxis.clone().multiplyScalar(-halfW))
    .add(shortAxis.clone().multiplyScalar( halfD));

  // Roof base corners (at height h)
  var flh = center.clone().add(longAxis.clone().multiplyScalar(-ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar(-halfD)).add(normal.clone().multiplyScalar(h));
  var frh = center.clone().add(longAxis.clone().multiplyScalar( ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar(-halfD)).add(normal.clone().multiplyScalar(h));
  var brh = center.clone().add(longAxis.clone().multiplyScalar( ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar( halfD)).add(normal.clone().multiplyScalar(h));
  var blh = center.clone().add(longAxis.clone().multiplyScalar(-ridgeHalfW))
    .add(shortAxis.clone().multiplyScalar( halfD)).add(normal.clone().multiplyScalar(h));

  function addFace(a, b, c) {
    var l = geometry.vertices.length;
    geometry.vertices.push(a, b, c);
    geometry.faces.push(new THREE.Face3(l, l+1, l+2));
  }

  // Hip faces (triangles from ridge end to corner)
  addFace(ridgeLeft, flh, fl);
  addFace(ridgeRight, fr, frh);
  addFace(ridgeRight, brh, br);
  addFace(ridgeLeft, bl, blh);

  // Gable faces (trapezoids from ridge to eave)
  addFace(ridgeLeft, ridgeRight, frh);
  addFace(ridgeLeft, frh, flh);
  addFace(ridgeRight, ridgeLeft, blh);
  addFace(ridgeRight, blh, brh);

  geometry.mergeVertices();
  geometry.computeFaceNormals();
  geometry.computeVertexNormals();
  processor.update(geometry);
}

三、参数说明

四、核心算法流程

五、详细步骤解析

Step 1: 2D 投影与包围盒（第 1196~1226 行）

与 roofGable 相同，先建立局部坐标系，将 footprint 顶点投影到2D平面，按极角排序。然后计算投影点的包围盒：

• W = maxX - minX：长轴方向跨度
• D = maxY - minY：短轴方向跨度

Step 2: 退化判断（第 1229~1248 行）

2.1 近正方形退化

if (Math.min(W,D) / Math.max(W,D) > 0.85) {
  func_roofPyramid(processor, angle);
  return;
}

当长短边比例超过 0.85 时（接近正方形），四坡屋顶退化为金字塔顶。

2.2 hipRun 超限退化

var h = Math.tan(THREE.Math.degToRad(angle)) * shortSize / 2;
var hipRun = h / Math.tan(THREE.Math.degToRad(angle));
if (hipRun > shortSize / 2 + 0.0001) {
  func_roofPyramid(processor, angle);
  return;
}

计算关键参数：

• 屋顶高度：h = tan(θ) × shortSize / 2
• hipRun（hip 线水平投影）：hipRun = h / tan(θ) = shortSize / 2

Step 3: 坐标系对齐（第 1237~1241 行）

var isWider = W >= D;
var longAxis = isWider ? xaxis : yaxis;
var shortAxis = isWider ? yaxis : xaxis;
var longSize = isWider ? W : D;
var shortSize = isWider ? D : W;

将坐标轴与 footprint 的长短边对齐，确保屋脊始终沿长边方向。

Step 4: 3D 顶点生成（第 1371~1389 行）

代码生成了三类顶点：

其中 ridgeHalfW = halfW - hipRun = halfW - shortSize/2 = (W - D)/2（当 W ≥ D 时）。

Step 5: 面片构建（第 1392~1414 行）

5.1 Hip 面（四个角点三角形）

5.2 Gable 面（前后水平面）

六、关键数学关系

七、使用示例

// 默认 30 度四坡屋顶
Roof --> roofHip()

// 45 度陡坡四坡屋顶
Roof --> roofHip(45)

// 在方形 footprint 上会自动退化为金字塔顶
Square --> primitiveQuad(4, 4) roofHip(30)

八、与其他 roof 函数的对比