title: understanding numpy's dstack function
body: <p>I have some trouble understanding what numpy's <code>dstack</code> function is actually doing. The documentation is rather sparse and just says: </p>
  
  <blockquote>
    <p>Stack arrays in sequence depth wise (along third axis). </p>
    
    <p>Takes a sequence of arrays and stack them along the third axis
      to make a single array. Rebuilds arrays divided by <code>dsplit</code>.
      This is a simple way to stack 2D arrays (images) into a single
      3D array for processing.</p>
  </blockquote>
  
  <p>So either I am really stupid and the meaning of this is obvious or I seem to have some misconception about the terms 'stacking', 'in sequence', 'depth wise' or 'along an axis'. However, I was of the impression that I understood these terms in the context of <code>vstack</code> and <code>hstack</code> just fine.</p>
  
  <p>Let's take this example:</p>
  
  <pre><code>In [193]: a
  Out[193]: 
  array([[0, 3],
         [1, 4],
         [2, 5]])
  In [194]: b
  Out[194]: 
  array([[ 6,  9],
         [ 7, 10],
         [ 8, 11]])
  In [195]: dstack([a,b])
  Out[195]: 
  array([[[ 0,  6],
          [ 3,  9]],
  
         [[ 1,  7],
          [ 4, 10]],
  
         [[ 2,  8],
          [ 5, 11]]])
  </code></pre>
  
  <p>First of all, <code>a</code> and <code>b</code> don't have a third axis so how would I stack them along '<em>the</em> third axis' to begin with? Second of all, assuming <code>a</code> and <code>b</code> are representations of 2D-images, why do I end up with <em>three</em> 2D arrays in the result as opposed to two 2D-arrays 'in sequence'?</p>