From 8903d70683799d78c1fe8cd4c4b7011ee91c5e31 Mon Sep 17 00:00:00 2001 From: Bai Yifan Date: Wed, 25 Sep 2019 12:56:57 +0800 Subject: [PATCH] Refine some api cn_doc (#1247) * Refine fsp_matrix/deformable_conv/fsp_matrix/polygon_box_transform api. --- .../api_cn/layers_cn/deformable_conv_cn.rst | 72 ++++++++++--------- doc/fluid/api_cn/layers_cn/flatten_cn.rst | 18 ++--- doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst | 21 +++--- .../layers_cn/polygon_box_transform_cn.rst | 13 ++-- 4 files changed, 64 insertions(+), 60 deletions(-) diff --git a/doc/fluid/api_cn/layers_cn/deformable_conv_cn.rst b/doc/fluid/api_cn/layers_cn/deformable_conv_cn.rst index e0a8907f8..fcf1185e9 100644 --- a/doc/fluid/api_cn/layers_cn/deformable_conv_cn.rst +++ b/doc/fluid/api_cn/layers_cn/deformable_conv_cn.rst @@ -5,9 +5,10 @@ deformable_conv .. py:function:: paddle.fluid.layers.deformable_conv(input, offset, mask, num_filters, filter_size, stride=1, padding=0, dilation=1, groups=None, deformable_groups=None, im2col_step=None, param_attr=None, bias_attr=None, modulated=True, name=None) -可变形卷积层 +**可变形卷积算子** + +deformable_conv op对输入4-D Tensor计算2-D可变形卷积。给定输入Tensor x，输出Tensor y，可变形卷积运算如下所示： -在4-D输入上计算2-D可变形卷积。给定输入图像x，输出特征图y，可变形卷积操作如下所示： 可形变卷积v2: :math:`y(p) = \sum_{k=1}^{K}{w_k * x(p + p_k + \Delta p_k) * \Delta m_k}` @@ -16,19 +17,20 @@ deformable_conv :math:`y(p) = \sum_{k=1}^{K}{w_k * x(p + p_k + \Delta p_k)}` -其中 :math:`\Delta p_k 和 \Delta m_k` 分别为第k个位置的可学习偏移和调制标量。其中在可形变卷积中:math:`\Delta m_k`为1. -参考可变形卷积网络v2: `可变形程度越高，结果越好 `_ 和 `形变卷积`_。 +其中 :math:`\Delta p_k` 和 :math:`\Delta m_k` 分别为第k个位置的可学习偏移和调制标量。在deformable_conv_v1中 :math:`\Delta m_k` 为1. + +具体细节可以参考论文：`<> `_ 和 `<> `_ 。 **示例** 输入： - 输入形状： :math:`(N, C_{in}, H_{in}, W_{in})` + input 形状： :math:`(N, C_{in}, H_{in}, W_{in})` 卷积核形状： :math:`(C_{out}, C_{in}, H_f, W_f)` - 偏移形状： :math:`(N, 2 * deformable\_groups * H_f * H_w, H_{in}, W_{in})` + offset 形状： :math:`(N, 2 * deformable\_groups * H_f * H_w, H_{in}, W_{in})` - 掩膜形状： :math:`(N, deformable\_groups * H_f * H_w, H_{in}, W_{in})` + mask 形状： :math:`(N, deformable\_groups * H_f * H_w, H_{in}, W_{in})` 输出： 输出形状： :math:`(N, C_{out}, H_{out}, W_{out})` @@ -43,48 +45,52 @@ deformable_conv 参数： - - **input** (Variable) - 形式为[N, C, H, W]的输入图像。 - - **offset** (Variable) – 可变形卷积层的输入坐标偏移。 - - **Mask** (Variable) – 可变形卷积层的输入掩膜。 - - **num_filters** (int) – 卷积核数。和输出图像通道数相同。 - - **filter_size** (int|tuple|None) – 卷积核大小。如果filter_size为元组，则必须包含两个整数(filter_size_H, filter_size_W)。否则卷积核将为方形。 - - **stride** (int|tuple) – 步长大小。如果stride为元组，则必须包含两个整数(stride_H, stride_W)。否则stride_H = stride_W = stride。默认stride = 1。 - - **padding** (int|tuple) – padding大小。如果padding为元组，则必须包含两个整数(padding_H, padding_W)。否则padding_H = padding_W = padding。默认padding = 0。 - - **dilation** (int|tuple) – dilation大小。如果dilation为元组，则必须包含两个整数(dilation_H, dilation_W)。否则dilation_H = dilation_W = dilation。默认dilation = 1。 - - **groups** (int) – 可变形卷积层的群组数。依据Alex Krizhevsky的Deep CNN论文中的分组卷积，有：当group=2时，前一半卷积核只和前一半输入通道有关，而后一半卷积核只和后一半输入通道有关。默认groups=1。 - - **deformable_groups** (int) – 可变形群组分区数。默认deformable_groups = 1。 - - **im2col_step** (int) – 每个im2col计算的最大图像数。总batch大小应该可以被该值整除或小于该值。如果您面临内存问题，可以尝试在此处使用一个更小的值。默认im2col_step = 64。 - - **param_attr** (ParamAttr|None) – 可变形卷积的可学习参数/权重的参数属性。如果将其设置为None或ParamAttr的一个属性，可变形卷积将创建ParamAttr作为param_attr。如果没有设置此param_attr的Initializer，该参数将被Normal(0.0, std)初始化，且其中的std为 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}`。默认值None。 - - **bias_attr** (ParamAttr|bool|None) – 可变形卷积层的偏置的参数属性。如果设为False，则输出单元不会加偏置。如果设为None或者ParamAttr的一个属性，conv2d会创建ParamAttr作为bias_attr。如果不设置bias_attr的Initializer，偏置会被初始化为0。默认值None。 - - **modulated** （bool）- 确定使用v1和v2中的哪个版本，如果为True，则选择使用v2。默认为True。 - - **name** (str|None) – 该层的名字（可选项）。如果设为None，该层将会被自动命名。默认值None。 + - **input** (Variable) - 形状为 :math:`[N, C, H, W]` 的输入Tensor，数据类型为float32或float64。 + - **offset** (Variable) – 可变形卷积层的输入坐标偏移，数据类型为float32或float64。 + - **mask** (Variable, 可选) – 可变形卷积层的输入掩码，当使用可变形卷积算子v2时，请将mask设置为None, 数据类型为float32或float64。 + - **num_filters** (int) – 卷积核数，与输出Tensor通道数相同。 + - **filter_size** (int|tuple) – 卷积核大小。如果filter_size为元组，则必须包含两个整数(filter_size_H, filter_size_W)。若数据类型为int，卷积核形状为(filter_size, filter_size)。 + - **stride** (int|tuple) – 步长大小。如果stride为元组，则必须包含两个整数(stride_H, stride_W)。否则stride_H = stride_W = stride。缺省值为1。 + - **padding** (int|tuple) – padding大小。如果padding为元组，则必须包含两个整数(padding_H, padding_W)。否则padding_H = padding_W = padding。缺省值为0。 + - **dilation** (int|tuple) – dilation大小。如果dilation为元组，则必须包含两个整数(dilation_H, dilation_W)。否则dilation_H = dilation_W = dilation。缺省值为1。 + - **groups** (int) – 卷积组数。依据Alex Krizhevsky的Deep CNN论文中的分组卷积，有：当group=2时，前一半卷积核只和前一半输入通道有关，而后一半卷积核只和后一半输入通道有关。缺省值为1。 + - **deformable_groups** (int) – 可变形卷积组数。缺省值为1。 + - **im2col_step** (int) – 每个im2col计算的最大图像数。总batch大小应可以被该值整除或小于该值。如果您面临内存问题，可以尝试在此处使用一个较小的值。缺省值为64。 + - **param_attr** (ParamAttr，可选) – 可变形卷积的可学习权重的属性。如果将其设置为None或某种ParamAttr，可变形卷积将创建ParamAttr作为param_attr。如果没有设置此param_attr的Initializer，该参数将被Normal(0.0, std)初始化，且其中的std为 :math:`(\frac{2.0 }{filter\_elem\_num})^{0.5}` 。缺省值为None。 + - **bias_attr** (ParamAttr|bool，可选) – 可变形卷积层的偏置的参数属性。如果设为False，则输出单元不会加偏置。如果设为None或者某种ParamAttr，conv2d会创建ParamAttr作为bias_attr。如果不设置bias_attr的Initializer，偏置会被初始化为0。缺省值为None。 + - **modulated** （bool）- 确定使用v1和v2中的哪个版本，如果为True，则选择使用v2。缺省值为True。 + - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 -返回：储存可变形卷积结果的张量变量。 +返回：可变形卷积输出的4-D Tensor，数据类型为float32或float64。 -返回类型：变量(Variable) +返回类型：Variable -抛出：ValueError – 如果input, filter_size, stride, padding和groups的大小不匹配。 +抛出异常：ValueError – 如果input, filter_size, stride, padding和groups的大小不匹配。 **代码示例** .. code-block:: python #deformable conv v2: - + import paddle.fluid as fluid - data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') - offset = fluid.layers.data(name='offset', shape=[18, 32, 32], dtype='float32') - mask = fluid.layers.data(name='mask', shape=[9, 32, 32], dtype='float32') + C_in, H_in, W_in = 3, 32, 32 + filter_size, deformable_groups = 3, 1 + data = fluid.layers.data(name='data', shape=[C_in, H_in, W_in], dtype='float32') + offset = fluid.layers.data(name='offset', shape=[2*deformable_groups*filter_size**2, H_in, W_in], dtype='float32') + mask = fluid.layers.data(name='mask', shape=[deformable_groups*filter_size**2, H_in, W_in], dtype='float32') out = fluid.layers.deformable_conv(input=data, offset=offset, mask=mask, - num_filters=2, filter_size=3, padding=1, modulated=True) + num_filters=2, filter_size=filter_size, padding=1, modulated=True) #deformable conv v1: import paddle.fluid as fluid - data = fluid.layers.data(name='data', shape=[3, 32, 32], dtype='float32') - offset = fluid.layers.data(name='offset', shape=[18, 32, 32], dtype='float32') + C_in, H_in, W_in = 3, 32, 32 + filter_size, deformable_groups = 3, 1 + data = fluid.layers.data(name='data', shape=[C_in, H_in, W_in], dtype='float32') + offset = fluid.layers.data(name='offset', shape=[2*deformable_groups*filter_size**2, H_in, W_in], dtype='float32') out = fluid.layers.deformable_conv(input=data, offset=offset, mask=None, - num_filters=2, filter_size=3, padding=1, modulated=False) + num_filters=2, filter_size=filter_size, padding=1, modulated=False) diff --git a/doc/fluid/api_cn/layers_cn/flatten_cn.rst b/doc/fluid/api_cn/layers_cn/flatten_cn.rst index 5debe7c32..906c84f05 100644 --- a/doc/fluid/api_cn/layers_cn/flatten_cn.rst +++ b/doc/fluid/api_cn/layers_cn/flatten_cn.rst @@ -5,7 +5,7 @@ flatten .. py:function:: paddle.fluid.layers.flatten(x, axis=1, name=None) -将输入张量压扁成二维矩阵 +flatten op将输入的多维Tensor展平成2-D Tensor矩阵 例如： @@ -30,25 +30,27 @@ flatten Out.shape = (1, 3 * 100 * 100 * 4) 参数： - - **x** (Variable) - 一个秩>=axis 的张量 - - **axis** (int) - flatten的划分轴，[0, axis) 轴数据被flatten到输出矩阵的0轴，[axis, R)被flatten到输出矩阵的1轴，其中R是输入张量的秩。axis的值必须在[0,R]范围内。当 axis= 0 时，输出张量的形状为 (1，d_0 \* d_1 \*… d_n) ，其输入张量的形状为(d_0, d_1，… d_n)。 - - **name** (str|None) - 此层的名称(可选)。如果没有设置，层将自动命名。 + - **x** (Variable) - 一个维度数>=axis 的多维Tensor, 数据类型可以为float32，float64，int8，int32或int64。 + - **axis** (int) - flatten展开的分割轴，[0, axis) 轴数据被flatten到输出矩阵的0轴，[axis, R)数据被flatten到输出矩阵的1轴，其中R是输入张量的总维度数。axis的值必须在[0,R]范围内。当 axis=0 时，若输入Tensor的维度为 :math:`[d_0, d_1，… d_n]` ，则输出张量的Tensor维度为 :math:`[1，d_0 * d_1 *… d_n]` ，缺省值为1。 + - **name** (str，可选) - 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 -返回: 一个二维张量，它包含输入张量的内容，但维数发生变化。输入的[0, axis)维将沿给定轴flatten到输出的前一个维度，剩余的输入维数flatten到输出的后一个维度。 +返回: 一个 2-D Tensor，它包含输入Tensor的数据，但维度发生变化。输入的[0, axis)维将沿axis展平到输出Tensor的0维度，剩余的输入维数展平到输出的1维度。数据类型与输入x相同。 返回类型: Variable 抛出异常： - - ValueError: 如果 x 不是一个变量 - - ValueError: 如果axis的范围不在 [0, rank(x)] + - ValueError: 如果 x 不是一个Variable + - ValueError: 如果axis的范围不在 [0, rank(x)] 范围内 **代码示例** .. code-block:: python import paddle.fluid as fluid - x = fluid.layers.data(name="x", shape=[4, 4, 3], dtype="float32") + x = fluid.layers.data(name="x", shape=[4, 4, 3], append_batch_size=False, dtype="float32") + # x shape is [4, 4, 3] out = fluid.layers.flatten(x=x, axis=2) + # out shape is [16, 3] diff --git a/doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst b/doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst index cdbb65cb7..64b31e830 100644 --- a/doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst +++ b/doc/fluid/api_cn/layers_cn/fsp_matrix_cn.rst @@ -7,21 +7,21 @@ fsp_matrix **FSP matrix op** -此运算用于计算两个特征映射的求解过程（FSP）矩阵。给定形状为[x_channel，h，w]的特征映射x和形状为[y_channel，h，w]的特征映射y，我们可以分两步得到x和y的fsp矩阵： +fsp_matrix op用于计算两个4-D Tensor特征图的求解过程（FSP）矩阵。假设特征图x的形状为 :math:`[x\_channel，h，w]` ，特征图y的形状为 :math:`[y\_channel，h，w]` ，fsp_matrix op分两步得到x和y的fsp矩阵： -1.用形状[X_channel，H*W]将X重塑为矩阵，并用形状[H*W，y_channel]将Y重塑和转置为矩阵。 +1.将x reshape到形状为 :math:`[x\_channel，h*w]` 的矩阵，将y reshape到形状为 :math:`[h*w，y\_channel]` 的矩阵。 -2.乘以x和y得到形状为[x_channel，y_channel]的fsp矩阵。 +2.对x和y做矩阵乘法得到形状为 :math:`[x\_channel，y\_channel]` 的fsp矩阵。 -输出是一批fsp矩阵。 +输出是一个batch的fsp矩阵。 参数： - - **x** (Variable): 一个形状为[batch_size, x_channel, height, width]的特征映射 - - **y** (Variable)：具有形状[batch_size, y_channel, height, width]的特征映射。Y轴通道可以与输入（X）的X轴通道不同，而其他尺寸必须与输入（X）相同。 + - **x** (Variable): 一个形状为 :math:`[batch\_size, x\_channel, height, width]` 的 4-D 特征图Tensor, 数据类型为float32或float64。 + - **y** (Variable)：一个形状为 :math:`[batch\_size, y\_channel, height, width]` 的 4-D 特征图Tensor, 数据类型为float32或float64。y_channel可以与输入（x）的x_channel不同，而其他维度必须与输入（x）相同。 -返回：形状为[batch_size, x_channel, y_channel]的fsp op的输出。x_channel 是x的通道，y_channel是y的通道。 +返回：一个形状为 :math:`[batch\_size, x\_channel, y\_channel]` 的fsp矩阵, 是一个 3-D Tensor，数据类型与输入数据类型一致。其中，x_channel是输入x的通道数，y_channel是输入y的通道数。数据类型为float32或float64。 -返回类型：fsp matrix (Variable) +返回类型：Variable **代码示例** @@ -35,8 +35,3 @@ fsp_matrix filter_size=1) loss = fluid.layers.fsp_matrix(feature_map_0, feature_map_1) - - - - - diff --git a/doc/fluid/api_cn/layers_cn/polygon_box_transform_cn.rst b/doc/fluid/api_cn/layers_cn/polygon_box_transform_cn.rst index 414d25cce..e729bcb6b 100644 --- a/doc/fluid/api_cn/layers_cn/polygon_box_transform_cn.rst +++ b/doc/fluid/api_cn/layers_cn/polygon_box_transform_cn.rst @@ -5,18 +5,19 @@ polygon_box_transform .. py:function:: paddle.fluid.layers.polygon_box_transform(input, name=None) -PolygonBoxTransform 算子。 +**PolygonBoxTransform 算子** -该算子用于将偏移坐标转变为真正的坐标。 +该op用于将偏移坐标改变为真实的坐标。 -输入是检测网络的最终几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数字 :math:`(x_i, y_i)` ，所以何输出包含 2*n 个通道。 +输入4-D Tensor是检测网络最终的几何输出。我们使用 2*n 个数来表示从 polygon_box 中的 n 个顶点(vertice)到像素位置的偏移。由于每个距离偏移包含两个数 :math:`(x_i, y_i)` ，所以几何输出通道数为 2*n。 参数： - - **input** （Variable） - shape 为[batch_size，geometry_channels，height，width]的张量 + - **input** （Variable） - 形状为 :math:`[batch\_size，geometry\_channels，height，width]` 的4-D Tensor，数据类型为float32或float64。 + - **name** (str，可选) – 该参数供开发人员打印调试信息时使用，具体用法请参见 :ref:`api_guide_Name` ，缺省值为None。 -返回：与输入 shape 相同 +返回：polygon_box_transform输出的真实坐标，是一个 4-D Tensor。数据类型为float32或float64。 -返回类型：output（Variable） +返回类型：Variable **代码示例** -- GitLab