modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp

   1 // This file is part of OpenCV project.
   2 // It is subject to the license terms in the LICENSE file found in the top-level directory
   3 // of this distribution and at http://opencv.org/license.html
   4 #ifndef OPENCV_OBJDETECT_DICTIONARY_HPP
   5 #define OPENCV_OBJDETECT_DICTIONARY_HPP
   6
   7 #include <opencv2/core.hpp>
   8
   9 namespace cv {
  10 namespace aruco {
  11
  12 //! @addtogroup objdetect_aruco
  13 //! @{
  14
  15
  16 /** @brief Dictionary/Set of markers, it contains the inner codification
  17  *
  18  * BytesList contains the marker codewords where:
  19  * - bytesList.rows is the dictionary size
  20  * - each marker is encoded using `nbytes = ceil(markerSize*markerSize/8.)`
  21  * - each row contains all 4 rotations of the marker, so its length is `4*nbytes`
  22  *
  23  * `bytesList.ptr(i)[k*nbytes + j]` is then the j-th byte of i-th marker, in its k-th rotation.
  24  */
  25 class CV_EXPORTS_W_SIMPLE Dictionary {
  26
  27     public:
  28     CV_PROP_RW Mat bytesList;         // marker code information
  29     CV_PROP_RW int markerSize;        // number of bits per dimension
  30     CV_PROP_RW int maxCorrectionBits; // maximum number of bits that can be corrected
  31
  32
  33     CV_WRAP Dictionary();
  34
  35     CV_WRAP Dictionary(const Mat &bytesList, int _markerSize, int maxcorr = 0);
  36
  37
  38
  39     /** @brief Read a new dictionary from FileNode.
  40      *
  41      * Dictionary format:\n
  42      * nmarkers: 35\n
  43      * markersize: 6\n
  44      * maxCorrectionBits: 5\n
  45      * marker_0: "101011111011111001001001101100000000"\n
  46      * ...\n
  47      * marker_34: "011111010000111011111110110101100101"
  48      */
  49     CV_WRAP bool readDictionary(const cv::FileNode& fn);
  50
  51     /** @brief Write a dictionary to FileStorage, format is the same as in readDictionary().
  52      */
  53     CV_WRAP void writeDictionary(FileStorage& fs, const String& name = String());
  54
  55     /** @brief Given a matrix of bits. Returns whether if marker is identified or not.
  56      *
  57      * It returns by reference the correct id (if any) and the correct rotation
  58      */
  59     CV_WRAP bool identify(const Mat &onlyBits, CV_OUT int &idx, CV_OUT int &rotation, double maxCorrectionRate) const;
  60
  61     /** @brief Returns the distance of the input bits to the specific id.
  62      *
  63      * If allRotations is true, the four posible bits rotation are considered
  64      */
  65     CV_WRAP int getDistanceToId(InputArray bits, int id, bool allRotations = true) const;
  66
  67
  68     /** @brief Generate a canonical marker image
  69      */
  70     CV_WRAP void generateImageMarker(int id, int sidePixels, OutputArray _img, int borderBits = 1) const;
  71
  72
  73     /** @brief Transform matrix of bits to list of bytes in the 4 rotations
  74       */
  75     CV_WRAP static Mat getByteListFromBits(const Mat &bits);
  76
  77
  78     /** @brief Transform list of bytes to matrix of bits
  79       */
  80     CV_WRAP static Mat getBitsFromByteList(const Mat &byteList, int markerSize);
  81 };
  82
  83
  84
  85
  86 /** @brief Predefined markers dictionaries/sets
  87  *
  88  * Each dictionary indicates the number of bits and the number of markers contained
  89  * - DICT_ARUCO_ORIGINAL: standard ArUco Library Markers. 1024 markers, 5x5 bits, 0 minimum
  90                           distance
  91  */
  92 enum PredefinedDictionaryType {
  93     DICT_4X4_50 = 0,        ///< 4x4 bits, minimum hamming distance between any two codes = 4, 50 codes
  94     DICT_4X4_100,           ///< 4x4 bits, minimum hamming distance between any two codes = 3, 100 codes
  95     DICT_4X4_250,           ///< 4x4 bits, minimum hamming distance between any two codes = 3, 250 codes
  96     DICT_4X4_1000,          ///< 4x4 bits, minimum hamming distance between any two codes = 2, 1000 codes
  97     DICT_5X5_50,            ///< 5x5 bits, minimum hamming distance between any two codes = 8, 50 codes
  98     DICT_5X5_100,           ///< 5x5 bits, minimum hamming distance between any two codes = 7, 100 codes
  99     DICT_5X5_250,           ///< 5x5 bits, minimum hamming distance between any two codes = 6, 250 codes
 100     DICT_5X5_1000,          ///< 5x5 bits, minimum hamming distance between any two codes = 5, 1000 codes
 101     DICT_6X6_50,            ///< 6x6 bits, minimum hamming distance between any two codes = 13, 50 codes
 102     DICT_6X6_100,           ///< 6x6 bits, minimum hamming distance between any two codes = 12, 100 codes
 103     DICT_6X6_250,           ///< 6x6 bits, minimum hamming distance between any two codes = 11, 250 codes
 104     DICT_6X6_1000,          ///< 6x6 bits, minimum hamming distance between any two codes = 9, 1000 codes
 105     DICT_7X7_50,            ///< 7x7 bits, minimum hamming distance between any two codes = 19, 50 codes
 106     DICT_7X7_100,           ///< 7x7 bits, minimum hamming distance between any two codes = 18, 100 codes
 107     DICT_7X7_250,           ///< 7x7 bits, minimum hamming distance between any two codes = 17, 250 codes
 108     DICT_7X7_1000,          ///< 7x7 bits, minimum hamming distance between any two codes = 14, 1000 codes
 109     DICT_ARUCO_ORIGINAL,    ///< 6x6 bits, minimum hamming distance between any two codes = 3, 1024 codes
 110     DICT_APRILTAG_16h5,     ///< 4x4 bits, minimum hamming distance between any two codes = 5, 30 codes
 111     DICT_APRILTAG_25h9,     ///< 5x5 bits, minimum hamming distance between any two codes = 9, 35 codes
 112     DICT_APRILTAG_36h10,    ///< 6x6 bits, minimum hamming distance between any two codes = 10, 2320 codes
 113     DICT_APRILTAG_36h11     ///< 6x6 bits, minimum hamming distance between any two codes = 11, 587 codes
 114 };
 115
 116
 117 /** @brief Returns one of the predefined dictionaries defined in PredefinedDictionaryType
 118   */
 119 CV_EXPORTS Dictionary getPredefinedDictionary(PredefinedDictionaryType name);
 120
 121
 122 /** @brief Returns one of the predefined dictionaries referenced by DICT_*.
 123   */
 124 CV_EXPORTS_W Dictionary getPredefinedDictionary(int dict);
 125
 126 /** @brief Extend base dictionary by new nMarkers
 127   *
 128   * @param nMarkers number of markers in the dictionary
 129   * @param markerSize number of bits per dimension of each markers
 130   * @param baseDictionary Include the markers in this dictionary at the beginning (optional)
 131   * @param randomSeed a user supplied seed for theRNG()
 132   *
 133   * This function creates a new dictionary composed by nMarkers markers and each markers composed
 134   * by markerSize x markerSize bits. If baseDictionary is provided, its markers are directly
 135   * included and the rest are generated based on them. If the size of baseDictionary is higher
 136   * than nMarkers, only the first nMarkers in baseDictionary are taken and no new marker is added.
 137   */
 138 CV_EXPORTS_W Dictionary extendDictionary(int nMarkers, int markerSize, const Dictionary &baseDictionary = Dictionary(),
 139                                          int randomSeed=0);
 140
 141
 142
 143 //! @}
 144 }
 145 }
 146
 147 #endif