Merge pull request #3724 from catree:add_visual_servo_references

Rename getInteractionMatrix() to computeInteractionMatrix()

Author: asmorkalov

modules/tracking/doc/tracking.bib

@@ -76,3 +76,43 @@ @Article{Lukezic_IJCV2018
 journal={International Journal of Computer Vision},
 year={2018},
 }
+
+@article{chaumette:inria-00350283,
+  title={{Visual servo control, Part I: Basic approaches}},
+  author={Chaumette, Fran{\c c}ois and Hutchinson, S.},
+  url={https://inria.hal.science/inria-00350283},
+  journal={{IEEE Robotics and Automation Magazine}},
+  publisher={{Institute of Electrical and Electronics Engineers}},
+  volume={13},
+  number={4},
+  pages={82-90},
+  year={2006},
+  pdf={https://inria.hal.science/inria-00350283/file/2006_ieee_ram_chaumette.pdf},
+  hal_id={inria-00350283},
+  hal_version={v1},
+}
+
+@article{chaumette:inria-00350638,
+  title={{Visual servo control, Part II: Advanced approaches}},
+  author={Chaumette, Fran{\c c}ois and Hutchinson, S.},
+  url={https://inria.hal.science/inria-00350638},
+  journal={{IEEE Robotics and Automation Magazine}},
+  publisher={{Institute of Electrical and Electronics Engineers}},
+  volume={14},
+  number={1},
+  pages={109-118},
+  year={2007},
+  pdf={https://inria.hal.science/inria-00350638/file/2007_ieee_ram_chaumette.pdf},
+  hal_id={inria-00350638},
+  hal_version={v1},
+}
+
+@article{Hutchinson1996ATO,
+  title={A tutorial on visual servo control},
+  author={Seth A. Hutchinson and Gregory Hager and Peter Corke},
+  journal={IEEE Trans. Robotics Autom.},
+  year={1996},
+  volume={12},
+  pages={651-670},
+  url={https://api.semanticscholar.org/CorpusID:1814423}
+}

modules/tracking/include/opencv2/tracking/twist.hpp

@@ -16,7 +16,7 @@ inline namespace tracking
  * @brief Compute the camera twist from a set of 2D pixel locations, their
  * velocities, depth values and intrinsic parameters of the camera. The pixel
  * velocities are usually obtained from optical flow algorithms, both dense and
- * sparse flow can be used to compute the flow between images and duv computed by
+ * sparse flow can be used to compute the flow between images and \p duv computed by
  * dividing the flow by the time interval between the images.
  *
  * @param uv 2xN matrix of 2D pixel locations
@@ -30,9 +30,10 @@ CV_EXPORTS cv::Vec6d computeTwist(const cv::Mat& uv, const cv::Mat& duv, const c
                                   const cv::Mat& K);
 
 /**
- * @brief Compute the interaction matrix for a set of 2D pixels. This is usually
+ * @brief Compute the interaction matrix ( @cite Hutchinson1996ATO @cite chaumette:inria-00350283
+ * @cite chaumette:inria-00350638 ) for a set of 2D pixels. This is usually
  * used in visual servoing applications to command a robot to move at desired pixel
- * locations/velocities. By inverting this matrix one can estimate camera spatial
+ * locations/velocities. By inverting this matrix, one can estimate camera spatial
  * velocity i.e., the twist.
  *
  * @param uv 2xN matrix of 2D pixel locations
@@ -41,8 +42,8 @@ CV_EXPORTS cv::Vec6d computeTwist(const cv::Mat& uv, const cv::Mat& duv, const c
  * @param J 2Nx6 interaction matrix
  *
  */
-CV_EXPORTS void getInteractionMatrix(const cv::Mat& uv, const cv::Mat& depths, const cv::Mat& K,
-                                     cv::Mat& J);
+CV_EXPORTS void computeInteractionMatrix(const cv::Mat& uv, const cv::Mat& depths, const cv::Mat& K,
+                                         cv::Mat& J);
 
 //! @}
 

modules/tracking/src/twist.cpp

@@ -9,7 +9,7 @@ namespace detail
 inline namespace tracking
 {
 
-void getInteractionMatrix(const cv::Mat& uv, const cv::Mat& depths, const cv::Mat& K, cv::Mat& J)
+void computeInteractionMatrix(const cv::Mat& uv, const cv::Mat& depths, const cv::Mat& K, cv::Mat& J)
 {
     CV_Assert(uv.cols == depths.cols);
     CV_Assert(depths.type() == CV_32F);
@@ -64,7 +64,7 @@ cv::Vec6d computeTwist(const cv::Mat& uv, const cv::Mat& duv, const cv::Mat& dep
     CV_Assert(uv.cols * 2 == duv.rows);
 
     cv::Mat J;
-    getInteractionMatrix(uv, depths, K, J);
+    computeInteractionMatrix(uv, depths, K, J);
     cv::Mat Jinv;
     cv::invert(J, Jinv, cv::DECOMP_SVD);
     cv::Mat twist = Jinv * duv;

modules/tracking/test/test_twist.cpp

@@ -39,7 +39,7 @@ TEST_F(TwistTest, TestInteractionMatrix)
     cv::Mat uv = cv::Mat(2, 1, CV_32F, {1.0f, 1.0f});
     cv::Mat depth = cv::Mat(1, 1, CV_32F, {2.0f});
 
-    getInteractionMatrix(uv, depth, K, J);
+    computeInteractionMatrix(uv, depth, K, J);
     ASSERT_EQ(J.cols, 6);
     ASSERT_EQ(J.rows, 2);
     float expected[2][6] = {{-0.5f, 0.0f, 0.5f, 1.0f, -2.0f, 1.0f},
@@ -87,7 +87,7 @@ TEST_F(TwistTest, TestComputeWithNonZeroPixelVelocities)
     float duv_data[] = {1.0f, 2.0f, 1.0f, 3.0f, 1.0f, 4.0f};
     cv::Mat duv = cv::Mat(6, 1, CV_32F, duv_data);
 
-    getInteractionMatrix(uv, depth, K, J);
+    computeInteractionMatrix(uv, depth, K, J);
     ASSERT_EQ(J.cols, 6);
     ASSERT_EQ(J.rows, 6);
     float expected_jac[6][6] = {{-1.0f, 0.0f, 1.0f, 1.0f, -2.0f, 1.0f},