inference-engine/thirdparty/clDNN/api/CPP/crop.hpp

   1 /*
   2 // Copyright (c) 2016 Intel Corporation
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the "License");
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //      http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 */
  16
  17 ///////////////////////////////////////////////////////////////////////////////////////////////////
  18 #pragma once
  19 #include "../C/crop.h"
  20 #include "primitive.hpp"
  21
  22 namespace cldnn
  23 {
  24 /// @addtogroup cpp_api C++ API
  25 /// @{
  26 /// @addtogroup cpp_topology Network Topology
  27 /// @{
  28 /// @addtogroup cpp_primitives Primitives
  29 /// @{
  30
  31
  32 /// @brief Marker type indicating that instead of reference input size left, top,
  33 ///        right and bottom borders (to cut out) should be specified.
  34 ///
  35 /// @details Used to differentiate constructors.
  36 struct crop_borders_t {};
  37
  38 /// @brief Marker indicating that instead of reference input size left, top,
  39 ///        right and bottom borders (to cut out) should be specified.
  40 constexpr auto crop_borders = crop_borders_t{};
  41
  42 /// @brief Performs crop operation on input.
  43 /// @details Crops the input to the shape of reference_input across all dimensions taking into account specified input offsets.
  44 /// @n       Borders variant calculated output shape from input shape minus the specified borders.
  45 /// @n
  46 /// @n\b Examples
  47 /// @n Crop without offset example:
  48 /// \image html crop_no_offset.jpg
  49 /// @n Crop with offset example:
  50 /// \image html crop_w_offset.jpg
  51 /// @n
  52 /// @n\b Requirements (reference size variant)
  53 /// @n - Input size cannot be greater than reference size in any dimension
  54 /// @n - All sizes have to have positive numbers
  55 /// @n - Reference size plus offset cannot exceed input size
  56 /// @n
  57 /// @n\b Requirements (borders variant)
  58 /// @n - Borders support batch, feature and spatial dimensions (rest of dimensions ignored).
  59 /// @n - Input size cannot be greater than reference size in any dimension
  60 /// @n - All sizes specified in borders have to have non-negative values (positive or @c 0).
  61 /// @n - Sum of sizes of opposite borders must be lower than input size (on all non-ignored dimensions).
  62 /// @n
  63 /// @n Breaking any of this conditions will cause exception throw.
  64 struct crop : public primitive_base<crop, CLDNN_PRIMITIVE_DESC(crop)>
  65 {
  66     CLDNN_DECLARE_PRIMITIVE(crop)
  67
  68     /// @brief Constructs crop primitive.
  69     /// @param id This primitive id.
  70     /// @param input Input primitive id.
  71     /// @param reference_input Reference input tensor with the required dimensions.
  72     /// @param offsets Input offsets.
  73     crop(
  74         const primitive_id& id,
  75         const primitive_id& input,
  76         const tensor& reference_input,
  77         const tensor& offsets,
  78         const padding& output_padding = padding()
  79     )
  80         :primitive_base(id, {input}, output_padding)
  81         , reference_input(reference_input)
  82         , offsets(offsets)
  83     {
  84     }
  85
  86     /// @brief Constructs crop primitive (borders variant).
  87     ///
  88     /// @details Allows to specify borders from each side that should be cut out
  89     ///          by the primitive.
  90     /// @n       NOTE: Borders variant supports only up to four dimensions.
  91     ///
  92     /// @param id         Identifier of newly created primitive.
  93     /// @param input      Identifier of input primitive which dimensions will be cropped.
  94     /// @param lt_borders Border sizes (spatial dimensions define left (X) and top (Y)
  95     ///                   borders, non-spatial dimensions - lower borders)
  96     /// @param rb_borders Border sizes (spatial dimensions define right (X) and bottom (Y)
  97     ///                   borders, non-spatial dimensions - upper borders)
  98     crop(
  99         const primitive_id& id,
 100         const primitive_id& input,
 101         const tensor& lt_borders,
 102         const tensor& rb_borders,
 103         const crop_borders_t,
 104         const padding& output_padding = padding()
 105     )
 106         :primitive_base(id, {input}, output_padding)
 107         , reference_input(rb_borders.negate())
 108         , offsets(lt_borders)
 109     {
 110     }
 111
 112     /// @brief Constructs crop primitive (symmetric borders variant).
 113     ///
 114     /// @details Allows to specify borders from each side that should be cut out
 115     ///          by the primitive.
 116     /// @n       NOTE: Borders variant supports only up to four dimensions.
 117     ///
 118     /// @param id         Identifier of newly created primitive.
 119     /// @param input      Identifier of input primitive which dimensions will be cropped.
 120     /// @param xy_borders Border sizes (symmetric; spatial dimensions define left/right (X)
 121     ///                   and top/bottom (Y) borders, non-spatial dimensions - lower/upper borders).
 122     crop(
 123         const primitive_id& id,
 124         const primitive_id& input,
 125         const tensor& xy_borders,
 126         const crop_borders_t,
 127         const padding& output_padding = padding()
 128     )
 129         :primitive_base(id, {input}, output_padding)
 130         , reference_input(xy_borders.negate())
 131         , offsets(xy_borders)
 132     {
 133     }
 134
 135     /// @brief Constructs a copy from C API @CLDNN_PRIMITIVE_DESC{crop}
 136     crop(const dto* dto)
 137         :primitive_base(dto)
 138         , reference_input(dto->reference_input)
 139         , offsets(dto->offsets)
 140     {
 141     }
 142
 143     /// @brief Reference input tensor with the required dimensions.
 144     tensor reference_input;
 145     /// @brief Input offsets.
 146     tensor offsets;
 147
 148 protected:
 149     void update_dto(dto& dto) const override
 150     {
 151         dto.reference_input = reference_input;
 152         dto.offsets = offsets;
 153     }
 154 };
 155 /// @}
 156 /// @}
 157 /// @}
 158 }