add anchor clustering

docs/apis/datasets.md

@@ -4,7 +4,9 @@
 
 * [ImageNet](#1)
 * [VOCDetection](#2)
+  * [cluster_yolo_anchor](#21)
 * [CocoDetection](#3)
+  * [cluster_yolo_anchor](#31)
 * [SegDataset](#4)
 
 ## <h2 id="1">paddlex.datasets.ImageNet</h2>
@@ -25,7 +27,7 @@ paddlex.datasets.ImageNet(data_dir, file_list, label_list, transforms=None, num_
 > > * **num_workers** (int|str)：数据集中样本在预处理过程中的进程数。默认为'auto'。当设为'auto'时，根据系统的实际CPU核数设置`num_workers`: 如果CPU核数的一半大于8，则`num_workers`为8，否则为CPU核数的一半。  
 > > * **shuffle** (bool): 是否需要对数据集中样本打乱顺序。默认为False。  
 
-## <h2 id="1">paddlex.datasets.VOCDetection</h2>
+## <h2 id="2">paddlex.datasets.VOCDetection</h2>
 > **用于目标检测模型**  
 ```python
 paddlex.datasets.VOCDetection(data_dir, file_list, label_list, transforms=None, num_workers='auto', shuffle=False)
@@ -44,7 +46,30 @@ paddlex.datasets.VOCDetection(data_dir, file_list, label_list, transforms=None,
 > > * **num_workers** (int|str)：数据集中样本在预处理过程中的进程数。默认为'auto'。当设为'auto'时，根据系统的实际CPU核数设置`num_workers`: 如果CPU核数的一半大于8，则`num_workers`为8，否则为CPU核数的一半。
 > > * **shuffle** (bool): 是否需要对数据集中样本打乱顺序。默认为False。
 
-## <h2 id="1">paddlex.datasets.CocoDetection</h2>
+### <h3 id="21">cluster_yolo_anchor</h3>
+
+```python
+cluster_yolo_anchor(num_anchors, image_size, cache=True, cache_path=None, iters=300, gen_iters=1000, thresh=.25)
+```
+
+> 分析数据集中所有图像的标签，聚类生成YOLO系列检测模型指定格式的anchor，返回结果按照由小到大排列。
+
+> **注解**
+>
+> 自定义YOLO系列模型的`anchor`需要同时指定`anchor_masks`参数。`anchor_masks`参数为一个二维的列表，其长度等于模型backbone获取到的特征图数量（对于PPYOLO的MobileNetV3和ResNet18_vd，特征图数量为2，其余情况为3）。列表中的每一个元素也为列表，代表对应特征图上所检测的anchor编号。
+> 以PPYOLO网络的默认参数`anchors=[[10, 13], [16, 30], [33, 23], [30, 61], [62, 45], [59, 119], [116, 90], [156, 198], [373, 326]]`，`anchor_masks=[[6, 7, 8], [3, 4, 5], [0, 1, 2]]`为例，代表在第一个特征图上检测尺度为`[116, 90], [156, 198], [373, 326]`的目标，在第二个特征图上检测尺度为`[30, 61], [62, 45], [59, 119]`的目标，以此类推。
+
+> **参数**
+>
+> > * **num_anchors** (int): 生成anchor的数量。PPYOLO，当backbone网络为MobileNetV3或ResNet18_vd时通常设置为6，其余情况通常设置为9。对于PPYOLOv2、PPYOLOTiny、YOLOv3，通常设置为9。
+> > * **image_size** (List[int] or int)：训练时网络输入的尺寸。如果为list，长度须为2，分别代表高和宽；如果为int，代表输入尺寸高和宽相同。
+> > * **cache** (bool): 是否使用缓存。聚类生成anchor需要遍历数据集统计所有真值框的尺寸以及所有图片的尺寸，较为耗时。如果为True，会将真值框尺寸信息以及图片尺寸信息保存至`cache_path`路径下，若路径下已存缓存文件，则加载该缓存。如果为False，则不会保存或加载。默认为True。
+> > * **cache_path** (None or str)：真值框尺寸信息以及图片尺寸信息缓存路径。 如果为None，则使用数据集所在的路径`data_dir`。默认为None。
+> > * **iters** (int)：K-Means聚类算法迭代次数。
+> > * **gen_iters** (int)：基因演算法迭代次数。
+> > * **thresh** (float)：anchor尺寸与真值框尺寸之间比例的阈值。
+
+## <h2 id="3">paddlex.datasets.CocoDetection</h2>
 > **用于实例分割/目标检测模型**  
 ```python
 paddlex.datasets.CocoDetection(data_dir, ann_file, transforms=None, num_workers='auto', shuffle=False)
@@ -62,7 +87,30 @@ paddlex.datasets.CocoDetection(data_dir, ann_file, transforms=None, num_workers=
 > > * **num_workers** (int|str)：数据集中样本在预处理过程中的线程或进程数。默认为'auto'。当设为'auto'时，根据系统的实际CPU核数设置`num_workers`: 如果CPU核数的一半大于8，则`num_workers`为8，否则为CPU核数的一半。  
 > > * **shuffle** (bool): 是否需要对数据集中样本打乱顺序。默认为False。
 
-## <h2 id="1">paddlex.datasets.SegDataset</h2>
+### <h3 id="31">cluster_yolo_anchor</h3>
+
+```python
+cluster_yolo_anchor(num_anchors, image_size, cache=True, cache_path=None, iters=300, gen_iters=1000, thresh=.25)
+```
+
+> 分析数据集中所有图像的标签，聚类生成YOLO系列检测模型指定格式的anchor，返回结果按照由小到大排列。
+
+> **注解**
+>
+> 自定义YOLO系列模型的`anchor`需要同时指定`anchor_masks`参数。`anchor_masks`参数为一个二维的列表，其长度等于模型backbone获取到的特征图数量（对于PPYOLO的MobileNetV3和ResNet18_vd，特征图数量为2，其余情况为3）。列表中的每一个元素也为列表，代表对应特征图上所检测的anchor编号。
+> 以PPYOLO网络的默认参数`anchors=[[10, 13], [16, 30], [33, 23], [30, 61], [62, 45], [59, 119], [116, 90], [156, 198], [373, 326]]`，`anchor_masks=[[6, 7, 8], [3, 4, 5], [0, 1, 2]]`为例，代表在第一个特征图上检测尺度为`[116, 90], [156, 198], [373, 326]`的目标，在第二个特征图上检测尺度为`[30, 61], [62, 45], [59, 119]`的目标，以此类推。
+
+> **参数**
+>
+> > * **num_anchors** (int): 生成anchor的数量。PPYOLO，当backbone网络为MobileNetV3或ResNet18_vd时通常设置为6，其余情况通常设置为9。对于PPYOLOv2、PPYOLOTiny、YOLOv3，通常设置为9。
+> > * **image_size** (List[int] or int)：训练时网络输入的尺寸。如果为list，长度须为2，分别代表高和宽；如果为int，代表输入尺寸高和宽相同。
+> > * **cache** (bool): 是否使用缓存。聚类生成anchor需要遍历数据集统计所有真值框的尺寸以及所有图片的尺寸，较为耗时。如果为True，会将真值框尺寸信息以及图片尺寸信息保存至`cache_path`路径下，若路径下已存缓存文件，则加载该缓存。如果为False，则不会保存或加载。默认为True。
+> > * **cache_path** (None or str)：真值框尺寸信息以及图片尺寸信息缓存路径。 如果为None，则使用数据集所在的路径`data_dir`。默认为None。
+> > * **iters** (int)：K-Means聚类算法迭代次数。
+> > * **gen_iters** (int)：基因演算法迭代次数。
+> > * **thresh** (float)：anchor尺寸与真值框尺寸之间比例的阈值。
+
+## <h2 id="4">paddlex.datasets.SegDataset</h2>
 > **用于语义分割模型**  
 ```python
 paddlex.datasets.SegDataset(data_dir, file_list, label_list=None, transforms=None, num_workers='auto', shuffle=False)