unfold

→Tensor

unfold(x: Tensor, kernel_size: int | tuple[int, int], dilation: int | tuple[int, int] = 1, padding: int | tuple[int, int] = 0, stride: int | tuple[int, int] = 1)

source

Extract sliding local blocks (im2col) from a batched 4-D tensor.

Slides a (kH, kW) window across the spatial extent of x (with given stride, padding, and dilation) and flattens each window into a column of the output. This is the classical im2col operation — convolution can be written as unfold + matmul + fold.

The number of output locations is

L = \prod_d \left\lfloor \frac{S_{\mathrm{in},d} + 2 p_d - d_d (k_d - 1) - 1}{s_d} \right\rfloor + 1

where $d$ indexes spatial dims and $s, p, k, d$ are stride / padding / kernel / dilation respectively.

Parameters

xTensor

Input of shape (N, C, H, W).

kernel_sizeint or (int, int)

Spatial size of the sliding window.

dilationint or (int, int)= 1

Spacing between elements within a window. Default 1.

paddingint or (int, int)= 0

Implicit zero padding applied symmetrically on both sides.

strideint or (int, int)= 1

Step between successive windows. Default 1.

Returns

Tensor

Tensor of shape (N, C·kH·kW, L).

Notes

The inverse, fold, sums overlapping blocks back into an image. fold(unfold(x)) == x only when stride equals kernel size and padding is zero — otherwise overlapping windows produce higher counts at interior pixels.

Examples

>>> import lucid
>>> from lucid.nn.functional import unfold
>>> x = lucid.randn(1, 3, 8, 8)
>>> u = unfold(x, kernel_size=3, stride=1, padding=1)
>>> u.shape                        # (N, C·kH·kW, L) = (1, 27, 64)
(1, 27, 64)