From c12e1ecb866bf64d23b8a054ba01afefa410762d Mon Sep 17 00:00:00 2001
From: Alex <alexander.panov@xperience.ai>
Date: Tue, 4 Jul 2023 02:44:30 +0300
Subject: [PATCH] update aruco bytesList docs

---
 doc/opencv.bib                                |  8 ++++
 .../opencv2/objdetect/aruco_dictionary.hpp    | 39 +++++++++++--------
 2 files changed, 31 insertions(+), 16 deletions(-)

diff --git a/doc/opencv.bib b/doc/opencv.bib
index 64aa363202..6071cc3e1b 100644
--- a/doc/opencv.bib
+++ b/doc/opencv.bib
@@ -1377,3 +1377,11 @@
   year={2005},
   pages={70-74}
 }
+@inproceedings{wang2016iros,
+    AUTHOR     = {John Wang and Edwin Olson},
+    TITLE      = {{AprilTag} 2: Efficient and robust fiducial detection},
+    BOOKTITLE  = {Proceedings of the {IEEE/RSJ} International Conference on Intelligent
+                 Robots and Systems {(IROS)}},
+    YEAR       = {2016},
+    MONTH      = {October},
+}
diff --git a/modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp b/modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp
index c46b5fbfb5..bc7b934b2a 100644
--- a/modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp
+++ b/modules/objdetect/include/opencv2/objdetect/aruco_dictionary.hpp
@@ -13,32 +13,39 @@ namespace aruco {
 //! @{
 
 
-/** @brief Dictionary/Set of markers, it contains the inner codification
+/** @brief Dictionary is a set of unique ArUco markers of the same size
  *
- * BytesList contains the marker codewords where:
+ * `bytesList` storing as 2-dimensions Mat with 4-th channels (CV_8UC4 type was used) and contains the marker codewords where:
  * - bytesList.rows is the dictionary size
- * - each marker is encoded using `nbytes = ceil(markerSize*markerSize/8.)`
+ * - each marker is encoded using `nbytes = ceil(markerSize*markerSize/8.)` bytes
  * - each row contains all 4 rotations of the marker, so its length is `4*nbytes`
- *
- * `bytesList.ptr(i)[k*nbytes + j]` is then the j-th byte of i-th marker, in its k-th rotation.
+ * - the byte order in the bytesList[i] row:
+ * `//bytes without rotation/bytes with rotation 1/bytes with rotation 2/bytes with rotation 3//`
+ * So `bytesList.ptr(i)[k*nbytes + j]` is the j-th byte of i-th marker, in its k-th rotation.
+ * @note Python bindings generate matrix with shape of bytesList `dictionary_size x nbytes x 4`,
+ * but it should be indexed like C++ version. Python example for j-th byte of i-th marker, in its k-th rotation:
+ * `aruco_dict.bytesList[id].ravel()[k*nbytes + j]`
  */
 class CV_EXPORTS_W_SIMPLE Dictionary {
 
     public:
-    CV_PROP_RW Mat bytesList;         // marker code information
-    CV_PROP_RW int markerSize;        // number of bits per dimension
-    CV_PROP_RW int maxCorrectionBits; // maximum number of bits that can be corrected
-
+    CV_PROP_RW Mat bytesList;         ///< marker code information. See class description for more details
+    CV_PROP_RW int markerSize;        ///< number of bits per dimension
+    CV_PROP_RW int maxCorrectionBits; ///< maximum number of bits that can be corrected
 
     CV_WRAP Dictionary();
 
+    /** @brief Basic ArUco dictionary constructor
+     *
+     * @param bytesList bits for all ArUco markers in dictionary see memory layout in the class description
+     * @param _markerSize ArUco marker size in units
+     * @param maxcorr maximum number of bits that can be corrected
+     */
     CV_WRAP Dictionary(const Mat &bytesList, int _markerSize, int maxcorr = 0);
 
-
-
     /** @brief Read a new dictionary from FileNode.
      *
-     * Dictionary format:\n
+     * Dictionary example in YAML format:\n
      * nmarkers: 35\n
      * markersize: 6\n
      * maxCorrectionBits: 5\n
@@ -54,13 +61,13 @@ class CV_EXPORTS_W_SIMPLE Dictionary {
 
     /** @brief Given a matrix of bits. Returns whether if marker is identified or not.
      *
-     * It returns by reference the correct id (if any) and the correct rotation
+     * Returns reference to the marker id in the dictionary (if any) and its rotation.
      */
     CV_WRAP bool identify(const Mat &onlyBits, CV_OUT int &idx, CV_OUT int &rotation, double maxCorrectionRate) const;
 
-    /** @brief Returns the distance of the input bits to the specific id.
+    /** @brief Returns Hamming distance of the input bits to the specific id.
      *
-     * If allRotations is true, the four posible bits rotation are considered
+     * If `allRotations` flag is set, the four posible marker rotations are considered
      */
     CV_WRAP int getDistanceToId(InputArray bits, int id, bool allRotations = true) const;
 
@@ -70,7 +77,7 @@ class CV_EXPORTS_W_SIMPLE Dictionary {
     CV_WRAP void generateImageMarker(int id, int sidePixels, OutputArray _img, int borderBits = 1) const;
 
 
-    /** @brief Transform matrix of bits to list of bytes in the 4 rotations
+    /** @brief Transform matrix of bits to list of bytes with 4 marker rotations
       */
     CV_WRAP static Mat getByteListFromBits(const Mat &bits);