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 example gallery for tutorials on these.

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

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

import navis
# Load an example file (here a FlyWire neuron I downloaded and saved locally)
mesh = navis.read_mesh('~/Downloads/test_neuron.stl')
type navis.MeshNeuron
name test_neuron
id 720575940633212055
units 1 dimensionless
n_vertices 40905
n_faces 82126

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

# When reading all files in folder you have to specificy the file extension (e.g. *.stl)
meshes = navis.read_mesh('~/Downloads/neurons/*.stl')
<class 'navis.core.neuronlist.NeuronList'> containing 8 neurons (30.1MiB)
type name units n_vertices n_faces
0 navis.MeshNeuron 720575940614739286 1 dimensionless 59628 119270
1 navis.MeshNeuron 720575940632670433 1 dimensionless 60880 121759
... ... ... ... ... ...
6 navis.MeshNeuron 720575940633280107 1 dimensionless 43403 85888
7 navis.MeshNeuron 720575940615856345 1 dimensionless 83919 167793

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

# Load a mesh file into a Volume
vol = navis.read_mesh('~/Downloads/test_mesh.stl', output='volume')
<navis.Volume(name=test_neuron, color=(0.85, 0.85, 0.85, 0.2), vertices.shape=(40905, 3), faces.shape=(82126, 3))>

For saving MeshNeuron or Volume to disk, use navis.write_mesh():

# Save single neuron to file
m = navis.example_neurons(1, kind='mesh')
navis.write_mesh(m, '~/Downloads/neuron.obj')
# 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 MeshNeuron and Volume from scratch - they are just vertices and faces after all. So if e.g. your mesh file format is not covered by read_mesh() or you created the mesh yourself using a marching cube algorithm, just create the neuron/volume yourself:

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]])
# Turn into MeshNeuron
m = navis.MeshNeuron((vertices, faces), name='my_mesh', units='microns')
type navis.MeshNeuron
name my_mesh
units 1 micrometer
n_vertices 3
n_faces 1
vol = navis.Volume(vertices, faces, name='my_volume')
<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 navis.MeshNeuron and navis.Volume for details.

Also note that all navis neurons can be stored to disk using pickle - see the pickling tutorial.

Hopefully the above has given you some entry points on how to load/save your data. See also the 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 Converting neuron types).