# 数学模块

# 基础模块： Math

模块接口：

接口名称	接口含义	参数1类型	参数2类型	返回值说明	返回值类型
sin	正弦	浮点型-弧度值	空	返回以弧度为单位的角度的正弦值	浮点型
cos	余弦	浮点型-弧度值	空	返回以弧度为单位的角度的余弦值	浮点型
tan	正切	浮点型-弧度值	空	返回以弧度为单位的角度的正切值	浮点型
asin	反正弦	浮点型	空	返回以弧度为单位的角度的反正弦值结果范围在 -pi/2 到 pi/2 之间	浮点型
acos	反余弦	浮点型	空	返回以弧度为单位的角度的反余弦值结果范围在 0 到 pi 之间	浮点型
atan	反正切	浮点型	空	返回以弧度为单位的角度的反正切值结果范围在 -pi/2 到 pi/2 之间	浮点型
radians	角度转换	浮点型	空	将角度从度数转为弧度	浮点型
degrees	角度转换	浮点型	空	将角度从弧度转为度数	浮点型
ceil	向上取整	浮点型	空	返回大于或者等于参数的最小整数	整数
floor	向下取整	浮点型	空	返回小于或者等于参数的最大整数	整数
exp	幂函数	浮点型	空	返回e的x次幂 x为参数1	浮点型
log	对数函数	浮点型	浮点型>0	只有参数1时, 返回参数1的自然底数包含两个参数时, 返回log(x)/log(base) x: 参数1的值 base: 参数2的值两个参数都需要大于0	浮点型
log2	以2为底数的对数函数	浮点型	空	返回 x 以2为底的对数参数大于0	浮点型
log10	以10为底数的对数函数	浮点型	空	返回 x 以10为底的对数参数大于0	浮点型
pow	指数函数	浮点型	浮点型	返回 x 的 y 次幂 x: 参数1的值, 不可为0 y: 参数2的值	浮点型
sqrt	平方根	浮点型	空	返回参数的算数平方根	浮点型
pi	圆周率Π	空	空	返回16位精度的圆周率	浮点型
e	自然常数e	空	空	返回十六位精度的圆周率	浮点型

# 三维向量： Vector3

展开: (三维向量)

定义方式：

// 空参构建 [0, 0, 0]
var b = new Vector3();

// 参数构建[0, 1, 0]
var a = new Vector3(0, 1, 0);

// 通过在程序中定义的点构建[p.x, p.y, p.z]
// 无法通过拾取件构建
var p = new Point();
var vector2 = new Vector3(p);

1
2
3
4
5
6
7
8
9
10

属性：

.x // 三维向量的x值, Number类型
.y // 三维向量的y值, Number类型
.z // 三维向量的z值, Number类型

1
2
3

复制方式： 引用复制
方法API：
- add
  - 参数: add (v: Vector3)
  - 功能：将传入的向量v和这个向量相加。
  - 返回值： this (Vector3)
- addScalar
  - 参数: addScalar (s: Number)
  - 功能：将传入的标量s和这个向量的x值、y值以及z值相加。
  - 返回值： this (Vector3)
- addScaledVector
  - 参数: addScaledVector (v: Vector3, s: Number)
  - 功能：将所传入的v与s相乘所得的乘积和这个向量相加。
  - 返回值： this (Vector3)
- addVectors
  - 参数: addVectors (a: Vector3, b: Vector3)
  - 功能：将该向量设置为a + b。
  - 返回值： this (Vector3)
- applyMatrix4
  - 参数: applyMatrix4 (m: Matrix4)
  - 功能：将该向量乘以四阶矩阵m(第四个维度隐式的为1)，并按照视角划分。
  - 返回值： this (Vector3)
- angleTo
  - 参数: angleTo (v: Vector3)
  - 返回值：该向量与向量v之间的角度 (Number, 弧度)
- ceil
  - 参数: ceil ()
  - 功能：将该向量x分量、y分量以及z分量向上取整为最接近的整数。
  - 返回值： this (Vector3)
- clamp
  - 参数: clamp (min: Vector3, max: Vector3)
    min - 在限制范围内，x值、y值和z的最小值。
    max - 在限制范围内，x值、y值和z的最大值。
  - 功能：
    如果该向量的x值、y值或z值大于限制范围内最大x值、y值或z值，则该值将会被所对应的值取代。
    如果该向量的x值、y值或z值小于限制范围内最小x值、y值或z值，则该值将会被所对应的值取代。
  - 返回值： this (Vector3)
- clampLength
  - 参数: clampLength (min: Number, max: Number)
    min - 长度将被限制为的最小值。
    max - 长度将被限制为的最大值。
  - 功能：
    如果向量长度大于最大值，则它将会被最大值所取代。
    如果向量长度小于最小值，则它将会被最小值所取代。
  - 返回值： this (Vector3)
- clampScalar
  - 参数: clampScalar (min: Number, max: Number)
    min - 分量将被限制为的最小值。
    max - 分量将被限制为的最大值。
  - 功能：
    如果该向量的x值、y值或z值大于最大值，则它们将被最大值所取代。
    如果该向量的x值、y值或z值小于最小值，则它们将被最小值所取代。
  - 返回值： this (Vector3)
- clone
  - 参数: clone ()
  - 返回值：一个新的Vector3，其具有和当前这个向量相同的x、y和z (Vector3)
- copy
  - 参数: copy (v: Vector3)
  - 功能：将所传入Vector3的x、y和z属性复制给当前的Vector3。
  - 返回值： this (Vector3)
- cross
  - 参数: cross (v: Vector3)
  - 功能：将该向量设置为它本身与传入的v的叉积(cross product)。
  - 返回值： this (Vector3)
- crossVectors
  - 参数: crossVectors (a: Vector3, b: Vector3)
  - 功能：将该向量设置为传入的a与b的叉积 (cross product)。
  - 返回值： this (Vector3)
- distanceTo
  - 参数: distanceTo (v: Vector3)
  - 返回值：该向量到所传入的v间的距离 (Number)
- manhattanDistanceTo
  - 参数: manhattanDistanceTo (v: Vector3)
  - 返回值：向量到所传入的v之间的曼哈顿距离 (Number)
- distanceToSquared
  - 参数: distanceToSquared (v: Vector3)
  - 返回值：该向量到传入的v的平方距离 (Number)
- divide
  - 参数: divide (v: Vector3)
  - 功能：将该向量除以向量v。
  - 返回值： this (Vector3)
- divideScalar
  - 参数: divideScalar (s: Number)
  - 功能：
    将该向量除以标量s。
    如果传入的s = 0，则向量(this)将被设置为( 0, 0, 0 )。
  - 返回值： this (Vector3)
- dot
  - 参数: dot ()
  - 返回值：该向量和所传入v的点积 (Number)
- equals
  - 参数: equals (v: Vector3)
  - 返回值：该向量和v的严格相等性 (Boolean)
- floor
  - 参数: floor ()
  - 功能：向量的分量向下取整为最接近的整数值。
  - 返回值： this (Vector3)
- fromArray
  - 参数: fromArray (array: List, offset: Integer)
    array - 来源矩阵。
    offset - (可选)在数组中的元素偏移量，默认值为0。
  - 功能：设置向量中的x值为array[offset + 0]，y值为array[offset + 1]， z值为array[offset + 2]。
  - 返回值： this (Vector3)
- getComponent
  - 参数: getComponent (index: Integer)
    index - (支持传入参数的值) 0, 1 或 2。
  - 功能：通过位置信息获取三维向量的元素值。
  - 返回值：
    如果index值为0，返回x值 (Number)
    如果index值为1，返回y值 (Number)
    如果index值为2，返回z值 (Number)
- length
  - 参数: length ()
  - 返回值：从(0, 0, 0) 到 (x, y, z)的欧几里得长度 (Number)
- manhattanLength
  - 参数: manhattanLength ()
  - 返回值：该向量的曼哈顿长度 (Number)
- lengthSq
  - 参数: lengthSq ()
  - 返回值：计算从(0, 0, 0)到(x, y, z)的欧几里得长度的平方 (Number)
- lerp
  - 参数: lerp (v: Vector3, alpha: Number)
    v - 朝着进行插值的Vector3。
    alpha - 插值因数，其范围通常在[0, 1]闭区间。
  - 功能：在该向量与传入的向量v之间的线性插值，alpha是沿着线的长度的百分比(alpha=0时表示的是当前向量，alpha=1时表示的是所传入的向量v)。
  - 返回值： this (Vector3)
- lerpVectors
  - 参数: lerpVectors (v1: Vector3, v2: Vector3, alpha: Number)
    v1 - 起始的Vector3。
    v2 - 朝着进行插值的Vector3。
    alpha - 插值因数，其范围通常在[0, 1]闭区间。
  - 功能：将此向量设置为在v1和v2之间进行线性插值的向量，其中alpha为两个向量之间连线的长度的百分比(alpha=0时表示的是v1, alpha=1时表示的是v2)。
  - 返回值： this (Vector3)
- max
  - 参数: max (v: Vector3)
  - 功能：如果该向量的x值、y值或z值小于所传入v的x值、y值或z值，则将该值替换为对应的最大值。
  - 返回值： this (Vector3)
- min
  - 参数: min (v: Vector3)
  - 功能：如果该向量的x值、y值或z值大于所传入v的x值、y值或z值，则将该值替换为对应的最小值。
  - 返回值： this (Vector3)
- multiply
  - 参数: multiply (v: Vector3)
  - 功能：将该向量与所传入的向量v进行相乘。
  - 返回值： this (Vector3)
- multiplyScalar
  - 参数: multiplyScalar (s: Number)
  - 功能：将该向量与所传入的标量s进行相乘。
  - 返回值： this (Vector3)
- multiplyVectors
  - 参数: multiplyVectors (a: Vector3, b: Vector3)
  - 功能：按照分量顺序，将该向量设置为和a * b相等。
  - 返回值： this (Vector3)
- negate
  - 参数: negate ()
  - 功能：向量取反，即：x = -x, y = -y , z = -z。
  - 返回值： this (Vector3)
- normalize
  - 参数: normalize ()
  - 功能：将该向量转换为单位向量(方向相同，长度(length)为1)。
  - 返回值： this (Vector3)
- projectOnPlane
  - 参数: projectOnPlane (planeNormal: Vector3)
    planeNormal – 表示平面法线的向量
  - 功能：通过从该向量中减去投影到平面法线上的向量，将该向量投影到平面上。
  - 返回值： this (Vector3)
- projectOnVector
  - 参数: projectOnVector (Vector3: Vector3)
  - 功能：投影(Projects)该向量到向量v上。
  - 返回值： this (Vector3)
- reflect
  - 参数: reflect (normal: Vector3)
    normal – 反射平面的法线
  - 功能：将这个向量反射到与法线正交的平面之外(假设法线有长度)。
  - 返回值： this (Vector3)
- round
  - 参数: round ()
  - 功能：向量中的分量四舍五入取整为最接近的整数值。
  - 返回值： this (Vector3)
- roundToZero
  - 参数: roundToZero ()
  - 功能：向量中的分量朝向0取整数(若分量为负数则向上取整，若为正数则向下取整)。
  - 返回值： this (Vector3)
- set
  - 参数: set (x: Number, y: Number, z: Number)
  - 功能：设置该向量的x、y 和 z 分量。
  - 返回值： this (Vector3)
- setComponent
  - 参数: setComponent (index: Integer, value: Number)
    index - (支持传入参数的值) 0、1 或 2。
    value - 设置对应位置的值。
  - 功能：
    若index为 0 则设置 x 值为 value。
    若index为 1 则设置 y 值为 value。
    若index为 2 则设置 z 值为 value。
  - 返回值： this (Vector3)
- setFromMatrixColumn
  - 参数: setFromMatrixColumn (matrix: Matrix4, index: Integer)
  - 功能：从传入的四阶矩阵matrix由index指定的列中，设置该向量的x值、y值和z值。
  - 返回值： this (Vector3)
- setFromMatrixPosition
  - 参数: setFromMatrixPosition (m: Matrix4)
  - 功能：从变换矩阵(transformation matrix)m中，设置该向量为其中与位置相关的元素。
  - 返回值： this (Vector3)
- setFromMatrixScale
  - 参数: setFromMatrixScale (m: Matrix4)
  - 功能：从变换矩阵(transformation matrix)m中，设置该向量为其中与缩放相关的元素。
  - 返回值： this (Vector3)
- setLength
  - 参数: setLength (l: Number)
  - 功能：将该向量的方向设置为和原向量相同，但是长度(length)为l。
  - 返回值： this (Vector3)
- setScalar
  - 参数: setScalar (scalar: Number)
  - 功能：将该向量的x、y和z值同时设置为等于传入的scalar。
  - 返回值： this (Vector3)
- setX
  - 参数: setX (x: Number)
  - 功能：将向量中的x值替换为x。
  - 返回值： this (Vector3)
- setY
  - 参数: setY (y: Number)
  - 功能：将向量中的y值替换为y。
  - 返回值： this (Vector3)
- setZ
  - 参数: setZ (z: Number)
  - 功能：将向量中的z值替换为z。
  - 返回值： this (Vector3)
- sub
  - 参数: sub (v: Vector3)
  - 功能：从该向量减去向量v。
  - 返回值： this (Vector3)
- subScalar
  - 参数: subScalar (s: Number)
  - 功能：从该向量的x、y和z中减去标量s。
  - 返回值： this (Vector3)
- subVectors
  - 参数: subVectors (a: Vector3, b: Vector3)
  - 功能：将该向量设置为a - b。
  - 返回值： this (Vector3)
- toArray
  - 参数: toArray (array: List, offset: Integer)
    array - (可选) 被用于存储向量的数组。如果这个值没有传入，则将创建一个新的数组。
    offset - (可选) 数组中元素的偏移量，默认值为0。
  - 功能：返回一个数组[x, y ,z]，或者将x、y和z复制到所传入的array中。
  - 返回值：返回存储向量的数组(List)
- transformDirection
  - 参数: transformDirection (m: Matrix4)
  - 功能：通过传入的矩阵(m的左上角3 x 3子矩阵)变换向量的方向，并将结果进行normalizes (归一化)。
  - 返回值： this (Vector3)
- random
  - 参数: random ()
  - 功能：将这个向量的每个分量设置为0到1之间的伪随机数(不包括1)
  - 返回值： this (Vector3)

# 四阶矩阵： Matrix4

展开: (四阶矩阵)

定义方式：

// 空参构造一个4 X 4的单位矩阵
var matrix = new Matrix4();

1
2

属性：

.elements 	// 使用一维数组模拟存储四阶矩阵 List<Number>类型

复制方式： 引用复制
方法API：
- clone
  - 参数: clone ()
  - 返回值：一个新的矩阵，元素elements与该矩阵相同 (Matrix4)
- copy
  - 参数: copy (m: Matrix4)
  - 功能：将矩阵m的元素elements复制到当前矩阵中。
  - 返回值： this (Matrix4)
- copyPosition
  - 参数: copyPosition (m: Matrix4)
  - 功能：将给定矩阵m: Matrix4 的平移分量拷贝到当前矩阵中。
  - 返回值： this (Matrix4)
- determinant
  - 参数: determinant ()
  - 返回值：该矩阵的行列式 (Number)
- equals
  - 参数: equals (m: Matrix4)
  - 返回值：当前矩阵与矩阵m的对应元素是否一一相等 (Boolean)
- extractBasis
  - 参数: extractBasis (xAxis: Vector3, yAxis: Vector3, zAxis: Vector3)
  - 功能：
    将矩阵的基向量basis提取到指定的3个轴向量中。如下：
```
如果矩阵如下: [a, b, c, d,
              e, f, g, h,
              i, j, k, l,
              m, n, o, p]
然后x轴y轴z轴被设为：
xAxis = (a, e, i)
yAxis = (b, f, j)
zAxis = (c, g, k) 
```
    1
    2
    3
    4
    5
    6
    7
    8
  - 返回值： this (Matrix4)
- extractRotation
  - 参数: extractRotation (m: Matrix4)
  - 功能：将给定矩阵m的旋转分量提取到该矩阵的旋转分量中。
  - 返回值： this (Matrix4)
- fromArray
  - 参数: fromArray (array: List, offset: Integer)
    array - 用来存储设置元素数据的数组。
    offset - (可选参数) 数组的偏移量，默认值为 0。
  - 功能：使用基于列优先格式(column-major)的数组来设置该矩阵。
  - 返回值： this (Matrix4)
- getInverse
  - 参数: getInverse (m: Matrix4)
  - 功能： m - 取逆的矩阵。
  - 返回值： this (Matrix4)
- getMaxScaleOnAxis
  - 参数: getMaxScaleOnAxis ()
  - 返回值： 3个轴方向的最大缩放值。(Number)
- identity
  - 参数: identity ()
  - 功能：将当前矩阵重置为单位矩阵。
  - 返回值： this (Matrix4)
- lookAt
  - 参数: lookAt (eye: Vector3, center: Vector3, up: Vector3)
  - 功能：构造一个旋转矩阵，从eye 指向 center，由向量up定向。
  - 返回值： this (Matrix4)
- makeRotationAxis
  - 参数: makeRotationAxis (axis: Vector3, theta: Number)
    axis - 旋转轴，需要被归一化。
    theta - 旋转量(弧度)。
  - 功能：设置当前矩阵为围绕轴 axis 旋转量为 theta弧度。
  - 返回值： this (Matrix4)
- makeBasis
  - 参数: makeBasis (xAxis: Vector3, yAxis: Vector3, zAxis: Vector3)
  - 功能:
```
通过给定的三个向量设置该矩阵为基矩阵basis: [xAxis.x, yAxis.x, zAxis.x, 0,
                                         xAxis.y, yAxis.y, zAxis.y, 0,
                                         xAxis.z, yAxis.z, zAxis.z, 0,
                                         0,    0,     0,     1]
```
    1
    2
    3
    4
  - 返回值： this (Matrix4)
- makeRotationX
  - 参数: makeRotationX (theta: Number)
    theta - 旋转角度
  - 功能：把该矩阵设置为绕Y轴旋转弧度theta (θ)大小的矩阵。
  - 返回值： this (Matrix4)
- makeRotationY
  - 参数: makeRotationY (theta: Number)
    theta - 旋转角度。
  - 功能：把该矩阵设置为绕Y轴旋转弧度theta (θ)大小的矩阵。
  - 返回值： this (Matrix4)
- makeRotationZ
  - 参数: makeRotationZ (theta: Number)
    theta - 旋转角度。
  - 功能：把该矩阵设置为绕Z轴旋转弧度theta (θ)大小的矩阵。
  - 返回值： this (Matrix4)
- makeScale
  - 参数: makeScale (x: Number, y: Number, z: Number)
    x - 在X轴方向的缩放比。
    y - 在Y轴方向的缩放比。
    z - 在Z轴方向的缩放比。
  - 功能：
```
将这个矩阵设置为缩放变换: [x, 0, 0, 0,
                         0, y, 0, 0,
                         0, 0, z, 0,
                         0, 0, 0, 1]
```
    1
    2
    3
    4
  - 返回值： this (Matrix4)
- makeShear
  - 参数: makeShear (x: Number, y: Number, z: Number)
    x - 在X轴上剪切的量。
    y - 在Y轴上剪切的量。
    z - 在Z轴上剪切的量。
  - 功能：
```
将这个矩阵设置为缩放变换: [1, y, z, 0,
                         x, 1, z, 0,
                         x, y, z, 0,
                         0, 0, 0, 1]
```
    1
    2
    3
    4
  - 返回值： this (Matrix4)
- makeTranslation
  - 参数: makeTranslation (x: Number, y: Number, z: Number)
    x - 在X轴上的平移量。
    y - 在Y轴上的平移量。
    z - 在Z轴上的平移量。
  - 功能：
```
将这个矩阵设置为缩放变换: [1, 0, 0, x,
                         0, 1, 0, y,
                         0, 0, 1, z,
                         0, 0, 0, 1]
```
    1
    2
    3
    4
  - 返回值： this (Matrix4)
- multiply
  - 参数: multiply (m: Matrix4)
  - 功能：将当前矩阵乘以矩阵m。
  - 返回值： this (Matrix4)
- multiplyMatrices
  - 参数: multiplyMatrices (a: Matrix4, b: Matrix4)
  - 功能：设置当前矩阵为矩阵a x 矩阵b。
  - 返回值： this (Matrix4)
- multiplyScalar
  - 参数: multiplyScalar (s: Number)
  - 功能：当前矩阵所有的元素乘以该缩放值s。
  - 返回值： this (Matrix4)
- premultiply
  - 参数: premultiply (m: Matrix4)
  - 功能：将矩阵m乘以当前矩阵。
  - 返回值： this (Matrix4)
- scale
  - 参数: scale (v: Vector3)
  - 功能：将该矩阵的列向量乘以对应向量v的分量。
  - 返回值： this (Matrix4)
- set
  - 参数: set (n11: Number, n12: Number, n13: Number, n14: Number, n21: Number, n22: Number, n23: Number, n24: Number, n31: Number, n32: Number, n33: Number, n34: Number, n41: Number, n42: Number, n43: Number, n44: Number)
  - 功能：
    以行优先的格式将传入的数值设置给该矩阵中的元素elements。
```
var m = new Matrix4(); 
m.set(11, 12, 13, 14, 
      21, 22, 23, 24, 
      31, 32, 33, 34, 
      41, 42, 43, 44);
// 对应的实际的elements的存储为：
m.elements = [11, 21, 31, 41,
              12, 22, 32, 42,
              13, 23, 33, 43,
              14, 24, 34, 44 ];
```
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
  - 返回值： this (Matrix4)
- setPosition
  - 参数: setPosition (v: Vector3)
  - 功能：取传入参数v中值设置该矩阵的位置分量。
  - 返回值： this (Matrix4)
- setPosition
  - 参数: setPosition (x: Number, y: Number, z: Number)
  - 功能：将传入参数x, y, z设置为该矩阵的位置分量。
  - 返回值： this (Matrix4)
- toArray
  - 参数: toArray (array: List, offset: Integer)
    array - (可选参数) 存储矩阵元素的数组，如果未指定会创建一个新的数组。
    offset - (可选参数) 存放矩阵元素数组的偏移量，默认值为0。
  - 功能：使用列优先格式将此矩阵的元素写入数组中。
  - 返回值：存储矩阵元素的数组(List)
- transpose
  - 参数: transpose ()
  - 功能：将该矩阵转置Transposes。
  - 返回值： this (Matrix4)