From 47d3b5cd9daf5f09fe7e21d266b53b434ea983ad Mon Sep 17 00:00:00 2001 From: qingqing01 Date: Fri, 27 Sep 2019 16:15:33 +0800 Subject: [PATCH] Polish CN doc for some APIs. (#1434) * Polish cn doc for some APIs * Small fix * Add data type --- .../api_cn/layers_cn/detection_output_cn.rst | 34 +++--- .../layers_cn/generate_mask_labels_cn.rst | 28 ++--- .../api_cn/layers_cn/multi_box_head_cn.rst | 106 ++++++++++++------ doc/fluid/api_cn/layers_cn/random_crop_cn.rst | 20 +++- .../api_cn/layers_cn/target_assign_cn.rst | 28 ++--- 5 files changed, 128 insertions(+), 88 deletions(-) diff --git a/doc/fluid/api_cn/layers_cn/detection_output_cn.rst b/doc/fluid/api_cn/layers_cn/detection_output_cn.rst index 1b3e7691d..5bda1b79b 100644 --- a/doc/fluid/api_cn/layers_cn/detection_output_cn.rst +++ b/doc/fluid/api_cn/layers_cn/detection_output_cn.rst @@ -5,32 +5,30 @@ detection_output .. py:function:: paddle.fluid.layers.detection_output(loc, scores, prior_box, prior_box_var, background_label=0, nms_threshold=0.3, nms_top_k=400, keep_top_k=200, score_threshold=0.01, nms_eta=1.0) -Detection Output Layer for Single Shot Multibox Detector(SSD) +给定回归位置偏移、置信度以及先验框信息计算检测的输出，执行步骤如下： -该操作符用于获得检测结果，执行步骤如下： + 1.根据先验框(``prior_box``)信息和回归位置偏移解码出预测框坐标。 - 1.根据prior box框解码输入边界框（bounding box）预测 + 2.通过多类非极大值抑制(NMS)获得最终检测输出。 - 2.通过运用多类非极大值抑制(NMS)获得最终检测结果 - -请注意，该操作符不将最终输出边界框剪切至图像窗口。 +请注意，该操作符没有将最终输出边界框clip至图像大小。 参数： - - **loc** (Variable) - 一个三维张量（Tensor），维度为[N,M,4]，代表M个bounding bboxes的预测位置。N是批尺寸，每个边界框（boungding box）有四个坐标值，布局为[xmin,ymin,xmax,ymax] - - **scores** (Variable) - 一个三维张量（Tensor），维度为[N,M,C]，代表预测置信预测。N是批尺寸，C是类别数，M是边界框数。对每类一共M个分数，对应M个边界框 - - **prior_box** (Variable) - 一个二维张量（Tensor),维度为[M,4]，存储M个框，每个框代表[xmin,ymin,xmax,ymax]，[xmin,ymin]是anchor box的左上坐标，如果输入是图像特征图，靠近坐标系统的原点。[xmax,ymax]是anchor box的右下坐标 - - **prior_box_var** (Variable) - 一个二维张量（Tensor），维度为[M,4]，存有M变量群 - - **background_label** (float) - 背景标签索引，背景标签将会忽略。若设为-1，将考虑所有类别 - - **nms_threshold** (int) - 用于NMS的临界值（threshold） - - **nms_top_k** (int) - 基于score_threshold过滤检测后，根据置信数维持的最大检测数 - - **keep_top_k** (int) - NMS步后，每一图像要维持的总bbox数 - - **score_threshold** (float) - 临界函数（Threshold），用来过滤带有低置信数的边界框（bounding box）。若未提供，则考虑所有框 - - **nms_eta** (float) - 适应NMS的参数 + - **loc** (Variable) - 3-D Tensor，数据类型为float32或float64，表示回归位置偏移。维度为[N,M,4]，M是输入的预测bounding box的个数，N是batch size，每个bounding box有四个坐标值，格式为[xmin,ymin,xmax,ymax]，[xmin,ymin]是左上角坐标，[xmax,ymax]是右下角坐标。 + - **scores** (Variable) - 3-D Tensor，数据类型为float32或float64，表示未归一化的置信度。维度为[N,M,C]，N和M的含义同上，C是类别数。 + - **prior_box** (Variable) - 2-D Tensor，表示先验框。维度为[M,4]，M是提取的先验框个数，格式为[xmin,ymin,xmax,ymax]。 + - **prior_box_var** (Variable) - 2-D Tensor，表示先验框的方差，和 ``prior_box`` 维度相同。 + - **background_label** (int) - 背景标签类别值，背景标签类别上不做NMS。若设为-1，将考虑所有类别。默认值是0。 + - **nms_threshold** (float) - 用于NMS的阈值（threshold），默认值是0.3。 + - **nms_top_k** (int) - 基于score_threshold过滤预测框后，NMS操作前，要挑选出的置信度高的预测框的个数。默认值是400。 + - **keep_top_k** (int) - NMS操作后，要挑选的bounding box总数。默认值是200。 + - **score_threshold** (float) - 置信度得分阈值（Threshold），在NMS之前用来过滤低置信数的边界框（bounding box）。若未提供，则考虑所有框。默认值是0.001。 + - **nms_eta** (float) - 一种adaptive NMS的参数，仅当该值小于1.0时才起作用。默认值是1.0。 返回： - 输出一个LoDTensor，形为[No,6]。每行有6个值：[label,confidence,xmin,ymin,xmax,ymax]。No是该mini-batch的总检测数。对每个实例，第一维偏移称为LoD，偏移数为N+1，N是batch size。第i个图像有LoD[i+1]-LoD[i]检测结果。如果为0，第i个图像无检测结果。如果所有图像都没有检测结果，LoD会被设置为{1}，并且输出张量只包含一个值-1。（1.3版本后对于没有检测结果的boxes, LoD的值由之前的{0}调整为{1}） + 输出是2-D LoDTensor，形状为[No,6]。每行有6个值：[label,confidence,xmin,ymin,xmax,ymax]。No是该mini-batch总的检测框数。LoD的层级数为1，如果采用偏移的LoD表示，则第i个图像有 ``LoD[i+1] - LoD[i]`` 个检测结果，如果等于0，则表示无检测结果。 -返回类型：变量（Variable） +返回类型：Variable **代码示例**： diff --git a/doc/fluid/api_cn/layers_cn/generate_mask_labels_cn.rst b/doc/fluid/api_cn/layers_cn/generate_mask_labels_cn.rst index 77c88d277..8df46a913 100644 --- a/doc/fluid/api_cn/layers_cn/generate_mask_labels_cn.rst +++ b/doc/fluid/api_cn/layers_cn/generate_mask_labels_cn.rst @@ -7,9 +7,9 @@ generate_mask_labels **为Mask-RCNN生成mask标签** -对于给定的 RoI (Regions of Interest) 和相应的标签，该算子可以对前景RoI进行采样。 该mask branch对每个前景RoI还具有 :math:`K*M^{2}` 维输出目标，用于编码分辨率为M×M的K个二进制mask，K个种类中的各种类分别对应一个这样的二进制mask。 此mask输出目标用于计算掩码分支的损失。 +对于给定的 RoI (Regions of Interest) 和 输入ground truth的分类标签和分割的坐标标签，采样出前景RoI，并返回其在输入 ``rois`` 中索引位置，并对每个RoI生成 :math:`K*M^{2}` 的二值mask标签。K为类别个数，M是RoI特征图大小。这些输出目标一般用于计算mask分支的损失。 -请注意groud-truth（真实值，下简称GT）分段的数据格式。假设分段如下， 第一个实例有两个GT对象。 第二个实例有一个GT对象，该对象有两个GT分段。 +请注意分割groud-truth（真实标签，下简称GT)数据格式，这里要求分割标签为坐标信息，假如，第一个实例有两个GT对象。 第二个实例有一个GT对象，该GT分割标签是两段(例如物体中间被隔开)，输入标签格式组织如下: :: @@ -37,21 +37,21 @@ generate_mask_labels 参数： - - **im_info** (Variable) – 具有形状[N，3]的2-D张量。 N是批量大小，其每个元素是图像的[高度，宽度，比例]，对应第二维中的3。图像比例是 :math:`\frac{target\_size}{original\_size}` 。 - - **gt_classes** (Variable) – 形为[M，1]的2-D LoDTensor。 M是真实值的总数，其每个元素都是一个类标签，对应第二维中的1。 - - **is_crowd** (Variable) – 一个形为 ``gt_classes`` 的2-D LoDTensor，每个元素都是一个标志，指示一个groundtruth是否为crowd（群）。 - - **gt_segms** (Variable) – 这个输入是一个形状为[S，2]的2D LoDTensor，它的LoD级别为3。通常用户不需要理解LoD，但用户应该在Reader中返回正确的数据格式。LoD [0]表示每个实例中GT对象的数目。 LoD [1]表示每个对象的分段数。 LoD [2]表示每个分段的多边形(polygon)数。S为多边形坐标点的总数。每个元素是（x，y）坐标点。 - - **rois** (Variable) – 形为[R，4]的2-D LoDTensor。 R是RoI的总数，其中每个元素是在原始图像范围内具有（xmin，ymin，xmax，ymax）格式的边界框(bounding box)。 - - **labels_int32** (Variable) – 形为[R，1]且类型为int32的2-D LoDTensor。 R与rois中的R含义相同。每个元素都反映了RoI的一个类标签。 - - **num_classes** (int) – 种类数目 - - **resolution** (int) – mask预测的分辨率 + - **im_info** (Variable) – 维度为[N，3]的2-D Tensor，数据类型为float32。 N是batch size，其每个元素是图像的高度、宽度、比例，比例是图片预处理时resize之后的大小和原始大小的比例 :math:`\frac{target\_size}{original\_size}` 。 + - **gt_classes** (Variable) – 维度为[M，1]的2-D LoDTensor，数据类型为int32，LoD层数为1。 M是的groud-truth总数，其每个元素是类别索引。 + - **is_crowd** (Variable) – 维度和 ``gt_classes`` 相同的 LoDTensor，数据类型为int32，每个元素指示一个ground-truth是否为crowd（crowd表示一组对象的集合）。 + - **gt_segms** (Variable) – 维度为[S，2]的2D LoDTensor，它的LoD层数为3，数据类型为float32。通常用户不需要理解LoD，但用户应该在Reader中返回正确的数据格式。LoD[0]表示每个实例中GT对象的数目。 LoD[1]表示每个GT对象的标签分段数。LoD[2]表示每个分段标签多边形(polygon)坐标点的个数。S为所有示例的标签的多边形坐标点的总数。每个元素是（x，y）坐标点。 + - **rois** (Variable) – 维度维度[R，4]的2-D LoDTensor，LoD层数为1，数据类型为float32。 R是RoI的总数，其中每个元素是在原始图像范围内具有（xmin，ymin，xmax，ymax）格式的bounding box。 + - **labels_int32** (Variable) – 形为[R，1]且类型为int32的2-D LoDTensor，数据类型为int32。 R与 ``rois`` 中的R含义相同。每个元素表示RoI框的一个类别标签索引。 + - **num_classes** (int) – 类别数目。 + - **resolution** (int) – 特征图分辨率大小。 返回： - - 形为[P，4]的2D LoDTensor。 P是采样出的RoI总数。每个元素都是在原始图像大小范围内具有[xmin，ymin，xmax，ymax]格式的边界框(bounding box)。 - - mask_rois_has_mask_int32（Variable）：形状为[P，1]的2D LoDTensor，其中每个元素为对于输入的RoI进行输出的mask RoI 索引 - - mask_int32（Variable）：形状为[P，K * M * M]的2D LoDTensor，K为种类数，M为mask预测的分辨率，每个元素都是二进制目标mask值。 + - mask_rois (Variable): 维度为[P，4]的2-D LoDTensor，数据类型为float32。P是采样出的RoI总数，每个元素都是在原始图像大小范围内具有[xmin，ymin，xmax，ymax]格式的bounding box。 + - mask_rois_has_mask_int32（Variable)：维度为[P，1]的2-D LoDTensor，数据类型为int32。每个元素表示采样出的RoI在输入 ``rois`` 内的位置索引。 + - mask_int32（Variable)：维度为[P，K * M * M]的2-D LoDTensor，数据类型为int32。K为种类数，M为特征图的分辨率大小，每个元素都是二值mask标签。 -返回类型：mask_rois (Variable) +返回类型：tuple(Variable) **代码示例**： diff --git a/doc/fluid/api_cn/layers_cn/multi_box_head_cn.rst b/doc/fluid/api_cn/layers_cn/multi_box_head_cn.rst index 57e614295..350a0df6d 100644 --- a/doc/fluid/api_cn/layers_cn/multi_box_head_cn.rst +++ b/doc/fluid/api_cn/layers_cn/multi_box_head_cn.rst @@ -5,44 +5,52 @@ multi_box_head .. py:function:: paddle.fluid.layers.multi_box_head(inputs, image, base_size, num_classes, aspect_ratios, min_ratio=None, max_ratio=None, min_sizes=None, max_sizes=None, steps=None, step_w=None, step_h=None, offset=0.5, variance=[0.1, 0.1, 0.2, 0.2], flip=True, clip=False, kernel_size=1, pad=0, stride=1, name=None, min_max_aspect_ratios_order=False) -生成SSD（Single Shot MultiBox Detector）算法的候选框。有关此算法的详细信息，请参阅SSD论文 `SSD：Single Shot MultiBox Detector `_ 的2.2节。 +基于SSD（Single Shot MultiBox Detector）算法，在不同层输入特征上提取先验框、计算回归的坐标位置和分类的置信度，并合并到一起作为输出，具体参数解释和输出格式参考下面说明。更详细信息，请参阅SSD论文 `SSD：Single Shot MultiBox Detector `_ 的2.2节。 参数： - - **inputs** （list | tuple）- 输入变量列表，所有变量的格式为NCHW。 - - **image** （Variable）- PriorBoxOp的输入图像数据，布局为NCHW。 - - **base_size** （int）- base_size用于根据 ``min_ratio`` 和 ``max_ratio`` 来获取 ``min_size`` 和 ``max_size`` 。 - - **num_classes** （int）- 类的数量。 - - **aspect_ratios** （list | tuple）- 生成候选框的宽高比。 ``input`` 和 ``aspect_ratios`` 的长度必须相等。 - - **min_ratio** （int）- 生成候选框的最小比率。 - - **max_ratio** （int）- 生成候选框的最大比率。 - - **min_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``min_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 - - **max_sizes** （list | tuple | None）- 如果len（输入）<= 2，则必须设置 ``max_sizes`` ，并且 ``min_sizes`` 的长度应等于输入的长度。默认值：无。 - - **steps** （list | tuple）- 如果step_w和step_h相同，则step_w和step_h可以被steps替换。 - - **step_w** （list | tuple）- 候选框跨越宽度。如果step_w [i] == 0.0，将自动计算输跨越入[i]宽度。默认值：无。 - - **step_h** （list | tuple）- 候选框跨越高度，如果step_h [i] == 0.0，将自动计算跨越输入[i]高度。默认值：无。 - - **offset** （float）- 候选框中心偏移。默认值：0.5 - - **variance** （list | tuple）- 在候选框编码的方差。默认值：[0.1,0.1,0.2,0.2]。 - - **flip** （bool）- 是否翻转宽高比。默认值：false。 - - **clip** （bool）- 是否剪切超出边界的框。默认值：False。 - - **kernel_size** （int）- conv2d的内核大小。默认值：1。 - - **pad** （int | list | tuple）- conv2d的填充。默认值：0。 - - **stride** （int | list | tuple）- conv2d的步长。默认值：1， - - **name** （str）- 候选框的名称。默认值：无。 - - **min_max_aspect_ratios_order** （bool）- 如果设置为True，则输出候选框的顺序为[min，max，aspect_ratios]，这与Caffe一致。请注意，此顺序会影响卷积层后面的权重顺序，但不会影响最终检测结果。默认值：False。 - -返回：一个带有四个变量的元组，（mbox_loc，mbox_conf，boxes, variances）: - - - **mbox_loc** ：预测框的输入位置。布局为[N，H * W * Priors，4]。其中 ``Priors`` 是每个输位置的预测框数。 - - - **mbox_conf** ：预测框对输入的置信度。布局为[N，H * W * Priors，C]。其中 ``Priors`` 是每个输入位置的预测框数，C是类的数量。 - - - **boxes** ： ``PriorBox`` 的输出候选框。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总框数。 - - - **variances** ： ``PriorBox`` 的方差。布局是[num_priors，4]。 ``num_priors`` 是每个输入位置的总窗口数。 - -返回类型：元组（tuple） - -**代码示例** + - **inputs** (list(Variable) | tuple(Variable)) - 输入特征的列表，仅支持格式为NCHW的4-D Tensor。 + - **image** (Variable) - 一般是网络输入的图像数据，仅支持NCHW格式。 + - **base_size** (int) - 输入图片的大小，当输入个数len(inputs) > 2，并且 ``min_size`` 和 ``max_size`` 为None时，通过 ``baze_size``, ``min_ratio`` 和 ``max_ratio`` 来计算出 ``min_size`` 和 ``max_size`` 。计算公式如下: + + .. code-block:: python + + min_sizes = [] + max_sizes = [] + step = int(math.floor(((max_ratio - min_ratio)) / (num_layer - 2))) + for ratio in six.moves.range(min_ratio, max_ratio + 1, step): + min_sizes.append(base_size * ratio / 100.) + max_sizes.append(base_size * (ratio + step) / 100.) + min_sizes = [base_size * .10] + min_sizes + max_sizes = [base_size * .20] + max_sizes + + - **num_classes** (int) - 类别数。 + - **aspect_ratios** (list(float) | tuple(float) | list(list(float)) | tuple(tuple(float)) - 候选框的宽高比， ``aspect_ratios`` 和 ``input`` 的个数必须相等。如果每个特征层提取先验框的 ``aspect_ratio`` 多余一个，写成嵌套的list，例如[[2., 3.]]。 + - **min_ratio** (int）- 先验框的长度和 ``base_size`` 的最小比率，注意，这里是百分比，加入比率为0.2，这里应该给20.0。默认值: None。 + - **max_ratio** (int）- 先验框的长度和 ``base_size`` 的最大比率，注意事项同 ``min_ratio`` 。默认值: None。 + - **min_sizes** (list(float) | tuple(float) | None）- 每层提取的先验框的最小长度，如果输入个数len(inputs)<= 2，则必须设置 ``min_sizes`` ，并且 ``min_sizes`` 的个数应等于len(inputs)。默认值：None。 + - **max_sizes** (list | tuple | None）- 每层提取的先验框的最大长度，如果len(inputs）<= 2，则必须设置 ``max_sizes`` ，并且 ``min_sizes`` 的长度应等于len(inputs)。默认值：None。 + - **steps** (list(float) | tuple(float)) - 相邻先验框的中心点步长 ，如果在水平和垂直方向上步长相同，则设置steps即可，否则分别通过step_w和step_h设置不同方向的步长。如果 ``steps``, ``ste_w`` 和 ``step_h`` 均为None，步长为输入图片的大小 ``base_size`` 和特征图大小的比例。默认值：None。 + - **step_w** (list(float）| tuple(float)) - 水平方向上先验框中心点步长。默认值：None。 + - **step_h** (list | tuple) - 垂直方向上先验框中心点步长。默认值：None。 + - **offset** (float) - 左上角先验框中心在水平和垂直方向上的偏移。默认值：0.5 + - **variance** (list | tuple) - 先验框的方差。默认值：[0.1,0.1,0.2,0.2]。 + - **flip** (bool) - 是否翻转宽高比。默认值：False。 + - **clip** (bool) - 是否剪切超出边界的框。默认值：False。 + - **kernel_size** (int) - 计算回归位置和分类置信度的卷积核的大小。默认值：1。 + - **pad** (int | list(int) | tuple(int)) - 计算回归位置和分类置信度的卷积核的填充。默认值：0。 + - **stride** (int | list | tuple) - 计算回归位置和分类置信度的卷积核的步长。默认值：1。 + - **name** (str) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 + - **min_max_aspect_ratios_order** (bool) - 如果设置为True，则输出先验框的顺序为[min，max，aspect_ratios]，这与Caffe一致。请注意，此顺序会影响卷积层后面的权重顺序，但不会影响最终检测结果。默认值：False。 + +返回： + - **mbox_loc(Variable)** - 预测框的回归位置。格式为[N，num_priors，4]，其中 ``N`` 是batch size， ``num_priors`` 是总共提取的先验框的个数。 + - **mbox_conf(Variable）** - 预测框的分类信度。格式为[N，num_priors，C]，其中 ``num_priors`` 同上，C是类别数。 + - **boxes(Variable)** - 提取的先验框。布局是[num_priors，4]， ``num_priors`` 同上，常量4是坐标个数。 + - **variances(Variable)** - 提取的先验框方差。布局是[num_priors，4]， ``num_priors`` 同上。 + +返回类型：list(Variable) | tuple(Variable） + +**代码示例1: 设置min_ratio和max_ratio** .. code-block:: python @@ -69,5 +77,31 @@ multi_box_head clip=True) +**代码示例2: 设置min_sizes和max_sizes** + +.. code-block:: python + + import paddle.fluid as fluid + + images = fluid.layers.data(name='data', shape=[3, 300, 300], dtype='float32') + conv1 = fluid.layers.data(name='conv1', shape=[512, 19, 19], dtype='float32') + conv2 = fluid.layers.data(name='conv2', shape=[1024, 10, 10], dtype='float32') + conv3 = fluid.layers.data(name='conv3', shape=[512, 5, 5], dtype='float32') + conv4 = fluid.layers.data(name='conv4', shape=[256, 3, 3], dtype='float32') + conv5 = fluid.layers.data(name='conv5', shape=[256, 2, 2], dtype='float32') + conv6 = fluid.layers.data(name='conv6', shape=[128, 1, 1], dtype='float32') + + mbox_locs, mbox_confs, box, var = fluid.layers.multi_box_head( + inputs=[conv1, conv2, conv3, conv4, conv5, conv6], + image=images, + num_classes=21, + min_sizes=[60.0, 105.0, 150.0, 195.0, 240.0, 285.0], + max_sizes=[[], 150.0, 195.0, 240.0, 285.0, 300.0], + aspect_ratios=[[2.], [2., 3.], [2., 3.], [2., 3.], [2.], [2.]], + base_size=300, + offset=0.5, + flip=True, + clip=True) + diff --git a/doc/fluid/api_cn/layers_cn/random_crop_cn.rst b/doc/fluid/api_cn/layers_cn/random_crop_cn.rst index 3cbbd401e..492c641a7 100644 --- a/doc/fluid/api_cn/layers_cn/random_crop_cn.rst +++ b/doc/fluid/api_cn/layers_cn/random_crop_cn.rst @@ -5,14 +5,16 @@ random_crop .. py:function:: paddle.fluid.layers.random_crop(x, shape, seed=None) -该operator对batch中每个实例进行随机裁剪。这意味着每个实例的裁剪位置不同，裁剪位置由均匀分布随机生成器决定。所有裁剪的实例都具有相同的shape，由参数shape决定。 +该操作对batch中每个实例进行随机裁剪，即每个实例的裁剪位置不同，裁剪位置由均匀分布随机数生成器决定。所有裁剪后的实例都具有相同的维度，由 ``shape`` 参数决定。 参数: - - **x(Variable)** - 一组随机裁剪的实例 - - **shape(int)** - 裁剪实例的形状 - - **seed(int|变量|None)** - 默认情况下，随机种子从randint(-65536,-65536)中取得 + - **x(Variable)** - 多维Tensor。 + - **shape(list(int))** - 裁剪后最后几维的形状，注意， ``shape`` 的个数小于 ``x`` 的秩。 + - **seed(int|Variable，可选)** - 设置随机数种子，默认情况下，种子是[-65536,-65536)中一个随机数，如果类型是Variable，要求数据类型是int64，默认值：None。 -返回: 裁剪后的batch +返回: 裁剪后的Tensor。 + +返回类型：Variable **代码示例**: @@ -20,9 +22,15 @@ random_crop import paddle.fluid as fluid img = fluid.layers.data("img", [3, 256, 256]) + # cropped_img的shape: [-1, 3, 224, 224] cropped_img = fluid.layers.random_crop(img, shape=[3, 224, 224]) + + # cropped_img2的shape: [-1, 2, 224, 224] + # cropped_img2 = fluid.layers.random_crop(img, shape=[2，224, 224]) + - + # cropped_img2的shape: [-1, 3, 128, 224] + # cropped_img2 = fluid.layers.random_crop(img, shape=[128, 224]) diff --git a/doc/fluid/api_cn/layers_cn/target_assign_cn.rst b/doc/fluid/api_cn/layers_cn/target_assign_cn.rst index 0639e3dc9..ae53d8d9a 100644 --- a/doc/fluid/api_cn/layers_cn/target_assign_cn.rst +++ b/doc/fluid/api_cn/layers_cn/target_assign_cn.rst @@ -5,11 +5,9 @@ target_assign .. py:function:: paddle.fluid.layers.target_assign(input, matched_indices, negative_indices=None, mismatch_value=None, name=None) -对于给定的目标边界框（bounding box）和标签（label），该操作符对每个预测赋予分类和逻辑回归目标函数以及预测权重。权重具体表示哪个预测无需贡献训练误差。 +对于每个实例，根据 ``match_indices`` 和 ``negative_indices`` 位置索引, 给输入 ``out`` 和 ``out_weight`` 赋值。输入 ``input`` 和 ``negative_indices`` 均为2-D LoDTensor。假如 ``input`` 中每个实例的行偏移称作lod，该操作计算步骤如下： -对于每个实例，根据 ``match_indices`` 和 ``negative_indices`` 赋予输入 ``out`` 和 ``out_weight``。将定输入中每个实例的行偏移称为lod，该操作符执行分类或回归目标函数，执行步骤如下： - -1.根据match_indices分配所有输入 +1.根据match_indices赋值: .. code-block:: text @@ -23,24 +21,26 @@ target_assign out[j][j][0 : K] = {mismatch_value, mismatch_value, ...} out_weight[i][j] = 0. -2.如果提供neg_indices，根据neg_indices分配out_weight： +2.如果提供neg_indices，则再次依据该输入赋值： -假设neg_indices中每个实例的行偏移称为neg_lod，该实例中第i个实例和neg_indices的每个id如下： +neg_indices中的第i个实例的索引称作neg_indice，则对于第i个实例： .. code-block:: text - out[i][id][0 : K] = {mismatch_value, mismatch_value, ...} - out_weight[i][id] = 1.0 + for id in neg_indice: + out[i][id][0 : K] = {mismatch_value, mismatch_value, ...} + out_weight[i][id] = 1.0 参数： - - **inputs** (Variable) - 输入为三维LoDTensor，维度为[M,P,K] - - **matched_indices** (Variable) - 张量（Tensor），整型，输入匹配索引为二维张量（Tensor），类型为整型32位，维度为[N,P]，如果MatchIndices[i][j]为-1，在第i个实例中第j列项不匹配任何行项。 - - **negative_indices** (Variable) - 输入负例索引，可选输入，维度为[Neg,1]，类型为整型32，Neg为负例索引的总数 - - **mismatch_value** (float32) - 为未匹配的位置填充值 + - **input** (Variable) - 输入为3-D LoDTensor，为了方便在上述文档中解释，假如维度是[M,P,K]。 + - **matched_indices** (Variable) - 输入为2-D Tensor，数据类型为int32，表示在输入中匹配位置，具体计算如上，同样，为了方便解释，假如维度大小为[N,P]，如果 ``matched_indices[i][j]`` 为-1，表示在第 ``i`` 个实例中第j列项没有任何匹配项，输出会设置成 ``mismatch_value`` 。 + - **negative_indices** (Variable，可选) - 维度为2-D LoDTensor，数据类型为int32。可以不设置，如果设置，会依据该位置索引再次给输出赋值，具体参考上述文档。 + - **mismatch_value** (float32，可选) - 未匹配的位置填充值。 + - **name** (str) - 具体用法请参见 :ref:`api_guide_Name` ，一般无需设置，默认值为None。 -返回：返回一个元组（out,out_weight）。out是三维张量，维度为[N,P,K],N和P与neg_indices中的N和P一致，K和输入X中的K一致。如果match_indices[i][j]存在，out_weight是输出权重，维度为[N,P,1]。 +返回：返回一个元组（out,out_weight）。out是三维张量，维度为[N,P,K]，N和P与 ``matched_indices`` 中的N和P一致，K和输入X中的K一致。 ``out_weight`` 的维度为[N,P,1]。 -返回类型：元组（tuple） +返回类型：tuple(Variable) **代码示例**： -- GitLab