{
"cells": [
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"3D Plotting\n",
"***********\n",
"\n",
"Depending on the context, pymaid uses two different backends for 3D plotting, `vispy `_ and `plotly `_. "
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. raw:: html\n",
"\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
vispy
\n",
"
\n",
"
\n",
"\n",
"* Interactive\n",
"* Persistent\n",
"* Fast\n",
"* Works from terminal\n",
"\n",
".. raw:: html\n",
"\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
plotly
\n",
"
\n",
"
\n",
"\n",
"* Interactive\n",
"* Browser-based\n",
"* Slow to load\n",
"* Works in Jupyter notebooks\n",
"\n",
".. raw:: html\n",
"\n",
"
\n",
"
\n",
"
\n",
"
\n",
"
\n",
" \n",
"In general, you want to use Vispy if you are using the terminal or an IDE and Plotly if you are working with Jupyter notebooks. Please note that Vispy currently simply *does NOT work* within Jupyter notebooks.\n",
"\n",
"By default, pymaid will try to choose the correct backend for you *automatically*!"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"3D plots with plotly\n",
"====================\n",
"\n",
"`Plotly `_ is a web-based, open-source toolkit for interactive data visualizations. It has bindings for e.g. R and Python. In the pymaid context you will want to use plotly whenever you are working within a Jupyter notebook."
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
""
],
"text/vnd.plotly.v1+html": [
""
]
},
"metadata": {},
"output_type": "display_data"
}
],
"source": [
"import pymaid\n",
"\n",
"# Connect to CATMAID\n",
"rm = pymaid.CatmaidInstance('https://www.your.catmaid-server.org',\n",
" 'HTTP_USER' ,\n",
" 'HTTP_PASSWORD',\n",
" 'TOKEN')\n",
"\n",
"# Get some neurons\n",
"nl = pymaid.get_neurons(['57311', '27295'])"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"First, we need to generate a plotly figure. Note how we specify ``backend='plotly'``? This is, strictly speaking, not necessary as pymaid will automatically detect that we are operating in an Jupyter environment and choose plotly accordingly. Explicitly setting the backend is just for demonstration purposes."
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"outputs": [],
"source": [
"# Generate a plotly figure\n",
"fig = nl.plot3d(backend='plotly', connectors=True, width=800)"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. raw:: html\n",
" :file: 3d_plot.html\n",
" \n",
"|\n",
"|\n",
"|\n",
"|"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"By default, plotly figures are automatically plotted \"inline\". We can control this behavior by adjusting the ``plotly_inline`` parameter. Use this, for example, to write the 3D plot to a separate html file:"
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [],
"source": [
"# Import plotly bindings\n",
"import plotly.offline\n",
"plotly.offline.init_notebook_mode(connected=True)\n",
"\n",
"# Generate the figure without plotting it right away\n",
"fig = nl.plot3d(backend='plotly', connectors=True, width=1200, plotly_inline=False)\n",
"\n",
"# This will open the plot in a separate browser window\n",
"plotly.offline.plot(fig, filename='3d_plot.html')"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Navigating the 3D viewer\n",
"++++++++++++++++++++++++\n",
"\n",
"1. Rotating: Hold left mousebutton\n",
"2. Zooming: Use the mousewheel or hold left+right mousebutton and drag\n",
"3. Panning: Hold shift + left mousebutton\n",
"4. Perspective: Hold shift + left and right mousebutton\n",
"\n",
"Adding volumes\n",
"++++++++++++++ \n",
"\n",
":func:`pymaid.plot3d` allows plotting of volumes (e.g. neuropil meshes). It's very straight forward to use meshes directly from you Catmaid Server:"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"# Provide colors\n",
"vols = [pymaid.get_volume('LH_R', color=(255, 0, 0, .2)),\n",
" pymaid.get_volume('LH_L', color=(0, 255, 0, .2))]\n",
"fig = pymaid.plot3d([nl, *vols], backend='plotly', width=1200)"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. raw:: html\n",
" :file: 3d_volumes.html\n",
" \n",
"|\n",
"|\n",
"|\n",
"|\n",
"\n",
"You can also pass your own custom volumes:"
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [],
"source": [
"cust_vol = pymaid.Volume(vertices = [(1, 2, 1), (5, 6, 7), (8, 6, 4)],\n",
" faces = [(0, 1, 2)],\n",
" name = 'custom volume',\n",
" color = (255, 0, 0))\n",
"fig = pymaid.plot3d(cust_vol, backend='plotly', width=1200)"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
".. raw:: html\n",
" :file: 3d_custom.html\n",
" \n",
"|\n",
"|\n",
"|\n",
"|"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"3D plots using Vispy\n",
"--------------------\n",
"\n",
".. role:: red\n",
"\n",
":red:`Below examples will not work from within a Jupyter notebook`. \n",
"\n",
".. note::\n",
" Vispy itself uses either one of these backends:\n",
" Qt, GLFW,SDL2, Wx, or Pyglet. By default, pymaid\n",
" installs and sets PyQt5 as vispy's backend. If\n",
" you need to change that use e.g. ``vispy.use(app='PyQt4')``\n",
" \n",
" If you are experiencing issues when using vispy\n",
" as backend, you should try installing the dev\n",
" version (currently 0.6.0dev0) directly from\n",
" `Github `_.\n",
" The version installed from PIP is 0.5.2.\n",
" \n",
"Plot using Vispy. This will open a 3D viewer."
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"viewer = nl.plot3d()"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"Saving a screenshot:"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [],
"source": [
"viewer.screenshot('screenshot.png', alpha=True)"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"The :class:`pymaid.Viewer` is persistent. Calling :func:`~pymaid.plot3d` again will add objects to the canvas."
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {
"collapsed": true
},
"outputs": [],
"source": [
"nl2 = pymaid.get_neurons([987675, 543210])\n",
"nl2.plot3d()"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"To clear canvas either pass ``clear3d=True`` parameter when plotting..."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [],
"source": [
"nl2.plot3d(clear3d=True)"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"... or call :func:`pymaid.clear3d` or :func:`pymaid.Viewer.clear`."
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"pymaid.clear3d()\n",
"\n",
"viewer.clear()"
]
},
{
"cell_type": "raw",
"metadata": {},
"source": [
"The viewer will survive simply closing the window. To wipe canvas from memory do:"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [],
"source": [
"pymaid.close3d() #or\n",
"viewer.close()"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"If working with multiple viewers, you can specify which :class:`pymaid.Viewer` to add the neurons to."
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [],
"source": [
"# Open two viewers\n",
"v1 = pymaid.Viewer()\n",
"v2 = pymaid.Viewer()\n",
"\n",
"# Add neurons to each one separately\n",
"v1.add(nl)\n",
"v2.add(nl2)\n",
"\n",
"# Clear one viewer\n",
"v1.clear()\n",
"\n",
"# Close the second viewer\n",
"v2.close()"
]
},
{
"cell_type": "raw",
"metadata": {
"raw_mimetype": "text/restructuredtext"
},
"source": [
"If you've lost track of your viewer, simply use :func:`pymaid.get_viewer` to get it back."
]
}
],
"metadata": {
"celltoolbar": "Raw Cell Format",
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.4"
}
},
"nbformat": 4,
"nbformat_minor": 2
}