Numpy dstack() Function

---

---

The Numpy dstack() function is used to stack arrays in sequence depth-wise (along the third axis). This function is part of the numpy module. It is useful for stacking multiple arrays to create a 3D array, where each input array becomes a layer in the third dimension.

For example, stacking two 2D arrays with the same shape will result in a 3D array with the same height and width as the input arrays, and a depth equal to the number of arrays stacked.

In the numpy.dstack() function, if the input arrays have different shapes along the first or second axis, it will raise a ValueError.

Syntax

Following is the syntax of the Numpy dstack() function −

numpy.dstack(arrays)

Parameters

Following are the parameters of the Numpy dstack() function −

• arrays - Sequence of arrays to be stacked. The arrays must have the same shape along the first and second axes.

Return Values

The function returns a 3D array with a new depth dimension, combining all input arrays along this third axis.

Example

Following is a basic example to stack two 1D arrays depth-wise using Numpy dstack() −

import numpy as np
array1 = np.array([1, 2, 3])
array2 = np.array([4, 5, 6])
dstacked_array = np.dstack((array1, array2))
print("Array 1 -", array1)
print("Array 2 -", array2)
print("Depth-wise Stacked Array -\n", dstacked_array)

Output

Following is the output of the above code −

Array 1 - [1 2 3]
Array 2 - [4 5 6]
Depth-wise Stacked Array -
 [[[1 4]
  [2 5]
  [3 6]]]

Example - Depth-wise Stacking 2D Arrays

In the following example, we stack two 2D arrays depth-wise using numpy.dstack() to create a 3D array. Each input array has a shape of (2, 3), and the resulting array will have a shape of (2, 3, 2) −

import numpy as np
array1 = np.array([[10, 20, 30], [40, 50, 60]])
array2 = np.array([[70, 80, 90], [100, 110, 120]])
dstacked_array = np.dstack((array1, array2))
print("Array 1 -\n", array1)
print("Array 2 -\n", array2)
print("Depth-wise Stacked Array -\n", dstacked_array)
print("Shape of Depth-wise Stacked Array -", dstacked_array.shape)

Output

Following is the output of the above code −

Array 1 -
 [[10 20 30]
  [40 50 60]]
Array 2 -
 [[ 70  80  90]
  [100 110 120]]
Depth-wise Stacked Array -
 [[[ 10  70]
  [ 20  80]
  [ 30  90]]

 [[ 40 100]
  [ 50 110]
  [ 60 120]]]
Shape of Depth-wise Stacked Array - (2, 3, 2)

Example - Stacking Arrays with Different Shapes

The input arrays must have the same shape along the first two axes. If they do not, numpy.dstack() will raise a ValueError. In the following example, we attempt to stack arrays of incompatible shapes −

import numpy as np
array1 = np.array([[1, 2], [3, 4]])
array2 = np.array([[5, 6, 7], [8, 9, 10]])
try:
    dstacked_array = np.dstack((array1, array2))
    print(dstacked_array)
except ValueError as e:
    print("ValueError:", e)

Output

Following is the output of the above code −

ValueError: all the input array dimensions except for the concatenation axis must match exactly