048-Grosch-1.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<img src=\"https://gitlab.version.fz-juelich.de/grosch1/pvlink_demo_for_jupytercon/-/raw/JupyterCon2020/img/logo.png\"\n",
    "     style=\"float:right; width:25%; height:25%; margin-top:25px;\">\n",
    "\n",
    "# Jupyter for interactive In-Situ Visualization with ParaView/Catalyst\n",
    "\n",
    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/git/https%3A%2F%2Fgitlab.version.fz-juelich.de%2Fgrosch1%2Fpvlink_demo_for_jupytercon/JupyterCon2020)  \n",
    "Try out the *pvlink* extension and the example notebooks in binder."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Behind the Scenes\n",
    "\n",
    "To checkout how *pvlink* works and what happens behind the scenes, [click here](https://gitlab.version.fz-juelich.de/grosch1/pvlink_demo_for_jupytercon/-/blob/JupyterCon2020/BehindTheScenes.md)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Basic Usage"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> If you are trying this notebook out on Binder, you need to use [jupyter server proxy](#Using-jupyter-server-proxy)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## SimpleRenderer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Start a ParaViewWeb server on the command line, for example using the code from the [official ParaView example](https://kitware.github.io/paraviewweb/examples/RemoteRenderer.html#Using-ParaView-as-server)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "%%script bash --bg\n",
    "pvpython pv_server.py --port 1234 --authKey wslink-secret"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can then connect to the ParaViewWeb Server using a `SimpleRenderer`, passing the session URL and the authentication key."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pvlink import SimpleRenderer\n",
    "\n",
    "simple = SimpleRenderer(sessionURL='ws://localhost:1234/ws', authKey='wslink-secret')\n",
    "display(simple)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> If you are trying this notebook out on Binder, you need to use [jupyter server proxy](#Using-jupyter-server-proxy)."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in this setup, it is not possible to change the content to be rendered from within the notebook. The content is determined only at the start of the ParaViewWeb server."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## RemoteRenderer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most likely you *do* want to be able to make changes to the displayed source. In this case you should use the `RemoteRenderer`, which handles the ParaViewWeb server for you. You can still pass all arguments of the webserver as python arguments, in both short and long form."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from pvlink import RemoteRenderer"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(RemoteRenderer.webserver_arguments_help())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, `active_renderer = RemoteRenderer(port=8080)` and `active_renderer = RemoteRenderer(p=8080)` would both set the server to start on port 8080.\n",
    "\n",
    "You can also pass no arguments. In that case, the next free port starting from 8080 will be chosen and a random authKey will be generated for you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Using RemoteRenderer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "> If you are trying this notebook out on Binder, you need to use [jupyter server proxy](#Using-jupyter-server-proxy)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "renderer = RemoteRenderer()\n",
    "display(renderer)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print('renderer port:\\t', renderer.port)\n",
    "print('renderer authKey:', renderer.authKey)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The window that appears will be blank since there are no views or sources. These can be created using ParaView's python module."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from paraview import simple\n",
    "from pvlink.utility import SetRecommendedRenderSettings\n",
    "\n",
    "# Create a view and...\n",
    "view1 = simple.CreateView('RenderView', 'view1')\n",
    "# ...disable interactor-based render calls and\n",
    "# ensure pvserver-side rendering (if applicable)\n",
    "SetRecommendedRenderSettings(view1)\n",
    "# Create and show a source\n",
    "source1 = simple.Cone()\n",
    "simple.Show(source1, view1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Update the renderer widget to display the changes\n",
    "renderer.update_render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Multiple views"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can create more than one view in ParaView. Per default, a `RemoteRenderer`will show the active view."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "print(renderer.viewID) # viewID = -1 will always show active view"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Create a second view\n",
    "view2 = simple.CreateView('RenderView', 'view2')\n",
    "view2.Background = [0,0,0]\n",
    "SetRecommendedRenderSettings(view2)\n",
    "# And show a different source in it\n",
    "source2 = simple.Sphere()\n",
    "simple.Show(source2, view2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The renderer will now show the second view, since it is the currently active one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "renderer.update_render()\n",
    "display(renderer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you want a `RemoteRenderer` to show a fixed view, regardless of which view is active, you can do so by setting its viewID."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "renderer.viewID = view2.GetGlobalIDAsString()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Changing the active view will now not change the view in the `RemoteRenderer` anymore."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "simple.SetActiveView(view1)\n",
    "renderer.update_render()\n",
    "display(renderer)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Using jupyter server proxy"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "`pvlink` supports the usage of [jupyter server proxy](https://github.com/jupyterhub/jupyter-server-proxy). If your notebook is not running locally and you cannot or do not want to tunnel the ParaViewWeb server to your local workstation, you should use *jupyter server proxy*.\n",
    "\n",
    "To do so, you need to specify the baseURL behind which your notebook is running in the baseURL initialization argument of your `RemoteRenderer`.\n",
    "> *Example:* If your notebook is running at http://localhost:8888 and you would access a process running on port 1234 via http://localhost:8888/proxy/1234, the baseURL would be the part before \"proxy\", localhost:8888.\n",
    "\n",
    "If your notebook is running on HTTPS, set `useJupyterServerProxyHttps=True` to use the HTTPS certificates of the notebook server. This is necessary and keeps the connection between the client browser and the (jupyter server) proxy encrypted.\n",
    "You also need to set `disableExternalPort=True` in order to disable port checking during the WebSocket opening handshake. Otherwise, the connection will fail with a port mismatch error as the notebook and the webserver do not run on the same port."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, for a notebook running on https://jupyter-jsc.fz-juelich.de, the `RemoteRenderer` would be setup like this:\n",
    "```proxied_renderer = RemoteRenderer(baseURL='jupyter-jsc.fz-juelich.de/user/<user>/<workspace>', \n",
    "                                  disableExternalPort=True,\n",
    "                                  useJupyterServerProxyHttps=True)```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# You will most likely have to change the baseURL to the URL at which your notebook server is running\n",
    "proxied_renderer = RemoteRenderer(baseURL='localhost:8888', \n",
    "                                  disableExternalPort=True,\n",
    "                                  useJupyterServerProxy=True) # useJupyterServerProxyHttps if https"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For more information on how to use the `RemoteRenderer`, see the [RemoteRenderer section](#RemoteRenderer) of this notebook."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from paraview import simple\n",
    "from pvlink.utility import SetRecommendedRenderSettings\n",
    "\n",
    "# Create a view and...\n",
    "view3 = simple.CreateView('RenderView', 'view3')\n",
    "# ...disable interactor-based render calls and\n",
    "# ensure pvserver-side rendering (if applicable)\n",
    "SetRecommendedRenderSettings(view3)\n",
    "# Create and show a source\n",
    "source3 = simple.Box()\n",
    "simple.Show(source3, view3)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "proxied_renderer.viewID = view3.GetGlobalIDAsString()\n",
    "display(proxied_renderer)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "PyParaView-5.8",
   "language": "python",
   "name": "pyparaview-5.8"
  },
  "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}