Update docs

docs/data/tools.md

@@ -2,13 +2,14 @@
 
 PaddleRS在`tools`目录中提供了丰富的遥感影像处理工具，包括：
 
-- `coco2mask.py`：用于将COCO格式的标注文件转换为png格式。
+- `coco2mask.py`：用于将COCO格式的标注文件转换为.png格式。
 - `mask2shape.py`：用于将模型推理输出的.png格式栅格标签转换为矢量格式。
 - `mask2geojson.py`：用于将模型推理输出的.png格式栅格标签转换为GeoJSON格式。
 - `match.py`：用于实现两幅影像的配准。
 - `split.py`：用于对大幅面影像数据进行切片。
 - `coco_tools/`：COCO工具合集，用于统计处理COCO格式标注文件。
 - `prepare_dataset/`：数据集预处理脚本合集。
+- `extract_ms_patches.py`：从整幅遥感影像中提取多尺度影像块。
 
 ## 使用说明
 
@@ -20,7 +21,7 @@ cd tools
 
 ### coco2mask
 
-`coco2mask.py`的主要功能是将图像以及对应的COCO格式的分割标签转换为图像与.png格式的标签，结果会分别存放在`img`和`gt`两个目录中。相关的数据样例可以参考[中国典型城市建筑物实例数据集](https://www.scidb.cn/detail?dataSetId=806674532768153600&dataSetType=journal)。对于mask，保存结果为单通道的伪彩色图像。使用方式如下：
+`coco2mask.py`的主要功能是将影像以及对应的COCO格式的分割标签转换为影像与.png格式的标签，结果会分别存放在`img`和`gt`两个目录中。相关的数据样例可以参考[中国典型城市建筑物实例数据集](https://www.scidb.cn/detail?dataSetId=806674532768153600&dataSetType=journal)。对于mask，保存结果为单通道的伪彩色影像。使用方式如下：
 
 ```shell
 python coco2mask.py --raw_dir {输入目录路径} --save_dir {输出目录路径}
@@ -28,8 +29,8 @@ python coco2mask.py --raw_dir {输入目录路径} --save_dir {输出目录路
 
 其中：
 
-- `raw_dir`：存放原始数据的目录，其中图像存放在`images`子目录中，标签以`xxx.json`格式保存。
-- `save_dir`：保存输出结果的目录，其中图像保存在`img`子目录中，.png格式的标签保存在`gt`子目录中。
+- `raw_dir`：存放原始数据的目录，其中影像存放在`images`子目录中，标签以`xxx.json`格式保存。
+- `save_dir`：保存输出结果的目录，其中影像保存在`img`子目录中，.png格式的标签保存在`gt`子目录中。
 
 ### mask2shape
 
@@ -41,10 +42,10 @@ python mask2shape.py --srcimg_path {带有地理信息的原始影像路径} --m
 
 其中：
 
-- `srcimg_path`：原始影像路径，需要带有地理坐标信息，以便为生成的shapefile提供crs等信息。
+- `srcimg_path`：原始影像路径，需要带有地理元信息，以便为生成的shapefile提供地理投影坐标系等信息。
 - `mask_path`：模型推理得到的.png格式的分割结果。
 - `save_path`：保存shapefile的路径，默认为`output`。
-- `ignore_index`：需要在shapefile中忽略的索引值（例如分割任务中的背景类），默认为255。
+- `ignore_index`：需要在shapefile中忽略的索引值（例如分割任务中的背景类），默认为`255`。
 
 ### mask2geojson
 
@@ -69,37 +70,37 @@ python match.py --im1_path [时相1影像路径] --im2_path [时相2影像路径
 
 其中：
 
-- `im1_path`：时相1影像路径。该影像必须包含地理信息，且配准过程中以该影像为基准图像。
+- `im1_path`：时相1影像路径。该影像必须包含地理信息，且配准过程中以该影像为基准影像。
 - `im2_path`：时相2影像路径。该影像的地理信息将不被用到。配准过程中将该影像配准到时相1影像。
 - `im1_bands`：时相1影像用于配准的波段，指定为三通道（分别代表R、G、B）或单通道，默认为[1, 2, 3]。
 - `im2_bands`：时相2影像用于配准的波段，指定为三通道（分别代表R、G、B）或单通道，默认为[1, 2, 3]。
-- `save_path`: 配准后时相2影像输出路径。
+- `save_path`： 配准后时相2影像输出路径。
 
 ### split
 
-`split.py`的主要功能是将大幅面遥感图像划分为图像块，这些图像块可以作为训练时的输入。使用方式如下：
+`split.py`的主要功能是将大幅面遥感影像划分为影像块，这些影像块可以作为训练时的输入。使用方式如下：
 
 ```shell
-python split.py --image_path {输入影像路径} [--mask_path {真值标签路径}] [--block_size {图像块尺寸}] [--save_dir {输出目录}]
+python split.py --image_path {输入影像路径} [--mask_path {真值标签路径}] [--block_size {影像块尺寸}] [--save_dir {输出目录}]
 ```
 
 其中：
 
-- `image_path`：需要切分的图像的路径。
-- `mask_path`：一同切分的标签图像路径，默认没有。
-- `block_size`：切分图像块大小，默认为512。
-- `save_folder`：保存切分后结果的文件夹路径，默认为`output`。
+- `image_path`：需要切分的影像的路径。
+- `mask_path`：一同切分的标签影像路径，默认为`None`。
+- `block_size`：切分影像块大小，默认为512。
+- `save_dir`：保存切分后结果的文件夹路径，默认为`output`。
 
 ### coco_tools
 
 目前`coco_tools`目录中共包含6个工具，各工具功能如下：
 
-- `json_InfoShow.py`:    打印json文件中各个字典的基本信息；
-- `json_ImgSta.py`:      统计json文件中的图像信息，生成统计表、统计图；
-- `json_AnnoSta.py`:     统计json文件中的标注信息，生成统计表、统计图；
-- `json_Img2Json.py`:    统计test集图像，生成json文件；
-- `json_Split.py`:       将json文件中的内容划分为train set和val set；
-- `json_Merge.py`:       将多个json文件合并为一个。
+- `json_InfoShow.py`：    打印json文件中各个字典的基本信息；
+- `json_ImgSta.py`：      统计json文件中的影像信息，生成统计表、统计图；
+- `json_AnnoSta.py`：     统计json文件中的标注信息，生成统计表、统计图；
+- `json_Img2Json.py`：    统计test集影像，生成json文件；
+- `json_Split.py`：       将json文件中的内容划分为train set和val set；
+- `json_Merge.py`：       将多个json文件合并为一个。
 
 详细使用方法请参见[coco_tools使用说明](coco_tools.md)。
 
@@ -123,3 +124,26 @@ python prepare_dataset/prepare_levircd.py --help
 - `--ratios`：对于支持子集随机划分的数据集，指定需要划分的各个子集的样本比例。示例：`--ratios 0.7 0.2 0.1`。
 
 您可以在[此文档](https://github.com/PaddlePaddle/PaddleRS/blob/develop/docs/intro/data_prep.md)中查看PaddleRS提供哪些数据集的预处理脚本。
+
+### extract_ms_patches
+
+`extract_ms_patches.py`的主要功能是利用四叉树从整幅遥感影像中提取不同尺度的包含感兴趣目标的影像块，提取的影像块可用作模型训练样本。使用方式如下：
+
+```shell
+python extract_ms_patches.py --image_paths {一个或多个输入影像路径} --mask_path {真值标签路径} [--save_dir {输出目录}] [--min_patch_size {最小的影像块尺寸}] [--bg_class {背景类类别编号}] [--target_class {目标类类别编号}] [--max_level {检索的最大尺度层级}] [--include_bg] [--nonzero_ratio {影像块中非零像素占比阈值}] [--visualize]
+```
+
+其中：
+
+- `image_paths`：源影像路径，可以指定多个路径。
+- `mask_path`：真值标签路径。
+- `save_dir`：保存切分后结果的文件夹路径，默认为`output`。
+- `min_patch_size`：提取的影像块的最小尺寸（以影像块长/宽的像素个数计），即四叉树的叶子结点在图中覆盖的最小范围，默认为`256`。
+- `bg_class`：背景类别的类别编号，默认为`0`。
+- `target_class`：目标类别的类别编号，若为`None`，则表示所有背景类别以外的类别均为目标类别，默认为`None`。
+- `max_level`：检索的最大尺度层级，若为`None`，则表示不限制层级，默认为`None`。
+- `include_bg`：若指定此选项，则也保存那些仅包含背景类别、不包含目标类别的影像块。
+- `--nonzero_ratio`：指定一个阈值，对于任意一幅源影像，若影像块中非零像素占比小于此阈值，则该影像块将被舍弃。若为`None`，则表示不进行过滤。默认为`None`。
+- `--visualize`：若指定此选项，则程序执行完毕后将生成图像`./vis_quadtree.png`，其中保存有四叉树中节点情况的可视化结果，一个例子如下图所示：
+
+[vis_quadtree_example](https://user-images.githubusercontent.com/21275753/189264850-f94b3d7b-c631-47b1-9833-0800de2ccf54.png)

tools/extract_ms_patches.py

@@ -284,7 +284,7 @@ if __name__ == '__main__':
                         help="Path of images. Different images must have unique file names.")
     parser.add_argument("--mask_path", type=str, required=True, \
                         help="Path of mask.")
-    parser.add_argument("--save_dir", type=str, required=True, \
+    parser.add_argument("--save_dir", type=str, default='output', \
                         help="Path to save the extracted patches.")
     parser.add_argument("--min_patch_size", type=int, default=256, \
                         help="Minimum patch size (height and width).")