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 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')
mesh
| 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')
meshes
| 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')
vol
<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')
m
| type | navis.MeshNeuron |
|---|---|
| name | my_mesh |
| units | 1 micrometer |
| n_vertices | 3 |
| n_faces | 1 |
vol = navis.Volume(vertices, faces, name='my_volume')
vol
<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).