＜python基础＞查询函数的帮助文档

cv2.kmeans函数中包含很多参数，因不理解各参数的含义以及如何取值，故想要查看其帮助文档。

在网上找到了一份查看帮助文档的教程，提供了5个方法。测试了其中大多数方法，发现显示结果略有差异，故作记录。方法原文见：https://www.codenong.com/cs106691818/

系统：windows11；IDE：pycharm；python：3.7

## 方法1 ：dir(module_name.func_name)

import cv2

dir(cv2)
dir(cv2.kmeans)
'''
运行后不显示结果，尝试用print函数显示结果
'''

print(dir(cv2))
'''
显示cv2中所有的函数名称，结果太多不展示
'''
print(dir(cv2.kmeans))
'''
显示的内容为：['__call__', '__class__', '__delattr__', '__dir__', 
'__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', 
'__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', 
'__lt__', '__module__', '__name__', '__ne__', '__new__', '__qualname__',
 '__reduce__', '__reduce_ex__', '__repr__', '__self__', '__setattr__', 
 '__sizeof__', '__str__', '__subclasshook__', '__text_signature__']
 
不太清楚返回参数的含义，但不是我需要的。
'''

## 方法2 ：module.func_name?

import cv2

cv2?
cv2.kmeans?
'''
报错：SyntaxError: invalid syntax
尝试用print()函数打印结果
'''
print(cv2?)
'''
依然报错
'''

## 方法3 ：help()函数

import cv2

help(cv2.kmeans)
'''
显示的内容为：
kmeans(...)
    kmeans(data, K, bestLabels, criteria, attempts, flags[, centers]) -> retval, bestLabels, centers
    .   @brief Finds centers of clusters and groups input samples around the clusters.
    .   
    .   The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters
    .   and groups the input samples around the clusters. As an output, \f$\texttt{bestLabels}_i\f$ contains a
    .   0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
    .   
    .   @note
    .   -   (Python) An example on K-means clustering can be found at
    .       opencv_source_code/samples/python/kmeans.py
    .   @param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
    .   Examples of this array can be:
    .   -   Mat points(count, 2, CV_32F);
    .   -   Mat points(count, 1, CV_32FC2);
    .   -   Mat points(1, count, CV_32FC2);
    .   -   std::vector\<cv::Point2f\> points(sampleCount);
    .   @param K Number of clusters to split the set by.
    .   @param bestLabels Input/output integer array that stores the cluster indices for every sample.
    .   @param criteria The algorithm termination criteria, that is, the maximum number of iterations and/or
    .   the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster
    .   centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
    .   @param attempts Flag to specify the number of times the algorithm is executed using different
    .   initial labellings. The algorithm returns the labels that yield the best compactness (see the last
    .   function parameter).
    .   @param flags Flag that can take values of cv::KmeansFlags
    .   @param centers Output matrix of the cluster centers, one row per each cluster center.
    .   @return The function returns the compactness measure that is computed as
    .   \f[\sum _i  \| \texttt{samples} _i -  \texttt{centers} _{ \texttt{labels} _i} \| ^2\f]
    .   after every attempt. The best (minimum) value is chosen and the corresponding labels and the
    .   compactness value are returned by the function. Basically, you can use only the core of the
    .   function, set the number of attempts to 1, initialize labels each time using a custom algorithm,
    .   pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best
    .   (most-compact) clustering.
    
    这个是我想查看的文档
'''

## 方法4 ：print(module_name.func_name.__doc__)

print(cv2.kmeans.__doc__)
'''
显示的内容为：
kmeans(data, K, bestLabels, criteria, attempts, flags[, centers]) -> retval, bestLabels, centers
.   @brief Finds centers of clusters and groups input samples around the clusters.
.   
.   The function kmeans implements a k-means algorithm that finds the centers of cluster_count clusters
.   and groups the input samples around the clusters. As an output, \f$\texttt{bestLabels}_i\f$ contains a
.   0-based cluster index for the sample stored in the \f$i^{th}\f$ row of the samples matrix.
.   
.   @note
.   -   (Python) An example on K-means clustering can be found at
.       opencv_source_code/samples/python/kmeans.py
.   @param data Data for clustering. An array of N-Dimensional points with float coordinates is needed.
.   Examples of this array can be:
.   -   Mat points(count, 2, CV_32F);
.   -   Mat points(count, 1, CV_32FC2);
.   -   Mat points(1, count, CV_32FC2);
.   -   std::vector\<cv::Point2f\> points(sampleCount);
.   @param K Number of clusters to split the set by.
.   @param bestLabels Input/output integer array that stores the cluster indices for every sample.
.   @param criteria The algorithm termination criteria, that is, the maximum number of iterations and/or
.   the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster
.   centers moves by less than criteria.epsilon on some iteration, the algorithm stops.
.   @param attempts Flag to specify the number of times the algorithm is executed using different
.   initial labellings. The algorithm returns the labels that yield the best compactness (see the last
.   function parameter).
.   @param flags Flag that can take values of cv::KmeansFlags
.   @param centers Output matrix of the cluster centers, one row per each cluster center.
.   @return The function returns the compactness measure that is computed as
.   \f[\sum _i  \| \texttt{samples} _i -  \texttt{centers} _{ \texttt{labels} _i} \| ^2\f]
.   after every attempt. The best (minimum) value is chosen and the corresponding labels and the
.   compactness value are returned by the function. Basically, you can use only the core of the
.   function, set the number of attempts to 1, initialize labels each time using a custom algorithm,
.   pass them with the ( flags = #KMEANS_USE_INITIAL_LABELS ) flag, and then choose the best
.   (most-compact) clustering.

和help()方法显示的内容一样
'''

总结：

1. 方法3 和方法4打印的内容相同，均为函数的帮助文档。

2. 方法1+print()函数可以查看cv2包中都有什么函数，但不显示帮助文档。

3. 方法2在上述环境中报错，故不显示任何信息。

4. 由于原文档未提及编程环境，猜测方法1与方法2在本环境中失效的原因为编程环境的差异。目前上述方法未在linux系统以及其他IDE中测试。