Three.js几何体核心 API

通用说明（所有 *Geometry 都继承自 BufferGeometry）

共有重要属性 / 方法：

• attributes: 顶点属性集合（常见：
  • position: BufferAttribute 顶点位置（必有）；
  • normal: BufferAttribute 法线（光照用）；
  • uv: BufferAttribute 贴图坐标；
  • 对索引几何体还会有 index: BufferAttribute）。
• boundingBox: Box3 | null、boundingSphere: Sphere | null：包围体（computeBoundingBox() / computeBoundingSphere() 生成）。
• 变换：translate(x,y,z) / rotateX|Y|Z(rad) / scale(x,y,z) / center()。
• 索引：toNonIndexed()（把索引几何体展开为非索引）、setIndex()、setAttribute(name, attr)。
• 其它：drawRange（只绘制一部分）、dispose()（释放 GPU 资源）。
• 每个具体几何体通常还带 .parameters，保存构造参数快照（便于调试/序列化）。

BoxGeometry

签名：new THREE.BoxGeometry(width, height, depth, widthSegments?, heightSegments?, depthSegments?)

参数

• width/height/depth: 盒子尺寸。
• widthSegments/heightSegments/depthSegments: 各方向分段数，越大越细（默认 1）。

常见属性：.parameters = { width, height, depth, widthSegments, heightSegments, depthSegments }

用法建议：增加分段便于形变/顶点着色/法线更精细。

代码示例

CapsuleGeometry

签名：new THREE.CapsuleGeometry(radius?, length?, capSegments?, radialSegments?)

参数

• radius: 半球帽和圆柱过渡的半径。
• length: 中间圆柱段长度（不含两端半球）。
• capSegments: 帽部（半球）分段。
• radialSegments: 周向分段。

属性：.parameters = { radius, length, capSegments, radialSegments }

建议：角色碰撞体/科幻胶囊造型常用。

示例

CircleGeometry

签名：new THREE.CircleGeometry(radius, segments?, thetaStart?, thetaLength?)

参数

• radius: 半径。
• segments: 圆周细分（≥3）。
• thetaStart: 起始角（弧度）。
• thetaLength: 扫掠角（弧度，默认 2π）。

属性：.parameters = { radius, segments, thetaStart, thetaLength }

示例

ConeGeometry

签名：new THREE.ConeGeometry(radius, height, radialSegments?, heightSegments?, openEnded?, thetaStart?, thetaLength?)

参数

• radius: 底面半径。
• height: 高。
• radialSegments: 底面周向分段。
• heightSegments: 高度方向分段。
• openEnded: 是否开口（默认 false，即有底面）。
• thetaStart/thetaLength: 切扇角范围。

属性：.parameters = {...}

示例

CylinderGeometry

签名：new THREE.CylinderGeometry(radiusTop, radiusBottom, height, radialSegments?, heightSegments?, openEnded?, thetaStart?, thetaLength?)

参数

• radiusTop/radiusBottom: 上/下半径（上 0 即圆锥）。
• height、radialSegments、heightSegments：同上。
• openEnded: 是否两端开口。
• thetaStart/thetaLength: 角范围。

示例

DodecahedronGeometry（十二面体）

签名：new THREE.DodecahedronGeometry(radius?, detail?)

参数

• radius: 外接球半径。
• detail: 细分层级（>0 会三角化并细分）。

示例

EdgesGeometry

签名：new THREE.EdgesGeometry(geometry, thresholdAngle?)

作用：从输入几何体抽取可见边线（相邻面的夹角大于阈值）。

参数

• geometry: 源几何体。
• thresholdAngle: 阈值角度（度），默认 1。

产物：几何顶点线段，可配 LineSegments 使用。

示例

ExtrudeGeometry

签名：new THREE.ExtrudeGeometry(shapes, options)

作用：将 2D 形状沿法线方向拉伸为 3D。

核心参数（options）

• steps: 沿拉伸方向的分段。
• depth: 拉伸深度（若无 extrudePath）。
• bevelEnabled: 倒角开关。
• bevelThickness: 倒角厚度。
• bevelSize: 倒角大小（边向内收）。
• bevelOffset: 倒角偏移（有助于防止自交）。
• bevelSegments: 倒角分段。
• curveSegments: 形状曲线采样分段。
• extrudePath: 沿路径（Curve）挤出（取代 depth）。
• UVGenerator: 自定义 UV 生成器。

示例：挤出一个“心形”并倒角

IcosahedronGeometry（二十面体）

签名：new THREE.IcosahedronGeometry(radius?, detail?)
参数同十二面体。

示例

LatheGeometry（车削体）

签名：new THREE.LatheGeometry(points, segments?, phiStart?, phiLength?)

作用：将一条 二维轮廓线（points: Vector2[]） 围绕 Y 轴 旋转生成实体。

参数

• points: 轮廓从下到上的 Vector2(x, y) 点列（x 为半径）。
• segments: 周向分段。
• phiStart/phiLength: 旋转范围（弧度）。

示例：花瓶

OctahedronGeometry（八面体）

签名：new THREE.OctahedronGeometry(radius?, detail?)

示例

PlaneGeometry

签名：new THREE.PlaneGeometry(width, height, widthSegments?, heightSegments?)

参数

• width/height: 平面尺寸。
• widthSegments/heightSegments: 细分（用于波浪/形变）。

示例

PolyhedronGeometry

签名：new THREE.PolyhedronGeometry(vertices, indices, radius?, detail?)

作用：用自定义顶点/面索引定义多面体，再按 radius 归一化到外接球，detail 细分。

参数

• vertices: 扁平数组 [x1,y1,z1, x2,y2,z2, ...]。
• indices: 扁平三元组数组 [a,b,c, ...]（顶点索引）。
• radius/detail: 同上。

示例：自定义金字塔（四角锥）

RingGeometry

签名：new THREE.RingGeometry(innerRadius, outerRadius, thetaSegments?, phiSegments?, thetaStart?, thetaLength?)

参数

• innerRadius/outerRadius: 内/外半径。
• thetaSegments: 圆环周向分段。
• phiSegments: 径向分段（由内向外）。
• thetaStart/thetaLength: 扇形范围。

示例

ShapeGeometry

签名：new THREE.ShapeGeometry(shapes, curveSegments?)

作用：把 2D Shape 直接三角化成平面网格（与 ExtrudeGeometry 区别：不拉伸）。

参数

• shapes: Shape | Shape[]。
• curveSegments: 采样密度。

示例

SphereGeometry

签名：new THREE.SphereGeometry(radius, widthSegments?, heightSegments?, phiStart?, phiLength?, thetaStart?, thetaLength?)

参数

• radius：半径。
• widthSegments：经线（水平环）分段。
• heightSegments：纬线（垂直）分段。
• phiStart/phiLength：水平角范围（0→2π）。
• thetaStart/thetaLength：垂直角范围（0→π）。

示例

TetrahedronGeometry（四面体）

签名：new THREE.TetrahedronGeometry(radius?, detail?)
参数同其他正多面体。

示例

TorusGeometry（圆环）

签名：new THREE.TorusGeometry(radius, tube?, radialSegments?, tubularSegments?, arc?)

参数

• radius: 圆环“中心圈”的半径。
• tube: 管道半径（截面半径）。
• radialSegments: 管道截面上的分段数。
• tubularSegments: 沿环方向的分段数。
• arc: 绘制弧度（默认 2π，可绘半环）。

示例

TorusKnotGeometry（圆环结）

签名：new THREE.TorusKnotGeometry(radius?, tube?, tubularSegments?, radialSegments?, p?, q?)

参数

• radius/tube/tubularSegments/radialSegments：同 TorusGeometry。
• p、q：结的绕行参数（沿环与绕自身的次数，互素时形成漂亮结）。

示例

TubeGeometry

签名：new THREE.TubeGeometry(path, tubularSegments?, radius?, radialSegments?, closed?)

作用：沿三维曲线 path: Curve<Vector3> 拉出一条“管”。

参数

• path: 任意 THREE.Curve（常用 CatmullRomCurve3）。
• tubularSegments: 沿曲线方向分段数。
• radius: 管半径。
• radialSegments: 管道截面分段。
• closed: 曲线是否闭合。

示例：Catmull-Rom 曲线管

WireframeGeometry

签名：new THREE.WireframeGeometry(geometry)

作用：把任意面的几何体转换为线框几何（所有三角边）。

对比 EdgesGeometry：

• WireframeGeometry：把所有边都画出来；
• EdgesGeometry：只画明显的轮廓/锐边（按阈值角过滤）。

示例

额外示例：通用操作合集（背口诀）

快速择器（什么时候用哪一个？）

• 规则体：Box / Sphere / Plane / Cylinder / Cone / Torus / TorusKnot / 各种 *hedron。
• 曲线/路径：Tube (沿曲线)、Lathe (旋转生成)。
• 2D → 3D：Shape (平面)、Extrude (拉伸/沿路挤出)、Ring / Circle。
• 线框/轮廓：Wireframe / Edges。
• 自定义：Polyhedron（顶点+索引自由）。