CATMAID-to-Blender

Plugin for Blender to interface with CATMAID servers, request and analyze data. Tested with Blender 2.77 and CATMAID 2016.09.01

I encourage you to open an issue or contact me directly if you run into problems or have a feature request!

Installation:

First download CATMAIDImport.py, then:

Option A:

1. Directly place CATMAIDImport.py in \Blender...\scripts\addons
2. Start Blender -> File -> User Preferences -> Addons -> Search for CATMAIDImport addon
3. Activate the script by ticking the check box and click Save User Settings (see here for more detailed description)

Option B:

1. Start Blender -> File -> User Preferences -> Addons -> Install from File and select CATMAIDImport.py
2. Activate by ticking check box and click Save User Setting

Dependencies:

None! Blender for Windows and MacOS brings its own Python distribution and the plugin is written such that it works (mostly) without any external libraries.

Optional Python packages:

On Windows/MacOs:

• scipy (will increase performance for clustering).

On Linux:

• numpy (without numpy, functionality will be limited).
• scipy (will increase performance for clustering).

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

• Download pip's get-pip.py and save e.g. in your downloads directory
• Run get-pip.py from Blender Python console:

with open('/Users/YOURNAME/Downloads/get-pip.py') as source_file:
    exec(source_file.read())

• Then use pip to install any given package. Here, we install as Scipy an example:

import pip
pip.main(['install','scipy'])

There appears to be a bug with macOS 10.12 Sierra which makes above steps fail if run from within Blender. In that case try:

1. Make sure Blender is in your Applications folder
2. Right click on Blender icon -> Show Package Contents
3. Navigate to Contents/Resources/2.78/python/bin and run python3.5m by drag&dropping it into a Terminal
4. Try above steps from the Terminal

Before First Use:

Open File -> User Preferences, navigate to Add-ons -> CATMAIDImport and change CATMAID Server URL in preferences to your server. I also recommend saving your credentials for convenience.

The CATMAID API authorizes requests using an API token tied to user account instead of a username and password. For Information on how to retrieve your Token look here.

Quickstart Guide:

Import/Export panel will show up under the Scene tab in the Properties windows

• Functions (e.g. Retrieving skeletons/connectors) that need you to be logged into your CATMAID server will be grayed-out until you did so by hitting 'Connect 2 CATMAID'
• Skeletons can be retrieved by their skeleton ID, by annotations or based on connectivity (Retrieve Partners)
  • Important side node: in order to identify cell bodies, the script searches for nodes with a radius > 10
• Once imported, skeleton/connector data can be readily exported to vector graphics (SVG) with a broad range of options (e.g. coloring, filters, scaling). Look at lower left panel when exporting for these options.

Tutorials:

Please check out the Github Wiki for additional information and tutorials.

Examples:

1. Color neurons by similarity and export to vector graphic (SVG)

2. Group postsynaptic sites based on what presynaptic neuron they connect to

3. Check out Schlegel et al., 2016 (eLife) for more examples.

Using Python to manipulate data within Blender:

First, download pymaid to interact with and manipulate CATMAID data programmatically. In Blender's Python console:

import sys
sys.path.append('PATH_TO_PYMAID')

from pymaid import CatmaidInstance, get_3D_skeleton
from catnat import cut_neuron
from CATMAIDImport import CATMAIDtoBlender

remote_instance = CatmaidInstance( 'www.your.catmaid-server.org' , 'user' , 'password', 'token' )

#Get skeleton for a neuron of interest
skeleton_data = get_3D_skeleton ( ['SKELETON_ID'], myInstance )[0]

#Cut neurons at specific treenode
proximal, distal = cut_neuron( skeleton_data, TREENODE_ID )

#Bring the neuron fragments into Blender
CATMAIDtoBlender.extract_nodes( proximal,
                                SKELETON_ID,
                                neuron_name = 'proximal fragment',
                                resampling = 2,
                                import_connectors = False,
                                conversion_factor = 10000 
                                )

License:

This code is under GNU GPL V3

Acknowledgments and how to cite:

General:

Please cite Schlegel et al., 2016 (eLife) if you use the plugin in your publication.

Specific Methods:

Some functions available within the plugin are based on/derived from previously published methods. Please cite the original papers if you make use of these specific methods.

1. Comparison of neurons based on morphology: Cell. 2013 Dec 19;155(7):1610-23. doi: 10.1016/j.cell.2013.11.025. A bidirectional circuit switch reroutes pheromone signals in male and female brains. Kohl J, Ostrovsky AD, Frechter S, Jefferis GS. http://www.cell.com/abstract/S0092-8674(13)01476-1
2. Comparison of neurons based on connectivity: Science. 2012 Jul 27;337(6093):437-44. doi: 10.1126/science.1221762. The connectome of a decision-making neural network. Jarrell TA, Wang Y, Bloniarz AE, Brittin CA, Xu M, Thomson JN, Albertson DG, Hall DH, Emmons SW. http://science.sciencemag.org/content/337/6093/437.long
3. Comparison of neurons based on synapse distribution: eLife. doi: 10.7554/eLife.16799 Synaptic transmission parallels neuromodulation in a central food-intake circuit. Schlegel, P., Texada, M. J., Miroschnikow, A., Schoofs, A., Hückesfeld, S., Peters, M., … Pankratz, M. J. https://elifesciences.org/content/5/e16799