Blender 3D

NAVis comes with an interface to import neurons into Blender 3D for high quality renderings and videos: navis.interfaces.blender

Because NAVis requires Python at least 3.8 this only works with Blender 2.8x or higher!

Installation

Blender comes with its own Python 3.X distribution! So you need to install NAVis explicitly for this distribution in order to use it within Blender.

There are several ways to install additional packages for Blender’s built-in Python. The easiest way is probably this:

1. Find out where Blender’s Python lives (this depends on your OS). In Blender’s Python console run this:

   >>> import sys
   >>> sys.executable
   '[..]/blender.app/Contents/Resources/3.0/python/bin/python3.9'
   

2. Check if Blender’s Python already came with the package manager pip:

   [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 -m pip --version
   

   If the above command throws an error along the lines of “No module named pip”: get pip by downloading get-pip.py from here and install by executing with your Python distribution:

   [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 get-pip.py
   

   If pip is there but horrendously outdated, you can update it like so:

   [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 -m pip install pip -U
   

3. Use pip to install NAVis (or any other package for that matter). Please note we have to - again - specify that we want to install for Blender’s Python:

   [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 -m pip install navis
   

Important

It’s possible that this install fails with an error message along the lines of ‘Python.h’ file not found. The reason for this is that Blender ships with a “Python light” and you have to manually provide the Python header files:

First, find out the exact Blender Python version:

[..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 -V

Next point your browser at https://www.python.org/downloads/source/ and download the Gzipped source tarball from the exact same Python version, i.e. Python-3.X.X.tgz and save it to your Downloads directory.

Finally you need to copy everything in the Include folder inside that tarball into the corresponding include folder in your Blender’s Python. In a terminal run:

cd ~/Downloads/
tar -xzf Python-3.X.X.tgz
cp Python-3.X.X/Include/* [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9

If the above fails you have one more option: figure out which dependency fails to compile and compile it on your system’s Python.

1. Install the exact same version of Python as Blender is running on your system

2. Download the source code for the offending dependency either from PyPI where it’ll likely be some tar.gz file under “Download files” or from the Github repository

3. Run python setup.py bdist_wheel to compile the dependency into a wheel file (will appear as .whl file in a /dist subdirectory)

4. Go back to Blender’s Python and install the dependency from that wheel: [..]/blender.app/Contents/Resources/3.0/python/bin/python3.9 -m pip install <full file name of wheel file with .whl extension>

4. You should now be all set to use NAVis in Blender. Check out Quickstart!

Quickstart

navis.interfaces.blender provides a simple interface that lets you add, select and manipulate neurons from within Blender’s Python console:

First, import and set up NAVis like you are used to.

>>> import navis
>>> # Get example neurons
>>> nl = navis.example_neurons()

Now initialise the interface with Blender and import the neurons.

>>> # The blender interface has to be imported explicitly
>>> import navis.interfaces.blender as b3d
>>> # Initialise handler
>>> h = b3d.Handler()
>>> # Load neurons into scene
>>> h.add(nl)

The interface lets you manipulate neurons in Blender too.

>>> # Colorize neurons
>>> h.colorize()
>>> # Change thickness of all neurons
>>> h.neurons.bevel(.02)
>>> # Select subset
>>> subset = h.select(nl[:2])
>>> # Make subset red
>>> subset.color(1, 0, 0)
>>> # Clear all objects
>>> h.clear()

Note

Blender’s Python console does not show all outputs. Please check the terminal if you experience issues. In Windows simply go to Help >> Toggle System Console. In MacOS, right-click Blender in Finder >> Show Package Contents >> MacOS >> double click on blender.

Last but not least, here’s a little taster of what you can do with Blender:

Reference

The navis.interfaces.blender.Handler is providing the interface between navis and Blender.

navis.interfaces.blender.Handler([scaling, ...])

Class that interfaces with scene in Blender.

To manipulate objects (i.e. neurons, synapses and such):

navis.interfaces.blender.Handler.add(x[, ...])	Add neuron(s) to scene.
navis.interfaces.blender.Handler.clear()	Clear all neurons
navis.interfaces.blender.Handler.select(x, *args)	Select given neurons.
navis.interfaces.blender.Handler.hide()	Hide all neuron-related objects.
navis.interfaces.blender.Handler.unhide()	Unide all neuron-related objects.

Materials

navis.interfaces.blender.Handler.color(r, g, b)	Assign color to all neurons.
navis.interfaces.blender.Handler.colorize()	Randomly colorize ALL neurons.
navis.interfaces.blender.Handler.emit(v)	Change emit value.
navis.interfaces.blender.Handler.use_transparency(v)	Change transparency (True/False).
navis.interfaces.blender.Handler.alpha(v)	Change alpha (0-1).
navis.interfaces.blender.Handler.bevel(r)	Change bevel of ALL neurons.

Selections

navis.interfaces.blender.Handler.select(x, *args)	Select given neurons.
navis.interfaces.blender.ObjectList.select([...])	Select objects in 3D viewer
navis.interfaces.blender.ObjectList.color(r, g, b)	Assign color to all objects in the list.
navis.interfaces.blender.ObjectList.colorize([...])	Assign colors across the color spectrum.
navis.interfaces.blender.ObjectList.emit(e)	Change emit value.
navis.interfaces.blender.ObjectList.use_transparency(t)	Change transparency (True/False).
navis.interfaces.blender.ObjectList.alpha(a)	Change alpha (0-1).
navis.interfaces.blender.ObjectList.bevel(r)	Change bevel radius of objects.
navis.interfaces.blender.ObjectList.hide([...])	Hide objects.
navis.interfaces.blender.ObjectList.unhide([...])	Unhide objects.
navis.interfaces.blender.ObjectList.hide_others()	Hide everything BUT these objects.
navis.interfaces.blender.ObjectList.delete()	Delete neurons in the selection.