Merge pull request #37 from rnd-team-dev/r0.15.0

R0.15.0

Author: robertsulej

CHANGELOG.rst

@@ -1,6 +1,23 @@
 Release history
 ===============
 
+`v0.15.0` - 2022-12-30
+----------------------
+
+**NOTE:** NVIDIA driver r520 or above is required.
+
+Added
+~~~~~
+
+- AI upsampler and HDR denoiser
+- Catmull-Rom curve primitive
+
+Changed
+~~~~~~~
+
+- binaries updated to OptiX 7.6
+- raytracing and callbacks workflow explained in the docs 
+
 `v0.14.4` - 2022-10-27
 ----------------------
 
@@ -536,6 +553,7 @@ Added
 - this changelog, markdown description content type tag for PyPI
 - use [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
+.. _`v0.15.0`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.15.0
 .. _`v0.14.4`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.14.4
 .. _`v0.14.3`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.14.3
 .. _`v0.14.2`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.14.2

README.rst

@@ -13,6 +13,8 @@ PlotOptiX
 
 **Data visualisation and ray tracing in Python based on NVIDIA OptiX framework.**
 
+`Docs <https://plotoptix.rnd.team>`__
+
 - Check what we are doing with PlotOptiX on `Behance <https://www.behance.net/RnDTeam>`__, `Facebook <https://www.facebook.com/rndteam>`__, and `Instagram <https://www.instagram.com/rnd.team.studio/>`__.
 - Join us on `Patreon <https://www.patreon.com/rndteam?fan_landing=true>`__ for news, release plans and hi-res content.
 
@@ -41,7 +43,7 @@ No need to write shaders, intersection algorithms, handle 3D scene technicalitie
 
 Check `examples on GitHub <https://github.com/rnd-team-dev/plotoptix/tree/master/examples>`__ for practical code samples and `documentation pages <https://plotoptix.rnd.team>`__ for a complete API reference.
 
-PlotOptiX is a set of CUDA shaders by `R&D Team <https://rnd.team>`_ wrapped in C#/C++ libraries with a Python API. PlotOptiX is based on `NVIDIA OptiX 7.5 <https://developer.nvidia.com/optix>`_ framework and makes use of RTX-capable GPU's.
+PlotOptiX is a set of CUDA shaders by `R&D Team <https://rnd.team>`_ wrapped in C#/C++ libraries with a Python API. PlotOptiX is based on `NVIDIA OptiX 7.6 <https://developer.nvidia.com/optix>`_ framework and makes use of RTX-capable GPU's.
 
 You can quickly display data in a simple plot:
 
@@ -61,7 +63,7 @@ Features
 - *geometries*: particles (spheres), parallelepipeds, parallelograms, tetrahedrons, linear segments, bezier curves, b-splines; *meshes*: shaded surface or wireframe, automatically generated from a parametric surface or f(x,y) data, or defined with vertices and faces, e.g. created with `pygmsh <https://github.com/nschloe/pygmsh>`__, or loaded from a file, e.g. supported by `trimesh <https://github.com/mikedh/trimesh>`__, or loaded from a Wavefront .obj file with a native loader
 - *materials*: flat, diffuse, reflective, refractive; including: light dispersion, surface roughness and metalness, volume scattering, and nested volumes
 - *light sources*: spherical and parallelogram, light emission in volumes, uniform environmental light or environment map
-- *post-processing*: tonal correction curves, levels adjustment, apply mask/overlay, AI denoiser
+- *post-processing*: tonal correction curves, levels adjustment, apply mask/overlay, AI denoiser and upsampler
 - *callbacks*: at the scene initialization, start and end of each frame raytracing, end of progressive accumulation
 - 8/16/32bps(hdr) image output to `numpy <http://www.numpy.org>`__ array, or save to popular image file formats
 - zero-copy access to GPU buffers wrapped in ndarrays: 8/32bps image, hit and object info, albedo, normals
@@ -73,8 +75,8 @@ Features
 System Requirements
 -------------------
 
-- a `CUDA-enabled GPU <https://developer.nvidia.com/cuda-gpus>`__ with compute capability 5.0 (Maxwell) to latest (Ampere);
-   - NVIDIA driver >= r515;
+- a `CUDA-enabled GPU <https://developer.nvidia.com/cuda-gpus>`__ with compute capability 5.0 (Maxwell) to latest (Ada Lovelace);
+   - NVIDIA driver >= r520;
 - **Python 3 64-bit**
 - Windows:
    - Framework .NET >= 4.8 (present in all modern Windows)

docs/conf.py

@@ -69,7 +69,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/images/flow_1.png

@@ -1,6 +1,42 @@
 NpOptiX - base, headless raytracer
 ==================================
 
+Ray-tracing and compute loop
+----------------------------
+
+Calculations in PlotOptiX are performed in threads parallel to the thread where you created :class:`plotoptix.NpOptiX`
+object. This design allows building interactive applications where heavy calulations are not blocking UI. There are two
+threads: one used for the ray tracing work done by OptiX engine (GPU work) and the second thread where any user calculations,
+e.g. scene updates, can be performed (usually using CPU).
+
+Callbacks are provided to synchrionize user code and OptiX tasks. The full workflow is illustrated in figures below, however it is best explained
+with `the example code <https://github.com/rnd-team-dev/plotoptix/blob/master/examples/2_animations_and_callbacks/1_surface_plot_animated.ipynb>`__.
+Note, code in calbacks should follow recommendations indicated in the Fig.1. and in the :ref:`callbacks` section. The
+basic rules are:
+
+* Access results stored in the output buffers only when they are frozen (``on_launch_finished``, ``on_rt_accum_done``) or use
+  ``on_rt_accum_done`` to synchronize your code with the end of ray tracing; otherwise buffers may be still empty or contain
+  undefined data.
+* Put lenghty calculations in ``on_scene_compute`` so they can run in parallel to ray tracing. Heavy computations in other callbacks
+  will degrade overall performance.
+* Do the scene and configuration updates in ``on_rt_completed``. Note that most updates will reset the accumulation frame counter and the
+  whole ray tracing loop will be restarted, which will also clear the output buffers. 
+
+.. image:: images/flow_1.png
+   :alt: PlotOptiX compute flow
+
+Fig. 1. PlotOptiX computations flow. Details of the OptiX tast are ommited for clarity (i.e. scene compilation and multi-gpu management).
+
+.. image:: images/flow_2.png
+   :alt: PlotOptiX compute flow
+
+Fig. 2. Timeline of tasks and callbacks. Note, ray tracing work and ``on_scene_compute`` are launched in parallel threads and ``on_rt_completed``
+is executed when all other task finished.
+
+
+API reference
+-------------
+
 .. autoclass:: plotoptix.NpOptiX
 
 .. toctree::

docs/images/flow_2.png

@@ -1,3 +1,5 @@
+.. _callbacks:
+
 Callbacks
 =========