Add read_geo_info and update docs

deploy/README.md

@@ -21,9 +21,9 @@ from paddlers.deploy import Predictor
 #     model_dir: 模型路径（必须是导出的部署或量化模型）。
 #     use_gpu: 是否使用GPU，默认为False。
 #     gpu_id: 使用GPU的ID，默认为0。
-#     cpu_thread_num：使用cpu进行预测时的线程数，默认为1。
-#     use_mkl: 是否使用mkldnn计算库，CPU情况下使用，默认为False。
-#     mkl_thread_num: mkldnn计算线程数，默认为4。
+#     cpu_thread_num：使用CPU进行预测时的线程数，默认为1。
+#     use_mkl: 是否使用MKL-DNN计算库，CPU情况下使用，默认为False。
+#     mkl_thread_num: MKL-DNN计算线程数，默认为4。
 #     use_trt: 是否使用TensorRT，默认为False。
 #     use_glog: 是否启用glog日志, 默认为False。
 #     memory_optimize: 是否启动内存优化，默认为True。
@@ -34,21 +34,20 @@ from paddlers.deploy import Predictor
 predictor = Predictor("static_models/", use_gpu=True)
 
 # 第二步：调用Predictor的predict()方法执行推理。该方法接受的输入参数如下：
-#     img_file(List[str or tuple or np.ndarray], str, tuple, or np.ndarray):
-#         对于场景分类、图像复原、目标检测和语义分割任务来说，该参数可为单一图像路径，或是解码后的、排列格式为（H, W, C）
-#         且具有float32类型的BGR图像（表示为numpy的ndarray形式），或者是一组图像路径或np.ndarray对象构成的列表；对于变化检测
+#     img_file: 对于场景分类、图像复原、目标检测和图像分割任务来说，该参数可为单一图像路径，或是解码后的、排列格式为（H, W, C）
+#         且具有float32类型的图像数据（表示为numpy的ndarray形式），或者是一组图像路径或np.ndarray对象构成的列表；对于变化检测
 #         任务来说，该参数可以为图像路径二元组（分别表示前后两个时相影像路径），或是两幅图像组成的二元组，或者是上述两种二元组
 #         之一构成的列表。
-#     topk(int): 场景分类模型预测时使用，表示预测前topk的结果。默认值为1。
-#     transforms (paddlers.transforms): 数据预处理操作。默认值为None, 即使用`model.yml`中保存的数据预处理操作。
-#     warmup_iters (int): 预热轮数，用于评估模型推理以及前后处理速度。若大于1，会预先重复预测warmup_iters，而后才开始正式的预测及其速度评估。默认为0。
-#     repeats (int): 重复次数，用于评估模型推理以及前后处理速度。若大于1，会预测repeats次取时间平均值。默认值为1。
+#     topk: 场景分类模型预测时使用，表示选取模型输出概率大小排名前`topk`的类别作为最终结果。默认值为1。
+#     transforms: 对输入数据应用的数据变换算子。若为None，则使用从`model.yml`中读取的算子。默认值为None。
+#     warmup_iters: 预热轮数，用于评估模型推理以及前后处理速度。若大于1，会预先重复执行`warmup_iters`次推理，而后才开始正式的预测及其速度评估。默认值为0。
+#     repeats: 重复次数，用于评估模型推理以及前后处理速度。若大于1，会执行`repeats`次预测并取时间平均值。默认值为1。
 #
 # 下面的语句传入两幅输入影像的路径
 res = predictor.predict(("demo_data/A.png", "demo_data/B.png"))
 
 # 第三步：解析predict()方法返回的结果。
-#     对于语义分割和变化检测任务而言，predict()方法返回的结果为一个字典或字典构成的列表。字典中的`label_map`键对应的值为类别标签图，对于二值变化检测
+#     对于图像分割和变化检测任务而言，predict()方法返回的结果为一个字典或字典构成的列表。字典中的`label_map`键对应的值为类别标签图，对于二值变化检测
 #     任务而言只有0（不变类）或者1（变化类）两种取值；`score_map`键对应的值为类别概率图，对于二值变化检测任务来说一般包含两个通道，第0个通道表示不发生
 #     变化的概率，第1个通道表示发生变化的概率。如果返回的结果是由字典构成的列表，则列表中的第n项与输入的img_file中的第n项对应。
 #

docs/apis/data.md

@@ -2,10 +2,102 @@
 
 ## 数据集
 
-在PaddleRS中，所有数据集均继承自
+在PaddleRS中，所有数据集均继承自父类[`BaseDataset`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/base.py)。
 
-## 数据预处理/数据增强算子
+### `CDDataset`
 
-## 组合数据处理算子
+https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/cd_dataset.py
 
-## `decode_image()`
+### `ClasDataset`
+
+https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/clas_dataset.py
+
+### `COCODetDataset`
+
+https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/coco.py
+
+### `VOCDetDataset`
+
+https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/voc.py
+
+### `SegDataset`
+
+https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/datasets/seg_dataset.py
+
+## 数据读取API
+
+遥感影像的来源多样，数据格式十分繁杂。PaddleRS为不同类型、不同格式的遥感影像提供了统一的读取接口。目前，PaddleRS支持.png、.jpg、.bmp、.npy等常见文件格式的读取，也支持处理遥感领域常用的GeoTiff、img等影像格式。
+
+根据实际需要，用户可以选择`paddlers.transforms.decode_image()`或`paddlers.transforms.DecodeImg`进行数据读取。`DecodeImg`是[数据变换算子](#数据变换算子)之一，可以与其它算子组合使用。`decode_image`是对`DecodeImg`算子的封装，方便用户以函数调用的方式使用。
+
+`decode_image()`函数的参数列表如下：
+
+|参数名称|类型|参数说明|默认值|
+|-------|----|--------|-----|
+|`im_path`|`str`|输入图像路径。||
+|`to_rgb`|`bool`|若为`True`，则执行BGR到RGB格式的转换。|`True`|
+|`to_uint8`|`bool`|若为`True`，则将读取的图像数据量化并转换为uint8类型。|`True`|
+|`decode_bgr`|`bool`|若为`True`，则自动将非地学格式影像（如jpeg影像）解析为BGR格式。|`True`|
+|`decode_sar`|`bool`|若为`True`，则自动将2通道的地学格式影像（如GeoTiff影像）作为SAR影像解析。|`True`|
+|`read_geo_info`|`bool`|若为`True`，则从影像中读取地理信息。|`False`|
+
+返回格式如下：
+
+- 若`read_geo_info`为`False`，则以np.ndarray形式返回读取的影像数据（[h, w, c]排布）；
+- 若`read_geo_info`为`True`，则返回一个二元组，其中第一个元素为读取的影像数据，第二个元素为一个字典，其中的键值对为影像的地理信息，如地理变换信息、地理投影信息等。
+
+## 数据变换算子
+
+在PaddleRS中定义了一系列类，这些类在实例化之后，可通过调用`__call__`方法执行某种特定的数据预处理或数据增强操作。PaddleRS将这些类称为数据预处理/数据增强算子，并统称为**数据变换算子**。所有数据变换算子均继承自父类[`Transform`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/transforms/operators.py)。
+
+### `Transform`
+
+`Transform`对象的`__call__`方法接受唯一的参数`sample`。`sample`必须为字典或字典构成的序列。当`sample`是序列时，为`sample`中的每个字典执行数据变换操作，并将变换结果依次存储在一个Python built-in list中返回；当`sample`是字典时，`Transform`对象根据其中的一些键值对提取输入（这些键称为“输入键”），执行变换后，将结果以键值对的形式写入`sample`中（这些键称为“输出键”）。需要注意的是，目前PaddleRS中许多`Transform`对象都存在复写行为，即，输入键与输出键之间存在交集。`sample`中常见的键名及其表示的含义如下表：
+
+|键名|说明|
+|----|----|
+|`'image'`|影像路径或数据。对于变化检测任务，指第一时相影像数据。|
+|`'image2'`|变化检测任务中第二时相影像数据。|
+|`'image_t1'`|变化检测任务中第一时相影像路径。|
+|`'image_t2'`|变化检测任务中第二时相影像路径。|
+|`'mask'`|图像分割/变化检测任务中的真值标签路径或数据。|
+|`'aux_masks'`|图像分割/变化检测任务中的辅助标签路径或数据。|
+|`'gt_bbox'`|目标检测任务中的检测框标注数据。|
+|`'gt_poly'`|目标检测任务中的多边形标注数据。|
+
+## 组合数据变换算子
+
+使用`paddlers.transforms.Compose`对一组数据变换算子进行组合。`Compose`对象在构造时接受一个列表输入。在调用`Compose`对象时，相当于串行执行列表中的每一个数据变换算子。示例如下：
+
+```python
+# 使用Compose组合多种变换方式。Compose中包含的变换将按顺序串行执行
+train_transforms = T.Compose([
+    # 读取影像
+    T.DecodeImg(),
+    # 将影像缩放到512x512大小
+    T.Resize(target_size=512),
+    # 以50%的概率实施随机水平翻转
+    T.RandomHorizontalFlip(prob=0.5),
+    # 将数据归一化到[-1,1]
+    T.Normalize(
+        mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]),
+    # 挑选并排布后续需要使用的信息
+    T.ArrangeSegmenter('train')
+])
+```
+
+一般来说，`Compose`对象接受的数据变换算子列表中，首个元素为`paddlers.transforms.DecodeImg`对象，用于读取影像数据；最后一个元素为[`Arrange`算子](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/transforms/operators.py)，用于从`sample`字典中抽取信息并排列。
+
+对于图像分割任务和变化检测任务的验证集而言，可在`Arrange`算子之前插入`ReloadMask`算子以重新加载真值标签。示例如下：
+
+```python
+eval_transforms = T.Compose([
+    T.DecodeImg(),
+    T.Resize(target_size=512),
+    T.Normalize(
+        mean=[0.5, 0.5, 0.5], std=[0.5, 0.5, 0.5]),
+    # 重新加载标签
+    T.ReloadMask(),
+    T.ArrangeSegmenter('eval')
+])
+```