.. _local_data_meshes_tut:

Meshes
------

``navis`` lets you import neurons from a variety of local and remote sources. In this tutorial you will learn how to load meshes 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.

``navis`` knows two types of meshes: :class:`navis.MeshNeuron` for neurons and :class:`navis.Volume` for e.g. neuropil or brain meshes. 

For reading run-of-the-mill files containing meshes, ``navis`` provides a single function: :func:`navis.read_mesh`. Under the hood, that function uses ``trimesh.load_mesh`` which supports most of the common formats (`.obj`, `.ply`, `.stl`, etc.). 

.. code:: ipython3

    import navis

.. code:: ipython3

    # Load an example file (here a FlyWire neuron I downloaded and saved locally)
    mesh = navis.read_mesh('~/Downloads/test_neuron.stl')
    mesh




.. 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.MeshNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>test_neuron</td>
        </tr>
        <tr>
          <th>id</th>
          <td>720575940633212055</td>
        </tr>
        <tr>
          <th>units</th>
          <td>1 dimensionless</td>
        </tr>
        <tr>
          <th>n_vertices</th>
          <td>40905</td>
        </tr>
        <tr>
          <th>n_faces</th>
          <td>82126</td>
        </tr>
      </tbody>
    </table>
    </div>



The interface is similar to ``read_swc`` in that you can point :func:`navis.read_mesh` at single file or at folders with multiple files:

.. code:: ipython3

    # When reading all files in folder you have to specificy the file extension (e.g. *.stl)
    meshes = navis.read_mesh('~/Downloads/neurons/*.stl')
    meshes








.. raw:: html

    &lt;class 'navis.core.neuronlist.NeuronList'&gt; containing 8 neurons (30.1MiB)<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>type</th>
          <th>name</th>
          <th>units</th>
          <th>n_vertices</th>
          <th>n_faces</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <th>0</th>
          <td>navis.MeshNeuron</td>
          <td>720575940614739286</td>
          <td>1 dimensionless</td>
          <td>59628</td>
          <td>119270</td>
        </tr>
        <tr>
          <th>1</th>
          <td>navis.MeshNeuron</td>
          <td>720575940632670433</td>
          <td>1 dimensionless</td>
          <td>60880</td>
          <td>121759</td>
        </tr>
        <tr>
          <th>...</th>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
          <td>...</td>
        </tr>
        <tr>
          <th>6</th>
          <td>navis.MeshNeuron</td>
          <td>720575940633280107</td>
          <td>1 dimensionless</td>
          <td>43403</td>
          <td>85888</td>
        </tr>
        <tr>
          <th>7</th>
          <td>navis.MeshNeuron</td>
          <td>720575940615856345</td>
          <td>1 dimensionless</td>
          <td>83919</td>
          <td>167793</td>
        </tr>
      </tbody>
    </table>
    </div>



By default, :func:`navis.read_mesh` will return neurons. Use the ``output`` parameter to get  a :class:`navis.Volume` (or a ``trimesh.Trimesh``) instead:

.. code:: ipython3

    # Load a mesh file into a Volume
    vol = navis.read_mesh('~/Downloads/test_mesh.stl', output='volume')
    vol




.. parsed-literal::

    <navis.Volume(name=test_neuron, color=(0.85, 0.85, 0.85, 0.2), vertices.shape=(40905, 3), faces.shape=(82126, 3))>



For saving :class:`~navis.MeshNeuron` or :class:`~navis.Volume` to disk, use :func:`navis.write_mesh`:

.. code:: ipython3

    # Save single neuron to file 
    m = navis.example_neurons(1, kind='mesh')
    navis.write_mesh(m, '~/Downloads/neuron.obj')

.. code:: ipython3

    # Save a bunch of neurons to mesh 
    nl = navis.example_neurons(3, kind='mesh')
    navis.write_mesh(nl, '~/Downloads/', filetype='obj')






Manually constructing meshes
============================

It's super easy to construct :class:`~navis.MeshNeuron` and :class:`~navis.Volume` from scratch - they are just vertices and faces after all. So if e.g. your mesh file format is not covered by :func:`~navis.read_mesh` or you created the mesh yourself using a marching cube algorithm, just create the neuron/volume yourself:

.. code:: ipython3

    import numpy as np
    
    # Create some mock vertices
    vertices = np.array([[1, 0, 0],
                         [0, 1, 0],
                         [0, 0, 1]])
    # Make a single triangular face using the vertex indices
    faces = np.array([[0, 1, 2]])

.. code:: ipython3

    # Turn into MeshNeuron
    m = navis.MeshNeuron((vertices, faces), name='my_mesh', units='microns')
    m




.. 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.MeshNeuron</td>
        </tr>
        <tr>
          <th>name</th>
          <td>my_mesh</td>
        </tr>
        <tr>
          <th>units</th>
          <td>1 micrometer</td>
        </tr>
        <tr>
          <th>n_vertices</th>
          <td>3</td>
        </tr>
        <tr>
          <th>n_faces</th>
          <td>1</td>
        </tr>
      </tbody>
    </table>
    </div>



.. code:: ipython3

    vol = navis.Volume(vertices, faces, name='my_volume')
    vol




.. parsed-literal::

    <navis.Volume(name=my_volume, color=(0.85, 0.85, 0.85, 0.2), vertices.shape=(3, 3), faces.shape=(1, 3))>



One thing to keep in mind here is that ``navis`` only works with triangular faces (i.e. no quads or polygons)! Please see the docstring of :class:`navis.MeshNeuron` and :class:`navis.Volume` for details.

Also note that all navis neurons can be stored to disk using ``pickle`` - see the :ref:`pickling tutorial <local_data_pickle_tut>`. 

Hopefully the above has given you some entry points on how to load/save your data. See also the :ref:`I/O API reference api_io>`. Keep in mind that you can also convert one neuron type into another - for example by skeletonizing ``MeshNeurons`` (see :ref:`neuron_conversion`).