add hdr examples, add hdr reading support, fix camera switching when ray generation program changes, prepare for the release

Author: robertsulej

CHANGELOG.rst

@@ -1,14 +1,15 @@
 Release history
 ===============
 
-v0.8.1 - unreleased
--------------------
+`v0.8.1`_ - 2020-06-14
+----------------------
 
 Added
 ~~~~~
 
 - camera mode for baking 360 degree panoramic views
 - support 16 bit per channel and hdr (32 bit fp per channel) output to image files and ndarray
+- support reading hdr images
 
 Fixed
 ~~~~~
@@ -344,6 +345,7 @@ v0.1.2.5 - 2019-04-16
 
 Two weeks and some steps from the initial release. Starting changelog relative to this point.
 
+.. _`v0.8.1`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.8.1
 .. _`v0.8.0`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.8.0
 .. _`v0.7.2`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.7.2
 .. _`v0.7.1`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.7.1

examples/1_basic_plot_making/10_1_save_hdr_environment_map.ipynb

@@ -0,0 +1,320 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## High dynamic range and environment maps\n",
+    "\n",
+    "This example shows how to:\n",
+    "   - setup camera for baking 360 degree panoramic environment map\n",
+    "   - save image file with 8/16/32 bits per sample color depth\n",
+    "   - use OpenCV to save image in HDR format\n",
+    "\n",
+    "![plotoptix ray_tracing_output](https://plotoptix.rnd.team/images/360deg_env_map.jpg \"This notebook output\")\n",
+    "\n",
+    "Saving images to jpg format is great when you want to use them quickly, with no additional editing outside your script. Jpg uses 8 bit/sample color depth and lossy compression - such output of your work is ready to go e.g. to the web.\n",
+    "\n",
+    "If you plan to apply retouching in an image editing software you'll appreciate saving your renders to a lossless format, with 16 bit/sample color depth. PlotOptiX can do that, tiff (Linux/Windows) and png (Windows) formats are supported.\n",
+    "\n",
+    "However, the full information is preserved only if 32 bit/sample, floating point precision data, is saved to a file. Such a high dynamic range (HDR) representation keeps all the bright lights and details in shadows without clamping and rounding errors. Exposure and any tonal corrections can be re-adjusted in HDR images without quality losses. And, most importantly, HDR images are the best for lighting scenes as environment maps - that is what we are going to show in this example. HDR image are written by PlotOptiX natively in tiff format, or you can use OpenCV to save such images in the Radiance file format (.hdr)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "from plotoptix import TkOptiX"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Generate some data - balls distributed on a sphere:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "n = 2000\n",
+    "r0 = 0.1\n",
+    "R = 4\n",
+    "\n",
+    "r = r0 + 0.3 * np.random.rand(n)\n",
+    "\n",
+    "x = np.random.normal(loc=0, scale=1.0, size=n)\n",
+    "y = np.random.normal(loc=0, scale=1.0, size=n)\n",
+    "z = np.random.normal(loc=0, scale=1.0, size=n)\n",
+    "xyz = np.stack((x, y, z)).T\n",
+    "for i in range(n): xyz[i] *= R / np.linalg.norm(xyz[i])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "A simple function to signal that ray tracing has finished:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "def accum_done(rt: TkOptiX) -> None:\n",
+    "    print(\"rt completed!\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Setup the ray tracing parameters. **Note** that AI denoiser is NOT applied. It could result with a visible seam at the line joining vertical edges of the image, when the image is displayed as an environment map. Instead, only a gamma correction is used and you need to accumulate enough data to reduce the noise."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt = TkOptiX(on_rt_accum_done=accum_done)\n",
+    "rt.set_param(\n",
+    "    min_accumulation_step=2,\n",
+    "    max_accumulation_frames=300\n",
+    ")\n",
+    "rt.set_uint(\"path_seg_range\", 4, 8) # a little more than the default (2,6) to improve the ambient occlusion impression\n",
+    "\n",
+    "exposure = 1; gamma = 2.2\n",
+    "rt.set_float(\"tonemap_exposure\", exposure)\n",
+    "rt.set_float(\"tonemap_gamma\", gamma)\n",
+    "rt.add_postproc(\"Gamma\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Setup lighting: one bright warm spherical light and some cold light from the ambient."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "rt.setup_light(\"l1\", pos=[1.5, 0, 1.5], color=[4.5, 4.2, 3.1], radius=0.75, in_geometry=False)\n",
+    "\n",
+    "rt.set_ambient([0.4, 0.6, 0.8])\n",
+    "rt.set_background(0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Setup cameras: one for making the panoramic view, one to show balls from inside the sphere, and one looking from a distance."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.setup_camera(\"cam1\", cam_type=\"Panoramic\", eye=[0, 0, 0], target=[0, 0, -1], up=[0, 1, 0])\n",
+    "\n",
+    "rt.setup_camera(\"cam2\", cam_type=\"DoF\",\n",
+    "                eye=[0, 0, 2], target=[0, 0, 0], up=[0, 1, 0],\n",
+    "                aperture_radius=0.2, fov=45, focal_scale=2.8)\n",
+    "\n",
+    "rt.setup_camera(\"cam3\", cam_type=\"DoF\",\n",
+    "                eye=[0, 0, 10], target=[0, 0, 0], up=[0, 1, 0],\n",
+    "                aperture_radius=0.07, fov=35, focal_scale=0.56)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Upload data points:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.set_data(\"points\", pos=xyz, r=r, c=0.7)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Open the GUI window:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "rt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Switch camera views. Let the ray tracing to converge with *cam1* active, this is the image to be used in the next example."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {
+    "scrolled": true
+   },
+   "outputs": [],
+   "source": [
+    "rt.set_current_camera(\"cam2\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "rt completed!\n"
+     ]
+    }
+   ],
+   "source": [
+    "rt.set_current_camera(\"cam1\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Save images with 8, 16 and 32 bit/sample color depths. 360 degree environment maps can be inspected with the script ``7_panorama_viewer.py`` or used by the notebook ``10_2_read_hdr_360deg_env_map.ipynb``. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.save_image(\"rt_output_8bps.jpg\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.save_image(\"rt_output_16bps.tif\", bps=\"Bps16\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.save_image(\"rt_output_32bps.tif\", bps=\"Bps32\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Save the image also in Radiance file, if you have OpenCV installed."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "float32 (1084, 1924, 3) 1.2066944\n"
+     ]
+    },
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import cv2\n",
+    "\n",
+    "a = rt.get_rt_output(\"Bps32\", \"BGR\") # ray tracing output in 32bps depth and channels order required for .hdr format\n",
+    "print(a.dtype, a.shape, np.max(a))   # note it is a floating point array, and strong lights are above 1.0 values\n",
+    "\n",
+    "cv2.imwrite('rt_output_32bps.hdr', a)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rt.close()"
+   ]
+  }
+ ],
+ "metadata": {
+  "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.7.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}