torch.atleast_3d
function atleast_3d(input: Tensor): voidReturns a tensor with at least 3 dimensions.
Ensures input tensors have at least 3 dimensions. Useful for:
- Image processing: Converting flat data to spatial tensors for convolutions
- 3D convolutions: Preparing volumetric data for 3D CNN operations
- Multi-dimensional indexing: Guaranteeing shape
[D1, D2, D3]or higher - Batched 2D operations: Adding dimensions for batch processing
Reshaping rules:
- 0D (scalar): Reshaped to
[1, 1, 1] - 1D (vector): Reshaped to
[1, N, 1](wrapping with dimensions) - 2D (matrix): Reshaped to
[M, N, 1](adding depth dimension) - 3D or higher: Returned unchanged
- 1D becomes [1, N, 1]: A 1D vector is wrapped with dimensions on both sides, creating shape
[1, N, 1]. This is symmetric and preserves the element count. - 2D gains depth dimension: A 2D matrix gains a singleton depth dimension, becoming
[M, N, 1]. This represents a single-layer 3D tensor. - Zero-copy for 3D+: Tensors that are already 3D or higher are returned unchanged with no reshape overhead.
- Symmetric for 1D: The reshaping of 1D tensors to
[1, N, 1]is symmetric, different from atleast_2d which produces[1, N](asymmetric).
- 2D adds depth, not batch: For a 2D matrix, atleast_3d adds a depth dimension, not a batch dimension. Use atleast_2d with unsqueeze(0) if you need to add a batch dimension.
- Memory layout: Reshaping operations don't copy data but do create new shape metadata. The underlying storage remains the same, so this is efficient.
Parameters
inputTensor- The input tensor (any dimensions, including 0D, 1D, and 2D)
Returns
Tensor with at least 3 dimensions: - 0D tensors become shape [1, 1, 1] - 1D tensors of shape [N] become [1, N, 1] - 2D tensors of shape [M, N] become [M, N, 1] - Higher-dimensional tensors are unchanged
Examples
// Scalar becomes [1, 1, 1]
const scalar = torch.tensor(7);
torch.atleast_3d(scalar); // Shape [1, 1, 1]
// 1D vector becomes [1, N, 1] (wrapped)
const vec = torch.tensor([1, 2, 3]);
torch.atleast_3d(vec); // Shape [1, 3, 1]
// 2D matrix becomes [M, N, 1] (adding depth)
const matrix = torch.tensor([[1, 2], [3, 4]]);
torch.atleast_3d(matrix); // Shape [2, 2, 1]
// 3D tensor unchanged
const volume = torch.randn([3, 4, 5]);
torch.atleast_3d(volume); // Shape [3, 4, 5], unchanged// Prepare image for 3D convolution
const image_2d = torch.randn([256, 256]); // Single 2D image
const image_3d = torch.atleast_3d(image_2d); // [256, 256, 1] - single channel
// Now compatible with 3D CNN operations
const output = conv3d(image_3d, kernel_3d);// Batch processing for volumetric data
const volume = torch.randn([32, 32, 32]); // Single volume
const volume_3d = torch.atleast_3d(volume); // Still [32, 32, 32]
// Use in 3D operations knowing shape is stable// Processing mixed-dimension time series
const scalar_ts = torch.tensor(0.5); // Single value: 0D
const vector_ts = torch.tensor([1, 2, 3]); // Sequence: 1D
const matrix_ts = torch.randn([10, 5]); // Batch of sequences: 2D
// Normalize all to 3D for consistent processing
const data_3d = [
torch.atleast_3d(scalar_ts), // [1, 1, 1]
torch.atleast_3d(vector_ts), // [1, 3, 1]
torch.atleast_3d(matrix_ts) // [10, 5, 1]
];
// All now compatible with 3D operations
for (const d of data_3d) {
processVolume(d); // Guaranteed 3D shape
}See Also
- PyTorch torch.atleast_3d()
- atleast_1d - Ensure at least 1 dimension
- atleast_2d - Ensure at least 2 dimensions
- unsqueeze - Add a dimension at specific position
- reshape - Arbitrary shape transformation