Complete shadow examples notebook

Author: vidartf

examples/Shadows.ipynb

@@ -1,5 +1,23 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Shadows with pythreejs\n",
+    "\n",
+    "This example is meant to demonstrate how to set up shadows with pythreejs. It is mainly based on the example code you can find in the three.js documentation, but is adapted to highlight some of the nuances of using it from pythreejs."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Setup\n",
+    "\n",
+    "First, we set up an example scene for exploring shadow behavior."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -21,6 +39,13 @@
     "view_height = 600"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Create some example geometry in nice coder colors:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -59,6 +84,13 @@
     "plane.rotation = (-3.14/2, 0, 0, 'XYZ')"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Create camera and lighting:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -67,7 +99,6 @@
    "source": [
     "camera = PerspectiveCamera( position=[10, 6, 10], aspect=view_width/view_height)\n",
     "key_light = SpotLight(position=[0, 10, 10], angle = 0.3, penumbra = 0.1)\n",
-    "key_light.target = cube\n",
     "ambient_light = AmbientLight()"
    ]
   },
@@ -86,23 +117,63 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {},
+   "metadata": {
+    "scrolled": false
+   },
    "outputs": [],
    "source": [
     "renderer"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Configuring shadows\n",
+    "\n",
+    "Now we can start playing around with the shadows in such a way that the results of the different options are immediately shown in the rendered scene."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First, set the spot light to track the cube position:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "key_light.target = cube"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Turn on shadows in the renderer:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Turn on shadows in the renderer\n",
     "renderer.shadowMap.enabled = True\n",
     "renderer.shadowMap.type = 'PCFSoftShadowMap'  # default PCFShadowMap"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Even with shadow maps enabled, there are still no shadows. This is because three.js only includes those lights and objects that has been explicitly marked for shadows in its calculations. Let's turn on some of these:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -111,12 +182,20 @@
    "source": [
     "# Enable shadows for the light\n",
     "key_light.castShadow = True\n",
-    "# Enable objects for casting/receiving shadows:\n",
+    "\n",
+    "# Enable casting/receiving shadows for some objects:\n",
     "sphere.castShadow = True\n",
     "cube.castShadow = True\n",
     "plane.receiveShadow = True"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's move the cube closer to the sphere:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -126,6 +205,13 @@
     "cube.position = (0, 1, 2)"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that the light changed to track the position of the cube. It is also clear that the shadow from the cube is not being taken into account on the sphere. As before, we can turn this on with `receiveShadow` on the sphere, but we also need to mark the sphere material for an update. This is needed for any shadow changes *after the first frame with shadows* is rendered."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -137,13 +223,28 @@
     "sphere.material.needsUpdate = True"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, let's zoom in on the details of the shadows:"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "key_light.shadow.mapSize = (2048, 2048)"
+    "camera.position = [2.92, 1.75, 2.92]\n",
+    "camera.quaternion = [-0.18, 0.38, 0.076, 0.90]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here, we can see that there is some pixelation of the shadows (although it is smoothed by using `PCFSoftShadowMap`). This can be fixed by increasing the resolution of the shadow map:"
    ]
   },
   {
@@ -152,7 +253,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "repr(key_light.shadow.camera)"
+    "key_light.shadow.mapSize = (2048, 2048)"
    ]
   },
   {