Interactive use of CAVE datasets

Neuroglancer

The most full-featured tool for interacting with CAVE data is Neuroglancer.

How do I use neuroglancer

Neuroglancer has a complex and powerful user interface. Learning to leverage it to navigate datasets in 3 dimensions can be challenging. Watching a video tutorial is probably the best way to learn how to use neuroglancer. Below are some links to videos that demonstrate using neuroglancer in some particular contexts.

• Flywire 101 instructions
• Microns instructions
• Allen institute open (neuro)science tutorial

Neuroglancer states/links

One of the principles behind neuroglancer is that every aspect of the viewers state is encoded into a json compatabile dictionary and for most versions encode that json directly in the URL. This means copy and pasting the URL into a message will transmit all aspects of the viewing state with that link. What dataset, what neurons are loaded, what angle they are being viewed at are all reproduced when someone clicks on such a link. This gives neuroglancer a powerful social property where what one users is seeing can be instantly transmitted to another users half way across the globe, and that user can begin rotating, zooming and selecting different elements of that same view.

This can produce some challenges however. Neuroglancer links can quickly become long. Some messaging clients and email clients can end up mangling long links. Shortening links can be done in a few ways. Conventional link shortening services such as tinyurl or bitly can be used. When you start adding hundreds to thousands of annotations to neuroglancer, the size of that dictionary can grow to be larger than the maximum allowable size of an URL, which varies from browser to browser, but can be as short as 2083 characters. For this reason, some neuroglancer instances come with buttons that produce ‘shortened’ links directly from neuroglancer.

What server does neuroglancer run on?

Neuroglancer doesn’t have a server it runs on. It is a webpage you download to your browser which then runs in your local browser. It may communicate to other servers when you do things, but those servers are places where imagery, segmentation or annotations are stored. Often they are just cloud buckets with data stored in them, so the only servers involved are the servers that support that cloud storage system. For CAVE, neuroglancer interacts often with the PyChunkedGraph service to serve it segmentation results and let the user make proofreading edtis. This is important to understand that when ‘neuroglancer’ isn’t working, it’s usually not because neuroglancer itself is broken, but rather servers that it is communicating with.

What website is neuroglancer?

You might notice that you end up at websites that all look a bit like neuroglancer but don’t have precisely the same features or have the same URL. Why is that? Which one should you use? Here we will hope to explain and outline some of the different websites with neuroglancer interfaces on them.

Versions

Different groups often have a desire or need to customize the look, feel or features of neuroglancer in a way that benefits the audience for that website. To do this, they need to setup their own website and put a version of neuroglancer’s codebase there that is modified or configured differently than other websites that might have neuroglancer functionality. Sometimes these websites are cross compatable and you could have been using one rather than the other, but if the versions of neuroglancer that are deployed to those websites are too different, the code might not be compatible. We’ll highlight some of the most popular ones we know about and explain why you should use one versus another.

Websites

• neuroglancer-demo.appspot.com This is a website which is always tracking the main branch of google’s repository of neuroglancer. Changes to this version of neuroglancer happen automatically when code is checked into the google repository.

• neuromancer-seung-import.appspot.com This is a website that is tracking the main branch of the Seung Lab fork of neuroglancer. It contains a number of features which were developed to facilitate work done in MIcRONs and Flywire, including

  • adding an ‘undo’ button to the state, storing changes to neuroglancer’s state in the local cache.
  • shortening the state as it appears in the URL bar to be a “local_id”. Note, copying/pasting these local links does not reproduce links across other machines. This improved performance for URLs with long states.
  • Developing a link shortener button to facilitate link sharing that was compatible with the shorter “local” urls.
  • creating a system for grouping and tagging annotations
  • creating mechanisms to download and upload annotations
  • creating the first interface with the Chunkedgraph proofreading and meshing services.

  While this work was happening, google neuroglancer was evolving rapidly, and these codebases become highly diverged. As of August 2023, the Seung Lab branch is 237 commits ahead and 743 commits behind google master. This means this branch is missing many key features, including:

  • reading sharded file formats, including sharded meshes and image volumes in precomputed or zarr.
  • reading precomputed annotation layers
  • handling multi-resolution meshes.

  Due to this unfortunate situation, further development on this branch has been ceased in favor of trying to contribute directly to the google branch and bring it up to feature parity with the Seung lab branch.

• neuroglancer.neuvue.io This is a fork of the seung-lab’s fork which is maintained by the Applied Physics Laboratory. It added some features to neuroglancer that improved the ergonomics of proofreading. Most, but not all features have been merged back to the Seung Lab branch.

  • hotkeys for splitting and merging
  • automated re-running of the find path tool and clearing of the the points after running the split tool.

• ngl.flywire.ai This is a version of a neuroglancer dependanct project that was built upon the seung-lab branch using the “ng-extend” framework. It added several features that are utilized by the flywire community including

  • buttons to simplify loading different image and segmentation layers
  • a leaderboard for tracking users with the most edits
  • a chat functionality for chatting with other users

• spelunker.cave-explorer.org This is a fork of the main google repository by the CAVE team to add the essentially functionality found in the Seung Lab branch back into main line google. Efforts are being made to keep this branch up to date with main line google, but include features that we feel confident will and should make it into mainline google eventually. However, these features are subject to change and so this deployment is considered a beta branch, and so all links are not gaurunteed to be backward compatible with future changes. As of February 24, 2024 this branch is 27 commits ahead and 30 commits behind google master.

• ngl.cave-explorer.org This is a deployment of mainline google’s branch which simply is compiled with different build-time options than are configured for neuroglancer-demo.app-spot.com. In particular, it presently has some configured link shorteneres, so the share button is available to users and configured to use the original CAVE state share server for link shortening. We also intend to change the default key-bindings for this deployment to make proofreading more ergonomical, when Pull Request 464 is merged. This is considered a more stable deployment and will provide a higher level of backward compatability support for links.