#-------------------------------------------------------------

#

# Licensed to the Apache Software Foundation (ASF) under one

# or more contributor license agreements. See the NOTICE file

# distributed with this work for additional information

# regarding copyright ownership. The ASF licenses this file

# to you under the Apache License, Version 2.0 (the

# "License"); you may not use this file except in compliance

# with the License. You may obtain a copy of the License at

#

# http://www.apache.org/licenses/LICENSE-2.0

#

# Unless required by applicable law or agreed to in writing,

# software distributed under the License is distributed on an

# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY

# KIND, either express or implied. See the License for the

# specific language governing permissions and limitations

# under the License.

#

#-------------------------------------------------------------

/*

* Utility functions.

*/

channel_sums = function(matrix[double] X, int C, int Hin, int Win)

return (matrix[double] out) {

/*

* Computes a channel-wise summation over a 4D input.

*

* Inputs:

* - X: Inputs, of shape (N, C*Hin*Win).

* - C: Number of input channels (dimensionality of input depth).

* - Hin: Input height.

* - Win: Input width.

*

* Outputs:

* - out: Outputs, of shape (C, 1).

*/

# Here we sum each column, reshape to (C, Hin*Win), and sum each row to result in the summation

# for each channel.

out = rowSums(matrix(colSums(X), rows=C, cols=Hin*Win)) # shape (C, 1)

}

im2col = function(matrix[double] img, int Hin, int Win, int Hf, int Wf, int strideh, int stridew)

return (matrix[double] img_cols) {

/*

* Rearrange local image regions (patches) into columns.

*

* Assumes image has already been padded as necessary.

*

* Inputs:

* - img: Input image, of shape (C, Hin*Win), where C is the number

* of input channels (depth).

* - Hin: Input height, including padding.

* - Win: Input width, including padding.

* - Hf: Filter height.

* - Wf: Filter width.

* - strideh: Stride over height.

* - stridew: Stride over width.

*

* Outputs:

* - img_cols: Local spatial regions (patches) of the image stretched

* out into columns, of shape (C*Hf*Wf, Hout*Wout).

*/

C = nrow(img)

Hout = as.integer(floor((Hin-Hf)/strideh + 1))

Wout = as.integer(floor((Win-Wf)/stridew + 1))

# Note: We start with `img_cols` transposed to allow for row-major

# left-indexing inside the loop, which is more performant.

img_cols = matrix(0, rows=Hout*Wout, cols=C*Hf*Wf) # zeros

parfor (hout in 1:Hout, check=0) { # all output rows

hin = (hout-1)*strideh + 1

parfor (wout in 1:Wout, check=0) { # all output columns

win = (wout-1)*stridew + 1

# Extract a local patch of the input image corresponding spatially to the filter sizes.

img_patch = matrix(0, rows=C, cols=Hf*Wf) # zeros

parfor (c in 1:C) { # all channels

img_slice = matrix(img[c,], rows=Hin, cols=Win) # reshape

img_patch[c,] = matrix(img_slice[hin:hin+Hf-1, win:win+Wf-1], rows=1, cols=Hf*Wf)

}

img_cols[(hout-1)*Wout + wout,] = t(matrix(img_patch, rows=C*Hf*Wf, cols=1)) # reshape

}

}

img_cols = t(img_cols)

}

col2im = function(matrix[double] img_cols, int C, int Hin, int Win, int Hf, int Wf,

int strideh, int stridew, string reduction)

return (matrix[double] img) {

/*

* Create an image from columns of local image regions (patches).

*

* The reduction strategy determines how to deal with overlapping

* patches. If it is set to "add", any overlapping patches will be

* added together when creating the image. This is useful when

* computing gradients on the original image given gradients on the

* patches. Otherwise, if "none" is provided, any overlapping

* patches will just override previous ones when creating the image.

* This is useful when recreating an image from the output of

* `im2col`.

*

* Assumes original image was already padded as necessary.

*

* Inputs:

* - img_cols: Local spatial regions (patches) of the image stretched

* out into columns, of shape (C*Hf*Wf, Hout*Wout).

* - C: Number of input channels (dimensionality of input depth).

* - Hin: Input height, including padding.

* - Win: Input width, including padding.

* - Hf: Filter height.

* - Wf: Filter width.

* - strideh: Stride over height.

* - stridew: Stride over width.

* - reduction: The reduction strategy to use for overlapping

* patches. Valid options are "add" and "none".

*

* Outputs:

* - img: Input image, of shape (C, Hin*Win).

*/

Hout = as.integer(floor((Hin-Hf)/strideh + 1))

Wout = as.integer(floor((Win-Wf)/stridew + 1))

img = matrix(0, rows=C, cols=Hin*Win) # zeros

for (hout in 1:Hout) { # all output rows

hin = (hout-1)*strideh + 1

for (wout in 1:Wout) { # all output columns

win = (wout-1)*stridew + 1

# Extract a local patch of the input image corresponding spatially to the filter sizes.

img_patch = matrix(img_cols[,(hout-1)*Wout + wout], rows=C, cols=Hf*Wf) # zeros

parfor (c in 1:C) { # all channels

img_patch_slice = matrix(img_patch[c,], rows=Hf, cols=Wf) # reshape

if (reduction == "add") {

img_slice = matrix(0, rows=Hin, cols=Win)

img_slice[hin:hin+Hf-1, win:win+Wf-1] = img_patch_slice

img[c,] = img[c,] + matrix(img_slice, rows=1, cols=Hin*Win)

} else {

img_slice = matrix(img[c,], rows=Hin, cols=Win)

img_slice[hin:hin+Hf-1, win:win+Wf-1] = img_patch_slice

img[c,] = matrix(img_slice, rows=1, cols=Hin*Win)

}

}

}

}

}

pad_image = function(matrix[double] img, int Hin, int Win, int padh, int padw, double pad_value)

return (matrix[double] img_padded) {

/*

* Pads an image along the height and width dimensions with zeros.

*

* Inputs:

* - img: Input image, of shape (C, Hin*Win), where C is the number

* of input channels (depth).

* - Hin: Input height.

* - Win: Input width.

* - padh: Padding for top and bottom sides.

* - padw: Padding for left and right sides.

* - pad_value: Value to use for the padding.

* A typical value is 0.

*

* Outputs:

* - img_padded: The input image padded along the height and width

* dimensions, of shape (C, (Hin+2*padh)*(Win+2*padw)).

*/

C = nrow(img)

img_padded = matrix(0, rows=C, cols=(Hin+2*padh)*(Win+2*padw)) # zeros

parfor (c in 1:C) {

img_slice = matrix(img[c,], rows=Hin, cols=Win) # depth slice C reshaped

img_padded_slice = matrix(pad_value, rows=Hin+2*padh, cols=Win+2*padw)

img_padded_slice[padh+1:padh+Hin, padw+1:padw+Win] = img_slice

img_padded[c,] = matrix(img_padded_slice, rows=1, cols=(Hin+2*padh)*(Win+2*padw)) # reshape

}

}

unpad_image = function(matrix[double] img_padded, int Hin, int Win, int padh, int padw)

return (matrix[double] img) {

/*

* Unpads an image along the height and width dimensions.

*

* Inputs:

* - img_padded: The input image padded along the height and width

* dimensions, of shape (C, (Hin+2*padh)*(Win+2*padw)).

* - Hin: Input height of unpadded image.

* - Win: Input width of unpadded image.

* - padh: Padding for top and bottom sides.

* - padw: Padding for left and right sides.

*

* Outputs:

* - img: Input image, of shape (C, Hin*Win), where C is the number

* of input channels (depth).

*/

C = nrow(img_padded)

img = matrix(0, rows=C, cols=Hin*Win)

parfor (c in 1:C) {

img_padded_slice = matrix(img_padded[c,], rows=(Hin+2*padh), cols=(Win+2*padw))

img_slice = img_padded_slice[padh+1:padh+Hin, padw+1:padw+Win]

img[c,] = matrix(img_slice, rows=1, cols=Hin*Win)

}

}

threshold = function(matrix[double] X, double thresh)

return (matrix[double] out) {

/*

* Computes an indicator matrix with values in {0, 1} depending on

* whether or not the values in X are above the input threshold

*

* Inputs:

* - X: Inputs, of shape (any, any).

* - thresh: Input threshold.

*

* Outputs:

* - out: Outputs, of same shape as X.

*/

out = X > thresh

}