【opencv】示例-aruco_dict_utils.cpp 计算 ArUco 字典度量

该程序可用于计算 ArUco 字典度量。

要计算考虑翻转标记的指标，请使用 -'r' 标志。

该程序可用于创建和编写自定义 ArUco 词典。

#include <opencv2/objdetect/aruco_detector.hpp> // 包含aruco marker检测相关功能的头文件
#include <iostream> // 包含输入输出流相关功能的头文件


using namespace cv; // 使用命名空间cv，这样我们就可以直接使用OpenCV的函数和类而不需要加cv::前缀
using namespace std; // 使用命名空间std，标准的C++库函数比如std::cout可以直接写成cout


// 下面是静态函数的定义，因为我们不需要实例化对象就可以直接用类名调用它们
//为了确保ArUco标记的独一无二，这个函数计算了一个标记的自身最小汉明距离（即标记的不同旋转形态之间的最小差异度量），这有助于保证即使在不同的旋转下，标记也能被准确地检测和识别。
static int _getSelfDistance(const Mat &marker) {
    // 计算单个marker自身的汉明距离（marker之间的差异程度）


    Mat bytes = aruco::Dictionary::getByteListFromBits(marker); // 将marker的位图转换为字节列表


    double minHamming = (double)marker.total() + 1; // 初始化最小汉明距离为marker的总数+1
    for(int r = 1; r < 4; r++) { // 对每个旋转的标记进行遍历（共有四种旋转，不包括未旋转）
        // 创建两个临时的字节行，用于存储转换后的字节信息
        cv::Mat tmp1(1, bytes.cols, CV_8UC1, Scalar::all(0));
        cv::Mat tmp2(1, bytes.cols, CV_8UC1, Scalar::all(0));
        uchar* rot0 = tmp1.ptr(); // 获取行tmp1的指针
        uchar* rot1 = tmp2.ptr(); // 获取行tmp2的指针


        for (int i = 0; i < bytes.cols; ++i) { // 将marker的字节旋转r*90度并拷贝到临时字节行中
            rot0[i] = bytes.ptr()[i];
            rot1[i] = bytes.ptr()[bytes.cols*r + i];
        }


        // 计算两个临时行的汉明距离
        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING);
        // 更新最小汉明距离
        if (currentHamming < minHamming) minHamming = currentHamming;
    }
    
    // 对marker进行水平翻转和垂直翻转后的处理逻辑与上面类似，不再重复。
    // 在marker的所有可能的变换后，返回最小的汉明距离
    // 检查水平翻转后的情况
    Mat b; // 定义一个矩阵用于存储翻转的结果
    flip(marker, b, 0); // 对marker进行水平翻转
    Mat flipBytes = aruco::Dictionary::getByteListFromBits(b); // 获取翻转后marker的字节列表
    // 对翻转后的marker进行相似度检查，逻辑与上面类似
    for(int r = 0; r < 4; r++) {
        // ... 代码逻辑与上面类似 ...
        cv::Mat tmp1(1, flipBytes.cols, CV_8UC1, Scalar::all(0));
        cv::Mat tmp2(1, bytes.cols, CV_8UC1, Scalar::all(0));
        uchar* rot0 = tmp1.ptr();
        uchar* rot1 = tmp2.ptr();


        for (int i = 0; i < bytes.cols; ++i) {
            rot0[i] = flipBytes.ptr()[i];
            rot1[i] = bytes.ptr()[bytes.cols*r + i];
        }


        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING);
        if(currentHamming < minHamming) minHamming = currentHamming;
    }
    // 检查垂直翻转后的情况
    flip(marker, b, 1); // 对marker进行垂直翻转
    flipBytes = aruco::Dictionary::getByteListFromBits(b); // 获取翻转后marker的字节列表
    // 对垂直翻转后的marker进行相似度检查，逻辑与上面类似
    for(int r = 0; r < 4; r++) {
        // ... 代码逻辑与上面类似 ...
        cv::Mat tmp1(1, flipBytes.cols, CV_8UC1, Scalar::all(0));
        cv::Mat tmp2(1, bytes.cols, CV_8UC1, Scalar::all(0));
        uchar* rot0 = tmp1.ptr();
        uchar* rot1 = tmp2.ptr();


        for (int i = 0; i < bytes.cols; ++i) {
            rot0[i] = flipBytes.ptr()[i];
            rot1[i] = bytes.ptr()[bytes.cols*r + i];
        }


        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING);
        if(currentHamming < minHamming) minHamming = currentHamming;
    }
    // 返回最小汉明距离的四舍五入结果
    return cvRound(minHamming);
}
//计算给定字典中，某个ArUco标记与特定ID的其他标记之间在全部或部分旋转的情况下的最小汉明距离。这个函数可以用于评估字典中标记的独一无二性，以及是否可以准确识别翻转后的标记。
static inline int getFlipDistanceToId(const aruco::Dictionary& dict, InputArray bits, int id, bool allRotations = true) {
    // 根据给定的ID计算字典中一个标记与其余标记的汉明距离，包括考虑标记的翻转


    Mat bytesList = dict.bytesList; // 获取字典中所有标记的字节列表
    CV_Assert(id >= 0 && id < bytesList.rows); // 检查输入的ID是否有效


    unsigned int nRotations = 4; // 默认情况下，考虑所有4个旋转
    if(!allRotations) nRotations = 1; // 如果不考虑旋转，只需要计算未旋转的情况


    Mat candidateBytes = aruco::Dictionary::getByteListFromBits(bits.getMat()); // 获取候选标记的字节列表
    double currentMinDistance = int(bits.total() * bits.total()); // 初始化当前的最小汉明距离
    for(unsigned int r = 0; r < nRotations; r++) { // 遍历所有的旋转（可能包括未旋转）
        // 创建两个临时字节行
        cv::Mat tmp1(1, candidateBytes.cols, CV_8UC1, Scalar::all(0));
        cv::Mat tmp2(1, candidateBytes.cols, CV_8UC1, Scalar::all(0));
        uchar* rot0 = tmp1.ptr(); // 行tmp1的指针
        uchar* rot1 = tmp2.ptr(); // 行tmp2的指针


        for (int i = 0; i < candidateBytes.cols; ++i) { // 将字典中的标记旋转后，与候选标记的字节进行比较
            rot0[i] = bytesList.ptr(id)[r*candidateBytes.cols + i];
            rot1[i] = candidateBytes.ptr()[i];
        }


        // 计算当前的汉明距离
        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING);
        // 更新最小汉明距离
        if(currentHamming < currentMinDistance) {
            currentMinDistance = currentHamming;
        }
    }
    // 对候选标记进行水平翻转和垂直翻转后的处理逻辑与上面类似，不再重复。
    // 返回分配给字典中特定ID的汉明距离
    Mat b; // 定义一个Mat对象b用于存储翻转后的图像
    flip(bits.getMat(), b, 0); // 将输入的图像bits沿着水平轴翻转并存入b
    candidateBytes = aruco::Dictionary::getByteListFromBits(b); // 将翻转后的图像b转换为字节列表
    
    for(unsigned int r = 0; r < nRotations; r++) { // 循环遍历每种旋转状态
        cv::Mat tmp1(1, candidateBytes.cols, CV_8UC1, Scalar::all(0)); // 创建一个用于储存旋转的字节的临时Mat对象tmp1
        cv::Mat tmp2(1, candidateBytes.cols, CV_8UC1, Scalar::all(0)); // 创建一个用于储存原始字节的临时Mat对象tmp2
        uchar* rot0 = tmp1.ptr(); // 获取tmp1的指针
        uchar* rot1 = tmp2.ptr(); // 获取tmp2的指针
    
        for (int i = 0; i < candidateBytes.cols; ++i) { // 循环遍历字节的每一列
            rot0[i] = bytesList.ptr(id)[r*candidateBytes.cols + i]; // 读取固定ID的翻转状态的字节
            rot1[i] = candidateBytes.ptr()[i]; // 从候选字节中读取对应列的字节
        }
    
        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING); // 计算tmp1和tmp2之间的汉明距离
        if (currentHamming < currentMinDistance) { // 如果当前汉明距离小于当前记录的最小距离
            currentMinDistance = currentHamming; // 更新最小汉明距离
        }
    }
    
    flip(bits.getMat(), b, 1); // 将输入的图像bits沿着垂直轴翻转并存入b
    candidateBytes = aruco::Dictionary::getByteListFromBits(b); // 将翻转后的图像b转换为字节列表
    
    for(unsigned int r = 0; r < nRotations; r++) { // 循环遍历每种旋转状态，逻辑与上述相同
        // 对翻转的图像执行与上面相同的操作，检查汉明距离，并更新最小值
        // ... (代码逻辑与上面相同，未显示) ...
        cv::Mat tmp1(1, candidateBytes.cols, CV_8UC1, Scalar::all(0));
        cv::Mat tmp2(1, candidateBytes.cols, CV_8UC1, Scalar::all(0));
        uchar* rot0 = tmp1.ptr();
        uchar* rot1 = tmp2.ptr();


        for (int i = 0; i < candidateBytes.cols; ++i) {
            rot0[i] = bytesList.ptr(id)[r*candidateBytes.cols + i];
            rot1[i] = candidateBytes.ptr()[i];
        }


        double currentHamming = cv::norm(tmp1, tmp2, cv::NORM_HAMMING);
        if (currentHamming < currentMinDistance) {
            currentMinDistance = currentHamming;
        }
    }
    
    return cvRound(currentMinDistance);
}


// 以下函数用于生成定制的非对称ArUco字典
static inline aruco::Dictionary generateCustomAsymmetricDictionary(int nMarkers, int markerSize,
                                                                        const aruco::Dictionary &baseDictionary,
                                                                        int randomSeed) { 
    // 定义一个静态内联函数，用于生成定制的非对称的ArUco标记字典
    RNG rng((uint64)(randomSeed)); // 基于随机种子初始化一个随机数生成器


    aruco::Dictionary out; // 创建一个空的ArUco字典用于输出
    out.markerSize = markerSize; // 设置输出字典中标记的大小


    // 理论上最大的标记间汉明距离
    // 论文参考:S. Garrido-Jurado, et al., 2014. "Automatic generation and detection of highly reliable fiducial markers under occlusion".
    int C = (int)std::floor(float(markerSize * markerSize) / 4.f); // 计算理论最大标记间距
    int tau = 2 * (int)std::floor(float(C) * 4.f / 3.f); // 计算arity的临界值


    // 如果提供了基础字典，计算它的标记间距
    if(baseDictionary.bytesList.rows > 0) {
        CV_Assert(baseDictionary.markerSize == markerSize); // 确认基础字典的尺寸匹配
        out.bytesList = baseDictionary.bytesList.clone(); // 克隆基础字典的字节列表


        int minDistance = markerSize * markerSize + 1; // 初始化最小距离
        for(int i = 0; i < out.bytesList.rows; i++) { // 遍历基础字典所有标记
            Mat markerBytes = out.bytesList.rowRange(i, i + 1); // 获取当前标记的字节行
            Mat markerBits = aruco::Dictionary::getBitsFromByteList(markerBytes, markerSize); // 将当前标记的字节转换成位矩阵
            minDistance = min(minDistance, _getSelfDistance(markerBits)); // 更新最短汉明距离
            for(int j = i + 1; j < out.bytesList.rows; j++) { // 计算当前标记与其他标记的距离
                minDistance = min(minDistance, getFlipDistanceToId(out, markerBits, j)); // 更新最短汉明距离
            }
        }
        tau = minDistance; // 更新临界值tau
    }


    // 当前最佳的选项
    int bestTau = 0; // 初始化最佳tau
    Mat bestMarker; // 存储当前最佳标记


    // 经过指定次数未产生结果的迭代后，接受最佳选项
    const int maxUnproductiveIterations = 5000; // 最大无产出迭代次数
    int unproductiveIterations = 0; // 无产出迭代计数


    while(out.bytesList.rows < nMarkers) { // 当生成的标记数量还未满足要求时
        Mat currentMarker(markerSize, markerSize, CV_8UC1, Scalar::all(0)); // 创建一个新的空标记
        rng.fill(currentMarker, RNG::UNIFORM, 0, 2); // 使用随机数填充当前标记


        int selfDistance = _getSelfDistance(currentMarker); // 计算当前标记的自汉明距离
        int minDistance = selfDistance; // 将其设置为最小距离参考值


        // 如果自汉明距离大于或等于当前最佳，计算与之前接受的标记之间的距离
        if(selfDistance >= bestTau) {
            for(int i = 0; i < out.bytesList.rows; i++) { // 遍历之前接受的所有标记
                int currentDistance = getFlipDistanceToId(out, currentMarker, i); // 计算距离
                minDistance = min(currentDistance, minDistance); // 更新最小距离
                // 如果最小距离小于或等于最佳tau，则跳出循环
                if(minDistance <= bestTau) {
                    break;
                }
            }
        }


        // 如果距离足够大，接受当前标记
        // 如果距离足够大，则接受当前标记
        if(minDistance >= tau) { // 如果最小汉明距离大于等于预定的阈值tau
            unproductiveIterations = 0; // 重置无产出迭代计数器
            bestTau = 0; // 重置最好的tau值
            Mat bytes = aruco::Dictionary::getByteListFromBits(currentMarker); // 获取当前marker的字节列表
            out.bytesList.push_back(bytes); // 将当前marker添加到输出字典的字节列表中
        } else {
            // 如果距离不够大，则进入下面的流程
            unproductiveIterations++; // 无产出迭代计数器加一
        
            // 如果距离尚不够大，但比当前最佳选择要好
            if(minDistance > bestTau) { // 如果最小汉明距离大于当前最佳的tau值
                bestTau = minDistance; // 更新最好的tau值为当前的最小距离
                bestMarker = currentMarker; // 更新最好的marker为当前的marker
            }
        
            // 如果达到了无产出迭代的设定极限，接受当前最佳选择
            if(unproductiveIterations == maxUnproductiveIterations) { // 如果无产出迭代计数等于最大无产出迭代次数
                unproductiveIterations = 0; // 重置无产出迭代计数器
                tau = bestTau; // 设置tau为当前最好的tau值
                bestTau = 0; // 重置最好的tau值
                Mat bytes = aruco::Dictionary::getByteListFromBits(bestMarker); // 获取当前最佳marker的字节列表
                out.bytesList.push_back(bytes); // 将最佳marker添加到输出字典的字节列表中
            }
        }
    }


    // 更新生成字典的最大误差修正位数
    out.maxCorrectionBits = (tau - 1) / 2; // 计算并设置最大纠错位数


    return out; // 返回生成的自定义字典
}


// 以下函数用于获取字典中的最小汉明距离
static inline int getMinDistForDict(const aruco::Dictionary& dict) {
    // 定义一个静态内联函数，用于计算ArUco字典中所有标记的最小汉明距离
    const int dict_size = dict.bytesList.rows; // 获取字典中标记的数量
    const int marker_size = dict.markerSize; // 获取字典中标记的尺寸
    int minDist = marker_size * marker_size; // 初始化最小距离为标记尺寸的平方


    // 双重循环遍历每一对标记
    for (int i = 0; i < dict_size; i++) {
        Mat row = dict.bytesList.row(i); // 获取第i个标记的字节行
        Mat marker = dict.getBitsFromByteList(row, marker_size); // 将字节行转换为二进制位矩阵
        for (int j = 0; j < dict_size; j++) {
            // 确保不与自身比较
            if (j != i) {
                // 获取第i个标记与第j个标记的汉明距离，并更新最小距离
                minDist = min(dict.getDistanceToId(marker, j), minDist);
            }
        }
    }
    return minDist; // 返回最小距离
}
// 以下函数用于获取字典在考虑翻转marker的情况下的最小汉明距离
static inline int getMinAsymDistForDict(const aruco::Dictionary& dict) {
    // 定义一个静态内联函数，用于计算考虑翻转的情况下ArUco字典中所有标记的最小汉明距离
    const int dict_size = dict.bytesList.rows; // 获取字典中标记的数量
    const int marker_size = dict.markerSize; // 获取字典中标记的尺寸
    int minDist = marker_size * marker_size; // 初始化最小距离为标记尺寸的平方


    // 双重循环遍历每一对标记
    for (int i = 0; i < dict_size; i++)
    {
        Mat row = dict.bytesList.row(i); // 获取第i个标记的字节行
        Mat marker = dict.getBitsFromByteList(row, marker_size); // 将字节行转换为二进制位矩阵
        for (int j = 0; j < dict_size; j++)
        {
            if (j != i) // 确保不与自身比较
            {
                // 获取考虑翻转的情况下第i个标记与第j个标记的汉明距离，并更新最小距离
                minDist = min(getFlipDistanceToId(dict, marker, j), minDist);
            }
        }
    }
    return minDist; // 返回考虑翻转的最小距离
}


// 命令行参数定义字符串
const char* keys  =
        "{@outfile |<none> | Output file with custom dict }" // 输出文件参数，输出自定义字典到该文件
        "{r | false | Calculate the metric considering flipped markers }" // 计算考虑翻转标记的度量标准
        "{d | | Dictionary Name: ...}" // 字典名称参数
        "{nMarkers | | Number of markers in the dictionary }" // 字典中标记的数量参数
        "{markerSize | | Marker size }" // 标记大小参数
        "{cd | | Input file with custom dictionary }"; // 自定义字典的输入文件参数


// 程序简介
const char* about =
        "This program can be used to calculate the ArUco dictionary metric.\n"
        "To calculate the metric considering flipped markers use -'r' flag.\n"
        "This program can be used to create and write the custom ArUco dictionary.\n";


int main(int argc, char *argv[])
{
    CommandLineParser parser(argc, argv, keys); // 初始化命令行解析器
    parser.about(about); // 设置关于程序的信息
    if(argc < 2) {
        parser.printMessage(); // 如果参数数量不够，打印帮助信息
        return 0;
    }


    // 从解析器中取得命令行参数
    string outputFile = parser.get<String>(0); // 获取输出文件名
    int nMarkers = parser.get<int>("nMarkers"); // 获取标记数量
    int markerSize = parser.get<int>("markerSize"); // 获取标记大小
    bool checkFlippedMarkers = parser.get<bool>("r"); // 获取是否检查翻转标记的标志


    // 创建一个默认的ArUco字典
    aruco::Dictionary dictionary = aruco::getPredefinedDictionary(0);


    if (parser.has("d")) {
        // 如果提供了字典名称参数，获取相应的预定义字典
        string arucoDictName = parser.get<string>("d"); // 获取字典名称


        cv::aruco::PredefinedDictionaryType arucoDict; // 定义预定义字典类型变量
        // 根据提供的字典名称设置预定义字典类型变量
        if (arucoDictName == "DICT_4X4_50") { arucoDict = cv::aruco::DICT_4X4_50; } // 如果字典名称是"DICT_4X4_50"
        else if (arucoDictName == "DICT_4X4_100") { arucoDict = cv::aruco::DICT_4X4_100; } // 如果字典名称是"DICT_4X4_100"
        else if (arucoDictName == "DICT_4X4_250") { arucoDict = cv::aruco::DICT_4X4_250; } // 如果字典名称是"DICT_4X4_250"
        else if (arucoDictName == "DICT_4X4_1000") { arucoDict = cv::aruco::DICT_4X4_1000; } // 如果字典名称是"DICT_4X4_1000"
        else if (arucoDictName == "DICT_5X5_50") { arucoDict = cv::aruco::DICT_5X5_50; } // 如果字典名称是"DICT_5X5_50"
        else if (arucoDictName == "DICT_5X5_100") { arucoDict = cv::aruco::DICT_5X5_100; } // 如果字典名称是"DICT_5X5_100"
        else if (arucoDictName == "DICT_5X5_250") { arucoDict = cv::aruco::DICT_5X5_250; } // 如果字典名称是"DICT_5X5_250"
        else if (arucoDictName == "DICT_5X5_1000") { arucoDict = cv::aruco::DICT_5X5_1000; } // 如果字典名称是"DICT_5X5_1000"
        else if (arucoDictName == "DICT_6X6_50") { arucoDict = cv::aruco::DICT_6X6_50; } // 如果字典名称是"DICT_6X6_50"
        else if (arucoDictName == "DICT_6X6_100") { arucoDict = cv::aruco::DICT_6X6_100; } // 如果字典名称是"DICT_6X6_100"
        else if (arucoDictName == "DICT_6X6_250") { arucoDict = cv::aruco::DICT_6X6_250; } // 如果字典名称是"DICT_6X6_250"
        else if (arucoDictName == "DICT_6X6_1000") { arucoDict = cv::aruco::DICT_6X6_1000; } // 如果字典名称是"DICT_6X6_1000"
        else if (arucoDictName == "DICT_7X7_50") { arucoDict = cv::aruco::DICT_7X7_50; } // 如果字典名称是"DICT_7X7_50"
        else if (arucoDictName == "DICT_7X7_100") { arucoDict = cv::aruco::DICT_7X7_100; } // 如果字典名称是"DICT_7X7_100"
        else if (arucoDictName == "DICT_7X7_250") { arucoDict = cv::aruco::DICT_7X7_250; } // 如果字典名称是"DICT_7X7_250"
        else if (arucoDictName == "DICT_7X7_1000") { arucoDict = cv::aruco::DICT_7X7_1000; } // 如果字典名称是"DICT_7X7_1000"
        else if (arucoDictName == "DICT_ARUCO_ORIGINAL") { arucoDict = cv::aruco::DICT_ARUCO_ORIGINAL; } // 如果字典名称是"DICT_ARUCO_ORIGINAL"
        else if (arucoDictName == "DICT_APRILTAG_16h5") { arucoDict = cv::aruco::DICT_APRILTAG_16h5; } // 如果字典名称是"DICT_APRILTAG_16h5"
        else if (arucoDictName == "DICT_APRILTAG_25h9") { arucoDict = cv::aruco::DICT_APRILTAG_25h9; } // 如果字典名称是"DICT_APRILTAG_25h9"
        else if (arucoDictName == "DICT_APRILTAG_36h10") { arucoDict = cv::aruco::DICT_APRILTAG_36h10; } // 如果字典名称是"DICT_APRILTAG_36h10"
        else if (arucoDictName == "DICT_APRILTAG_36h11") { arucoDict = cv::aruco::DICT_APRILTAG_36h11; } // 如果字典名称是"DICT_APRILTAG_36h11"
        else {
            cout << "incorrect name of aruco dictionary \n"; // 如果没有匹配的字典名称，打印错误信息
            return 1; // 返回非零值表示错误
        }


        dictionary = aruco::getPredefinedDictionary(arucoDict); // 从预定义字典类型获取预定义字典
    }
    else if (parser.has("cd")) {
        // 如果提供了自定义字典文件参数，读取自定义字典
        FileStorage fs(parser.get<std::string>("cd"), FileStorage::READ);
        bool readOk = dictionary.readDictionary(fs.root());
        if(!readOk) {
            cerr << "Invalid dictionary file" << endl; // 如果读取失败，打印错误信息
            return 0;
        }
    }
    else if (outputFile.empty() || nMarkers == 0 || markerSize == 0) {
        cerr << "Dictionary not specified" << endl; // 如果必要的参数没有提供，打印错误信息
        return 0;
    }
    if (!outputFile.empty() && nMarkers > 0 && markerSize > 0)
    {
        // 如果提供了所需要的参数，则生成自定义字典并写入文件
        FileStorage fs(outputFile, FileStorage::WRITE);
        if (checkFlippedMarkers)
            dictionary = generateCustomAsymmetricDictionary(nMarkers, markerSize, aruco::Dictionary(), 0); // 生成考虑翻转的自定义字典
        else
            dictionary = aruco::extendDictionary(nMarkers, markerSize, aruco::Dictionary(), 0); // 扩展字典
        dictionary.writeDictionary(fs); // 写入字典到文件
    }


    // 计算并打印字典的最小汉明距离
    if (checkFlippedMarkers) {
        cout << "Hamming distance: " << getMinAsymDistForDict(dictionary) << endl; // 考虑翻转的最小汉明距离
    }
    else {
        cout << "Hamming distance: " << getMinDistForDict(dictionary) << endl; // 不考虑翻转的最小汉明距离
    }


    return 0; // 程序结束
}

PS V:\learn\opencv\github\opencv\sources\test\x64\Debug> ./test.exe  @outfile=custom_dict.yml -nMarkers=50 -markerSize=6
Hamming distance: 12

@outfile=custom_dict.yml