OpencvSharp 算子学习教案之 - Cv2.RQDecomp3x3 重载3
重载3：RQDecomp3x3(double[,] src, out double[,] mtxR, out double[,] mtxQ, out double[,] qx, out double[,] qy, out double[,] qz)

大家好，Opencv在很多工程项目中都会用到，而OpencvSharp则是以C#开发与实现的Opencv操作库，对.NET开发人员友好，但很多API的中文资料、应用场景及常见坑点等缺乏系统性归纳，因此这系列博客将给大家带来Cv2及Mat对象全系列算子学习教案，供大家参考学习。

Cv2.RQDecomp3x3

• 教案版本：V1.0
• 面向对象：OpenCvSharp 初学者
• 所属模块：calib3d
• 源码位置：OpenCvSharp/Cv2/Cv2_calib3d.cs:267

1. 函数名称（带参数签名）

public static Vec3d RQDecomp3x3(
    double[,] src,
    out double[,] mtxR,
    out double[,] mtxQ,
    out double[,] qx,
    out double[,] qy,
    out double[,] qz)

2. 函数用途

这是 double[,] 系列中最完整的重载：

1. 输出 mtxR、mtxQ。
2. 额外输出分轴旋转矩阵 qx/qy/qz。
3. 返回欧拉角 Vec3d。

适用场景：

1. 需要分析分轴旋转矩阵性质。
2. 需要对比不同重载输出的一致性。
3. 需要纯托管数组流程且输出信息最完整。

3. 函数公式

3.1 基础分解关系

$$A=RQ$$

其中：

$$R\text{ 上三角},Q\text{ 正交},Q{Q}^T=I$$

3.2 分轴矩阵性质

对于 qx/qy/qz，通常可做如下合法性检查：

$$\Vert q_x{q}_x^T-I{\Vert }_F,\Vert q_y{q}_y^T-I{\Vert }_F,\Vert q_z{q}_z^T-I{\Vert }_F$$

以及：

$$\det (q_x),\det (q_y),\det (q_z)\approx +1$$

4. 函数原理说明

该重载在基础重载能力上增加了轴向输出：

1. 输入 double[3,3]。
2. native 分解得到 R/Q。
3. 同时计算并输出 qx/qy/qz。
4. 返回欧拉角向量。

在教学与调试中，这个重载很适合解释“总旋转矩阵与分轴矩阵”的关系。

5. 参数含义解析

参数名	类型	必填	含义	备注
src	double[,]	是	输入 3x3 矩阵	必须为 3x3
mtxR	out double[,]	是	输出上三角矩阵	3x3
mtxQ	out double[,]	是	输出正交矩阵	3x3
qx	out double[,]	是	X 轴旋转矩阵	3x3
qy	out double[,]	是	Y 轴旋转矩阵	3x3
qz	out double[,]	是	Z 轴旋转矩阵	3x3

返回值 Vec3d：欧拉角（度）。

6. 应用场景列表

场景名	典型用途	输出重点
场景A：全量输出分解	一次获取全部结果	R/Q/qx/qy/qz
场景B：轴向矩阵质量检查	验证 qx/qy/qz 合法性	正交误差与行列式
场景C：与基础重载对比	确认核心输出一致性	R/Q/角度差异
场景D：扰动敏感性分析	比较噪声前后轴向变化	角度与轴矩阵差异
场景E：教学拆解演示	分步解释旋转结构	分轴矩阵可读性
场景F：调参定位问题	快速定位异常轴向输出	qx/qy/qz 指标
场景G：自动回归测试	覆盖完整输出字段	全量一致性检查

7. 函数使用示例（代表性场景完整示例）

7.1 场景A：全量输出分解

using OpenCvSharp;

double[,] src =
{
    { 880.0, 12.0, 320.0 },
    { 0.0, 920.0, 240.0 },
    { 0.0, 0.0, 1.0 },
};

var angles = Cv2.RQDecomp3x3(src, out var mtxR, out var mtxQ, out var qx, out var qy, out var qz);

7.2 场景B：轴向矩阵质量检查

using OpenCvSharp;

double detQx =
    qx[0,0] * (qx[1,1] * qx[2,2] - qx[1,2] * qx[2,1])
  - qx[0,1] * (qx[1,0] * qx[2,2] - qx[1,2] * qx[2,0])
  + qx[0,2] * (qx[1,0] * qx[2,1] - qx[1,1] * qx[2,0]);

7.3 场景C：与基础重载对比

using OpenCvSharp;

var anglesBasic = Cv2.RQDecomp3x3(src, out var rBasic, out var qBasic);
var anglesFull = Cv2.RQDecomp3x3(src, out var rFull, out var qFull, out _, out _, out _);

// 对比 rBasic/rFull、qBasic/qFull、anglesBasic/anglesFull 差异。

7.4 场景D：扰动敏感性分析

using OpenCvSharp;

var noisy = (double[,])src.Clone();
noisy[0, 2] += 0.2;
noisy[2, 1] -= 0.1;

var noisyAngles = Cv2.RQDecomp3x3(noisy, out _, out _, out var qxNoisy, out var qyNoisy, out var qzNoisy);

8. 函数使用注意事项

1. 输入必须是 double[3,3]。
2. 该重载输出较多，建议按“核心输出 + 质量指标”分层分析。
3. 轴向矩阵有浮点误差，判定合法性时应使用容差阈值。
4. 若只需要 R/Q，可优先使用基础重载简化代码。

9. 参数调优建议

1. 优先检查 mtxR 的上三角性与 mtxQ 的正交性。
2. 对 qx/qy/qz 增加正交误差阈值检查。
3. 对高噪声输入建议做敏感性分析，评估输出稳定性。
4. 对比基础重载与全量重载输出，验证实现一致性。

10. 示例代码运行说明（按场景关键逻辑）

场景A（全量输出分解）

1. 准备输入矩阵。
2. 调用全量重载拿到全部输出。
3. 输出核心结果用于可视化或日志。

场景B（轴向矩阵质量检查）

1. 计算 qx/qy/qz 正交误差。
2. 计算 qx/qy/qz 行列式。
3. 判断是否接近旋转矩阵要求。

场景C（与基础重载对比）

1. 同一输入分别调用两个重载。
2. 对比 R/Q/angles 差异。
3. 确认核心结果一致。

场景D（扰动敏感性分析）

1. 添加小幅扰动输入。
2. 执行全量分解并记录变化。
3. 对比欧拉角与轴向矩阵波动。

11. 常见错误排查

1. 错误：输入维度不对
   • 排查：确认是 double[3,3]。
2. 错误：轴向矩阵看起来“不正交”
   • 排查：是否用严格等于判断；应使用容差误差。
3. 错误：与基础重载结果不一致
   • 排查：确认输入完全相同，且比较时使用浮点容差。
4. 错误：扰动后变化过大
   • 排查：输入是否接近奇异矩阵，或扰动幅度设置过大。

---

对应 WPF 演示控件与样例代码：

• Features/Cv2RQDecomp3x3DoubleArrayFull/Cv2RQDecomp3x3DoubleArrayFullControl.xaml
• Samples/Cv2RQDecomp3x3/RQDecomp3x3DoubleFullDecomposeSample.cs
• Samples/Cv2RQDecomp3x3/RQDecomp3x3DoubleFullAxisQualitySample.cs
• Samples/Cv2RQDecomp3x3/RQDecomp3x3DoubleFullCompareBasicSample.cs
• Samples/Cv2RQDecomp3x3/RQDecomp3x3DoubleFullPerturbationSample.cs