Matrix3x3

概览

字段	值
Kind	Data · 数据 Data
Realm	common

Matrix3x3 表示一个三行三列的纯数值矩阵，用来承载三维空间中的线性变换数据，例如旋转与缩放关系。它支持求转置、求逆、求行列式与迹、按行或按列提取向量、把矩阵作用于三维向量，也能产出单位矩阵、零矩阵以及叉乘对应的反对称矩阵。矩阵既可以按九个分量一次性构造，也可以由克隆或各类代数运算的结果得到。

适用场景

当需要自己保存和运算线性变换数据时使用，例如把一组方向向量按同一个矩阵统一映射、对坐标系换算结果做转置或求逆，或在几何计算中对矩阵做行列式与迹的判定。

使用要点

先调用 Matrix3x3.New(m00, m01, m02, m10, m11, m12, m20, m21, m22) 或等价的简写 Matrix3x3(...) 按行传入九个分量得到矩阵实例，随后用 Apply 把 Vector3 变换成新的 Vector3，或用 GetRow、GetColumn 取出单行单列向量继续计算。需要保留中间结果时可以先用 Clone 复制一份，再用 GetTranspose、GetInverse、GetAbsoluteMatrix 取得新的矩阵，并用 GetDeterminant、GetTrace 获取数值指标。如果希望直接改写当前实例，则改用 SetAllValues、SetToZero 或 SetToIdentity 做原地赋值。

注意事项

Matrix3x3 是纯数据矩阵。Clone、GetTranspose、GetInverse、GetAbsoluteMatrix、Identity、Zero 和 ComputeSkewSymmetricMatrixForCrossProduct 返回新矩阵；SetAllValues、SetToZero 与 SetToIdentity 会原地修改当前实例。求逆前应确保矩阵可逆。

代码示例

构造可逆矩阵并读取行列式

-- @runtime client
local matrix = Matrix3x3.New(
    1, 0, 0,
    0, 2, 0,
    0, 0, 3
)
print('行列式:', matrix:GetDeterminant())
local inverse = matrix:GetInverse()
print('逆矩阵第一行:', inverse:GetRow(0))

函数 (16)

New

签名：New(m00: Float, m01: Float, m02: Float, m10: Float, m11: Float, m12: Float, m20: Float, m21: Float, m22: Float) -> Matrix3x3

创建一个新的 3x3 矩阵，按行主序传入 9 个浮点数参数。

参数	类型	说明
m00	Float	-
m01	Float	-
m02	Float	-
m10	Float	-
m11	Float	-
m12	Float	-
m20	Float	-
m21	Float	-
m22	Float	-

返回值 Matrix3x3

示例代码

构造 3x3 矩阵

-- @runtime client
-- 按 9 个分量构造（行优先）
local m = Matrix3x3.New(1, 0, 0, 0, 1, 0, 0, 0, 1)
print('构造的矩阵:', tostring(m))

Clone

签名：Clone() -> Matrix3x3

创建当前矩阵的一个完全独立的副本。

返回值 Matrix3x3

示例代码

克隆矩阵并验证独立性

-- @runtime client
-- 构造一个 3x3 矩阵
local mat = Matrix3x3(1, 2, 3, 4, 5, 6, 7, 8, 9)
-- 克隆矩阵
local cloned = mat:Clone()
-- 修改原矩阵，验证克隆体不受影响
mat:SetAllValues(0, 0, 0, 0, 0, 0, 0, 0, 0)
-- 打印克隆矩阵的第一行，应为原始值
local row0 = cloned:GetRow(0)
print("克隆矩阵第一行:", row0.x, row0.y, row0.z)

SetAllValues

签名：SetAllValues(m00: Float, m01: Float, m02: Float, m10: Float, m11: Float, m12: Float, m20: Float, m21: Float, m22: Float) -> void

一次性设置 3x3 矩阵的全部 9 个元素值。

参数	类型	说明
m00	Float	-
m01	Float	-
m02	Float	-
m10	Float	-
m11	Float	-
m12	Float	-
m20	Float	-
m21	Float	-
m22	Float	-

返回值 void

示例代码

批量设置矩阵分量

-- @runtime client
local m = Matrix3x3.Identity()
m:SetAllValues(1, 0, 0, 0, 1, 0, 0, 0, 1)
print('已设置为单位矩阵')

SetToZero

签名：SetToZero() -> void

将当前矩阵的所有元素设置为 0。

返回值 void

示例代码

重置为零矩阵

-- @runtime client
local m = Matrix3x3.Identity()
m:SetToZero()
print('已重置为零矩阵')

GetTranspose

签名：GetTranspose() -> Matrix3x3

返回当前矩阵的转置矩阵。

返回值 Matrix3x3

示例代码

转置矩阵并检查行列互换

-- @runtime client
local matrix = Matrix3x3.New(
    1, 2, 3,
    4, 5, 6,
    7, 8, 9
)
local transposed = matrix:GetTranspose()
local originalRow0 = matrix:GetRow(0)
local transposedColumn0 = transposed:GetColumn(0)
print('原矩阵第 0 行:', originalRow0)
print('转置矩阵第 0 列:', transposedColumn0)

GetDeterminant

签名：GetDeterminant() -> Float

计算并返回矩阵的行列式值。

返回值 Float

示例代码

计算矩阵行列式

-- @runtime client
-- 构造一个可逆矩阵
local mat = Matrix3x3(1, 0, 0, 0, 2, 0, 0, 0, 3)
-- 计算行列式
local det = mat:GetDeterminant()
print("行列式:", det)

GetTrace

签名：GetTrace() -> Float

计算并返回矩阵的迹，即主对角线元素之和。

返回值 Float

示例代码

计算矩阵的迹

-- @runtime client
-- 构造一个矩阵
local mat = Matrix3x3(1, 2, 3, 4, 5, 6, 7, 8, 9)
-- 计算迹（对角线元素之和）
local trace = mat:GetTrace()
print("迹:", trace)

GetInverse

签名：GetInverse() -> Matrix3x3

计算并返回当前矩阵的逆矩阵。

返回值 Matrix3x3

示例代码

求逆矩阵并验证

-- @runtime client
-- 构造一个可逆矩阵
local mat = Matrix3x3(1, 0, 0, 0, 2, 0, 0, 0, 3)
-- 求逆矩阵
local inv = mat:GetInverse()
-- 用逆矩阵乘以原矩阵的列向量，应得到单位向量
local col0 = mat:GetColumn(0)
local result = inv:Apply(col0)
print("逆矩阵作用后:", result.x, result.y, result.z)

GetAbsoluteMatrix

签名：GetAbsoluteMatrix() -> Matrix3x3

返回一个新矩阵，其每个元素是原矩阵对应元素的绝对值。

返回值 Matrix3x3

示例代码

获取逐元素绝对值矩阵

-- @runtime client
-- 构造一个包含负数的矩阵
local mat = Matrix3x3(-1, 2, -3, 4, -5, 6, -7, 8, -9)
-- 获取绝对值矩阵
local absMat = mat:GetAbsoluteMatrix()
-- 打印绝对值矩阵的第一行
local row0 = absMat:GetRow(0)
print("绝对值矩阵第一行:", row0.x, row0.y, row0.z)

SetToIdentity

签名：SetToIdentity() -> void

将当前矩阵设置为单位矩阵，对角线元素变为 1，其余变为 0。

返回值 void

示例代码

重置为单位矩阵

-- @runtime client
local m = Matrix3x3.New(2, 0, 0, 0, 2, 0, 0, 0, 2)
m:SetToIdentity()
print('已重置为单位矩阵')

Identity

签名：Identity() -> Matrix3x3

返回一个 3x3 单位矩阵（对角线元素为 1，其余为 0）。

返回值 Matrix3x3

示例代码

获取 3x3 单位矩阵

-- @runtime client
local m = Matrix3x3.Identity()
print('3x3 单位矩阵:', tostring(m))

Zero

签名：Zero() -> Matrix3x3

返回一个所有元素均为 0 的 3x3 零矩阵。

返回值 Matrix3x3

示例代码

获取零矩阵

-- @runtime client
-- 获取零矩阵
local zero = Matrix3x3.Zero()
-- 验证零矩阵乘以向量得到零向量
local vec = Vector3(1, 2, 3)
local result = zero:Apply(vec)
print("零矩阵作用后:", result.x, result.y, result.z)

GetColumn

签名：GetColumn(col: Int) -> Vector3

GetColumn 是 Matrix3x3 的实例方法，按列索引取出一列，并以 Vector3 的形式返回该列的三个分量。

参数	类型	说明
col	Int	-

返回值 Vector3

示例代码

按索引读取矩阵的列向量

-- @runtime client
-- 依次传入 9 个元素构造一个测试矩阵
local m = Matrix3x3.New(1, 2, 3, 4, 5, 6, 7, 8, 9)
-- 索引从 0 开始，取第一列
local col0 = m:GetColumn(0)
print("第 0 列:", col0.x, col0.y, col0.z)
-- 取最后一列，确认不同索引返回不同的列
local col2 = m:GetColumn(2)
print("第 2 列:", col2.x, col2.y, col2.z)
print("矩阵行列式:", m:GetDeterminant())

GetRow

签名：GetRow(row: Int) -> Vector3

GetRow 是 Matrix3x3 的实例方法，按行索引取出一行，并以 Vector3 的形式返回该行的三个分量。

参数	类型	说明
row	Int	-

返回值 Vector3

示例代码

按索引读取矩阵的行向量

-- @runtime client
-- 构造测试矩阵，元素按 m00 到 m22 的顺序传入
local m = Matrix3x3.New(1, 2, 3, 4, 5, 6, 7, 8, 9)
-- 索引从 0 开始，取第一行
local row0 = m:GetRow(0)
print("第 0 行:", row0.x, row0.y, row0.z)
-- 取最后一行做对比
local lastRow = m:GetRow(2)
print("第 2 行:", lastRow.x, lastRow.y, lastRow.z)
-- 取出的行向量可直接做向量运算
local dot = row0:Dot(m:GetRow(1))
print("第 0 行与第 1 行的点积:", dot)

ComputeSkewSymmetricMatrixForCrossProduct

签名：ComputeSkewSymmetricMatrixForCrossProduct(v: Vector3) -> Matrix3x3

ComputeSkewSymmetricMatrixForCrossProduct 接收一个 Vector3 参数 v，返回与该向量叉积运算相对应的反对称矩阵 Matrix3x3。

参数	类型	说明
v	Vector3	-

返回值 Matrix3x3

示例代码

构造叉积反对称矩阵

-- @runtime client
local v = Vector3.New(1, 2, 3)
local w = Vector3.New(4, 5, 6)
local skewMatrix = Matrix3x3.ComputeSkewSymmetricMatrixForCrossProduct(v)
local fromMatrix = skewMatrix:Apply(w)
local fromCross = v:Cross(w)
print('矩阵结果:', fromMatrix, '叉积结果:', fromCross)

Apply

签名：Apply(v: Vector3) -> Vector3

Apply 是 Matrix3x3 的实例方法，用于把当前 3x3 矩阵作用到一个 Vector3 向量上，并返回变换后的 Vector3 结果。

参数	类型	说明
v	Vector3	-

返回值 Vector3

示例代码

用矩阵变换向量

-- @runtime client
-- 构造单位矩阵，作为不改变向量方向的基准
local identity = Matrix3x3.New(1, 0, 0, 0, 1, 0, 0, 0, 1)
local v = Vector3.New(1, 2, 3)
-- 让矩阵作用于向量，返回新的 Vector3
local result = identity:Apply(v)
print("单位矩阵作用结果:", result.x, result.y, result.z)
-- 换成缩放矩阵，观察同一向量被放大后的结果
local scale = Matrix3x3.New(2, 0, 0, 0, 2, 0, 0, 0, 2)
local scaled = scale:Apply(v)
print("缩放矩阵作用结果:", scaled.x, scaled.y, scaled.z)