Merge pull request #29487 from Functionhx:fix/docs-combined

Fix calibration tutorial docs, decomposeProjectionMatrix, and convertMaps performance claims #29487

Fixes #25655, #26791, #27277.

Three doc fixes:
1. Calibration tutorial: rows/cols swapped, fixed np.mgrid consistency
2. decomposeProjectionMatrix: clarified transVect is camera center in homogeneous coordinates
3. convertMaps: replaced overstated 2x speed claim

### Pull Request Readiness Checklist
- [x] I agree to contribute under Apache 2 License
- [x] Not based on GPL/incompatible license
- [x] PR proposed to proper branch (4.x)
- [x] Reference to original bug report and related work
- [ ] Accuracy test, performance test, test data: N/A (doc-only)
- [x] Feature well documented and sample code buildable

doc/py_tutorials/py_calib3d/py_calibration/py_calibration.markdown

@@ -81,7 +81,7 @@ pass in terms of square size).
 
 So to find pattern in chess board, we can use the function, **cv.findChessboardCorners()**. We also
 need to pass what kind of pattern we are looking for, like 8x8 grid, 5x5 grid etc. In this example, we
-use 7x6 grid. (Normally a chess board has 8x8 squares and 7x7 internal corners). It returns the
+use 6x7 grid. (Normally a chess board has 8x8 squares and 7x7 internal corners). It returns the
 corner points and retval which will be True if pattern is obtained. These corners will be placed in
 an order (from left-to-right, top-to-bottom)
 
@@ -107,9 +107,11 @@ import glob
 # termination criteria
 criteria = (cv.TERM_CRITERIA_EPS + cv.TERM_CRITERIA_MAX_ITER, 30, 0.001)
 
-# prepare object points, like (0,0,0), (1,0,0), (2,0,0) ....,(6,5,0)
-objp = np.zeros((6*7,3), np.float32)
-objp[:,:2] = np.mgrid[0:7,0:6].T.reshape(-1,2)
+# prepare object points, like (0,0,0), (1,0,0), (2,0,0) ....,(5,6,0)
+cols = 6
+rows = 7
+objp = np.zeros((cols*rows,3), np.float32)
+objp[:,:2] = np.mgrid[0:cols,0:rows].T.reshape(-1,2)
 
 # Arrays to store object points and image points from all the images.
 objpoints = [] # 3d point in real world space
@@ -122,7 +124,7 @@ for fname in images:
     gray = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
 
     # Find the chess board corners
-    ret, corners = cv.findChessboardCorners(gray, (7,6), None)
+    ret, corners = cv.findChessboardCorners(gray, (cols, rows), None)
 
     # If found, add object points, image points (after refining them)
     if ret == True:
@@ -132,7 +134,7 @@ for fname in images:
         imgpoints.append(corners2)
 
         # Draw and display the corners
-        cv.drawChessboardCorners(img, (7,6), corners2, ret)
+        cv.drawChessboardCorners(img, (cols, rows), corners2, ret)
         cv.imshow('img', img)
         cv.waitKey(500)
 

doc/py_tutorials/py_calib3d/py_pose/py_pose.markdown

@@ -50,12 +50,14 @@ our X axis is drawn from (0,0,0) to (3,0,0), so for Y axis. For Z axis, it is dr
 (0,0,-3). Negative denotes it is drawn towards the camera.
 @code{.py}
 criteria = (cv.TERM_CRITERIA_EPS + cv.TERM_CRITERIA_MAX_ITER, 30, 0.001)
-objp = np.zeros((6*7,3), np.float32)
-objp[:,:2] = np.mgrid[0:7,0:6].T.reshape(-1,2)
+cols = 6
+rows = 7
+objp = np.zeros((cols*rows,3), np.float32)
+objp[:,:2] = np.mgrid[0:cols,0:rows].T.reshape(-1,2)
 
 axis = np.float32([[3,0,0], [0,3,0], [0,0,-3]]).reshape(-1,3)
 @endcode
-Now, as usual, we load each image. Search for 7x6 grid. If found, we refine it with subcorner
+Now, as usual, we load each image. Search for 6x7 grid. If found, we refine it with subcorner
 pixels. Then to calculate the rotation and translation, we use the function,
 **cv.solvePnPRansac()**. Once we those transformation matrices, we use them to project our **axis
 points** to the image plane. In simple words, we find the points on image plane corresponding to
@@ -65,7 +67,7 @@ to each of these points using our generateImage() function. Done !!!
 for fname in glob.glob('left*.jpg'):
     img = cv.imread(fname)
     gray = cv.cvtColor(img,cv.COLOR_BGR2GRAY)
-    ret, corners = cv.findChessboardCorners(gray, (7,6),None)
+    ret, corners = cv.findChessboardCorners(gray, (cols, rows), None)
 
     if ret == True:
         corners2 = cv.cornerSubPix(gray,corners,(11,11),(-1,-1),criteria)

modules/calib3d/include/opencv2/calib3d.hpp

@@ -881,7 +881,8 @@ CV_EXPORTS_W Vec3d RQDecomp3x3( InputArray src, OutputArray mtxR, OutputArray mt
 @param projMatrix 3x4 input projection matrix P.
 @param cameraMatrix Output 3x3 camera intrinsic matrix \f$\cameramatrix{A}\f$.
 @param rotMatrix Output 3x3 external rotation matrix R.
-@param transVect Output 4x1 translation vector T.
+@param transVect Output 4x1 vector representing the camera position in homogeneous coordinates.
+To obtain the translation vector, use t = -rotMatrix * transVect[:3].
 @param rotMatrixX Optional 3x3 rotation matrix around x-axis.
 @param rotMatrixY Optional 3x3 rotation matrix around y-axis.
 @param rotMatrixZ Optional 3x3 rotation matrix around z-axis.

modules/imgproc/include/opencv2/imgproc.hpp

@@ -2529,9 +2529,11 @@ with the WARP_RELATIVE_MAP flag :
 where values of pixels with non-integer coordinates are computed using one of available
 interpolation methods. \f$map_x\f$ and \f$map_y\f$ can be encoded as separate floating-point maps
 in \f$map_1\f$ and \f$map_2\f$ respectively, or interleaved floating-point maps of \f$(x,y)\f$ in
-\f$map_1\f$, or fixed-point maps created by using #convertMaps. The reason you might want to
-convert from floating to fixed-point representations of a map is that they can yield much faster
-(\~2x) remapping operations. In the converted case, \f$map_1\f$ contains pairs (cvFloor(x),
+\f$map_1\f$, or fixed-point maps created by using #convertMaps. Fixed-point maps
+use a more compact representation, which can reduce memory bandwidth and benefit
+repeated remap calls that reuse the same map. Performance gains vary by hardware
+and are typically modest; measure before converting. In the converted case,
+\f$map_1\f$ contains pairs (cvFloor(x),
 cvFloor(y)) and \f$map_2\f$ contains indices in a table of interpolation coefficients.
 
 This function cannot operate in-place.
@@ -2540,7 +2542,7 @@ This function cannot operate in-place.
 @param dst Destination image. It has the same size as map1 and the same type as src .
 @param map1 The first map of either (x,y) points or just x values having the type CV_16SC2 ,
 CV_32FC1, or CV_32FC2. See #convertMaps for details on converting a floating point
-representation to fixed-point for speed.
+representation to fixed-point.
 @param map2 The second map of y values having the type CV_16UC1, CV_32FC1, or none (empty map
 if map1 is (x,y) points), respectively.
 @param interpolation Interpolation method (see #InterpolationFlags). The methods #INTER_AREA