three.js 源码注释（七）Math/Euler.js

商域无疆 (http://blog.csdn.net/omni360/)

本文遵循“署名-非商业用途-保持一致”创作公用协议

转载请保留此句：商域无疆 -  本博客专注于 敏捷开发及移动和物联设备研究：数据可视化、GOLANG、Html5、WEBGL、THREE.JS，否则，出自本博客的文章拒绝转载或再转载，谢谢合作。

以下代码是THREE.JS 源码文件中Math/Quaternion.js文件的注释.

更多更新在 : https://github.com/omni360/three.js.sourcecode/blob/master/Three.js

// File:src/math/Euler.js/** * @author mrdoob / http://mrdoob.com/ * @author WestLangley / http://github.com/WestLangley * @author bhouston / http://exocortex.com *//*///Euler对象的构造函数.用来创建一个欧拉角的对象.Euler对象的功能函数采用///定义构造的函数原型对象来实现.//////用法: var euler = new Euler(5,3,2,'XYZ')///创建一个绕某轴旋转5度,绕y轴旋转某度,绕某轴旋转2度,旋转顺序为'XYZ'.有了旋转顺序才能确定每个x,y,z轴分别旋转多少度.///NOTE: 参数x,y,z代表3个轴的旋转角度,具体哪个轴旋转多少度,需要后面的参数(order)旋转顺序来确定.///NOTE: 参数(x,y,z,order)为可选参数,如果不指定参数(x,y,z,order),将创建一个坐标为(0,0,0,'XYZ')的Eular(欧拉角)对象./// NOTE: 参数order(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]////// 通俗的讲,欧拉角就是用来描述一个物体在三维空间中方向的一种常用的方法.举例来说,一个物体在三维空间中,绕x轴转了多少度,///y轴转了多少度,z轴转了多少度,来描述物体在三维空间中的方向./// 有点类似香港电影里飞虎队队员之间说,"飞鹰,飞鹰,在你的正前方,5点钟方向,发现目标,准备聚集目标."///*////<summary>Euler</summary>///<param name ="x" type="number">绕某轴旋转x度</param>///<param name ="y" type="number">绕某轴旋转y度</param>///<param name ="z" type="number">绕某轴旋转z度</param>///<param name ="order" type="String">order(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]</param>THREE.Euler = function ( x, y, z, order ) {this._x = x || 0;this._y = y || 0;this._z = z || 0;this._order = order || THREE.Euler.DefaultOrder;};THREE.Euler.RotationOrders = [ 'XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ];//(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]THREE.Euler.DefaultOrder = 'XYZ';//默认的旋转顺序为'XYZ'/********************************************下面是Euler对象提供的功能函数.****************************************/THREE.Euler.prototype = {constructor: THREE.Euler, //构造器_x: 0, _y: 0, _z: 0, _order: THREE.Euler.DefaultOrder,//将(_x,_y,_z,_order)初始化x,y,z为0,旋转顺序为默认旋转顺序'XYZ';/*///get x 方法用来获取euler角x值.///NOTE: get x()的用法是Euler.prototype.x(Euler.x),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>get x</summary>///<returns type="number">返回euler角_x值</returns>get x () {return this._x;//返回euler角_x值},/*///set x 方法用来从新设置Euler角的x值.并返回新的值的Euler角.///NOTE: set x()的用法是Euler.prototype.x=value(Euler.x = value),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>set x</summary>///<param name ="value" type="number">绕x轴旋转的角度值</param>set x ( value ) {this._x = value;//设置Euler角的_x值this.onChangeCallback(); //调用回调函数.},/*///get y 方法用来从获取euler角y值.///NOTE: get y()的用法是Euler.prototype.y(Euler.y),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>get y</summary>///<returns type="number">返回euler角_y值</returns>get y () {return this._y;//返回euler角_y值},/*///set y 方法用来从新设置Euler角的y值.并返回新的值的Euler角.///NOTE: set y()的用法是Euler.prototype.y=value(Euler.y = value),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>set y</summary>///<param name ="value" type="number">绕y轴旋转的角度值</param>set y ( value ) {this._y = value;//设置Euler角的_y值this.onChangeCallback(); //调用回调函数.},/*///get z 方法用来获取euler角z值.///NOTE: get z()的用法是Euler.prototype.z(Euler.z),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>get z</summary>///<returns type="number">返回euler角_z值</returns>get z () {return this._z;//返回euler角_z值},/*///set z 方法用来从新设置Euler角的z值.并返回新的值的Euler角.///NOTE: set z()的用法是Euler.prototype.z=value(Euler.z = value),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>set z</summary>///<param name ="value" type="number">绕z轴旋转的角度值</param>set z ( value ) {this._z = value;//设置Euler角的_z值this.onChangeCallback(); //调用回调函数.},/*///get order 方法用来获取euler角order值.///NOTE: get order()的用法是Euler.prototype.order(Euler.order),这种用法在除ie浏览器以外的浏览器上可以使用.*////<summary>get order</summary>///<returns type="number">返回euler角_z值</returns>get order () {return this._order;//返回euler角_order值},/*///set order 方法用来从新设置Euler角的order值.并返回新的值的Euler角.///NOTE: set order()的用法是Euler.prototype.order=value(Euler.order = value),这种用法在除ie浏览器以外的浏览器上可以使用.///NOTE: 参数(x,y,z,order)为可选参数,如果不指定参数(x,y,z,order),将创建一个坐标为(0,0,0,'XYZ')的Eular(欧拉角)对象./// NOTE: 参数order(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]*////<summary>set order</summary>///<param name ="value" type="number">绕z轴旋转的角度值</param>set order ( value ) {this._order = value;  //设置Euler角的_order值this.onChangeCallback(); //调用回调函数.},///TODO:这里缺少setX()方法.///TODO:这里缺少setY()方法.///TODO:这里缺少setZ()方法.///TODO:这里缺少setW()方法.///TODO:这里缺少setComponent()方法.///TODO:这里缺少getComponent()方法./*///set方法用来从新设置Euler(欧拉角)的x,y,z,order值.并返回新的坐标值的Euler(欧拉角)./// TODO:修改set方法,兼容x,y,z,order参数省略支持多态.*////<summary>set</summary>///<param name ="x" type="number">绕某轴旋转x度</param>///<param name ="y" type="number">绕某轴旋转y度</param>///<param name ="z" type="number">绕某轴旋转z度</param>///<param name ="order" type="number">order(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>set: function ( x, y, z, order ) {this._x = x;this._y = y;this._z = z;this._order = order || this._order;this.onChangeCallback();//调用回调函数.return this;//返回新的Euler(欧拉角)},/*///copy方法用来复制Euler(欧拉角)的(x,y,z,order)值.并返回新的Euler(欧拉角).*////<summary>copy</summary>///<param name ="euler(欧拉角)" type="Quaternion">Euler(欧拉角)</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>copy: function ( euler ) {this._x = euler._x;this._y = euler._y;this._z = euler._z;this._order = euler._order;this.onChangeCallback();//调用回调函数.return this;//返回新的Euler(欧拉角)},/*///setFromRotationMatrix方法利用一个参数m(旋转矩阵),达到旋转变换的目的吧./// NOTE:m是一个旋转矩阵,更多公式:http://en.wikipedia.org/wiki/Transformation_matrix////// 样例:这个样例是z轴旋转30度./----------------------------------------------------\|cos(heading) = 0.866| sin(heading) = 0.5   | 0 ||-----------------------|----------------------------|matrix =|-sin(heading) = -0.5   |cos(heading) = 0.866  | 0   ||-----------------------|----------------------|-----||     0                 |     0                | 1   |\----------------------------------------------------/angle = acos ( ( m00 + m11 + m22 - 1)/2)angle = acos ( ( 0.866 + 0.866 + 1 - 1)/2)angle = acos ( 0.866 )angle = 30 degreesx = (m21 - m12) = 0 - 0 =0y = (m02 - m20) = 0 - 0 =0z = (m10 - m01) = -0.5 - 0.5 = -1*////<summary>setFromRotationMatrix</summary>///<param name ="m" type="Matrix3">3x3矩阵(旋转矩阵)</param>///<param name ="order" type="String">order(旋转顺序) 默认顺序是'XYZ' 取值范围是['XYZ', 'YZX', 'ZXY', 'XZY', 'YXZ', 'ZYX' ]</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>setFromRotationMatrix: function ( m, order ) {var clamp = THREE.Math.clamp;//clamp用来设置数值的取值范围// assumes the upper 3x3 of m is a pure rotation matrix (i.e, unscaled)// 确保参数m是一个3x3的旋转矩阵.var te = m.elements;var m11 = te[ 0 ], m12 = te[ 4 ], m13 = te[ 8 ];var m21 = te[ 1 ], m22 = te[ 5 ], m23 = te[ 9 ];var m31 = te[ 2 ], m32 = te[ 6 ], m33 = te[ 10 ];order = order || this._order;if ( order === 'XYZ' ) {this._y = Math.asin( clamp( m13, - 1, 1 ) );if ( Math.abs( m13 ) < 0.99999 ) {this._x = Math.atan2( - m23, m33 );this._z = Math.atan2( - m12, m11 );} else {this._x = Math.atan2( m32, m22 );this._z = 0;}} else if ( order === 'YXZ' ) {this._x = Math.asin( - clamp( m23, - 1, 1 ) );if ( Math.abs( m23 ) < 0.99999 ) {this._y = Math.atan2( m13, m33 );this._z = Math.atan2( m21, m22 );} else {this._y = Math.atan2( - m31, m11 );this._z = 0;}} else if ( order === 'ZXY' ) {this._x = Math.asin( clamp( m32, - 1, 1 ) );if ( Math.abs( m32 ) < 0.99999 ) {this._y = Math.atan2( - m31, m33 );this._z = Math.atan2( - m12, m22 );} else {this._y = 0;this._z = Math.atan2( m21, m11 );}} else if ( order === 'ZYX' ) {this._y = Math.asin( - clamp( m31, - 1, 1 ) );if ( Math.abs( m31 ) < 0.99999 ) {this._x = Math.atan2( m32, m33 );this._z = Math.atan2( m21, m11 );} else {this._x = 0;this._z = Math.atan2( - m12, m22 );}} else if ( order === 'YZX' ) {this._z = Math.asin( clamp( m21, - 1, 1 ) );if ( Math.abs( m21 ) < 0.99999 ) {this._x = Math.atan2( - m23, m22 );this._y = Math.atan2( - m31, m11 );} else {this._x = 0;this._y = Math.atan2( m13, m33 );}} else if ( order === 'XZY' ) {this._z = Math.asin( - clamp( m12, - 1, 1 ) );if ( Math.abs( m12 ) < 0.99999 ) {this._x = Math.atan2( m32, m22 );this._y = Math.atan2( m13, m11 );} else {this._x = Math.atan2( - m23, m33 );this._y = 0;}} else {console.warn( 'THREE.Euler: .setFromRotationMatrix() given unsupported order: ' + order )//通过按照以上几种旋转顺序设置欧拉角对象失败报错}this._order = order;//重新设置旋转顺序this.onChangeCallback();//调用回调函数.return this;//返回新的Euler(欧拉角)},/*///setFromQuaternion方法通过四元数设置Euler(欧拉角)./// NOTE:参数(q)必须是单位向量,通过调用.normalize()得到单位向量./// NOTE:参数update是一个可选参数.如果不设置默认为true.*////<summary>setFromQuaternion</summary>///<param name ="q" type="Quaternion">四元数</param>///<param name ="order" type="String">旋转顺序</param>///<param name ="update" type="bool">update表示是否调用回调函数bool型标记值</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>setFromQuaternion: function ( q, order, update ) {var clamp = THREE.Math.clamp;//clamp用来设置数值的取值范围// q is assumed to be normalized// 确保q是一个单位向量// 下面网址是对四元数转换成欧拉角的一个详细的介绍.里面有好多的数学算法.// http://www.mathworks.com/matlabcentral/fileexchange/20696-function-to-convert-between-dcm-euler-angles-quaternions-and-euler-vectors/content/SpinCalc.mvar sqx = q.x * q.x;var sqy = q.y * q.y;var sqz = q.z * q.z;var sqw = q.w * q.w;order = order || this._order;if ( order === 'XYZ' ) {this._x = Math.atan2( 2 * ( q.x * q.w - q.y * q.z ), ( sqw - sqx - sqy + sqz ) );this._y = Math.asin(  clamp( 2 * ( q.x * q.z + q.y * q.w ), - 1, 1 ) );this._z = Math.atan2( 2 * ( q.z * q.w - q.x * q.y ), ( sqw + sqx - sqy - sqz ) );} else if ( order ===  'YXZ' ) {this._x = Math.asin(  clamp( 2 * ( q.x * q.w - q.y * q.z ), - 1, 1 ) );this._y = Math.atan2( 2 * ( q.x * q.z + q.y * q.w ), ( sqw - sqx - sqy + sqz ) );this._z = Math.atan2( 2 * ( q.x * q.y + q.z * q.w ), ( sqw - sqx + sqy - sqz ) );} else if ( order === 'ZXY' ) {this._x = Math.asin(  clamp( 2 * ( q.x * q.w + q.y * q.z ), - 1, 1 ) );this._y = Math.atan2( 2 * ( q.y * q.w - q.z * q.x ), ( sqw - sqx - sqy + sqz ) );this._z = Math.atan2( 2 * ( q.z * q.w - q.x * q.y ), ( sqw - sqx + sqy - sqz ) );} else if ( order === 'ZYX' ) {this._x = Math.atan2( 2 * ( q.x * q.w + q.z * q.y ), ( sqw - sqx - sqy + sqz ) );this._y = Math.asin(  clamp( 2 * ( q.y * q.w - q.x * q.z ), - 1, 1 ) );this._z = Math.atan2( 2 * ( q.x * q.y + q.z * q.w ), ( sqw + sqx - sqy - sqz ) );} else if ( order === 'YZX' ) {this._x = Math.atan2( 2 * ( q.x * q.w - q.z * q.y ), ( sqw - sqx + sqy - sqz ) );this._y = Math.atan2( 2 * ( q.y * q.w - q.x * q.z ), ( sqw + sqx - sqy - sqz ) );this._z = Math.asin(  clamp( 2 * ( q.x * q.y + q.z * q.w ), - 1, 1 ) );} else if ( order === 'XZY' ) {this._x = Math.atan2( 2 * ( q.x * q.w + q.y * q.z ), ( sqw - sqx + sqy - sqz ) );this._y = Math.atan2( 2 * ( q.x * q.z + q.y * q.w ), ( sqw + sqx - sqy - sqz ) );this._z = Math.asin(  clamp( 2 * ( q.z * q.w - q.x * q.y ), - 1, 1 ) );} else {console.warn( 'THREE.Euler: .setFromQuaternion() given unsupported order: ' + order )//通过按照以上几种旋转顺序设置欧拉角对象失败报错}this._order = order;//重新设置旋转顺序if ( update !== false ) this.onChangeCallback();//通过update参数判断是否调用回调函数.return this;//返回新的Euler(欧拉角)},/*///reorder方法通过四元数设置Euler(欧拉角)的旋转顺序./// NOTE:参数(q)必须是单位向量,通过调用.normalize()得到单位向量./// WARNING: reorder 方法将丢弃Euler(欧拉角)的旋转顺序信息.*////<summary>reorder</summary>///<param name ="order" type="String">旋转顺序</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>reorder: function () {// WARNING: reorder 方法将丢弃Euler(欧拉角)的旋转顺序信息.// WARNING: this discards revolution information -bhoustonvar q = new THREE.Quaternion();return function ( newOrder ) {q.setFromEuler( this );this.setFromQuaternion( q, newOrder );//调用setFromQuaternion()方法,返回新旋转顺序的Euler(欧拉角)};}(),/*equals方法///equals方法相当于比较运算符===,将当前Euler(欧拉角)和参数euler中的(x,y,z,order)值进行对比,返回bool型值.*////<summary>equals</summary>///<param name ="v" type="Euler(欧拉角)">Euler(欧拉角)(x,y,z,order)</param>///<returns type="bool">返回true or false</returns>equals: function ( euler ) {return ( euler._x === this._x ) && ( euler._y === this._y ) && ( euler._z === this._z ) && ( euler._order === this._order );},/*fromArray方法///fromArray方法将存储Euler(欧拉角)(x,y,z,order)值的数组赋值给当前Euler(欧拉角)对象/// NOTE:参数order是一个可选参数.如果不设置使用默认的旋转顺序.*////<summary>fromArray</summary>///<param name ="array" type="Array">Euler(欧拉角)(x,y,z,order)值数组array[x,y,z,order]</param>///<returns type="Euler(欧拉角)">返回新的Euler(欧拉角)</returns>fromArray: function ( array ) {this._x = array[ 0 ];this._y = array[ 1 ];this._z = array[ 2 ];if ( array[ 3 ] !== undefined ) this._order = array[ 3 ];this.onChangeCallback();//调用回调函数.return this;//返回新的Euler(欧拉角)},/*toArray方法///toArray方法将当前Euler(欧拉角)对象的属性赋值给数组array[5,3,2,'XYZ'].返回一个数组对象.*////<summary>toArray</summary>///<returns type="Array">Euler(欧拉角)(_x,_y,_z,_order)值数组array[x,y,z,order]</returns>toArray: function () {return [ this._x, this._y, this._z, this._order ];//返回一个包含x,y,z,order数值的数组,},/*onChange方法///onChange方法在将回调函数表达式作为callback参数传递给onChangeCallback()方法.*////<summary>onChange</summary>///<param name ="callback" type="function">回调函数</param>///<returns type="Euler(欧拉角)">Euler(欧拉角)</returns>onChange: function ( callback ) {this.onChangeCallback = callback;return this;},/*onChangeCallback方法///onChangeCallback方法克隆一个Euler(欧拉角)对象.///NOTE:onChangeCallback()方法在这里就是一个空的函数属性,在上面大部分的方法中都调用了onChangeCallback()方法,这是一种很方便的方法.*////<summary>onChangeCallback</summary>onChangeCallback: function () {},/*clone方法///clone方法克隆一个Euler(欧拉角)对象.*////<summary>clone</summary>///<returns type="Euler(欧拉角)">返回Euler(欧拉角)对象</returns>clone: function () {return new THREE.Euler( this._x, this._y, this._z, this._order );}};

商域无疆 (http://blog.csdn.net/omni360/)

本文遵循“署名-非商业用途-保持一致”创作公用协议

转载请保留此句：商域无疆 -  本博客专注于 敏捷开发及移动和物联设备研究：数据可视化、GOLANG、Html5、WEBGL、THREE.JS，否则，出自本博客的文章拒绝转载或再转载，谢谢合作。

以下代码是THREE.JS 源码文件中Math/Quaternion.js文件的注释.

更多更新在 : https://github.com/omni360/three.js.sourcecode/blob/master/Three.js