openvino/inference-engine/include/ie_layouts.h

// Copyright (C) 2018-2019 Intel Corporation
// SPDX-License-Identifier: Apache-2.0
//

/**
 * @brief A header file for data layouts and conversion between them
 * @file ie_layouts.h
 */
#pragma once

#include <algorithm>

#include "ie_api.h"
#include "ie_common.h"
#include "ie_precision.hpp"

namespace InferenceEngine {

/**
 * @brief This class describes blocking layouts
 */
class INFERENCE_ENGINE_API_CLASS(BlockingDesc) {
public:
    /**
     * @brief The default constructor which creates empty blocking descriptor
     */
    BlockingDesc();
    /**
     * @brief The constructor which allows to create blocking descriptors for standard layouts
     * @param dims real dimensions
     * @param layout memory layout
     */
    BlockingDesc(const SizeVector& dims, Layout layout);
    /**
     * @brief The constructor allows to create blocking descriptors for blocked memory
     * @param blocked_dims blocked dimensions
     * @param order the order of dimensions
     */
    BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order);
    /**
     * @brief The constructor allows to create blocking descriptors for blocked memory
     * @param blocked_dims blocked dimensions
     * @param order the order of dimensions
     * @param offset offset to the current memory block
     */
    BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset);
    /**
     * @brief The constructor allows to create blocking descriptors for blocked memory
     * @param blocked_dims blocked dimensions
     * @param order the order of dimensions
     * @param offset offset to the current memory block
     * @param dimOffsets per-dimension offset from the padding to actual data,
     */
    BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset, SizeVector dimOffsets);
    /**
     * @brief The constructor allows to create blocking descriptors for blocked memory
     * @param blocked_dims blocked dimensions
     * @param order the order of dimensions
     * @param offset offset to the current memory block
     * @param dimOffsets per-dimension offset from the padding to actual data,
     * @param strides strides for each dimension
     */
    BlockingDesc(const SizeVector& blocked_dims, const SizeVector& order, size_t offset, SizeVector dimOffsets, SizeVector strides);
    /**
     * @brief Destructor
     */
    virtual ~BlockingDesc() = default;

    /**
     * @brief Returns the blocked dimensions vector
     * @return blocked dimensions
     */
    const SizeVector& getBlockDims() const {
        return blockedDims;
    }

    /**
     * @brief Returns the vector of order
     * @return order
     */
    const SizeVector& getOrder() const {
        return order;
    }

    /**
     * @brief Returns the per-dimension offset vector
     * @return offsets
     */
    const SizeVector& getOffsetPaddingToData() const {
        return offsetPaddingToData;
    }

    /**
     * @brief Returns the offset to the current memory block
     * @return offset
     */
    size_t getOffsetPadding() const {
        return offsetPadding;
    }

    /**
     * @brief Returns strides for each dimension
     * @return strides
     */
    const SizeVector& getStrides() const {
        return strides;
    }

    /**
     * @brief The comparison operator for the BlockingDesc
     * @param rhs object to compare
     * @return true if objects are equal
     */
    bool operator == (const BlockingDesc& rhs) const;
    /**
     * @brief The comparison operator for the BlockingDesc
     * @param rhs object to compare
     * @return true if objects aren't equal
     */
    bool operator != (const BlockingDesc& rhs) const;

protected:
    void fillDesc(const SizeVector& blocked_dims, const SizeVector& order);

private:
    /** Blocked dimensions. */
    SizeVector blockedDims;
    /** Strides for blocked dimensions */
    SizeVector strides;
    /** The order of blocked dimensions **/
    SizeVector order;
    /** Per-dimension offset from the padding to actual data, the top-level
     * tensor with offsets applied must lie within the padding area. */
    SizeVector offsetPaddingToData;
    /** Offset from memory origin to the current block, non-zero only in
     * a description of a memory sub-block. */
    size_t offsetPadding;
};

/**
 * @brief This class defines Tensor description
 */
class INFERENCE_ENGINE_API_CLASS(TensorDesc) {
public:
    /**
     * @brief The constructor creates the tensor descriptor using blocking descriptor
     * @param precision memory precision
     * @param dims memory dimensions
     * @param blockDesc blocking descriptor
     */
    TensorDesc(const Precision& precision, SizeVector dims, const BlockingDesc& blockDesc);
    /**
     * @brief The constructor creates the tensor descriptor using standard layout
     * @param precision memory precision
     * @param dims memory dimensions
     * @param layout memory layout
     */
    TensorDesc(const Precision& precision, SizeVector dims, Layout layout);
    /**
     * @brief The constructor creates the empty tensor descriptor with precision and layout
     * @param precision memory precision
     * @param layout memory layout
     */
    TensorDesc(const Precision& precision, Layout layout);
    /**
     * @brief The default constructor which creates empty tensor descriptor
     */
    TensorDesc();
    /**
     * @brief Destructor
     */
    virtual ~TensorDesc() = default;

    /**
     * @brief Reshapes the tensor descriptor
     * @param dims new dimensions
     * @param layout new layout if it is necessary
     */
    void reshape(const SizeVector &dims, Layout layout = Layout::ANY);
    /**
     * @brief Reshapes the tensor descriptor
     * @param dims new dimensions
     * @param blockDesc new blocking descriptor
     */
    void reshape(const SizeVector &dims, const BlockingDesc &blockDesc);

    /**
     * @brief Returns the vector of dimensions
     * @return dimensions
     */
    SizeVector& getDims() {
        return dims;
    }
    /**
     * @brief Returns the constant vector of dimensions
     * @return dimensions
     */
    const SizeVector& getDims() const noexcept {
        return dims;
    }
    /**
     * @brief Sets dimensions
     * @param dims new dimensions
     */
    void setDims(const SizeVector& dims);

    /**
     * @brief Returns the memory layout
     * @return layout
     */
    Layout getLayout() const {
        return layout;
    }

    /**
     * @brief Sets the layout
     * @param l memory layout
     */
    void setLayout(Layout l) {
        bool inconsistentLayout = true;
        switch (l) {
            case Layout::SCALAR:
                inconsistentLayout = !dims.empty();
                break;
            case Layout::C:
                inconsistentLayout = dims.size() != 1;
                break;
            case Layout::BLOCKED:
            case Layout::ANY:
                inconsistentLayout = false;
                break;
            case Layout::NCDHW:
            case Layout::NDHWC:
                inconsistentLayout = dims.size() != 5;
                break;
            case Layout::OIHW:
            case Layout::NCHW:
            case Layout::NHWC:
                inconsistentLayout = dims.size() != 4;
                break;
            case Layout::CHW:
                inconsistentLayout = dims.size() != 3;
                break;
            case Layout::CN:
            case Layout::NC:
            case Layout::HW:
                inconsistentLayout = dims.size() != 2;
                break;
            default:
                break;
        }
        if (inconsistentLayout)
            THROW_IE_EXCEPTION << "Size of dims(" << std::to_string(dims.size()) << ") and format(" << l << ") are inconsistent.";
        layout = l;
    }

    /**
     * @brief Returns the memory precision
     * @return precision
     */
    const Precision& getPrecision() const {
        return precision;
    }

    /**
     * @brief Sets the memory precision
     * @param p precision
     */
    void setPrecision(const Precision& p) {
        precision = p;
    }

    /**
     * @brief Returns the blocking descriptor
     * @return blocking descriptor
     */
    const BlockingDesc& getBlockingDesc() const {
        return blockingDesc;
    }

    /**
     * @brief The comparison operator for the TensorDesc
     * @param rhs object to compare
     * @return true if objects are equal
     */
    bool operator == (const TensorDesc& rhs) const;
    /**
     * @brief The comparison operator for the TensorDesc
     * @param rhs object to compare
     * @return true if objects aren't equal
     */
    bool operator != (const TensorDesc& rhs) const;

    /**
     * @brief Calculates offset for the vector of dimensions
     * @param v vector of dimensions
     * @return offset
     */
    size_t offset(const SizeVector& v) const;
    /**
     * @brief Calculates offset for the local offset
     * @param l local offset
     * @return offset
     */
    size_t offset(size_t l) const;

    /**
     * @brief Returns the standard layout for dimensions
     * @param dims the vector of dimensions
     * @return the standard memory layout
     */
    static Layout getLayoutByDims(SizeVector dims);
private:
    /**
     * Memory layout
     */
    Layout layout;
    /**
     * @brief blob's dimensions
     */
    SizeVector dims;
    /**
     * @brief memory precision
     */
    Precision precision;
    /**
     * Detailed information about layout construction
     */
    BlockingDesc blockingDesc;
};

/**
 * @deprecated Deprecated since provides dims in reverse order
 */
INFERENCE_ENGINE_DEPRECATED
static const size_t I_N = 3;

/**
 * @deprecated Deprecated since provides dims in reverse order
 */
INFERENCE_ENGINE_DEPRECATED
static const size_t I_C = 2;

/**
 * @deprecated Deprecated since provides dims in reverse order
 */
INFERENCE_ENGINE_DEPRECATED
static const size_t I_H = 1;

/**
 * @deprecated Deprecated since provides dims in reverse order
 */
INFERENCE_ENGINE_DEPRECATED
static const size_t I_W = 0;

/**
 * @deprecated Uses TensorDesc working with layouts
 * @brief This class helps calculating offset in different layouts
 */
class INFERENCE_ENGINE_DEPRECATED INFERENCE_ENGINE_API_CLASS(LayoutOffsetCounter) {
private:
    Layout _layout;
    SizeVector _dims;

    size_t _dims_count;

    /**
     * @brief Stores multipliers that are calculated during the LayoutOffsetCounter construction.
     * The multipliers are used for conversion.
     */
    SizeVector _muls;
public:
    /**
     * @brief A default constructor
     * @param dims Tensor dimension array (reverse NCHW order as in the IR: w,h,c,n)
     */
    LayoutOffsetCounter(Layout layout, SizeVector dims);

    IE_SUPPRESS_DEPRECATED_START
    /**
     * @brief A copy constructor
     */
    LayoutOffsetCounter(const LayoutOffsetCounter & l);

    /**
     * @brief A copy assignment operator
     * @param l A value to copy from
     */
    LayoutOffsetCounter & operator = (const LayoutOffsetCounter & l);
    IE_SUPPRESS_DEPRECATED_END

    /**
     * @brief A destructor
     */
    ~LayoutOffsetCounter();

    /**
     * @brief Calculates an offset for the specified layout
     * @param pos Tensor position array (reverse NCHW order as in the IR: w,h,c,n)
     */
    size_t Offset(SizeVector pos);
};

/**
 * @deprecated Please use TensorDesc for conversion
 */
template<typename T>
INFERENCE_ENGINE_DEPRECATED
void ConvertLayout(Layout sourceLayout, Layout destLayout, const T* sourceBuffer, T* destBuffer, SizeVector dims) {
    IE_SUPPRESS_DEPRECATED_START
    if (dims.size() == 0) return;

    SizeVector pos(dims.size(), 0);
    LayoutOffsetCounter srcOffsetCounter(sourceLayout, dims);
    LayoutOffsetCounter destOffsetCounter(destLayout, dims);

    while (true) {
        // Setting the current item
        size_t ps = srcOffsetCounter.Offset(pos);
        size_t pd = destOffsetCounter.Offset(pos);

        destBuffer[pd] = sourceBuffer[ps];

        // Advancing pos
        size_t caret = 0;
        pos[caret]++;
        while (pos[caret] >= dims[caret]) {
            pos[caret] = 0;
            caret++;
            if (caret == pos.size()) {
                // We have finished converting
                return;
            }
            pos[caret]++;
        }
    }
    IE_SUPPRESS_DEPRECATED_END
}

}  // namespace InferenceEngine