See also: Controlling HBP Morphology Viewer from a Jupyter notebook

Exchanging data with HBP Morphology Viewer

If you are a website builder or Jupyter notebook user, you can use the HBP Morphology Viewer as a front end to display data in a secure and private way, or to convert neuron morphologies between the formats that the viewer supports. The mechanism for this is that you load a small library that opens HBP Morphology Viewer in a new tab from within your web application or notebook. This instance of HBP Morphology Viewer will be listening for incoming messages. Your website can send a command, and HBP Morphology Viewer will carry it out and display the result or return a response. The data-exchange mechanism is such that no data gets sent to the HBP Morphology Viewer server; all communication takes place in the browser on the client's computer. Therefore, the method is safe to use for privacy-sensitive data.

Impatient? See how it works

Two commands are currently supported:

Internally, commands to HBP Morphology Viewer are sent according to the json-rpc 2.0 protocol. This means that each command message is a JSON structure with fields id (message-id), method (one of the supported commands), params (command parameters), and that HBP Morphology Viewer responds with a JSON structure that specifies the result or error. In this tutorial we give examples on how to use each of the above commands.

The first step for each example is to open HBP Morphology Viewer in a new window/tab. Managing multiple tabs is tricky, and we provide a library movi-interface.js that takes care of the details:

You find the library in the /js folder of the Morphology Viewer website:

<script type="text/javascript" src=""></script>

In the examples, we create a button with an onclick field that calls the function onclickHandler. This function needs just two lines of code to invoke HBP Morphology Viewer:

var moviInterface;

function onclickHandler() {
  // define moviUrl here, it contains the address of the Morphology Viewer page that you want to load,
  // such as ``

  // reuse moviInterface if it exists
  moviInterface = moviInterface || new moviInterface_class(moviUrl);

  // define sbaCommand here


Calling new moviInterface_class(moviUrl) opens a new HBP Morphology Viewer window. Under some circumstances, this may trigger the browser's popup blocker. This is not a problem. As soon as you use moviInterface.send(...), the user will be prompted to re-open HBP Morphology Viewer, and this time the popup blocker will not kick in since the opening of the new window is a direct consequence of user interaction. To bypass the popup blocker completely, make sure to place new moviInterface_class inside an event handler that responds to a mouse click or key press.

Once moviInterface has been created, keep it in memory so that it can be used to send multiple messages to HBP Morphology Viewer.

Using the MoVi.import command

The arguments that come with this command are:

Working with the Url of the file to import into the viewer is easiest. This is used by the 'see how it works' example above. The Url must be on the same domain as the user's website, or point to a website that is specifically configured for cross-origin requests. The following example is more complex, because it first loads the contents of the file into the user's webpage and then sends the result to the Morphology Viewer. This mechanism can be useful for data that does not have a public url.

Try it yourself: Import file into the viewer example

Using the MoVi.convert command

The arguments that come with this command are:

The following converts a file from SWC to Neurolucida XML, and then displays it in the Morphology Viewer:

moviCommand = {
  "method": "MoVi.convert",
  "params": {
    "name": "../samples/",
    "toMime": "model/mbf.xml+gzip",
    "doRender": true

The converted neuron is returned by the send command by means of a Javascript Promise, to which you can assign an action to carry out when the Promise gets fulfilled.

Try it yourself: Convert SWC to XML example