three.js 源碼注釋（十五）Math/Plane.js

標籤：javascript   three.js   web3d   webgl   源碼   

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

本文遵循“署名-非商業用途-保持一致”創作公用協議

轉載請保留此句：商域無疆 -  本部落格專註於 敏捷開發及移動和物聯裝置研究：資料視覺效果、GOLANG、Html5、WEBGL、THREE.JS，否則，出自本部落格的文章拒絕轉載或再轉載，謝謝合作。

俺也是剛開始學,好多地兒肯定不對還請見諒.

以下代碼是THREE.JS 源碼檔案中Math/Plane.js檔案的注釋.

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

// File:src/math/Plane.js/** * @author bhouston / http://exocortex.com *//*///Plane對象的建構函式.用來在三維空間內建立一個法線向量為normal,從原點到平面的距離為constant的無限延展的二維平面對象.Plane對象的功能函數採用///定義構造的函數原型對象來實現.//////用法: var normal = new Vector3(0,0,0),constant = 5.5; var Plane = new Plane(normal,constant);///建立一個法線向量是0,0,0原點到平面的距離是5.5的二維平面.*////<summary>Plane</summary>///<param name ="normal" type="Vector3">平面法線向量</param>///<param name ="constant" type="Number">Number二維平面離原點的距離</param>THREE.Plane = function ( normal, constant ) {this.normal = ( normal !== undefined ) ? normal : new THREE.Vector3( 1, 0, 0 );//賦值或者初始化normalthis.constant = ( constant !== undefined ) ? constant : 0;//賦值或者初始化constant};/********************************************下面是Plane對象提供的功能函數.****************************************/THREE.Plane.prototype = {constructor: THREE.Plane,//構造器,返回對建立此對象的Plane函數的引用/*///set方法用來重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面.*////<summary>set</summary>///<param name ="normal" type="Vector3">平面法線向量</param>///<param name ="constant" type="Number">Number二維平面離原點的距離</param>///<returns type="Plane">返回新的二維平面</returns>set: function ( normal, constant ) {this.normal.copy( normal );this.constant = constant;return this;//返回新的二維平面},/*///setComponents方法用來通過x,y,z,w分量重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面.*////<summary>setComponents</summary>///<param name ="normal" type="Vector3">平面法線向量</param>///<param name ="x" type="Number">平面法線向量x座標</param>///<param name ="y" type="Number">平面法線向量y座標</param>///<param name ="z" type="Number">平面法線向量z座標</param>///<param name ="w" type="Number">Number二維平面離原點的距離w</param>///<returns type="Plane">返回新的二維平面</returns>setComponents: function ( x, y, z, w ) {this.normal.set( x, y, z );this.constant = w;return this;//返回新的二維平面},/*///setFromNormalAndCoplanarPoint方法用來通過參數normal(平面法線向量)和參數point(共面的點)重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面.*////<summary>setFromNormalAndCoplanarPoint</summary>///<param name ="normal" type="Vector3">平面法線向量</param>///<param name ="point" type="Vector3">共面的點</param>///<returns type="Plane">返回新的二維平面</returns>setFromNormalAndCoplanarPoint: function ( normal, point ) {this.normal.copy( normal );//下面point.dot()方法只接收this.normal,不接收normal,this.normal是被正常化的,是單位向量this.constant = - point.dot( this.normal );// must be this.normal, not normal, as this.normal is normalizedreturn this;//並返回新的二維平面},/*///setFromCoplanarPoints方法用來通過共面的點a,b,c重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面./// NOTE:setFromCoplanarPoints方法接受的3個點a,b,c,需要按照逆時針方向的順序傳入,來確定發現的方向.*////<summary>setFromCoplanarPoints</summary>///<param name ="a" type="Vector3">共面的點a</param>///<param name ="b" type="Vector3">共面的點b</param>///<param name ="c" type="Vector3">共面的點c</param>///<returns type="Plane">返回新的二維平面</returns>setFromCoplanarPoints: function () {var v1 = new THREE.Vector3();var v2 = new THREE.Vector3();return function ( a, b, c ) {var normal = v1.subVectors( c, b ).cross( v2.subVectors( a, b ) ).normalize();//先得到向量c,b的差,通過cross方法獲得向量a,b差的交叉乘積(交叉乘積垂直於向量a,b所在的平面),然後在調用normalize()方法獲得單位向量.// Q: should an error be thrown if normal is zero (e.g. degenerate plane)?//NOTE: 如果法向量normal是0,會產生一個無效的平面對象.this.setFromNormalAndCoplanarPoint( normal, a ); //setFromNormalAndCoplanarPoint方法用來通過參數normal(平面法線向量)和參數point(共面的點)重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面.return this;//返回新的二維平面};}(),/*///copy方法用來複製二維平面的法線向量normal,原點到平面的距離constant值.返回新的二維平面///TODO: copy方法和clone方法有什麼不同?*////<summary>copy</summary>///<param name ="Plane" type="Plane">二維平面</param>///<returns type="Plane">返回新的二維平面</returns>copy: function ( plane ) {this.normal.copy( plane.normal );this.constant = plane.constant;return this;//返回新的二維平面},/*///normalize方法用來正常化法線向量,並調整constant常量的值(獲得單位平面).*////<summary>normalize</summary>///<returns type="Plane">返回正常化後的二維平面(獲得單位平面)</returns>normalize: function () {// Note: will lead to a divide by zero if the plane is invalid.// NOTE: 注意如果平面無效將產生除數是0的錯誤.var inverseNormalLength = 1.0 / this.normal.length();this.normal.multiplyScalar( inverseNormalLength );this.constant *= inverseNormalLength;return this;//返回正常化的二維平面(獲得單位平面)},/*///negate方法用來翻轉法線,獲得當前平面的背面,*////<summary>negate</summary>///<returns type="Plane">返回當前平面的背面</returns>negate: function () {this.constant *= - 1;this.normal.negate();//翻轉法線,Vector3.negate方法將當前三維向量的(x,y,z)座標值若為負數時,返回正數. 而當前三維向量的(x,y,z)座標值若為正數時,返回負數. return this;//返回當前平面的背面},/*///distanceToPoint方法用來獲得三維空間內一點到Plane二維平面對象表面的最小長度.*////<summary>distanceToPoint</summary>///<param name ="point" type="Vector3">一個三維空間內的Vector3的三維點座標</param>///<returns type="Number">返回三維空間內一點到Plane二維平面對象表面的最小長度.</returns>distanceToPoint: function ( point ) {return this.normal.dot( point ) + this.constant;//返回三維空間內一點到Plane二維平面對象表面的最小長度},/*///distanceToPoint方法用來獲得Plane二維平面對象到三維空間內一個球體表面的最小長度.()*////<summary>distanceToPoint</summary>///<param name ="sphere" type="Sphere">一個三維空間內的Sphere的球體對象</param>///<returns type="Number">返回三維空間內Plane二維平面對象到三維空間內一個球體表面的最小長度.</returns>distanceToSphere: function ( sphere ) {return this.distanceToPoint( sphere.center ) - sphere.radius;//返回三維空間內Plane二維平面對象到三維空間內一個球體表面的最小長度},/*///projectPoint方法返回三維空間中一點到當前平面的投影.點到面上的投影等於從參數point到平面上的垂足,所以從垂足畫條線到點垂直於平面.*////<summary>projectPoint</summary>///<param name ="point" type="Vector3">Vector3三維向量</param>///<param name ="optionalTarget" type="Vector3">選擇性參數,接收返回結果</param>///<returns type="Number">返回點到平面的投影</returns>projectPoint: function ( point, optionalTarget ) {return this.orthoPoint( point, optionalTarget ).sub( point ).negate();//調用orthoPoint()方法,減去point,返回取反的結果},/*///orthoPoint方法返回一個與當前二維平面對象法線向量方向相同,與參數point到平面距離相等大小的向量(垂足).如果設定了optionalTarget參數,將結果儲存在optionalTarget裡.*////<summary>orthoPoint</summary>///<param name ="point" type="Vector3">Vector3三維向量</param>///<param name ="optionalTarget" type="Vector3">選擇性參數,接收返回結果</param>///<returns type="Vector3">返回一個與當前二維平面對象法線向量方向相同,與參數point到平面距離相等大小的向量(垂足).</returns>orthoPoint: function ( point, optionalTarget ) {var perpendicularMagnitude = this.distanceToPoint( point );//獲得平面到參數point的距離,賦值給prependicularMagnitudevar result = optionalTarget || new THREE.Vector3();//生命變數resault,用來存放結果return result.copy( this.normal ).multiplyScalar( perpendicularMagnitude );//調用multiplyScalar(perpendicularMagnitude)方法,將當前二維平面的法向量的分量x,y,z分別乘以獲得平面到參數point的距離.最後返回計算結果.},/*///isIntersectionLine方法擷取當前二維平面是否與參數line相交,返回true 或者 false*////<summary>isIntersectionLine</summary>///<param name ="line" type="Line3">三維空間中的線Line3</param>///<returns type="Boolean">返回true 或者 false</returns>isIntersectionLine: function ( line ) {// Note: this tests if a line intersects the plane, not whether it (or its end-points) are coplanar with it.// NOTE:isIntersectionLine()是測試線和面是否相交,不是誤以為線和面是否共面var startSign = this.distanceToPoint( line.start );var endSign = this.distanceToPoint( line.end );return ( startSign < 0 && endSign > 0 ) || ( endSign < 0 && startSign > 0 );//返回true 或者 false},/*///intersectLine方法擷取當前二維平面與參數line相交的交點,如果和參數Line不相交返回undefined,如果線和當前二維平面共面返回線的起點.*////<summary>isIntersectionLine</summary>///<param name ="line" type="Line3">三維空間中的線Line3</param>///<param name ="optionalTarget" type="Vector3">選擇性參數,接收返回結果</param>///<returns type="Boolean">返回當前二維平面與參數line相交的交點,如果和參數Line不相交或其它未知返回undefined,如果線和當前二維平面共面返回線的起點.</returns>intersectLine: function () {var v1 = new THREE.Vector3();return function ( line, optionalTarget ) {var result = optionalTarget || new THREE.Vector3();var direction = line.delta( v1 );var denominator = this.normal.dot( direction );if ( denominator == 0 ) {// line is coplanar, return origin// 如果線和當前二維平面共面返回線的起點if ( this.distanceToPoint( line.start ) == 0 ) {return result.copy( line.start );}// Unsure if this is the correct method to handle this case.// 如果其它未知返回undefinedreturn undefined;}var t = - ( line.start.dot( this.normal ) + this.constant ) / denominator;if ( t < 0 || t > 1 ) {return undefined;//如果和參數Line不相交返回undefined}return result.copy( direction ).multiplyScalar( t ).add( line.start );//返回當前二維平面與參數line相交的交點};}(),/*///coplanarPoint方法擷取當前二維平面的法線向量到當前二維平面投影(垂足,與當前平面的共面的點).///TODO:這裡沒有弄明白,有時間在弄清楚,高中幾何都快忘光了,鑽牛角尖了.不過知道在下面應用變換時調用了.*////<summary>coplanarPoint</summary>///<param name ="optionalTarget" type="Vector3">選擇性參數,接收返回結果</param>///<returns type="Boolean">返回共面的點.</returns>coplanarPoint: function ( optionalTarget ) {var result = optionalTarget || new THREE.Vector3();return result.copy( this.normal ).multiplyScalar( - this.constant );//返回共面的點},/*///applyMatrix4方法通過傳遞matrix(旋轉,縮放,移動等變換矩陣)對當前Plane二維平面對象的法線向量normal和,應用變換.*////<summary>applyMatrix4</summary>///<param name ="matrix" type="Matrix4">(旋轉,縮放,移動等變換矩陣</param>///<param name ="optionalNormalMatrix" type="Matrix3">選擇性參數,如果設定了就會對法線應用(旋轉,縮放,移動等變換矩陣</param>///<returns type="Boolean">返回變換後的二維平面.</returns>applyMatrix4: function () {var v1 = new THREE.Vector3();var v2 = new THREE.Vector3();var m1 = new THREE.Matrix3();return function ( matrix, optionalNormalMatrix ) {// compute new normal based on theory here:// http://www.songho.ca/opengl/gl_normaltransform.htmlvar normalMatrix = optionalNormalMatrix || m1.getNormalMatrix( matrix );var newNormal = v1.copy( this.normal ).applyMatrix3( normalMatrix );var newCoplanarPoint = this.coplanarPoint( v2 );//獲得共面的點newCoplanarPoint.applyMatrix4( matrix );this.setFromNormalAndCoplanarPoint( newNormal, newCoplanarPoint );//setFromNormalAndCoplanarPoint方法用來通過參數normal(平面法線向量)和參數point(共面的點)重新設定二維平面的法線向量normal,原點到平面的距離constant,並返回新的二維平面.return this;//返回變換後的二維平面};}(),/*///translate方法用來通過參數offset,移動當前二維平面的位置.*////<summary>translate</summary>///<param name ="offset" type="Vector3">位移量</param>///<returns type="Boolean">返回新的二維平面</returns>translate: function ( offset ) {this.constant = this.constant - offset.dot( this.normal );return this;//返回新的二維平面},/*///equals方法用來獲得參數Plane(一個Plane的二維平面)是否與當前二維平面完全相等,即法線向量normal和半徑相等.*////<summary>equals</summary>///<param name ="Plane" type="Plane">一個Plane的二維平面</param>///<returns type="Boolean">返回true 或者 false</returns>equals: function ( plane ) {return plane.normal.equals( this.normal ) && ( plane.constant == this.constant );//返回true 或者 false},/*clone方法///clone方法複製一個二維平面對象.*////<summary>clone</summary>///<returns type="Plane">返回二維平面對象</returns>clone: function () {return new THREE.Plane().copy( this );//返回二維平面對象}};

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

本文遵循“署名-非商業用途-保持一致”創作公用協議

轉載請保留此句：商域無疆 -  本部落格專註於 敏捷開發及移動和物聯裝置研究：資料視覺效果、GOLANG、Html5、WEBGL、THREE.JS，否則，出自本部落格的文章拒絕轉載或再轉載，謝謝合作。

以下代碼是THREE.JS 源碼檔案中Math/Plane.js檔案的注釋.

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

three.js 源碼注釋（十五）Math/Plane.js