Package: neuroglancer
Neuroglancer Python IntegrationThis package provides a Python interface for controllingNeuroglancer, a web-based 3-d
volumetric data viewer.The following features are supported:Viewing in-memory NumPy arrays (or any other array type with a similar
interface, including HDF5 arrays loaded through h5py)Reading and writing the Neuroglancer viewer state from PythonChanging Neuroglancer key and mouse bindingsDefining actions (to be triggered by key or mouse bindings) that cause a
Python callback to be invoked.It starts a local web server for communicating state changes using sockjs,
serving a copy of the Neuroglancer client code, and for serving data to the
Neuroglancer client if Python data sources are used.InstallationIt is recommended that you activate a suitable Python virtual environment before installing.Python 3.5 or later is required.You can install the latest published package fromPyPIwith:pipinstallneuroglancerIn most cases, this will use a prebuilt binary wheel, which requires neither node.js (to build the
Neuroglancer client) nor a C++ compiler.  If no binary wheel is available for your platform, a
source distribution (sdist) will be used instead, which requires a C++ compiler to build but does
not require node.js (the source distribution includes a prebuilt copy of the Neuroglancer client).Direct installation from remote git repositoryTo install the latest version from the Neuroglancer git repository, you can use:pipinstallgit+https://github.com/google/neuroglancerNote that installing from a git repository requires Node.js and a C++ compiler.To install a specific commitXXXXXXXXX:pipinstallgit+https://github.com/google/neuroglancer@XXXXXXXXXIn another Python package, you can declare a dependency on a git version using the syntax:setup(name='<package>',...,install_requires=[...,'neuroglancer @ git+https://github.com/google/neuroglancer@XXXXXXXXX',],)Installation from local checkout of git repositoryYou can also install from a local checkout of the git repository.  Two forms of installation are
supported: normal installation, and an editable installation for development purposes.As with installation from a remote git repository, installation from a local checkout requires
Node.js to build the Neuroglancer client and a C++ compiler to build the C++ mesh generation
extension module.Normal installationFor normal installation, run the following from the root of the repository:pythonsetup.pyinstallThat will automatically build the Neuroglancer client using Node.js if it has not already been built
(i.e. ifneuroglancer/static/index.htmldoes not exist).  To rebuild the Neuroglancer client
explicitly, you can use:pythonsetup.pybundle_clientornpmrunbuild-pythonNote: Installing from a local checkout usingpip install .also works, but it may be slower
because it makes a full copy of the local directory (https://github.com/pypa/pip/pull/7882),
including the possibly-large.gitandnode_modulesdirectories.Editable installation (for development purposes)During development, aneditableinstallation allows the package to be imported directly from the
local checkout directory:pipinstall-e.Any changes you make to the .py source files take effect the next time the package is imported,
without the need to reinstall.  If you make changes to the Neuroglancer client, you still need to
rebuild it withnpm run build-python.  You can also keep the Neuroglancer client continuously
up-to-date by runningnpm run dev-server-python.ExamplesSee the example programs in theexamples/directory.  Run them
using the Python interpreter in interactive mode, e.g.python-iexample.pyor using the IPython magic command%run -i python.pyDo not run an example non-interactively aspythonexample.pybecause then the server will exit immediately.Mesh generationFor in-memory segmentation volumes, mesh representations of the surface of each
object can be generated on-demand as they are requested by the client (e.g. due
to the user selecting a segment)SecurityBy default the server binds only to the127.0.0.1address, and for protection
against cross-site scripting attacks only accepts requests that include a valid
randomly-generated 160-bit secret key.Test suiteThe test suite can be run using thetoxcommand.  Some of the tests require a WebGL2-enabled web
browser in order to test interaction with the Neuroglancer client.  Both Chrome and Firefox are
supported, but currently due to bugs in Swiftshader, Chrome Headless does not work.  Firefox
Headless also currently does not support WebGL at all.  On Linux, you can successfully run the tests
headlessly on Firefox usingxvfb-run.  On other platforms, tests can't be run headlessly.# For headless using Firefox on xvfb (Linux only)sudoapt-getinstrallxvfb# On Debian-based systemstox-efirefox-xvfb# Run tests using non-headless Firefox# For non-headless using Chrometox-echrome# For non-headless using Firefoxtox-efirefox# To run only tests that do not require a browsertox-eskip-browser-testsRefer totox.inifor details of the test procedure.