EllipseCurve 是 Three.js 中一个专门用于定义二维椭圆路径的工具类，可以用于创建椭圆形路径、动画轨迹以及动态几何构造。它可以通过调整参数生成完整的椭圆或其任意部分。

本文将从基础用法开始，深入解析 EllipseCurve 的所有属性与方法，并通过多个示例展示它在实际项目中的广泛应用。

一、EllipseCurve 简介

1.1 定义与作用

EllipseCurve 用于生成基于参数方程的椭圆曲线：

通过调整角度范围和弧度方向，可精确控制曲线的形状和覆盖区域。

1.2 构造函数

const curve = new THREE.EllipseCurve(
  xCenter, yCenter,         // 椭圆中心坐标
  xRadius, yRadius,         // 椭圆的半径（宽高）
  startAngle, endAngle,     // 起始和结束角度（弧度）
  clockwise,                // 是否顺时针
  rotation                  // 椭圆的旋转角度
);

参数说明：

• xCenter, yCenter: 椭圆的中心位置。
• xRadius, yRadius: 椭圆的水平半径和垂直半径。
• startAngle, endAngle: 定义曲线的起始和结束角度（以弧度为单位）。
• clockwise: 是否以顺时针方向绘制（布尔值）。
• rotation: 整个椭圆的旋转角度（以弧度为单位）。

二、EllipseCurve 的属性和方法

2.1 属性

• type: 曲线的类型，默认为 'EllipseCurve'。
• aX, aY: 椭圆的中心位置（xCenter, yCenter）。
• xRadius, yRadius: 椭圆的水平和垂直半径。
• aStartAngle, aEndAngle: 起始和结束角度。
• aClockwise: 顺时针方向标记。
• aRotation: 椭圆的旋转角度。

2.2 方法

2.2.1 getPoint(t)

返回曲线在参数 ( t ) 处的二维点。

const point = curve.getPoint(0.5);
console.log(point); // Vector2 { x: ..., y: ... }

2.2.2 getPoints(divisions)

返回曲线上的点数组。

const points = curve.getPoints(50);
console.log(points); // [Vector2, Vector2, ...]

2.2.3 getTangent(t)

返回曲线在参数 ( t ) 处的切线方向。

const tangent = curve.getTangent(0.5);
console.log(tangent); // Vector2 { x: ..., y: ... }

2.2.4 clone()

克隆当前曲线对象。

const clonedCurve = curve.clone();
console.log(clonedCurve);

2.2.5 toJSON()

将曲线序列化为 JSON。

const json = curve.toJSON();
console.log(json);

2.2.6 fromJSON(json)

从 JSON 对象还原曲线。

const restoredCurve = new THREE.EllipseCurve().fromJSON(json);
console.log(restoredCurve);

三、实际应用与示例

3.1 绘制基本椭圆

以下代码展示如何在场景中绘制一个基本椭圆路径：

// 创建椭圆曲线
const curve = new THREE.EllipseCurve(
  0, 0,               // 椭圆中心
  10, 5,              // x 半径, y 半径
  0, Math.PI * 2,     // 起始角度, 结束角度
  false,              // 逆时针方向
  0                   // 无旋转
);

// 获取曲线上的点
const points = curve.getPoints(100);

// 转换为几何体
const geometry = new THREE.BufferGeometry().setFromPoints(points);

// 创建线条
const material = new THREE.LineBasicMaterial({ color: 0xff0000 });
const ellipse = new THREE.Line(geometry, material);
scene.add(ellipse);

3.2 部分弧线绘制

通过调整起始和结束角度，可以绘制部分弧线：

const arc = new THREE.EllipseCurve(
  0, 0,
  10, 5,
  0, Math.PI / 2, // 绘制 90° 的弧
  false,
  0
);

const points = arc.getPoints(50);
const geometry = new THREE.BufferGeometry().setFromPoints(points);
const material = new THREE.LineBasicMaterial({ color: 0x00ff00 });
const line = new THREE.Line(geometry, material);
scene.add(line);

3.3 动态轨迹动画

以下示例展示如何让物体沿椭圆轨迹移动：

const sphere = new THREE.Mesh(
  new THREE.SphereGeometry(0.5, 16, 16),
  new THREE.MeshBasicMaterial({ color: 0x0000ff })
);
scene.add(sphere);

let t = 0;
function animate() {
  t += 0.01;
  if (t > 1) t = 0;

  const point = curve.getPoint(t);
  sphere.position.set(point.x, point.y, 0);

  renderer.render(scene, camera);
  requestAnimationFrame(animate);
}
animate();

3.4 结合旋转构造复杂形状

通过旋转参数，可以生成倾斜的椭圆：

const rotatedCurve = new THREE.EllipseCurve(
  0, 0,
  10, 5,
  0, Math.PI * 2,
  false,
  Math.PI / 4 // 旋转 45°
);

const points = rotatedCurve.getPoints(100);
const geometry = new THREE.BufferGeometry().setFromPoints(points);
const material = new THREE.LineBasicMaterial({ color: 0xffff00 });
const line = new THREE.Line(geometry, material);
scene.add(line);

3.5 结合 Shape 填充椭圆区域

可以将 EllipseCurve 转换为 Shape，从而生成填充的几何体：

const shape = new THREE.Shape(curve.getPoints(100));
const geometry = new THREE.ShapeGeometry(shape);
const material = new THREE.MeshBasicMaterial({ color: 0x00ffcc, side: THREE.DoubleSide });
const mesh = new THREE.Mesh(geometry, material);
scene.add(mesh);

四、进阶应用

4.1 椭圆路径生成三维轨迹

结合 TubeGeometry，可将椭圆路径扩展为三维管道：

const tubeGeometry = new THREE.TubeGeometry(curve, 100, 1, 8, true);
const material = new THREE.MeshStandardMaterial({ color: 0x0000ff });
const tube = new THREE.Mesh(tubeGeometry, material);
scene.add(tube);

4.2 粒子轨迹动画

通过在椭圆路径上生成点并结合粒子系统，可以模拟轨迹：

const points = curve.getPoints(100);
const particleGeometry = new THREE.BufferGeometry().setFromPoints(points);
const material = new THREE.PointsMaterial({ size: 0.1, color: 0xff9900 });
const particles = new THREE.Points(particleGeometry, material);
scene.add(particles);

五、总结

EllipseCurve 是创建二维椭圆及其衍生形状的理想工具。它的灵活性体现在可以通过简单参数控制曲线范围、方向和旋转。无论是路径动画、形状构造还是复杂几何体生成，EllipseCurve 都能满足需求。通过掌握其属性与方法，并结合其他 Three.js 组件，你可以构建更为丰富的三维场景。