Documentation - KeyPoint class
Hi,
I have a question about the documentation of the KeyPoint class.
see files:
- core/include/opencv2/core/types.hpp
- core/src/opencv2/core/types.cpp
Background:
i was looking for a way to convert vector< KeyPoint > to vector< Point2f >.
There is the convert(const std::vector< KeyPoint > &keypoints, std::vector< Point2f > &points2f, const std::vector< int > &keypointIndexes=std::vector< int >()) function. The documentation in the header file says:
/**
This method converts vector of keypoints to vector of points or the reverse, where each keypoint is
assigned the same size and the same orientation.
@Param keypoints Keypoints obtained from any feature detection algorithm like SIFT/SURF/ORB
@Param points2f Array of (x,y) coordinates of each keypoint
@Param keypointIndexes Array of indexes of keypoints to be converted to points. (Acts like a mask to
convert only specified keypoints)
*/
and there is the convert (const std::vector< Point2f > &points2f, std::vector< KeyPoint > &keypoints, float size=1, float response=1, int octave=0, int class_id=-1) function on which the documentation says:
/** @overload
@Param points2f Array of (x,y) coordinates of each keypoint
@Param keypoints Keypoints obtained from any feature detection algorithm like SIFT/SURF/ORB
@Param size keypoint diameter
@Param response keypoint detector response on the keypoint (that is, strength of the keypoint)
@Param octave pyramid octave in which the keypoint has been detected
@Param class_id object id
*/
what expands to
"This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts."
in the documentation at http://docs.opencv.org/master/d2/d29/...
But if you see the implementation its clear that the actual functionalities of the both convert() functions do not fit their documentation. The first one converts from vector< KeyPoint > to vector< Point2f > and the overloaded one from vector< Point2f > to vector < KeyPoint >.
So now i'm not sure if
- everything is OK and well documented and me, as a newbie, just cannot read the documentation well
- the documentation in core/include/opencv2/core/types.hpp is wrong
- the implementation in core/src/opencv2/core/types.cpp is wrong
Would be nice if you guys could help me out on this. Is it a issue that need to get fixed? Or is it normal to document it this way?
I think everything is ok. In the description of the first function, it is stated that
convert()is used to convert vector of keypoints to vector of points or the reverse, so it is already defining functionality of both versions, so to say. The second function is indeed and overloaded function because the name remains (it is stillconvert()), though the different parameters change direction of conversion. However, if you feel this is unclear, feel free to add any further explanatory note and create a Pull Request (How to contribute)i expected two functions or a switch param: convertTo and convertFrom or something like that (convert(..., bool fromTo)). two functions would make more sense in my eyes because most of the params in the overloaded function have no use in the point->keypoint case.
i don't know why it is solved like this but i think it has historical/compatibility reasons.
to move/reorganize the comment would clarify the documentation, yes. the easy way without causing compatibility issues.
@uavcamera: then as I said, feel free to update the docs and create an official PR (following guides in contribution guide. Also, you can/should take a look at the documentation tutorial)
@LorenaGdL thanks for that http://docs.opencv.org/master/d4/db1/... !
is there a similar tutorial for writing the code? some things are not clear on the first view for newbies (things like CV_OUT)
hmmm I don't think so, or at least I don't remember it right now. There are some guidelines but not a tutorial