详细解释aruco::markdetection _detectInitialCandidates函数

_detectInitialCandidates 是 OpenCV 的 ArUco 模块中一个非常关键的函数，它负责检测图像中的候选 ArUco 标记。该函数的主要目标是：

• 使用多个尺度（scale）对输入图像进行自适应阈值处理；
• 在每个尺度下提取轮廓并筛选出符合要求的四边形角点；
• 将这些候选标记及其对应的轮廓保存到输出参数中。

---

📌 函数签名

static void _detectInitialCandidates(const Mat &grey,vector<vector<Point2f> > &candidates,vector<vector<Point> > &contours,const DetectorParameters &params)

参数说明：

参数名	类型	含义
grey	const Mat &	输入的灰度图像
candidates	vector<vector<Point2f> > &	输出的候选标记角点（4个点组成的矩形）
contours	vector<vector<Point> > &	输出的与候选角点对应的完整轮廓信息
params	const DetectorParameters &	检测器参数，控制检测过程的行为

🔍 功能详解

1️⃣ 设置自适应阈值窗口大小范围

CV_Assert(params.adaptiveThreshWinSizeMin >= 3 && params.adaptiveThreshWinSizeMax >= 3);
CV_Assert(params.adaptiveThreshWinSizeMax >= params.adaptiveThreshWinSizeMin);
CV_Assert(params.adaptiveThreshWinSizeStep > 0);

确保传入的参数合法：

• 自适应阈值窗口最小和最大尺寸 ≥ 3（OpenCV 要求）
• 步长必须大于 0

2️⃣ 计算要使用的窗口大小数量（即图像金字塔层数）

int nScales = (params.adaptiveThreshWinSizeMax - params.adaptiveThreshWinSizeMin) /params.adaptiveThreshWinSizeStep + 1;

根据设定的最小、最大窗口大小和步长，计算需要尝试多少种不同的窗口大小。

例如：min=20, max=40, step=5 → nScales = 5

---

3️⃣ 为每种窗口大小准备容器

vector<vector<vector<Point2f> > > candidatesArrays((size_t) nScales);
vector<vector<vector<Point> > > contoursArrays((size_t) nScales);

• candidatesArrays[i]：第 i 个窗口大小下的所有候选标记角点集合。
• contoursArrays[i]：对应的所有轮廓。

---

4️⃣ 多线程处理不同尺度（parallel_for_）

parallel_for_(Range(0, nScales), [&](const Range& range) {for (int i = begin; i < end; i++) {int currScale = params.adaptiveThreshWinSizeMin + i * params.adaptiveThreshWinSizeStep;Mat thresh;_threshold(grey, thresh, currScale, params.adaptiveThreshConstant);_findMarkerContours(thresh, candidatesArrays[i], contoursArrays[i],params.minMarkerPerimeterRate, params.maxMarkerPerimeterRate,params.polygonalApproxAccuracyRate, params.minCornerDistanceRate,params.minSideLengthCanonicalImg);}
});

对于每一个窗口大小：

1. 调用 _threshold() 进行自适应阈值处理：
   • 用于将图像二值化，便于后续提取轮廓。
2. 调用 _findMarkerContours() 提取轮廓并筛选出可能的 ArUco 标记角点：
   • 筛选条件包括：周长范围、是否为凸四边形、角点距离等。

---

5️⃣ 合并所有尺度的结果

for(int i = 0; i < nScales; i++) {for(unsigned int j = 0; j < candidatesArrays[i].size(); j++) {candidates.push_back(candidatesArrays[i][j]);contours.push_back(contoursArrays[i][j]);}
}

将不同尺度下检测到的候选标记统一合并到最终输出变量 candidates 和 contours 中。

---

🧠 关键辅助函数说明

✅ _threshold()

static void _threshold(InputArray _in, OutputArray _out, int winSize, double constant)

• 使用 adaptiveThreshold() 对图像进行自适应二值化。
• 确保窗口大小为奇数。
• 采用 ADAPTIVE_THRESH_MEAN_C 方法，反向二值化 (THRESH_BINARY_INV)。

---

✅ _findMarkerContours()

static void _findMarkerContours(const Mat &in,vector<vector<Point2f> > &candidates,vector<vector<Point> > &contoursOut,double minPerimeterRate,double maxPerimeterRate,double accuracyRate,double minCornerDistanceRate,int minSize)

这个函数负责从二值图像中提取轮廓，并筛选出可能是 ArUco 标记的四边形。

主要步骤：

1. 查找所有轮廓

   findContours(in, contours, RETR_LIST, CHAIN_APPROX_NONE);

2. 逐个轮廓筛选

   • 周长在指定范围内；
   • 多边形逼近后为凸四边形；
   • 四个角点之间最小距离满足要求；
   • 如果启用 ArUco3 功能，则额外判断最小边长。

3. 将符合条件的轮廓加入输出

   • 角点存入 candidates
   • 完整轮廓存入 contoursOut

---

📈 总结流程图

_detectInitialCandidates()
│
├─ 设置参数检查
│
├─ 计算使用多少种窗口大小（nScales）
│
├─ 并行遍历每个窗口大小：
│   ├─ 图像二值化（_threshold）
│   └─ 提取并筛选候选标记（_findMarkerContours）
│       ├─ 查找轮廓
│       ├─ 筛选轮廓（凸四边形、周长、角点距离等）
│       └─ 添加进临时容器
│
└─ 合并所有窗口大小下的结果到输出

---

🧰 参数影响分析（DetectorParameters）

参数名	作用
adaptiveThreshWinSizeMin	最小阈值窗口大小，决定最小可检测标记大小
adaptiveThreshWinSizeMax	最大阈值窗口大小，决定最大可检测标记大小
adaptiveThreshWinSizeStep	窗口大小递增步长
minMarkerPerimeterRate	最小周长比例（相对于图像宽度/高度）
maxMarkerPerimeterRate	最大周长比例
polygonalApproxAccuracyRate	多边形逼近精度比例
minCornerDistanceRate	角点间最小距离比例
minSideLengthCanonicalImg	ArUco3 功能中最小边长限制

---

📝 示例说明

假设你有如下代码调用：

Mat grey = ...; // 输入灰度图
vector<vector<Point2f>> candidates;
vector<vector<Point>> contours;
DetectorParameters params = DetectorParameters::create();
_detectInitialCandidates(grey, candidates, contours, params);

这段代码会：

• 使用多个窗口大小对图像进行自适应阈值；
• 提取轮廓并筛选出潜在的 ArUco 标记；
• 返回所有候选标记的四个角点坐标及其原始轮廓。

---

✅ 总结

特性	描述
功能	检测图像中所有可能的 ArUco 标记候选区域
输入	灰度图像、检测参数
输出	候选角点列表、对应轮廓列表
关键技术	自适应阈值、轮廓检测、多边形逼近、几何筛选
性能优化	使用 parallel_for_ 实现多线程加速
后续处理	通常交给 _reorderCandidatesCorners() 排序角点顺序