add demo for training w/ negative samples

docs/data/format/detection.md

@@ -6,6 +6,7 @@
   * [数据文件夹结构](#11)
   * [训练集、验证集列表和类别标签列表](#12)
 * [数据加载](#2)
+* [添加负样本](#3)
 
 
 ## <h2 id="1">数据格式</h2>
@@ -97,5 +98,44 @@ eval_dataset = pdx.datasets.VOCDetection(
                         file_list='./MyDataset/val_list.txt',
                         label_list='MyDataset/labels.txt',
                         transforms=eval_transforms)
+```
+
+## <h2 id="3">添加负样本</h2>
+
+检测任务支持添加负样本进行训练以降低误检率，代码示例如下：
+
+```python
+import paddlex as pdx
+from paddlex import transforms as T
+
+train_transforms = T.Compose([
+    T.RandomResizeByShort(
+        short_sizes=[640, 672, 704, 736, 768, 800],
+        max_size=1333,
+        interp='CUBIC'),
+    T.RandomHorizontalFlip(),
+    T.Normalize(
+            mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
+])
+
+# 情况一：train_list中已经包含负样本
+train_dataset = pdx.datasets.VOCDetection(
+                        data_dir='./MyDataset',
+                        file_list='./MyDataset/train_list.txt',
+                        label_list='./MyDataset/labels.txt',
+                        transforms=train_transforms,
+                        allow_empty=True,   # 是否加载负样本
+                        empty_ratio=1.)   # 用于指定负样本占总样本数的比例。如果小于0或大于等于1，则保留全部的负样本。默认为1。
+
+# 情况二：train_list中仅包含正样本，负样本在单独的路径下
+train_dataset = pdx.datasets.VOCDetection(
+                        data_dir='./MyDataset',
+                        file_list='./MyDataset/train_list.txt',
+                        label_list='./MyDataset/labels.txt',
+                        transforms=train_transforms)
+train_dataset.add_negative_samples(
+                        image_dir='path/to/negative/images',   # 背景图片所在的文件夹目录。
+                        empty_ratio=1)   # 用于指定负样本占总样本数的比例。如果为None，保留数据集初始化是设置的`empty_ratio`值，
+                                         # 否则更新原有`empty_ratio`值。如果小于0或大于等于1，则保留全部的负样本。默认为1。
 
 ```

docs/data/format/instance_segmentation.md

@@ -6,6 +6,7 @@
   * [数据文件夹结构](#11)
   * [训练集、验证集列表](#12)
 * [数据加载](#2)
+* [添加负样本](#3)
 
 
 ## <h2 id="1">数据格式</h2>
@@ -65,3 +66,42 @@ eval_dataset = pdx.dataset.CocoDetection(
                     ann_file='./MyDataset/val.json',
                     transforms=eval_transforms)
 ```
+
+
+## <h2 id="3">添加负样本</h2>
+
+实例分割任务支持添加负样本进行训练以降低误检率，代码示例如下：
+
+```python
+import paddlex as pdx
+from paddlex import transforms as T
+
+train_transforms = T.Compose([
+    T.RandomResizeByShort(
+        short_sizes=[640, 672, 704, 736, 768, 800],
+        max_size=1333,
+        interp='CUBIC'),
+    T.RandomHorizontalFlip(),
+    T.Normalize(
+            mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
+])
+
+# 情况一：ann_file中已经包含负样本
+train_dataset = pdx.dataset.CocoDetection(
+                    data_dir='./MyDataset/JPEGImages',
+                    ann_file='./MyDataset/train.json',
+                    transforms=train_transforms,
+                    allow_empty=True,   # 是否加载负样本
+                    empty_ratio=1.)   # 用于指定负样本占总样本数的比例。如果小于0或大于等于1，则保留全部的负样本。默认为1。
+
+# 情况二：train_list中仅包含正样本，负样本在单独的路径下
+train_dataset = pdx.dataset.CocoDetection(
+                    data_dir='./MyDataset/JPEGImages',
+                    ann_file='./MyDataset/train.json',
+                    transforms=train_transforms)
+train_dataset.add_negative_samples(
+                        image_dir='path/to/negative/images',   # 背景图片所在的文件夹目录。
+                        empty_ratio=1)   # 用于指定负样本占总样本数的比例。如果为None，保留数据集初始化是设置的`empty_ratio`值，
+                                         # 否则更新原有`empty_ratio`值。如果小于0或大于等于1，则保留全部的负样本。默认为1。
+
+```