From 3cdb419b15b13cdf29803aef9e5b4fd28cca930e Mon Sep 17 00:00:00 2001 From: chengduoZH Date: Fri, 9 Feb 2018 16:44:06 +0800 Subject: [PATCH] add doc for prior box --- python/paddle/v2/fluid/layers/nn.py | 158 ++++++++++++++++++++++++---- 1 file changed, 137 insertions(+), 21 deletions(-) diff --git a/python/paddle/v2/fluid/layers/nn.py b/python/paddle/v2/fluid/layers/nn.py index dc1839fd823..0d944c332b5 100644 --- a/python/paddle/v2/fluid/layers/nn.py +++ b/python/paddle/v2/fluid/layers/nn.py @@ -22,7 +22,6 @@ from ..param_attr import ParamAttr from layer_function_generator import autodoc from tensor import concat import math -import numpy as np from operator import mul __all__ = [ @@ -3006,10 +3005,43 @@ def reshape_with_axis(input, axis): """ **ReshapeWithAxis Layer** - """ - assert len(input.shape) > axis and axis >= 0, ' ' + According to the axis to merge the adjacent dim of input. Currently, the axis of + reshape_with_axis must be a scalar. + + Args: + input(variable): The input tensor. + axis(list): According to the axis to merge the adjacent dim. + + Returns: + Variable: A tensor variable. + + Examples: + .. code-block:: python + + x = fluid.layers.data(name="data", shape=[3, 32, 32], dtype="float32") + reshaped = fluid.layers.reshape_with_axis(input=x, axis=2) + reshaped.shape + >> [-1, 1024] + reshaped = fluid.layers.reshape_with_axis(input=x, axis=[1,3]) + reshaped.shape + >> [-1, 96, 32] + """ + assert isinstance(axis, list), "axis should be list." + assert len(input.shape) > len( + axis), "the length of axis should be litter than input.shape's." input_shape = input.shape - new_dim = [-1, reduce(mul, input_shape[axis:len(input_shape)], 1)] + temp = 0 + for ax in axis: + assert ax < len(input.shape) and ax > 0, \ + 'The data of Axis should be between 1 and len(input.shape)' + assert ax > temp, 'Axis should be incremented sequence' + temp = ax + axis += [len(input.shape)] + + new_shape = [] + for i in range(len(axis) - 1): + new_shape += [reduce(mul, input_shape[axis[i]:axis[i + 1]], 1)] + new_shape = [-1] + new_shape helper = LayerHelper('reshape', **locals()) out = helper.create_tmp_variable(helper.input_dtype()) @@ -3017,14 +3049,28 @@ def reshape_with_axis(input, axis): type='reshape', inputs={'X': [input]}, outputs={'Out': [out]}, - attrs={'shape': new_dim}) + attrs={'shape': new_shape}) return out -def reshape(input, new_dim): +def reshape(input, new_shape): """ **Reshape Layer** + Reshape the shape of input according to new_dim. + + Args: + input(variable): The input tensor. + new_shape(list): The new shape of input. + + Returns: + Variable: A tensor variable. + + Examples: + .. code-block:: python + + x = fluid.layers.data(name="data", shape=[3, 32, 32], dtype="float32") + reshaped = fluid.layers.reshape(input=x, new_shape=[-1, 1024]) """ helper = LayerHelper('reshape', **locals()) out = helper.create_tmp_variable(helper.input_dtype()) @@ -3051,6 +3097,44 @@ def prior_box(input, """ **Prior_box** + Generate prior boxes for SSD(Single Shot MultiBox Detector) algorithm. + Each position of the input produce N prior boxes, N is determined by + the count of min_sizes, max_sizes and aspect_ratios, The size of the + box is in range(min_size, max_size) interval, which is generated in + sequence according to the aspect_ratios. + + Args: + input(variable): The input feature data of PriorBox, the layout is NCHW. + image(variable): The input image data of PriorBoxOp, the layout is NCHW. + min_sizes(list): the min sizes of generated prior boxes. + max_sizes(list): the max sizes of generated prior boxes. + aspect_ratios(list): the aspect ratios of generated prior boxes. + variance(list): the variances to be encoded in prior boxes. + flip(bool): Whether to flip aspect ratios. + clip(bool): Whether to clip out-of-boundary boxes. + step_w(list): Prior boxes step across width, 0 for auto calculation. + step_h(list): Prior boxes step across height, 0 for auto calculation. + offset(float): Prior boxes center offset. + name(str): Name of the prior box layer. + + Returns: + boxes(variable): the output prior boxes of PriorBoxOp. The layout is + [H, W, num_priors, 4]. H is the height of input, W is the width + of input, num_priors is the box count of each position. + Variances(variable): the expanded variances of PriorBoxOp. The layout + is [H, W, num_priors, 4]. H is the height of input, W is the width + of input, num_priors is the box count of each position. + + Examples: + .. code-block:: python + + data = fluid.layers.data(name="data", shape=[3, 32, 32], dtype="float32") + conv2d = fluid.layers.conv2d( + input=data, num_filters=2, filter_size=3) + box, var = fluid.layers.prior_box(conv2d, data, + min_size, max_size, aspect_ratio, + variance, flip, clip, + step_w, step_h, offset) """ helper = LayerHelper("prior_box", **locals()) dtype = helper.input_dtype() @@ -3093,19 +3177,51 @@ def prior_boxes(input_layers, name=None): """ **Prior_boxes** - e.g. - prior_boxes( - input_layers = [conv1, conv2, conv3, conv4, conv5, conv6], - image = data, - min_ratio = 0.2, - max_ratio = 0.9, - steps = [8., 16., 32., 64., 100., 300.], - aspect_ratios = [[2.], [2., 3.], [2., 3.], [2., 3.], [2.], [2.]], - min_dim = 300, - offset = 0.5, - variance = [0.1], - flip=True, - clip=True) + + Generate prior boxes for SSD(Single Shot MultiBox Detector) algorithm. + Each position of the input produce N prior boxes, N is determined by + the count of min_sizes, max_sizes and aspect_ratios, The size of the + box is in range(min_size, max_size) interval, which is generated in + sequence according to the aspect_ratios. + + Args: + input(list): The list of input variables, the format of all variables is NCHW. + image(variable): The input image data of PriorBoxOp, the layout is NCHW. + min_ratio(list): the min sizes of generated prior boxes. + max_ratio(list): the max sizes of generated prior boxes. + aspect_ratios(list): the aspect ratios of generated prior boxes. + min_dim(int): + step_w(list): Prior boxes step across width, 0 for auto calculation. + step_h(list): Prior boxes step across height, 0 for auto calculation. + offset(float): Prior boxes center offset. + variance(list): the variances to be encoded in prior boxes. + flip(bool): Whether to flip aspect ratios. + clip(bool): Whether to clip out-of-boundary boxes. + name(str): Name of the prior box layer. + + Returns: + boxes(variable): the output prior boxes of PriorBoxOp. The layout is + [num_priors, 4]. num_priors is the total box count of each + position of input_layers. + Variances(variable): the expanded variances of PriorBoxOp. The layout + is [num_priors, 4]. num_priors is the total box count of each + position of input_layers + + Examples: + .. code-block:: python + + prior_boxes( + input_layers = [conv1, conv2, conv3, conv4, conv5, conv6], + image = data, + min_ratio = 0.2, + max_ratio = 0.9, + steps = [8., 16., 32., 64., 100., 300.], + aspect_ratios = [[2.], [2., 3.], [2., 3.], [2., 3.], [2.], [2.]], + min_dim = 300, + offset = 0.5, + variance = [0.1,0.1,0.1,0.1], + flip=True, + clip=True) """ assert isinstance(input_layers, list), 'input_layer should be a list.' num_layer = len(input_layers) @@ -3168,8 +3284,8 @@ def prior_boxes(input_layers, reshaped_boxes = [] reshaped_vars = [] for i in range(len(box_results)): - reshaped_boxes += [reshape_with_axis(box_results[i], axis=axis)] - reshaped_vars += [reshape_with_axis(var_results[i], axis=axis)] + reshaped_boxes += [reshape_with_axis(box_results[i], axis=[axis])] + reshaped_vars += [reshape_with_axis(var_results[i], axis=[axis])] helper = LayerHelper("concat", **locals()) dtype = helper.input_dtype() -- GitLab