TensorFlow v2.8.0 - Android NDK API - space

TensorFlow v2.8.0 - Android NDK API - space_to_depth 1. tf.nn.space_to_depth

TensorFlow
https://www.tensorflow.org/

TensorFlow -> API -> TensorFlow Core v2.8.0 -> Python
https://www.tensorflow.org/api_docs/python/tf/nn/space_to_depth

SpaceToDepth for tensors of type T.
广度至深度。

tf.nn.space_to_depth(
    input, block_size, data_format='NHWC', name=None
)

Rearranges blocks of spatial data, into depth.
重新排列空间数据块为 depth。

More specifically, this op outputs a copy of the input tensor where values from the height and width dimensions are moved to the depth dimension. The attr block_size indicates the input block size.
更具体地说，此 op 输出 the input tensor 的副本，其中 the height and width dimensions 上的值移至 the depth dimension。值 block_size 表示输入块的大小。

• Non-overlapping blocks of size block_size x block_size are rearranged into depth at each location. (在各个位置上，大小为 block_size x block_size 的不重叠块重组进 depth)
• The depth of the output tensor is block_size * block_size * input_depth.
• The Y, X coordinates within each block of the input become the high order component of the output channel index. (输入的每个块中的 Y, X 坐标变为输出张量 channel 索引的高序部分)
• The input tensor’s height and width must be divisible by block_size. (The input tensor’s height and width 必须能被 block_size 整除)

The data_format attr specifies the layout of the input and output tensors with the following options: “NHWC”: [ batch, height, width, channels ] “NCHW”: [ batch, channels, height, width ] “NCHW_VECT_C”: qint8 [ batch, channels / 4, height, width, 4 ]

It is useful to consider the operation as transforming a 6-D Tensor. e.g. for data_format = NHWC, Each element in the input tensor can be specified via 6 coordinates, ordered by decreasing memory layout significance as: n,oY,bY,oX,bX,iC (where n=batch index, oX, oY means X or Y coordinates within the output image, bX, bY means coordinates within the input block, iC means input channels). The output would be a transpose to the following layout: n,oY,oX,bY,bX,iC
将 the operation 视为转换 6-D Tensor 是有用的。可以通过 6 个坐标指定 the input tensor 中的每个元素，按照 decreasing memory layout significance 排序。

This operation is useful for resizing the activations between convolutions (but keeping all data), e.g. instead of pooling. It is also useful for training purely convolutional models.
该 OP 适用于在 convolutions 间缩放 activations，并保持所有的数据。

For example, given an input of shape [1, 2, 2, 1], data_format = “NHWC” and block_size = 2:

x = [[[[1], [2]],
      [[3], [4]]]]

This operation will output a tensor of shape [1, 1, 1, 4]:

[[[[1, 2, 3, 4]]]]

Here, the input has a batch of 1 and each batch element has shape [2, 2, 1], the corresponding output will have a single element (i.e. width and height are both 1) and will have a depth of 4 channels (1 * block_size * block_size). The output element shape is [1, 1, 4].

For an input tensor with larger depth, here of shape [1, 2, 2, 3], e.g.

x = [[[[1, 2, 3], [4, 5, 6]],
      [[7, 8, 9], [10, 11, 12]]]]

This operation, for block_size of 2, will return the following tensor of shape [1, 1, 1, 12]

[[[[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12]]]]

Similarly, for the following input of shape [1 4 4 1], and a block size of 2:

x = [[[[1],   [2],  [5],  [6]],
      [[3],   [4],  [7],  [8]],
      [[9],  [10], [13],  [14]],
      [[11], [12], [15],  [16]]]]

the operator will return the following tensor of shape [1 2 2 4]:

x = [[[[1, 2, 3, 4],
       [5, 6, 7, 8]],
      [[9, 10, 11, 12],
       [13, 14, 15, 16]]]]

1.1 Args

input: A Tensor.
block_size: An int that is >= 2. The size of the spatial block.
data_format: An optional string from: “NHWC”, “NCHW”, “NCHW_VECT_C”. Defaults to “NHWC”.
name: A name for the operation (optional).

2. ANEURALNETWORKS_SPACE_TO_DEPTH

Rearranges blocks of spatial data, into depth.
重新排列空间数据块为 depth。

More specifically, this op outputs a copy of the input tensor where values from the height and width dimensions are moved to the depth dimension. The value block_size indicates the input block size and how the data is moved.
更具体地说，此 op 输出 the input tensor 的副本，其中 the height and width dimensions 上的值移至 the depth dimension。值 block_size 表示输入块的大小以及数据的移动方式。

Chunks of data of size block_size * block_size from depth are rearranged into non-overlapping blocks of size block_size x block_size.
来自 depth 的大小为 block_size * block_size 的数据块被重新排列为大小为 block_size x block_size 的非重叠块。

chunk [tʃʌŋk]：n. 大块，厚块，厚片，相当大的量
divisible [dɪ'vɪzəb(ə)l]：adj. 可除，可除尽

The depth of the output tensor is input_depth * block_size * block_size. The input tensor’s height and width must be divisible by block_size.
The input tensor’s height and width 必须能被 block_size 整除。

Supported tensor OperandCode:

• ANEURALNETWORKS_TENSOR_FLOAT16 (since NNAPI feature level 3)
• ANEURALNETWORKS_TENSOR_FLOAT32
• ANEURALNETWORKS_TENSOR_QUANT8_ASYMM
• ANEURALNETWORKS_TENSOR_QUANT8_ASYMM_SIGNED (since NNAPI feature level 4)

operand ['ɒpərænd]：n.  *** 作数，运算对象

Supported tensor rank: 4, with “NHWC” or “NCHW” data layout. With the default data layout NHWC, the data is stored in the order of: [batch, height, width, channels]. Alternatively, the data layout could be NCHW, the data storage order of: [batch, channels, height, width]. NCHW is supported since NNAPI feature level 3.

• Note that DepthToSpace only works on 4D tensors.
• Note that SpaceToDepth only works on 4D tensors.

输入和输出数据必须是 4 维。

Inputs:

• 0: A 4-D tensor, of shape [batches, height, width, depth_in], specifying the input.
• 1: An ANEURALNETWORKS_INT32 scalar, specifying the block_size. block_size must be >=1 and block_size must be a divisor of both the input height and width.
• 2: An optional ANEURALNETWORKS_BOOL scalar, default to false. Set to true to specify NCHW data layout for input0 and output0. Available since NNAPI feature level 3.

Outputs:

• 0: The output 4-D tensor, of shape [batches, height/block_size, width/block_size, depth_inblock_sizeblock_size]. For a ANEURALNETWORKS_TENSOR_QUANT8_ASYMM and ANEURALNETWORKS_TENSOR_QUANT8_ASYMM_SIGNED tensor, the scale and zeroPoint must be the same as input0.

Available since NNAPI feature level 1.

3. Examples References

NeuralNetworks
https://developer.android.google.cn/ndk/reference/group/neural-networks