2026/9/7 16:28:35
FEATURED · 精选文章 
three.js DecoratedTorusKnot5a 全解析装饰纽结曲线家族、参数公式与 TubeGeometry 实操【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.jsDecoratedTorusKnot5a是 three.js 附加模块addonexamples/jsm/curves/CurveExtras.js 中提供的一类参数化三维装饰纽结Decorated Torus Knot曲线它继承自核心类Curve可以直接作为TubeGeometry的路径用于生成管状网格。本文结合官方文档页 docs/pages/DecoratedTorusKnot5a.html.md 与该曲线在仓库中的源码实现系统讲解其继承关系、scale参数语义、getPoint的底层几何公式并给出可直接运行的建模示例帮助读者把这一类曲线真正用起来。一、DecoratedTorusKnot5a 是什么DecoratedTorusKnot5a装饰纽结 5a是 three.js 官方示例中一组参数化曲线parametric curves集合的成员。CurveExtras.js文件头部注释将其定性为A bunch of parametric curves其中的曲线公式来自多种数学资料经过编码成为可复用的Curve子类。这些曲线平时不参与 three.js 核心构建而是作为附加模块随官方示例一同发布。除DecoratedTorusKnot5a之外同一个文件中还提供GrannyKnot、HeartCurve、VivianiCurve、TrefoilKnot、CinquefoilKnot以及同属装饰纽结家族的DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c等曲线导出列表可见源码 examples/jsm/curves/CurveExtras.js。从命名可以推断5a属于五叶装饰纽结家族的一个变体同族还有5c以及四叶家族的4a、4b。官方文档页 docs/pages/DecoratedTorusKnot5c.html.md 记录了同名兄弟类。二、导入方式addon 必须显式导入文档页明确指出DecoratedTorusKnot5a是附加模块必须显式导入这与 three.js 官方对 addons 的安装约定一致。官方文档中的导入写法为import { DecoratedTorusKnot5a } from three/addons/curves/CurveExtras.js;对应到当前仓库源码文件即 examples/jsm/curves/CurveExtras.js。由于该模块内同时导出了多条曲线也可以像官方示例那样整体导入命名空间后按需取用import * as Curves from three/addons/curves/CurveExtras.js; const knot new Curves.DecoratedTorusKnot5a();这样做的优点是可以把多条曲线放进一个字典、实现下拉切换曲线的交互官方示例 examples/webgl_geometry_extrude_splines.html 正是采用这一模式。三、继承关系与 Curve 基类文档页头部以Inheritance: Curve →标注了类的继承链——DecoratedTorusKnot5a直接继承Curve不存在中间父类。这一点在源码中得到了直接印证examples/jsm/curves/CurveExtras.js 处即为class DecoratedTorusKnot5a extends Curve。基类Curve定义于 src/extras/core/Curve.js它把getPoint()声明为抽象方法未实现时打印Curve: .getPoint() not implemented.警告并在其之上提供了大量派生的采样工具基类方法说明与 getPoint 的关系getPoint( t )依据插值因子返回曲线上的点由子类实现抽象方法本类重写getPointAt( u )返回曲线上沿曲线长度均匀分布的点内部经getUtoTmapping换算后调用getPointgetPoints( divisions )沿参数空间等距取点共divisions 1个点循环调用getPointgetSpacedPoints( divisions )沿弧长等距取点共divisions 1个点循环调用getPointAt这意味着DecoratedTorusKnot5a只要正确实现getPoint就能自动获得长度参数化、等距采样、TubeGeometry/ExtrudeGeometry路径等一整套能力这也是曲线类在 three.js 中被大量复用的设计基础。四、构造器与 scale 参数new DecoratedTorusKnot5a( scale : number )构造器接收唯一可选参数scale表示曲线的整体缩放系数。源码实现位于 examples/jsm/curves/CurveExtras.jsconstructor( scale 40 ) { super(); this.scale scale; }两点需要注意的事实构造器默认值文档页在构造器条目下将参数默认值标注为1而.scale属性条目下标注默认值为40对照源码可以看到实际构造器签名为scale 40与属性默认值一致。也就是说源码中的真实默认值是40。为避免歧义建议在使用时显式传入scale。不传参会怎样由于默认值为 40new DecoratedTorusKnot5a()会生成一个坐标跨度约在 ±72见第五节公式推导范围内的大尺寸曲线直接放进默认相机场景中可能会超出视野需要配合相机距离或网格缩放调整。五、.scale 属性属性scale : number存放曲线的整体缩放系数默认值 40。它的语义在getPoint返回时体现——所有分量统一乘以this.scale。缩放不改变曲线的形状与拓扑只改变空间尺寸因此在把它当作TubeGeometry路径使用时需要让管道半径与曲线尺寸保持协调半径过小会出现管道塌陷、过大会覆盖纽结自身。六、.getPoint() 源码与几何公式解读方法签名getPoint( t : number, optionalTarget : Vector3 ) : Vector3t插值因子表示曲线上的位置取值必须在[0, 1]区间内optionalTarget可选的目标向量结果直接写入该向量避免额外分配内存返回值曲线上对应位置的Vector3覆盖关系重写基类Curve#getPoint见 src/extras/core/Curve.js。完整实现源码位于 examples/jsm/curves/CurveExtras.jsgetPoint( t, optionalTarget new Vector3() ) { const point optionalTarget; const fi t * Math.PI * 2; const x Math.cos( 3 * fi ) * ( 1 0.3 * Math.cos( 5 * fi ) 0.5 * Math.cos( 10 * fi ) ); const y Math.sin( 3 * fi ) * ( 1 0.3 * Math.cos( 5 * fi ) 0.5 * Math.cos( 10 * fi ) ); const z 0.2 * Math.sin( 20 * fi ); return point.set( x, y, z ).multiplyScalar( this.scale ); }公式拆解令fi t · 2π则曲线三轴分量为分量数学表达式xcos(3·fi) · (1 0.3·cos(5·fi) 0.5·cos(10·fi))ysin(3·fi) · (1 0.3·cos(5·fi) 0.5·cos(10·fi))z0.2 · sin(20·fi)最后执行(x, y, z) · scale整体缩放。这条公式可以从几何上这样理解主绕行(cos(3·fi), sin(3·fi))表明在参数t从 0 到 1即fi从 0 到 2π的过程中曲线在 XY 平面绕行 3 圈构成纽结的主体环圈装饰调制括号内的1 0.3·cos(5·fi) 0.5·cos(10·fi)是沿环圈的径向装饰——振幅 0.3、频率 5 的低频起伏叠加振幅 0.5、频率 10 的高频起伏使环圈半径随绕行不断波动形成凹凸的装饰截面轮廓这也是它区别于普通TorusKnot曲线的关键Z 轴起伏0.2·sin(20·fi)以 20 倍频率让曲线在垂直方向上下摆动把平面绕行抬升成三维空间中的编织感周期性t 0与t 1时公式取值完全相同fi相差 2π三角函数周期一致因此曲线天然闭合适合构造closed true的TubeGeometry尺寸量级未缩放时scale 1三个分量的理论极值约落在[-1.8, 1.8]XY与[-0.2, 0.2]Z乘以默认 scale 40 后 XY 跨度可达 ±72 左右。七、配套示例webgl_geometry_extrude_splines官方示例 examples/webgl_geometry_extrude_splines.html 是展示这些参数曲线的标准参考它以命名空间方式导入CurveExtras.js把包括DecoratedTorusKnot5a在内的一众曲线实例化并放入splines字典DecoratedTorusKnot5a: new Curves.DecoratedTorusKnot5a(),随后通过下拉列表在字典中选取当前路径用TubeGeometry生成管状几何并叠加线框网格展示tubeGeometry new THREE.TubeGeometry( extrudePath, params.extrusionSegments, 2, params.radiusSegments, params.closed );其中extrusionSegments示例中为 100控制沿路径的分段数分段越密曲线越平滑radiusSegments控制管道截面的细分closed置为true时首尾相接恰好契合第五节证明的曲线闭合特性。由于DecoratedTorusKnot5a默认scale 40示例还单独通过mesh.scale对网格做整体缩放以适配相机。阅读该文件 examples/webgl_geometry_extrude_splines.html 可以了解完整的曲线注册与切换逻辑。八、实操一段可直接运行的完整示例下面给出将DecoratedTorusKnot5a转成可见三维网格的最小完整流程思路与官方示例一致参数曲线做路径 →TubeGeometry沿线扫掠 → 加入场景。为便于展示这里显式把scale设为 10 并配以相应半径import * as THREE from three; import { DecoratedTorusKnot5a } from three/addons/curves/CurveExtras.js; // 1. 构造装饰纽结曲线显式指定缩放避免依赖默认值 const curve new DecoratedTorusKnot5a( 10 ); // 2. 用曲线作为路径生成管状几何 // TubeGeometry( path, tubularSegments, radius, radialSegments, closed ) const geometry new THREE.TubeGeometry( curve, 400, 1.2, 12, true ); // 3. 组装网格并加入场景 const material new THREE.MeshStandardMaterial( { color: 0x8844ff, metalness: 0.3, roughness: 0.4 } ); const mesh new THREE.Mesh( geometry, material ); scene.add( mesh ); // 4. 相机距离要覆盖曲线跨度scale10 时 XY 跨度约 ±18加上管道半径 camera.position.set( 0, 0, 45 );同样的曲线也可以不经网格化而直接参与动画利用curve.getPoints( n )生成折线Line或用getPointAt让物体沿弧长匀速巡游因为曲线闭合非常适合做循环运动路径。九、常见问题与使用建议为什么形状与我预期的环面纽结不同DecoratedTorusKnot5a的公式是基环 多频调制 Z 轴高频起伏的组合与TorusKnotGeometry这类网格几何体是不同的生成途径。它以公式定义一条空间曲线外观取决于管道半径、分段数与调制频率的相互作用。修改外观调什么管道半径与tubularSegments由TubeGeometry控制若要改变装饰形态则需要修改 CurveExtras.js 中公式的系数与频率属于源码定制范畴仅用于理解原理。性能注意TubeGeometry的顶点数为(tubularSegments 1) × (radialSegments 1)DecoratedTorusKnot5a的高频调制需要足够的tubularSegments通常 200 以上才能表现平滑示例中使用的 100 是兼顾预览与性能的经验值。同一文件的其他曲线若需要不同形态的装饰纽结可直接对比同文件内的DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c它们各自的getPoint中频率与系数组合不同选择与展示方式完全一致。十、参考路径速查官方文档源文件docs/pages/DecoratedTorusKnot5a.html.md曲线源码 examples/jsm/curves/CurveExtras.js基类Curvesrc/extras/core/Curve.js管状几何体用法参考src/geometries/TubeGeometry.js可运行示例examples/webgl_geometry_extrude_splines.html同族文档DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c掌握DecoratedTorusKnot5a的类结构、参数语义与底层公式之后你既可以照官方示例在TubeGeometry中直接使用它生成装饰性网格也可以把这类周期闭合曲线当作相机轨道、粒子路径或沿路动画的底层工具充分发挥 three.jsCurve抽象体系的能力。【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
three.js DecoratedTorusKnot5a 全解析：装饰纽结曲线家族、参数公式与 TubeGeometry 实操
three.js DecoratedTorusKnot5a 全解析装饰纽结曲线家族、参数公式与 TubeGeometry 实操【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.jsDecoratedTorusKnot5a是 three.js 附加模块addonexamples/jsm/curves/CurveExtras.js 中提供的一类参数化三维装饰纽结Decorated Torus Knot曲线它继承自核心类Curve可以直接作为TubeGeometry的路径用于生成管状网格。本文结合官方文档页 docs/pages/DecoratedTorusKnot5a.html.md 与该曲线在仓库中的源码实现系统讲解其继承关系、scale参数语义、getPoint的底层几何公式并给出可直接运行的建模示例帮助读者把这一类曲线真正用起来。一、DecoratedTorusKnot5a 是什么DecoratedTorusKnot5a装饰纽结 5a是 three.js 官方示例中一组参数化曲线parametric curves集合的成员。CurveExtras.js文件头部注释将其定性为A bunch of parametric curves其中的曲线公式来自多种数学资料经过编码成为可复用的Curve子类。这些曲线平时不参与 three.js 核心构建而是作为附加模块随官方示例一同发布。除DecoratedTorusKnot5a之外同一个文件中还提供GrannyKnot、HeartCurve、VivianiCurve、TrefoilKnot、CinquefoilKnot以及同属装饰纽结家族的DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c等曲线导出列表可见源码 examples/jsm/curves/CurveExtras.js。从命名可以推断5a属于五叶装饰纽结家族的一个变体同族还有5c以及四叶家族的4a、4b。官方文档页 docs/pages/DecoratedTorusKnot5c.html.md 记录了同名兄弟类。二、导入方式addon 必须显式导入文档页明确指出DecoratedTorusKnot5a是附加模块必须显式导入这与 three.js 官方对 addons 的安装约定一致。官方文档中的导入写法为import { DecoratedTorusKnot5a } from three/addons/curves/CurveExtras.js;对应到当前仓库源码文件即 examples/jsm/curves/CurveExtras.js。由于该模块内同时导出了多条曲线也可以像官方示例那样整体导入命名空间后按需取用import * as Curves from three/addons/curves/CurveExtras.js; const knot new Curves.DecoratedTorusKnot5a();这样做的优点是可以把多条曲线放进一个字典、实现下拉切换曲线的交互官方示例 examples/webgl_geometry_extrude_splines.html 正是采用这一模式。三、继承关系与 Curve 基类文档页头部以Inheritance: Curve →标注了类的继承链——DecoratedTorusKnot5a直接继承Curve不存在中间父类。这一点在源码中得到了直接印证examples/jsm/curves/CurveExtras.js 处即为class DecoratedTorusKnot5a extends Curve。基类Curve定义于 src/extras/core/Curve.js它把getPoint()声明为抽象方法未实现时打印Curve: .getPoint() not implemented.警告并在其之上提供了大量派生的采样工具基类方法说明与 getPoint 的关系getPoint( t )依据插值因子返回曲线上的点由子类实现抽象方法本类重写getPointAt( u )返回曲线上沿曲线长度均匀分布的点内部经getUtoTmapping换算后调用getPointgetPoints( divisions )沿参数空间等距取点共divisions 1个点循环调用getPointgetSpacedPoints( divisions )沿弧长等距取点共divisions 1个点循环调用getPointAt这意味着DecoratedTorusKnot5a只要正确实现getPoint就能自动获得长度参数化、等距采样、TubeGeometry/ExtrudeGeometry路径等一整套能力这也是曲线类在 three.js 中被大量复用的设计基础。四、构造器与 scale 参数new DecoratedTorusKnot5a( scale : number )构造器接收唯一可选参数scale表示曲线的整体缩放系数。源码实现位于 examples/jsm/curves/CurveExtras.jsconstructor( scale 40 ) { super(); this.scale scale; }两点需要注意的事实构造器默认值文档页在构造器条目下将参数默认值标注为1而.scale属性条目下标注默认值为40对照源码可以看到实际构造器签名为scale 40与属性默认值一致。也就是说源码中的真实默认值是40。为避免歧义建议在使用时显式传入scale。不传参会怎样由于默认值为 40new DecoratedTorusKnot5a()会生成一个坐标跨度约在 ±72见第五节公式推导范围内的大尺寸曲线直接放进默认相机场景中可能会超出视野需要配合相机距离或网格缩放调整。五、.scale 属性属性scale : number存放曲线的整体缩放系数默认值 40。它的语义在getPoint返回时体现——所有分量统一乘以this.scale。缩放不改变曲线的形状与拓扑只改变空间尺寸因此在把它当作TubeGeometry路径使用时需要让管道半径与曲线尺寸保持协调半径过小会出现管道塌陷、过大会覆盖纽结自身。六、.getPoint() 源码与几何公式解读方法签名getPoint( t : number, optionalTarget : Vector3 ) : Vector3t插值因子表示曲线上的位置取值必须在[0, 1]区间内optionalTarget可选的目标向量结果直接写入该向量避免额外分配内存返回值曲线上对应位置的Vector3覆盖关系重写基类Curve#getPoint见 src/extras/core/Curve.js。完整实现源码位于 examples/jsm/curves/CurveExtras.jsgetPoint( t, optionalTarget new Vector3() ) { const point optionalTarget; const fi t * Math.PI * 2; const x Math.cos( 3 * fi ) * ( 1 0.3 * Math.cos( 5 * fi ) 0.5 * Math.cos( 10 * fi ) ); const y Math.sin( 3 * fi ) * ( 1 0.3 * Math.cos( 5 * fi ) 0.5 * Math.cos( 10 * fi ) ); const z 0.2 * Math.sin( 20 * fi ); return point.set( x, y, z ).multiplyScalar( this.scale ); }公式拆解令fi t · 2π则曲线三轴分量为分量数学表达式xcos(3·fi) · (1 0.3·cos(5·fi) 0.5·cos(10·fi))ysin(3·fi) · (1 0.3·cos(5·fi) 0.5·cos(10·fi))z0.2 · sin(20·fi)最后执行(x, y, z) · scale整体缩放。这条公式可以从几何上这样理解主绕行(cos(3·fi), sin(3·fi))表明在参数t从 0 到 1即fi从 0 到 2π的过程中曲线在 XY 平面绕行 3 圈构成纽结的主体环圈装饰调制括号内的1 0.3·cos(5·fi) 0.5·cos(10·fi)是沿环圈的径向装饰——振幅 0.3、频率 5 的低频起伏叠加振幅 0.5、频率 10 的高频起伏使环圈半径随绕行不断波动形成凹凸的装饰截面轮廓这也是它区别于普通TorusKnot曲线的关键Z 轴起伏0.2·sin(20·fi)以 20 倍频率让曲线在垂直方向上下摆动把平面绕行抬升成三维空间中的编织感周期性t 0与t 1时公式取值完全相同fi相差 2π三角函数周期一致因此曲线天然闭合适合构造closed true的TubeGeometry尺寸量级未缩放时scale 1三个分量的理论极值约落在[-1.8, 1.8]XY与[-0.2, 0.2]Z乘以默认 scale 40 后 XY 跨度可达 ±72 左右。七、配套示例webgl_geometry_extrude_splines官方示例 examples/webgl_geometry_extrude_splines.html 是展示这些参数曲线的标准参考它以命名空间方式导入CurveExtras.js把包括DecoratedTorusKnot5a在内的一众曲线实例化并放入splines字典DecoratedTorusKnot5a: new Curves.DecoratedTorusKnot5a(),随后通过下拉列表在字典中选取当前路径用TubeGeometry生成管状几何并叠加线框网格展示tubeGeometry new THREE.TubeGeometry( extrudePath, params.extrusionSegments, 2, params.radiusSegments, params.closed );其中extrusionSegments示例中为 100控制沿路径的分段数分段越密曲线越平滑radiusSegments控制管道截面的细分closed置为true时首尾相接恰好契合第五节证明的曲线闭合特性。由于DecoratedTorusKnot5a默认scale 40示例还单独通过mesh.scale对网格做整体缩放以适配相机。阅读该文件 examples/webgl_geometry_extrude_splines.html 可以了解完整的曲线注册与切换逻辑。八、实操一段可直接运行的完整示例下面给出将DecoratedTorusKnot5a转成可见三维网格的最小完整流程思路与官方示例一致参数曲线做路径 →TubeGeometry沿线扫掠 → 加入场景。为便于展示这里显式把scale设为 10 并配以相应半径import * as THREE from three; import { DecoratedTorusKnot5a } from three/addons/curves/CurveExtras.js; // 1. 构造装饰纽结曲线显式指定缩放避免依赖默认值 const curve new DecoratedTorusKnot5a( 10 ); // 2. 用曲线作为路径生成管状几何 // TubeGeometry( path, tubularSegments, radius, radialSegments, closed ) const geometry new THREE.TubeGeometry( curve, 400, 1.2, 12, true ); // 3. 组装网格并加入场景 const material new THREE.MeshStandardMaterial( { color: 0x8844ff, metalness: 0.3, roughness: 0.4 } ); const mesh new THREE.Mesh( geometry, material ); scene.add( mesh ); // 4. 相机距离要覆盖曲线跨度scale10 时 XY 跨度约 ±18加上管道半径 camera.position.set( 0, 0, 45 );同样的曲线也可以不经网格化而直接参与动画利用curve.getPoints( n )生成折线Line或用getPointAt让物体沿弧长匀速巡游因为曲线闭合非常适合做循环运动路径。九、常见问题与使用建议为什么形状与我预期的环面纽结不同DecoratedTorusKnot5a的公式是基环 多频调制 Z 轴高频起伏的组合与TorusKnotGeometry这类网格几何体是不同的生成途径。它以公式定义一条空间曲线外观取决于管道半径、分段数与调制频率的相互作用。修改外观调什么管道半径与tubularSegments由TubeGeometry控制若要改变装饰形态则需要修改 CurveExtras.js 中公式的系数与频率属于源码定制范畴仅用于理解原理。性能注意TubeGeometry的顶点数为(tubularSegments 1) × (radialSegments 1)DecoratedTorusKnot5a的高频调制需要足够的tubularSegments通常 200 以上才能表现平滑示例中使用的 100 是兼顾预览与性能的经验值。同一文件的其他曲线若需要不同形态的装饰纽结可直接对比同文件内的DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c它们各自的getPoint中频率与系数组合不同选择与展示方式完全一致。十、参考路径速查官方文档源文件docs/pages/DecoratedTorusKnot5a.html.md曲线源码 examples/jsm/curves/CurveExtras.js基类Curvesrc/extras/core/Curve.js管状几何体用法参考src/geometries/TubeGeometry.js可运行示例examples/webgl_geometry_extrude_splines.html同族文档DecoratedTorusKnot4a、DecoratedTorusKnot4b、DecoratedTorusKnot5c掌握DecoratedTorusKnot5a的类结构、参数语义与底层公式之后你既可以照官方示例在TubeGeometry中直接使用它生成装饰性网格也可以把这类周期闭合曲线当作相机轨道、粒子路径或沿路动画的底层工具充分发挥 three.jsCurve抽象体系的能力。【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
