Merge pull request #23575 from vovka643:4.x_aruco_calib3d_calibration

add ChArUco board pattern into calib3d/camera_calibration #23575

Added opportunity to calibrate camera using ChArUco board pattern in /samples/cpp/tutorial_code/calib3d/camera_calibration/caera_calibration.cpp 
### Pull Request Readiness Checklist

See details at https://github.com/opencv/opencv/wiki/How_to_contribute#making-a-good-pull-request

- [x] I agree to contribute to the project under Apache 2 License.
- [x] To the best of my knowledge, the proposed patch is not based on a code under GPL or another license that is incompatible with OpenCV
- [x] The PR is proposed to the proper branch
- [] There is a reference to the original bug report and related work
- [x] There is accuracy test, performance test and test data in opencv_extra repository, if applicable
      Patch to opencv_extra has the same branch name.
- [x] The feature is well documented and sample code can be built with the project CMake

doc/tutorials/calib3d/camera_calibration/camera_calibration.markdown

@@ -60,6 +60,7 @@ done through basic geometrical equations. The equations used depend on the chose
 objects. Currently OpenCV supports three types of objects for calibration:
 
 -   Classical black-white chessboard
+-   ChArUco board pattern
 -   Symmetrical circle pattern
 -   Asymmetrical circle pattern
 
@@ -88,7 +89,8 @@ Source code
 
 You may also find the source code in the `samples/cpp/tutorial_code/calib3d/camera_calibration/`
 folder of the OpenCV source library or [download it from here
-](https://github.com/opencv/opencv/tree/4.x/samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp). For the usage of the program, run it with `-h` argument. The program has an
+](https://github.com/opencv/opencv/tree/4.x/samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp).
+For the usage of the program, run it with `-h` argument. The program has an
 essential argument: the name of its configuration file. If none is given then it will try to open the
 one named "default.xml". [Here's a sample configuration file
 ](https://github.com/opencv/opencv/tree/4.x/samples/cpp/tutorial_code/calib3d/camera_calibration/in_VID5.xml) in XML format. In the
@@ -128,14 +130,23 @@ Explanation
 
     The formation of the equations I mentioned above aims
     to finding major patterns in the input: in case of the chessboard this are corners of the
-    squares and for the circles, well, the circles themselves. The position of these will form the
+    squares and for the circles, well, the circles themselves. ChArUco board is equivalent to
+    chessboard, but corners are mached by ArUco markers. The position of these will form the
     result which will be written into the *pointBuf* vector.
     @snippet samples/cpp/tutorial_code/calib3d/camera_calibration/camera_calibration.cpp find_pattern
     Depending on the type of the input pattern you use either the @ref cv::findChessboardCorners or
-    the @ref cv::findCirclesGrid function. For both of them you pass the current image and the size
-    of the board and you'll get the positions of the patterns. Furthermore, they return a boolean
-    variable which states if the pattern was found in the input (we only need to take into account
-    those images where this is true!).
+    the @ref cv::findCirclesGrid function or @ref cv::aruco::CharucoDetector::detectBoard method.
+    For all of them you pass the current image and the size of the board and you'll get the positions
+    of the patterns. cv::findChessboardCorners and cv::findCirclesGrid return a boolean variable
+    which states if the pattern was found in the input (we only need to take into account
+    those images where this is true!). `CharucoDetector::detectBoard` may detect partially visible
+    pattern and returns coordunates and ids of visible inner corners.
+
+    @note Board size and amount of matched points is different for chessboard, circles grid and ChArUco.
+    All chessboard related algorithm expects amount of inner corners as board width and height.
+    Board size of circles grid is just amount of circles by both grid dimentions. ChArUco board size
+    is defined in squares, but detection result is list of inner corners and that's why is smaller
+    by 1 in both dimentions.
 
     Then again in case of cameras we only take camera images when an input delay time is passed.
     This is done in order to allow user moving the chessboard around and getting different images.