diff --git a/deploy/README.md b/deploy/README.md index be9786c..328239d 100644 --- a/deploy/README.md +++ b/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项对应。 # diff --git a/docs/apis/data.md b/docs/apis/data.md index 75bf0ce..d4564d5 100644 --- a/docs/apis/data.md +++ b/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') +]) +``` diff --git a/docs/apis/infer.md b/docs/apis/infer.md index c292dfc..c7f3d1c 100644 --- a/docs/apis/infer.md +++ b/docs/apis/infer.md @@ -1,11 +1,195 @@ # PaddleRS推理API说明 +PaddleRS的动态图推理和静态图推理能力分别由训练器([`BaseModel`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/base.py)及其子类)和**预测器**(`paddlers.deploy.Predictor`)提供。 + ## 动态图推理API ### 整图推理 +#### `BaseChangeDetector.predict()` + +接口形式: + +```python +def predict(self, img_file, transforms=None): +``` + +输入参数: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`list[tuple]` \| `tuple[str\|np.ndarray]`|输入影像对数据(NumPy数组形式)或输入影像对路径。若仅预测一个影像对,使用一个元组顺序包含第一时相影像数据/路径以及第二时相影像数据/路径。若需要一次性预测一组影像对,以列表包含这些影像对的数据或路径(每个影像对对应列表中的一个元组)。|| +|`transforms`|`paddlers.transforms.Compose` \| `None`|对输入数据应用的数据变换算子。若为`None`,则使用训练器在验证阶段使用的数据变换算子。|`None`| + +返回格式: + +若`img_file`是一个元组,则返回对象为包含下列键值对的字典: + +``` +{"label map": 输出类别标签(以[h, w]格式排布),"score_map": 模型输出的各类别概率(以[h, w, c]格式排布)} +``` + +若`img_file`是一个列表,则返回对象为与`img_file`等长的列表,其中的每一项为一个字典(键值对如上所示),顺序对应`img_file`中的每个元素。 + +#### `BaseClassifier.predict()` + +接口形式: + +```python +def predict(self, img_file, transforms=None): +``` + +输入参数: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`list[str\|np.ndarray]` \| `str` \| `np.ndarray`|输入影像数据(NumPy数组形式)或输入影像路径。若需要一次性预测一组影像,以列表包含这些影像的数据或路径(每幅影像对应列表中的一个元素)。|| +|`transforms`|`paddlers.transforms.Compose` \| `None`|对输入数据应用的数据变换算子。若为`None`,则使用训练器在验证阶段使用的数据变换算子。|`None`| + +返回格式: + +若`img_file`是一个字符串或NumPy数组,则返回对象为包含下列键值对的字典: + +``` +{"label map": 输出类别标签, + "scores_map": 输出类别概率, + "label_names_map": 输出类别名称} +``` + +若`img_file`是一个列表,则返回对象为与`img_file`等长的列表,其中的每一项为一个字典(键值对如上所示),顺序对应`img_file`中的每个元素。 + +#### `BaseDetector.predict()` + +接口形式: + +```python +def predict(self, img_file, transforms=None): +``` + +输入参数: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`list[str\|np.ndarray]` \| `str` \| `np.ndarray`|输入影像数据(NumPy数组形式)或输入影像路径。若需要一次性预测一组影像,以列表包含这些影像的数据或路径(每幅影像对应列表中的一个元素)。|| +|`transforms`|`paddlers.transforms.Compose` \| `None`|对输入数据应用的数据变换算子。若为`None`,则使用训练器在验证阶段使用的数据变换算子。|`None`| + +返回格式: + +若`img_file`是一个字符串或NumPy数组,则返回对象为一个列表,列表中每个元素对应一个预测的目标框。列表中的元素为包含下列键值对的字典: + +``` +{"category_id": 类别ID, + "category": 类别名称, + "bbox": 目标框位置信息,依次包含目标框左上角的横、纵坐标以及目标框的宽度和长度, + "score": 类别置信度, + "mask": [RLE格式](https://baike.baidu.com/item/rle/366352)的掩模图(mask),仅实例分割模型预测结果包含此键值对} +``` + +若`img_file`是一个列表,则返回对象为与`img_file`等长的列表,其中的每一项为一个由字典(键值对如上所示)构成的列表,顺序对应`img_file`中的每个元素。 + +#### `BaseSegmenter.predict()` + +接口形式: + +```python +def predict(self, img_file, transforms=None): +``` + +输入参数: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`list[str\|np.ndarray]` \| `str` \| `np.ndarray`|输入影像数据(NumPy数组形式)或输入影像路径。若需要一次性预测一组影像,以列表包含这些影像的数据或路径(每幅影像对应列表中的一个元素)。|| +|`transforms`|`paddlers.transforms.Compose` \| `None`|对输入数据应用的数据变换算子。若为`None`,则使用训练器在验证阶段使用的数据变换算子。|`None`| + +返回格式: + +若`img_file`是一个字符串或NumPy数组,则返回对象为包含下列键值对的字典: + +``` +{"label map": 输出类别标签(以[h, w]格式排布),"score_map": 模型输出的各类别概率(以[h, w, c]格式排布)} +``` + +若`img_file`是一个列表,则返回对象为与`img_file`等长的列表,其中的每一项为一个字典(键值对如上所示),顺序对应`img_file`中的每个元素。 + ### 滑窗推理 +考虑到遥感影像的大幅面性质,PaddleRS为部分任务提供了滑窗推理支持。PaddleRS的滑窗推理功能具有如下特色: + +1. 为了解决一次读入整张大图直接导致内存不足的问题,PaddleRS采用延迟载入内存的技术,一次仅读取并处理一个窗口内的影像块。 +2. 用户可自定义滑窗的大小和步长。支持滑窗重叠,对于窗口之间重叠的部分,PaddleRS将自动对模型预测结果进行融合。 +3. 支持将推理结果保存为GeoTiff格式,支持对地理变换信息、地理投影信息的读取与写入。 + +目前,图像分割训练器([`BaseSegmenter`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/segmenter.py)及其子类)与变化检测训练器([`BaseChangeDetector`](https://github.com/PaddlePaddle/PaddleRS/blob/develop/paddlers/tasks/change_detector.py)及其子类)具有动态图滑窗推理API,以图像分割任务的API为例,说明如下: + +接口形式: + +```python +def slider_predict(self, + img_file, + save_dir, + block_size, + overlap=36, + transforms=None): +``` + +输入参数列表: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`str`|输入影像路径。|| +|`save_dir`|`str`|预测结果输出路径。|| +|`block_size`|`list[int]` \| `tuple[int]` \| `int`|滑窗的窗口大小(以列表或元组指定长、宽或以一个整数指定相同的长宽)。|| +|`overlap`|`list[int]` \| `tuple[int]` \| `int`|滑窗的滑动步长(以列表或元组指定长、宽或以一个整数指定相同的长宽)。|`36`| +|`transforms`|`paddlers.transforms.Compose` \| `None`|对输入数据应用的数据变换算子。若为`None`,则使用训练器在验证阶段使用的数据变换算子。|`None`| + +变化检测任务的滑窗推理API与图像分割任务类似,但需要注意的是输出结果中存储的地理变换、投影等信息以从第一时相影像中读取的信息为准。 + ## 静态图推理API ### Python API + +[将模型导出为部署格式](https://github.com/PaddlePaddle/PaddleRS/blob/develop/deploy/export/README.md)或执行模型量化后,PaddleRS提供`paddlers.deploy.Predictor`用于加载部署或量化格式模型以及执行基于[Paddle Inference](https://www.paddlepaddle.org.cn/tutorials/projectdetail/3952715)的推理。 + +#### 初始化`Predictor`对象 + +`Predictor.__init__()`接受如下参数: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`model_dir`|`str`|模型路径(必须是导出的部署或量化模型)。|| +|`use_gpu`|`bool`|是否使用GPU。|`False`| +|`gpu_id`|`int`|使用GPU的ID。|`0`| +|`cpu_thread_num`|`int`|使用CPU执行推理时的线程数。|`1`| +|`use_mkl`|`bool`|是否使用MKL-DNN计算库(此选项仅在使用CPU执行推理时生效)。|`False`| +|`mkl_thread_num`|`int`|MKL-DNN计算线程数。|`4`| +|`use_trt`|`bool`|是否使用TensorRT。|`False`| +|`use_glog`|`bool`|是否启用glog日志。|`False`| +|`memory_optimize`|`bool`|是否启用内存优化。|`True`| +|`max_trt_batch_size`|`int`|在使用TensorRT时配置的最大batch size。|`1`| +|`trt_precision_mode`|`str`|在使用TensorRT时采用的精度,可选值为`'float32'`或`'float16'`。|`'float32'`| + +#### `Predictor.predict()` + +接口形式: + +```python +def predict(self, + img_file, + topk=1, + transforms=None, + warmup_iters=0, + repeats=1): +``` + +输入参数列表: + +|参数名称|类型|参数说明|默认值| +|-------|----|--------|-----| +|`img_file`|`list[str\|tuple\|np.ndarray]` \| `str` \| `tuple` \| `np.ndarray`|对于场景分类、目标检测和图像分割任务来说,该参数可为单一图像路径,或是解码后的、排列格式为[h, w, c]且具有float32类型的图像数据(表示为NumPy数组形式),或者是一组图像路径或np.ndarray对象构成的列表;对于变化检测任务来说,该参数可以为图像路径二元组(分别表示前后两个时相影像路径),或是解码后的两幅图像组成的二元组,或者是上述两种二元组之一构成的列表。|| +|`topk`|`int`|场景分类模型预测时使用,表示选取模型输出概率大小排名前`topk`的类别作为最终结果。|`1`| +|`transforms`|`paddlers.transforms.Compose`\|`None`|对输入数据应用的数据变换算子。若为`None`,则使用从`model.yml`中读取的算子。|`None`| +|`warmup_iters`|`int`|预热轮数,用于评估模型推理以及前后处理速度。若大于1,将预先重复执行`warmup_iters`次推理,而后才开始正式的预测及其速度评估。|`0`| +|`repeats`|`int`|重复次数,用于评估模型推理以及前后处理速度。若大于1,将执行`repeats`次预测并取时间平均值。|`1`| + +`Predictor.predict()`的返回格式与相应的动态图推理API的返回格式完全相同,详情请参考[动态图推理API](#动态图推理api)。 diff --git a/docs/apis/train.md b/docs/apis/train.md index 0bf2df5..97f55b1 100644 --- a/docs/apis/train.md +++ b/docs/apis/train.md @@ -33,6 +33,8 @@ ### `BaseChangeDetector.train()` +接口形式: + ```python def train(self, num_epochs, @@ -74,6 +76,8 @@ def train(self, ### `BaseClassifier.train()` +接口形式: + ```python def train(self, num_epochs, @@ -115,6 +119,8 @@ def train(self, ### `BaseDetector.train()` +接口形式: + ```python def train(self, num_epochs, @@ -166,6 +172,8 @@ def train(self, ### `BaseSegmenter.train()` +接口形式: + ```python def train(self, num_epochs, @@ -209,6 +217,8 @@ def train(self, ### `BaseChangeDetector.evaluate()` +接口形式: + ```python def evaluate(self, eval_dataset, batch_size=1, return_details=False): ``` @@ -224,27 +234,29 @@ def evaluate(self, eval_dataset, batch_size=1, return_details=False): 当`return_details`为`False`(默认行为)时,输出为一个`collections.OrderedDict`对象。对于二类变化检测任务,输出包含如下键值对: ``` -{"iou": 变化类的IoU指标, -"f1": 变化类的F1分数, -"oacc": 总体精度(准确率), -"kappa": kappa系数} +{"iou": 变化类的IoU指标, + "f1": 变化类的F1分数, + "oacc": 总体精度(准确率), + "kappa": kappa系数} ``` 对于多类变化检测任务,输出包含如下键值对: ``` -{"miou": mIoU指标, -"category_iou": 各类的IoU指标, -"oacc": 总体精度(准确率), -"category_acc": 各类精确率, -"kappa": kappa系数, -"category_F1score": 各类F1分数} +{"miou": mIoU指标, + "category_iou": 各类的IoU指标, + "oacc": 总体精度(准确率), + "category_acc": 各类精确率, + "kappa": kappa系数, + "category_F1score": 各类F1分数} ``` 当`return_details`为`True`时,返回一个由两个字典构成的二元组,其中第一个元素为上述评价指标,第二个元素为仅包含一个key的字典,其`'confusion_matrix'`键对应值为以Python built-in list存储的混淆矩阵。 ### `BaseClassifier.evaluate()` +接口形式: + ```python def evaluate(self, eval_dataset, batch_size=1, return_details=False): ``` @@ -260,12 +272,14 @@ def evaluate(self, eval_dataset, batch_size=1, return_details=False): 输出为一个`collections.OrderedDict`对象,包含如下键值对: ``` -{"top1": top1准确率, -"top5": `top5准确率} +{"top1": top1准确率, + "top5": `top5准确率} ``` ### `BaseDetector.evaluate()` +接口形式: + ```python def evaluate(self, eval_dataset, @@ -292,13 +306,15 @@ def evaluate(self, 当`return_details`为`True`时,返回一个由两个字典构成的二元组,其中第一个字典为上述评价指标,第二个字典包含如下3个键值对: ``` -{"gt": 数据集标注信息, -"bbox": 预测得到的目标框信息, -"mask": 预测得到的掩模图信息} +{"gt": 数据集标注信息, + "bbox": 预测得到的目标框信息, + "mask": 预测得到的掩模图信息} ``` ### `BaseSegmenter.evaluate()` +接口形式: + ```python def evaluate(self, eval_dataset, batch_size=1, return_details=False): ``` @@ -314,12 +330,12 @@ def evaluate(self, eval_dataset, batch_size=1, return_details=False): 当`return_details`为`False`(默认行为)时,输出为一个`collections.OrderedDict`对象,包含如下键值对: ``` -{"miou": mIoU指标, -"category_iou": 各类的IoU指标, -"oacc": 总体精度(准确率), -"category_acc": 各类精确率, -"kappa": kappa系数, -"category_F1score": 各类F1分数} +{"miou": mIoU指标, + "category_iou": 各类的IoU指标, + "oacc": 总体精度(准确率), + "category_acc": 各类精确率, + "kappa": kappa系数, + "category_F1score": 各类F1分数} ``` 当`return_details`为`True`时,返回一个由两个字典构成的二元组,其中第一个元素为上述评价指标,第二个元素为仅包含一个key的字典,其`'confusion_matrix'`键对应值为以Python built-in list存储的混淆矩阵。 diff --git a/docs/intro/transforms.md b/docs/intro/transforms.md index be0d508..6144704 100644 --- a/docs/intro/transforms.md +++ b/docs/intro/transforms.md @@ -1,37 +1,33 @@ # 数据预处理/数据增强 -## 读取各种格式的遥感影像 +## PaddleRS已支持的数据变换算子列表 -遥感影像的来源多样,数据格式十分繁杂。PaddleRS为不同类型、不同格式的遥感影像提供了统一的读取接口,只需向`paddlers.transforms.decode_image()`函数传入影像路径,即可将其中的数据信息读取至内存。目前,`paddlers.transforms.decode_image()`支持.png、.jpg、.bmp、.npy等常见文件格式,也支持遥感领域常用的GeoTiff、img等影像格式。 +PaddleRS对不同遥感任务需要的数据预处理/数据增强(合称为数据变换)策略进行了有机整合,设计统一的算子。考虑到遥感影像的多波段特性,PaddleRS的大部分数据处理算子均能够处理任意数量波段的输入。PaddleRS目前提供的所有数据变换算子如下表: -## PaddleRS已支持的数据预处理/数据增强算子列表 - -PaddleRS对不同遥感任务需要的数据预处理/数据增强策略进行了有机整合,设计统一的算子。考虑到遥感影像的多波段特性,PaddleRS的大部分数据处理算子均能够处理任意数量波段的输入。PaddleRS目前提供的所有数据预处理/数据增强算子如下表: - -| 数据预处理/数据增强算子名 | 用途 | 任务 | ... | +| 数据变换算子名 | 用途 | 任务 | ... | | -------------------- | ------------------------------------------------- | -------- | ---- | -| Resize | 调整输入影像大小 | 所有任务 | ... | -| RandomResize | 随机调整输入影像大小 | 所有任务 | ... | -| ResizeByShort | 调整输入影像大小,保持纵横比不变(根据短边计算缩放系数) | 所有任务 | ... | -| RandomResizeByShort | 随机调整输入影像大小,保持纵横比不变(根据短边计算缩放系数) | 所有任务 | ... | -| ResizeByLong | 调整输入影像大小,保持纵横比不变(根据长边计算缩放系数) | 所有任务 | ... | -| RandomHorizontalFlip | 随机水平翻转输入影像 | 所有任务 | ... | -| RandomVerticalFlip | 随机竖直翻转输入影像 | 所有任务 | ... | -| Normalize | 对输入影像应用标准化 | 所有任务 | ... | -| CenterCrop | 对输入影像进行中心裁剪 | 所有任务 | ... | -| RandomCrop | 对输入影像进行随机中心裁剪 | 所有任务 | ... | -| RandomScaleAspect | 裁剪输入影像并重新缩放到原始尺寸 | 所有任务 | ... | -| RandomExpand | 根据随机偏移扩展输入影像 | 所有任务 | ... | -| Pad | 将输入影像填充到指定的大小 | 所有任务 | ... | -| MixupImage | 将两幅影像(及对应的目标检测标注)混合在一起作为新的样本 | 目标检测 | ... | -| RandomDistort | 对输入施加随机色彩变换 | 所有任务 | ... | -| RandomBlur | 对输入施加随机模糊 | 所有任务 | ... | -| Dehaze | 对输入图像进行去雾 | 所有任务 | ... | -| ReduceDim | 对输入图像进行波段降维 | 所有任务 | ... | -| SelectBand | 对输入影像进行波段选择 | 所有任务 | ... | -| RandomSwap | 随机交换两个时相的输入影像 | 变化检测 | ... | +| Resize | 调整输入影像大小。 | 所有任务 | ... | +| RandomResize | 随机调整输入影像大小。 | 所有任务 | ... | +| ResizeByShort | 调整输入影像大小,保持纵横比不变(根据短边计算缩放系数)。 | 所有任务 | ... | +| RandomResizeByShort | 随机调整输入影像大小,保持纵横比不变(根据短边计算缩放系数)。 | 所有任务 | ... | +| ResizeByLong | 调整输入影像大小,保持纵横比不变(根据长边计算缩放系数)。 | 所有任务 | ... | +| RandomHorizontalFlip | 随机水平翻转输入影像。 | 所有任务 | ... | +| RandomVerticalFlip | 随机竖直翻转输入影像。 | 所有任务 | ... | +| Normalize | 对输入影像应用标准化。 | 所有任务 | ... | +| CenterCrop | 对输入影像进行中心裁剪。 | 所有任务 | ... | +| RandomCrop | 对输入影像进行随机中心裁剪。 | 所有任务 | ... | +| RandomScaleAspect | 裁剪输入影像并重新缩放到原始尺寸。 | 所有任务 | ... | +| RandomExpand | 根据随机偏移扩展输入影像。 | 所有任务 | ... | +| Pad | 将输入影像填充到指定的大小。 | 所有任务 | ... | +| MixupImage | 将两幅影像(及对应的目标检测标注)混合在一起作为新的样本。 | 目标检测 | ... | +| RandomDistort | 对输入施加随机色彩变换。 | 所有任务 | ... | +| RandomBlur | 对输入施加随机模糊。 | 所有任务 | ... | +| Dehaze | 对输入图像进行去雾。 | 所有任务 | ... | +| ReduceDim | 对输入图像进行波段降维。 | 所有任务 | ... | +| SelectBand | 对输入影像进行波段选择。 | 所有任务 | ... | +| RandomSwap | 随机交换两个时相的输入影像。 | 变化检测 | ... | | ... | ... | ... | ... | ## 组合算子 -在实际的模型训练过程中,常常需要组合多种数据预处理与数据增强策略。PaddleRS提供了`paddlers.transforms.Compose`类以便捷地组合多个数据预处理/数据增强算子,使这些算子能够串行执行。关于`paddlers.transforms.Compose`的具体用法请参见[API说明](https://github.com/PaddlePaddle/PaddleRS/blob/develop/docs/apis/data.md)。 +在实际的模型训练过程中,常常需要组合多种数据预处理与数据增强策略。PaddleRS提供了`paddlers.transforms.Compose`以便捷地组合多个数据变换算子,使这些算子能够串行执行。关于`paddlers.transforms.Compose`的具体用法请参见[API说明](https://github.com/PaddlePaddle/PaddleRS/blob/develop/docs/apis/data.md)。 diff --git a/paddlers/tasks/classifier.py b/paddlers/tasks/classifier.py index 8ba6ea8..c626115 100644 --- a/paddlers/tasks/classifier.py +++ b/paddlers/tasks/classifier.py @@ -438,7 +438,9 @@ class BaseClassifier(BaseModel): Returns: If `img_file` is a string or np.array, the result is a dict with key-value pairs: - {"label map": `class_ids_map`, "scores_map": `label_names_map`}. + {"label map": `class_ids_map`, + "scores_map": `scores_map`, + "label_names_map": `label_names_map`}. If `img_file` is a list, the result is a list composed of dicts with the corresponding fields: class_ids_map (np.ndarray): class_ids diff --git a/paddlers/tasks/object_detector.py b/paddlers/tasks/object_detector.py index dd43e31..48c6d64 100644 --- a/paddlers/tasks/object_detector.py +++ b/paddlers/tasks/object_detector.py @@ -559,9 +559,13 @@ class BaseDetector(BaseModel): Returns: If `img_file` is a string or np.array, the result is a list of dict with key-value pairs: - {"category_id": `category_id`, "category": `category`, "bbox": `[x, y, w, h]`, "score": `score`}. - If `img_file` is a list, the result is a list composed of dicts with the - corresponding fields: + {"category_id": `category_id`, + "category": `category`, + "bbox": `[x, y, w, h]`, + "score": `score`, + "mask": `mask`}. + If `img_file` is a list, the result is a list composed of list of dicts + with the corresponding fields: category_id(int): the predicted category ID. 0 represents the first category in the dataset, and so on. category(str): category name diff --git a/paddlers/transforms/__init__.py b/paddlers/transforms/__init__.py index 03b253e..aafc4dd 100644 --- a/paddlers/transforms/__init__.py +++ b/paddlers/transforms/__init__.py @@ -24,11 +24,13 @@ def decode_image(im_path, to_rgb=True, to_uint8=True, decode_bgr=True, - decode_sar=True): + decode_sar=True, + read_geo_info=False): """ Decode an image. Args: + im_path (str): Path of the image to decode. to_rgb (bool, optional): If True, convert input image(s) from BGR format to RGB format. Defaults to True. to_uint8 (bool, optional): If True, quantize and convert decoded image(s) to @@ -38,9 +40,14 @@ def decode_image(im_path, decode_sar (bool, optional): If True, automatically interpret a two-channel geo image (e.g. geotiff images) as a SAR image, set this argument to True. Defaults to True. + read_geo_info (bool, optional): If True, read geographical information from + the image. Deafults to False. Returns: - np.ndarray: Decoded image. + np.ndarray|tuple: If `read_geo_info` is False, return the decoded image. + Otherwise, return a tuple that contains the decoded image and a dictionary + of geographical information (e.g. geographical transform and geographical + projection). """ # Do a presence check. osp.exists() assumes `im_path` is a path-like object. @@ -50,11 +57,15 @@ def decode_image(im_path, to_rgb=to_rgb, to_uint8=to_uint8, decode_bgr=decode_bgr, - decode_sar=decode_sar) + decode_sar=decode_sar, + read_geo_info=read_geo_info) # Deepcopy to avoid inplace modification sample = {'image': copy.deepcopy(im_path)} sample = decoder(sample) - return sample['image'] + if read_geo_info: + return sample['image'], sample['geo_info_dict'] + else: + return sample['image'] def build_transforms(transforms_info): diff --git a/paddlers/transforms/operators.py b/paddlers/transforms/operators.py index 7204f27..ea65c2e 100644 --- a/paddlers/transforms/operators.py +++ b/paddlers/transforms/operators.py @@ -180,22 +180,28 @@ class DecodeImg(Transform): decode_sar (bool, optional): If True, automatically interpret a two-channel geo image (e.g. geotiff images) as a SAR image, set this argument to True. Defaults to True. + read_geo_info (bool, optional): If True, read geographical information from + the image. Deafults to False. """ def __init__(self, to_rgb=True, to_uint8=True, decode_bgr=True, - decode_sar=True): + decode_sar=True, + read_geo_info=False): super(DecodeImg, self).__init__() self.to_rgb = to_rgb self.to_uint8 = to_uint8 self.decode_bgr = decode_bgr self.decode_sar = decode_sar + self.read_geo_info = False def read_img(self, img_path): img_format = imghdr.what(img_path) name, ext = os.path.splitext(img_path) + geo_trans, geo_proj = None, None + if img_format == 'tiff' or ext == '.img': try: import gdal @@ -209,7 +215,7 @@ class DecodeImg(Transform): dataset = gdal.Open(img_path) if dataset == None: - raise IOError('Can not open', img_path) + raise IOError('Cannot open', img_path) im_data = dataset.ReadAsArray() if im_data.ndim == 2 and self.decode_sar: im_data = to_intensity(im_data) # is read SAR @@ -217,26 +223,38 @@ class DecodeImg(Transform): else: if im_data.ndim == 3: im_data = im_data.transpose((1, 2, 0)) - return im_data + if self.read_geo_info: + geo_trans = dataset.GetGeoTransform() + geo_proj = dataset.GetGeoProjection() elif img_format in ['jpeg', 'bmp', 'png', 'jpg']: if self.decode_bgr: - return cv2.imread(img_path, cv2.IMREAD_ANYDEPTH | - cv2.IMREAD_ANYCOLOR | cv2.IMREAD_COLOR) + im_data = cv2.imread(img_path, cv2.IMREAD_ANYDEPTH | + cv2.IMREAD_ANYCOLOR | cv2.IMREAD_COLOR) else: - return cv2.imread(img_path, cv2.IMREAD_ANYDEPTH | - cv2.IMREAD_ANYCOLOR) + im_data = cv2.imread(img_path, cv2.IMREAD_ANYDEPTH | + cv2.IMREAD_ANYCOLOR) elif ext == '.npy': - return np.load(img_path) + im_data = np.load(img_path) else: raise TypeError("Image format {} is not supported!".format(ext)) + if self.read_geo_info: + return im_data, geo_trans, geo_proj + else: + return im_data + def apply_im(self, im_path): if isinstance(im_path, str): try: - image = self.read_img(im_path) + data = self.read_img(im_path) except: raise ValueError("Cannot read the image file {}!".format( im_path)) + if self.read_geo_info: + image, geo_trans, geo_proj = data + geo_info_dict = {'geo_trans': geo_trans, 'geo_proj': geo_proj} + else: + image = data else: image = im_path @@ -246,7 +264,10 @@ class DecodeImg(Transform): if self.to_uint8: image = to_uint8(image) - return image + if self.read_geo_info: + return image, geo_info_dict + else: + return image def apply_mask(self, mask): try: @@ -269,15 +290,37 @@ class DecodeImg(Transform): """ if 'image' in sample: - sample['image_ori'] = copy.deepcopy(sample['image']) - sample['image'] = self.apply_im(sample['image']) + if self.read_geo_info: + image, geo_info_dict = self.apply_im(sample['image']) + sample['image'] = image + sample['geo_info_dict'] = geo_info_dict + else: + sample['image'] = self.apply_im(sample['image']) + if 'image2' in sample: - sample['image2'] = self.apply_im(sample['image2']) + if self.read_geo_info: + image2, geo_info_dict2 = self.apply_im(sample['image2']) + sample['image2'] = image2 + sample['geo_info_dict2'] = geo_info_dict2 + else: + sample['image2'] = self.apply_im(sample['image2']) + if 'image_t1' in sample and not 'image' in sample: if not ('image_t2' in sample and 'image2' not in sample): raise ValueError - sample['image'] = self.apply_im(sample['image_t1']) - sample['image2'] = self.apply_im(sample['image_t2']) + if self.read_geo_info: + image, geo_info_dict = self.apply_im(sample['image_t1']) + sample['image'] = image + sample['geo_info_dict'] = geo_info_dict + else: + sample['image'] = self.apply_im(sample['image_t1']) + if self.read_geo_info: + image2, geo_info_dict2 = self.apply_im(sample['image_t2']) + sample['image2'] = image2 + sample['geo_info_dict2'] = geo_info_dict2 + else: + sample['image2'] = self.apply_im(sample['image_t2']) + if 'mask' in sample: sample['mask_ori'] = copy.deepcopy(sample['mask']) sample['mask'] = self.apply_mask(sample['mask']) @@ -286,6 +329,7 @@ class DecodeImg(Transform): if im_height != se_height or im_width != se_width: raise ValueError( "The height or width of the image is not same as the mask.") + if 'aux_masks' in sample: sample['aux_masks_ori'] = copy.deepcopy(sample['aux_masks']) sample['aux_masks'] = list( @@ -295,6 +339,7 @@ class DecodeImg(Transform): sample['im_shape'] = np.array( sample['image'].shape[:2], dtype=np.float32) sample['scale_factor'] = np.array([1., 1.], dtype=np.float32) + return sample