three.js 源码诠释（九十一）extras/core/Curve.js
three.js 源码注释（九十一）extras/core/Curve.js
商域无疆 (http://blog.****.net/omni360/)
本文遵循“署名-非商业用途-保持一致”创作公用协议
转载请保留此句：商域无疆 - 本博客专注于 敏捷开发及移动和物联设备研究：数据可视化、GOLANG、Html5、WEBGL、THREE.JS，否则，出自本博客的文章拒绝转载或再转载，谢谢合作。
俺也是刚开始学,好多地儿肯定不对还请见谅.
以下代码是THREE.JS 源码文件中extras/core/Curve.js文件的注释.
更多更新在 : https://github.com/omni360/three.js.sourcecode
/**
* @author zz85 / http://www.lab4games.net/zz85/blog
* Extensible curve object
*
* Some common of Curve methods 一些通用的方法.
* .getPoint(t), getTangent(t)
* .getPointAt(u), getTagentAt(u)
* .getPoints(), .getSpacedPoints()
* .getLength()
* .updateArcLengths()
*
* This following classes subclasses THREE.Curve:
* 这些是THREE.Curve的一些子类.
*
* -- 2d classes --
* THREE.LineCurve
* THREE.QuadraticBezierCurve
* THREE.CubicBezierCurve
* THREE.SplineCurve
* THREE.ArcCurve
* THREE.EllipseCurve
*
* -- 3d classes --
* THREE.LineCurve3
* THREE.QuadraticBezierCurve3
* THREE.CubicBezierCurve3
* THREE.SplineCurve3
* THREE.ClosedSplineCurve3
*
* A series of curves can be represented as a THREE.CurvePath
* 一个曲线序列可以用THREE.CurvePath
*
**/
/**************************************************************
* Abstract Curve base class 曲线抽象基类
**************************************************************/
/*
///Curve对象曲线抽象基类,一个可扩展的曲线对象包含插值方法.
///
/// 定义:样条曲线是经过一系列给定点的光滑曲线。最初，样条曲线都是借助于物理样条得到的，放样员把富有弹性的细木条（或有机玻璃条），
/// 用压铁固定在曲线应该通过的给定型值点处，样条做自然弯曲所绘制出来的曲线就是样条曲线。样条曲线不仅通过各有序型值点，
/// 并且在各型值点处的一阶和二阶导数连续，也即该曲线具有连续的、曲率变化均匀的特点。
/// NOTE:参考百度百科http://baike.baidu.com/view/1896463.htm?fr=aladdin
/// NOTE:关于三次样条插值,参考百度百科http://baike.baidu.com/view/2326225.htm?fr=aladdin
/// NOTE:关于更多样条曲线插值,参考维基百科http://zh.wikipedia.org/wiki/%E8%B2%9D%E8%8C%B2%E6%9B%B2%E7%B7%9A
/// NOTE:关于样条曲线,参考维基百科http://zh.wikipedia.org/wiki/%E6%A0%B7%E6%9D%A1%E5%87%BD%E6%95%B0
*/
///<summary>Curve</summary>
THREE.Curve = function () {
};
/****************************************
****下面是Curve对象提供的功能函数.
****************************************/
/*
///getPoint方法返回在curve对象上t点(取值范围0.0-1.0之间)的矢量.
*/
///<summary>getPoint</summary>
///<param name ="t" type="float">t的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.</param>
///<returns type="null">返回t点的具体坐标.</returns>
// Virtual base class method to overwrite and implement in subclasses
// 虚基类方法,需要在子类中重写具体实现.
// - t [0 .. 1]
// t的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.
THREE.Curve.prototype.getPoint = function ( t ) {
console.log( "Warning, getPoint() not implemented!" );
return null;
};
/*
///getPointAt方法获得一个点u在曲线上的相对位置,用弧长表示.
///定距等分曲线
*/
///<summary>getPointAt</summary>
///<param name ="u" type="float">u表示距离,通过调用getUtoTmapping方法,换算成t.</param>
///<returns type="float">返回点u在曲线上的相对位置,用弧长表示.</returns>
// Get point at relative position in curve according to arc length
//获得一个点u在曲线上的相对位置,用弧长表示.
// - u [0 .. 1]
// u的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.
THREE.Curve.prototype.getPointAt = function ( u ) {
var t = this.getUtoTmapping( u ); //调用getUtoTmapping,将当前样条曲线作为一个整体,返回点u在曲线上的相对位置或者对应distance对应的位置(0.0-1.0).
return this.getPoint( t ); //返回点u在曲线上的相对位置,用弧长表示.
};
/*
///getPoints方法根据divisions将曲线等分,获得在曲线对象上等分点的点序列.如果没有设置参数divisions,默认初始化为5等分.返回对应等分线段顶点的坐标数组.
///定量等分曲线
*/
///<summary>getPoints</summary>
///<param name ="divisions" type="int">根据divisions将曲线等分,获得在曲线对象上等分点的点序列.如果没有设置参数divisions,默认初始化为5等分.</param>
///<returns type="Vector3Array">返回对应等分线段顶点的坐标数组.</returns>
// Get sequence of points using getPoint( t )
// 根据divisions将曲线等分,获得在曲线对象上等分点的点序列.如果没有设置参数divisions,默认初始化为5等分.
THREE.Curve.prototype.getPoints = function ( divisions ) {
if ( ! divisions ) divisions = 5;
var d, pts = [];
for ( d = 0; d <= divisions; d ++ ) { //遍历等分数量
pts.push( this.getPoint( d / divisions ) ); //调用getPoint方法,返回对应等分线段端点的坐标.
}
return pts; //返回对应等分线段顶点的坐标数组.
};
/*
///getSpacedPoints方法根据divisions将曲线等分,获得在曲线对象上等分点的点序列.如果没有设置参数divisions,默认初始化为5等分.返回对应等分线段端点在曲线上的相对位置数组,用弧长表示.
*/
///<summary>getSpacedPoints</summary>
///<param name ="divisions" type="int">根据divisions将曲线等分,获得在曲线对象上等分点的点序列.如果没有设置参数divisions,默认初始化为5等分.</param>
///<returns type="Vector3Array">返回对应等分线段端点在曲线上的相对位置数组,用弧长表示.</returns>
// Get sequence of points using getPointAt( u )
// 获得一系列顶点的相对位置的数组.调用getPointAt方法.
THREE.Curve.prototype.getSpacedPoints = function ( divisions ) {
if ( ! divisions ) divisions = 5;
var d, pts = [];
for ( d = 0; d <= divisions; d ++ ) { //遍历等分数量
pts.push( this.getPointAt( d / divisions ) ); //调用getPointAt方法,返回对应等分线段端点在曲线上的相对位置数组,用弧长表示.
}
return pts; //返回对应等分线段端点在曲线上的相对位置数组,用弧长表示.
};
/*
///getLength将子曲线的长度的和放入缓存数组.返回曲线路经总长度
*/
///<summary>getLength</summary>
///<returns type="float">返回曲线路经总长度.</returns>
// Get total curve arc length
//获得曲线总的弧长
THREE.Curve.prototype.getLength = function () {
var lengths = this.getLengths();
return lengths[ lengths.length - 1 ];
};
/*
///getLengths将子曲线的长度的和放入缓存数组.返回长度数组
*/
///<summary>getLengths</summary>
///<returns type="floatArray">返回长度数组.</returns>
// Get list of cumulative segment lengths
// 获得个线段的长度的列表
THREE.Curve.prototype.getLengths = function ( divisions ) {
if ( ! divisions ) divisions = (this.__arcLengthDivisions) ? (this.__arcLengthDivisions): 200;
if ( this.cacheArcLengths
&& ( this.cacheArcLengths.length == divisions + 1 )
&& ! this.needsUpdate) {
//console.log( "cached", this.cacheArcLengths );
return this.cacheArcLengths;
}
this.needsUpdate = false;
var cache = [];
var current, last = this.getPoint( 0 );
var p, sum = 0;
cache.push( 0 );
for ( p = 1; p <= divisions; p ++ ) {
current = this.getPoint ( p / divisions );
sum += current.distanceTo( last );
cache.push( sum );
last = current;
}
this.cacheArcLengths = cache;
return cache; // { sums: cache, sum:sum }; Sum is in the last element.
};
/*
///updateArcLengths调用getLengths方法,更新长度数组.
*/
///<summary>updateArcLengths</summary>
///<returns type="floatArray">返回长度数组.</returns>
THREE.Curve.prototype.updateArcLengths = function() {
this.needsUpdate = true;
this.getLengths();
};
/*
///getUtoTmapping方法将当前样条曲线作为一个整体,返回点u在曲线上的相对位置或者对应distance对应的位置(0.0-1.0).
*/
///<summary>getUtoTmapping</summary>
///<param name ="u" type="float">u的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.</param>
///<param name ="distance" type="float">如果设置长度值,则返回对应长度在整条线段的位置</param>
///<returns type="float">点u在曲线上的相对位置或者对应distance对应的位置(0.0-1.0)</returns>
// Given u ( 0 .. 1 ), get a t to find p. This gives you points which are equi distance
// 获得在curve对象上u点(取值范围0.0-1.0之间)距离等于distance的点t.
THREE.Curve.prototype.getUtoTmapping = function ( u, distance ) {
var arcLengths = this.getLengths(); //获得这个线段的长度列表
var i = 0, il = arcLengths.length;
var targetArcLength; // The targeted u distance value to get 获得目标点u的长度值
if ( distance ) { //如果设置了长度
targetArcLength = distance;
} else {
targetArcLength = u * arcLengths[ il - 1 ]; //获得u点在整条线段(是由多个曲线对象组成的线段)中的位置.
}
//var time = Date.now();
// binary search for the index with largest value smaller than target u distance
// 遍历线段的索引,u值在曲线线段上的第几段,就是u值所在位置的线段在arcLengths的索引.
var low = 0, high = il - 1, comparison;
while ( low <= high ) {
i = Math.floor( low + ( high - low ) / 2 ); // less likely to overflow, though probably not issue here, JS doesn't really have integers, all numbers are floats
// 很少有可能溢出,为了保险,将浮点数转成整数
comparison = arcLengths[ i ] - targetArcLength;
if ( comparison < 0 ) {
low = i + 1;
continue;
} else if ( comparison > 0 ) {
high = i - 1;
continue;
} else {
high = i;
break;
// DONE
}
}
i = high;
//console.log('b' , i, low, high, Date.now()- time);
if ( arcLengths[ i ] == targetArcLength ) {
var t = i / ( il - 1 );
return t; //返回位置
}
// we could get finer grain at lengths, or use simple interpolatation between two points
// 获得更精确的长度,在两个索引值之间的位置.
var lengthBefore = arcLengths[ i ];
var lengthAfter = arcLengths[ i + 1 ];
var segmentLength = lengthAfter - lengthBefore;
// determine where we are between the 'before' and 'after' points
// 确定点在“before”和“after"的确切位置.
var segmentFraction = ( targetArcLength - lengthBefore ) / segmentLength;
// add that fractional amount to t
// 获得t在整个线段中的位置
var t = ( i + segmentFraction ) / ( il -1 );
return t; //返回位置.
};
/*
///getTangent方法将返回一个点t在曲线上位置向量的法线向量.
*/
///<summary>getTangent</summary>
///<param name ="t" type="float">t的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.</param>
///<returns type="Vector3">返回一个点t在曲线上位置向量的单位向量</returns>
// Returns a unit vector tangent at t
// 返回一个点t在曲线上位置向量的单位向量
// In case any sub curve does not implement its tangent derivation,
// 2 points a small delta apart will be used to find its gradient
// which seems to give a reasonable approximation
THREE.Curve.prototype.getTangent = function( t ) {
//这里为了给向量设定一个方向.
var delta = 0.0001; //设置一个delta值
var t1 = t - delta; //t点减delta值,
var t2 = t + delta; //t点加delta值.
// Capping in case of danger
if ( t1 < 0 ) t1 = 0;
if ( t2 > 1 ) t2 = 1;
var pt1 = this.getPoint( t1 );
var pt2 = this.getPoint( t2 );
var vec = pt2.clone().sub(pt1);
return vec.normalize(); //返回一个点t在曲线上位置向量的法线向量.
};
/*
///getTangent方法将返回一个点t在曲线上位置向量的法线向量.
*/
///<summary>getTangentAt</summary>
///<param name ="u" type="float">t的取值范围是0.0 - 1.0,将曲线作为一个整体,一个点在这个整体的位置.</param>
///<returns type="Vector3">返回一个点t在曲线上位置向量的单位向量</returns>
THREE.Curve.prototype.getTangentAt = function ( u ) {
var t = this.getUtoTmapping( u ); //getUtoTmapping方法将当前样条曲线作为一个整体,返回点u在曲线上的相对位置或者对应distance对应的位置(0.0-1.0).
return this.getTangent( t ); //getTangent方法将返回一个点t在曲线上位置向量的法线向量
};
/**************************************************************
* Utils
**************************************************************/
// 关于bezier曲线,b样条,nurbs曲线的一些差别.
//§ Bezier曲线中的每个控制点都会影响整个曲线的形状，而B样条中的控制点只会影响整个曲线的一部分，显然B样条提供了更多的灵活性；
//§ Bezier和B样条都是多项式参数曲线，不能表示一些基本的曲线，比如圆，所以引入了NURBS，即非均匀有理B样条来解决这个问题；
// 关于二次样条,3次样条曲线的一些简单的差别,二次样条有3个控制点控制一段曲线,三次样条曲线由4个控制点控制一段曲线.更细分的区别百度吧.
THREE.Curve.Utils = {
/*
///tangentQuadraticBezier方法将返回二次Bezier曲线上点t的切线
*/
///<summary>tangentQuadraticBezier</summary>
///<param name ="t" type="Vector3">三维向量</param>
///<param name ="p0" type="Vector3">三维向量</param>
///<param name ="p1" type="Vector3">三维向量</param>
///<param name ="p2" type="Vector3">三维向量</param>
///<returns type="number">二次Bezier曲线上点t的切线</returns>
tangentQuadraticBezier: function ( t, p0, p1, p2 ) {
return 2 * ( 1 - t ) * ( p1 - p0 ) + 2 * t * ( p2 - p1 ); //二次Bezier曲线上点t的切线
},
// Puay Bing, thanks for helping with this derivative!
/*
///tangentCubicBezier方法将返回三次Bezier曲线上点t的切线
*/
///<summary>tangentQuadraticBezier</summary>
///<param name ="t" type="Vector3">三维向量</param>
///<param name ="p0" type="Vector3">三维向量</param>
///<param name ="p1" type="Vector3">三维向量</param>
///<param name ="p2" type="Vector3">三维向量</param>
///<param name ="p3" type="Vector3">三维向量</param>
///<returns type="number">三次Bezier曲线上点t的切线</returns>
tangentCubicBezier: function (t, p0, p1, p2, p3 ) {
return - 3 * p0 * (1 - t) * (1 - t) +
3 * p1 * (1 - t) * (1-t) - 6 *t *p1 * (1-t) +
6 * t * p2 * (1-t) - 3 * t * t * p2 +
3 * t * t * p3; //三次Bezier曲线上点t的切线
},
/*
///tangentSpline方法将返回Spline曲线上点t的切线
*/
///<summary>tangentSpline</summary>
///<param name ="t" type="Vector3">三维向量</param>
///<param name ="p0" type="Vector3">三维向量</param>
///<param name ="p1" type="Vector3">三维向量</param>
///<param name ="p2" type="Vector3">三维向量</param>
///<param name ="p3" type="Vector3">三维向量</param>
///<returns type="number">返回Spline曲线上点t的切线</returns>
tangentSpline: function ( t, p0, p1, p2, p3 ) {
// To check if my formulas are correct
var h00 = 6 * t * t - 6 * t; // derived from 2t^3 − 3t^2 + 1
var h10 = 3 * t * t - 4 * t + 1; // t^3 − 2t^2 + t
var h01 = - 6 * t * t + 6 * t; // − 2t3 + 3t2
var h11 = 3 * t * t - 2 * t; // t3 − t2
return h00 + h10 + h01 + h11; //三次Bezier曲线上点t的切线
},
// Catmull-Rom
/*
///tangentSpline方法将点t在三次Bezier曲线上插值.
*/
///<summary>tangentSpline</summary>
///<param name ="t" type="Vector3">三维向量</param>
///<param name ="p0" type="Vector3">三维向量</param>
///<param name ="p1" type="Vector3">三维向量</param>
///<param name ="p2" type="Vector3">三维向量</param>
///<param name ="p3" type="Vector3">三维向量</param>
///<returns type="number">返回点t插值后的三次Bezier曲线</returns>
interpolate: function( p0, p1, p2, p3, t ) {
var v0 = ( p2 - p0 ) * 0.5;
var v1 = ( p3 - p1 ) * 0.5;
var t2 = t * t;
var t3 = t * t2;
return ( 2 * p1 - 2 * p2 + v0 + v1 ) * t3 + ( - 3 * p1 + 3 * p2 - 2 * v0 - v1 ) * t2 + v0 * t + p1; //返回点t插值后的三次Bezier曲线
}
};
// TODO: Transformation for Curves?
// TODO: 曲线这个东西,我还是接触的非常少的,不过理解的应该差不多.我自己能说服自己.以后希望更多有才的人来补充.
/**************************************************************
* 3D Curves
**************************************************************/
// A Factory method for creating new curve subclasses
// 一个构造方法用来创建新曲线子类.
/*
///create方法一个构造方法用来创建新曲线子类
*/
///<summary>create</summary>
///<param name ="constructor" type="Object.prototype">.</param>
///<returns type="Vector3">返回一个点t在曲线上位置向量的单位向量</returns>
THREE.Curve.create = function ( constructor, getPointFunc ) {
constructor.prototype = Object.create( THREE.Curve.prototype ); //构造新区线类.
constructor.prototype.getPoint = getPointFunc; //getPoint方法的具体实现
return constructor; //返回构造对象.
};
商域无疆 (http://blog.****.net/omni360/)
本文遵循“署名-非商业用途-保持一致”创作公用协议
转载请保留此句：商域无疆 - 本博客专注于 敏捷开发及移动和物联设备研究：数据可视化、GOLANG、Html5、WEBGL、THREE.JS，否则，出自本博客的文章拒绝转载或再转载，谢谢合作。
以下代码是THREE.JS 源码文件中extras/core/Curve.js文件的注释.
更多更新在 : https://github.com/omni360/three.js.sourcecode