.. _local_data_voxels_tut:

Voxel / Image Data
------------------

``navis`` lets you import neurons from a variety of local and remote sources. In this tutorial you will learn how to load voxel data from local data and - failing that - construct them from scratch. For loading remote data (e.g. the MICrONS, neuromorpho, Virtual Fly Brain or Janelia hemibrain datasets), ``navis`` has dedicated interfaces. See the :ref:`example gallery <example_gallery>` for tutorials on these.

Voxel data (e.g. from confocal scans) is represented by the :class:`navis.VoxelNeuron` class. At this point, ``navis`` supports reading just a single file format directly: ``.nrrd`` files via :func:`navis.read_nrrd` and :func:`navis.write_nrrd`. 

.. code:: ipython3

    import navis

For this example I downloaded one of Janelia's Fly Light confocal stacks (`link <https://splitgal4.janelia.org/>`_) and converted it to nrrd using ImageJ. 

.. code:: ipython3

    # Open one of the Janelia confocals (I converted this to nrrd using ImageJ)
    vxl = navis.read_nrrd('~/Downloads/JRC_SS86025_JRC_SS86025-20211112_49_B6.nrrd')
    vxl




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>type</th>
          <td>navis.VoxelNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>JRC_SS86025_JRC_SS86025-20211112_49_B6</td>
        </tr>
        <tr>
          <th>units</th>
          <td>[0.5189161 micrometer, 0.5189161 micrometer, 1...</td>
        </tr>
        <tr>
          <th>shape</th>
          <td>(1210, 563, 364)</td>
        </tr>
        <tr>
          <th>dtype</th>
          <td>&gt;u2</td>
        </tr>
      </tbody>
    </table>
    </div>



If push comes to shove you can construct :class:`navis.VoxelNeuron` either from a dense 3-dimensional matrix or from sparse 2-dimensional voxel data:

.. code:: ipython3

    import numpy as np
    
    # Create an empty 7x7x7 matrix
    dense = np.zeros((7, 7, 7))
    # Fill the center voxel
    dense[4, 4, 4] = 1
    
    # Create the neuron
    vxl = navis.VoxelNeuron(dense)
    vxl




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>type</th>
          <td>navis.VoxelNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>None</td>
        </tr>
        <tr>
          <th>units</th>
          <td>1 dimensionless</td>
        </tr>
        <tr>
          <th>shape</th>
          <td>(7, 7, 7)</td>
        </tr>
        <tr>
          <th>dtype</th>
          <td>float64</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    # Create an array with sparse x/y/z voxel coordinates
    sparse = np.array([[4, 4, 4],
                       [4, 4, 5]])
    
    # Construct neuron
    vxl = navis.VoxelNeuron(sparse)
    vxl




.. raw:: html

    <div>
    <style scoped>
        .dataframe tbody tr th:only-of-type {
            vertical-align: middle;
        }
    
        .dataframe tbody tr th {
            vertical-align: top;
        }
    
        .dataframe thead th {
            text-align: right;
        }
    </style>
    <table border="1" class="dataframe">
      <thead>
        <tr style="text-align: right;">
          <th></th>
          <th></th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>type</th>
          <td>navis.VoxelNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>None</td>
        </tr>
        <tr>
          <th>units</th>
          <td>1 dimensionless</td>
        </tr>
        <tr>
          <th>shape</th>
          <td>(5, 5, 6)</td>
        </tr>
        <tr>
          <th>dtype</th>
          <td>int64</td>
        </tr>
      </tbody>
    </table>
    </div>



Hopefully the above has given you some entry points on how to load your data. Please see the docstring of :class:`navis.VoxelNeuron` for details.

Also note that all navis neurons can be stored to disk using ``pickle`` - see the :ref:`pickling tutorial <local_data_pickle_tut>`. See also the :ref:`I/O API reference api_io>`.

Keep in mind that you can convert one neuron type into another - for example by meshing ``VoxelNeurons`` (see :ref:`neuron_conversion`).