Merge pull request #57 from rnd-team-dev/r0.18.0

R0.18.0

Author: robertsulej

CHANGELOG.rst

@@ -1,13 +1,38 @@
 Release history
 ===============
 
+`v0.18.1` - 2024-03-09
+----------------------
+
+Added
+~~~~~
+
+- Intel Open Image Denoiser libraries: HDR/LDR, supporting RGB/Albedo/Normal inputs.
+- Optional counting of transmission path segments (previously they were counted always and included in
+  the segment range limits).
+- Const-size geometry primitives (same radii, or u/v/w vectors for all data points) with much lower memory
+  consumption, beneficial e.g. for volume plots.
+- Volume coloring material for semi-transparent volume visualization (experimental).
+
+Changed
+~~~~~~~
+
+- Reviewed and improved camera kernels.
+
+Fixed
+~~~~~
+
+- Require min SM 5.0 instead of 6.0.
+- Minor lighting issues with masked transparency materials.
+
+
 `v0.17.1` - 2023-10-06
 ----------------------
 
 Added
 ~~~~~
 
-- Noise-balanced work distribution: absolute and relative noise modes 
+- Noise-balanced work distribution: absolute and relative noise modes.
 
 
 `v0.17.0` - 2023-08-18
@@ -617,6 +642,7 @@ Added
 - this changelog, markdown description content type tag for PyPI
 - use [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 
+.. _`v0.18.1`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.18.1
 .. _`v0.17.1`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.17.1
 .. _`v0.17.0`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.17.0
 .. _`v0.16.1`: https://github.com/rnd-team-dev/plotoptix/releases/tag/v0.16.1

LICENSE.txt

@@ -25,6 +25,9 @@ The Software includes binary libraries from the following sources. Before procee
 4. .NET components:
    MIT License (https://github.com/dotnet)
 
+5. Intel Open Image Denoise:
+   Apache License 2.0 (https://github.com/OpenImageDenoise/oidn/blob/master/LICENSE.txt)
+
 Section II: The Software End User License Agreement
 ---------------------------------------------------
 

MANIFEST.in

@@ -13,10 +13,10 @@ PlotOptiX
 
 **Data visualisation and ray tracing in Python based on NVIDIA OptiX framework.**
 
-`Docs <https://plotoptix.rnd.team>`__
+`Documentation <https://plotoptix.rnd.team>`__
 
-- Have a look what is possible with PlotOptiX: `Behance <https://www.behance.net/RnDTeam>`__, `Instagram <https://www.instagram.com/rnd.team.studio/>`__, and `Facebook <https://www.facebook.com/rndteam>`__.
-- Join us on `Patreon <https://www.patreon.com/rndteam?fan_landing=true>`__ for news, release plans and hi-res content.
+- Sample images created with PlotOptiX: `Behance <https://www.behance.net/RnDTeam>`__, `Instagram <https://www.instagram.com/rnd.team.studio/>`__, and `Facebook <https://www.facebook.com/rndteam>`__.
+- Join `Patreon <https://www.patreon.com/rndteam?fan_landing=true>`__ for news, release plans and hi-res content.
 
 PlotOptiX is a 3D `ray tracing <https://en.wikipedia.org/wiki/Ray_tracing_(graphics)>`__ package for Python, aimed at easy and aesthetic visualization
 of large datasets (and small as well). Data features can be represented in images as a position, size/thickness and color of primitives
@@ -44,7 +44,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.7 <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. It is based on `NVIDIA OptiX 7.7 <https://developer.nvidia.com/optix>`_ framework and makes use of RTX-capable GPU's.
 
 You can quickly display data in a simple plot:
 
@@ -64,7 +64,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 and upsampler
+- *post-processing*: tonal correction curves, levels adjustment, apply mask/overlay, AI denoisers and upsampler (OptiX native and Intel Open Image models)
 - *callbacks*: at the scene initialization, start and end of each frame raytracing, end of progressive accumulation
 - 8/16/32bps(hdr) image output to `numpy <https://numpy.org>`__ array, or save to popular image file formats
 - zero-copy access to GPU buffers wrapped in ndarrays: 8/32bpc image, hit and object info, albedo, normals

README.rst

@@ -38,6 +38,8 @@ Camera
 
 .. autoclass:: plotoptix.enums.Camera
     :members:
+.. autoclass:: plotoptix.enums.WorkDistribution
+    :members:
 
 Lights
 ------

docs/enums.rst

@@ -16,6 +16,7 @@ Create, load, update, and remove a plot
 .. automethod:: plotoptix.NpOptiX.update_mesh
 .. automethod:: plotoptix.NpOptiX.load_mesh_obj
 .. automethod:: plotoptix.NpOptiX.load_merged_mesh_obj
+.. automethod:: plotoptix.NpOptiX.load_multiple_mesh_obj
 .. automethod:: plotoptix.NpOptiX.set_displacement
 .. automethod:: plotoptix.NpOptiX.load_displacement
 .. automethod:: plotoptix.NpOptiX.delete_geometry

docs/npoptix_geometry.rst

@@ -4,26 +4,26 @@ Utility functions
 Colors
 ------
 
-.. automethod:: plotoptix.utils.make_color
-.. automethod:: plotoptix.utils.make_color_2d
-.. automethod:: plotoptix.utils.map_to_colors
+.. autofunction:: plotoptix.utils.make_color
+.. autofunction:: plotoptix.utils.make_color_2d
+.. autofunction:: plotoptix.utils.map_to_colors
 
 Image I/O
 ---------
 
-.. automethod:: plotoptix.utils.get_image_meta
-.. automethod:: plotoptix.utils.read_image
+.. autofunction:: plotoptix.utils.get_image_meta
+.. autofunction:: plotoptix.utils.read_image
 
 Noise generators
 ----------------
 
-.. automethod:: plotoptix.utils.simplex
+.. autofunction:: plotoptix.utils.simplex
 
 Miscellaneous
 -------------
 
-.. automethod:: plotoptix.utils.get_gpu_architecture
-.. automethod:: plotoptix.utils.set_gpu_architecture
+.. autofunction:: plotoptix.utils.get_gpu_architecture
+.. autofunction:: plotoptix.utils.set_gpu_architecture
 
 .. toctree::
    :caption: API Reference

docs/utils.rst

@@ -39,44 +39,51 @@ def main():
 
     # Create plots:
 
-    optix = TkOptiX() # create and configure, show the window later
+    rt = TkOptiX() # create and configure, show the window later
 
     # accumulate up to 30 frames (override default of 4 frames)
-    optix.set_param(max_accumulation_frames=30)
+    rt.set_param(max_accumulation_frames=30)
 
     # white background
-    optix.set_background(0.99)
+    rt.set_background(0.99)
 
-    # add plots, ParticleSet geometry is default
-    optix.set_data("particles", pos=particles, r=rp, c=cp)
-    # and use geom parameter to specify cubes geometry;
+    # add plots, ParticleSet geometry with variable radius is default
+    rt.set_data("particles", pos=particles, r=rp, c=cp)
+    #rt.set_data("particles", pos=particles, r=0.02, c=cp, geom="ParticleSetConstSize")
+    
+    # use geom parameter to specify cubes geometry;
     # Parallelepipeds can be described precisely with U, V, W vectors,
     # but here we only provide the r parameter - this results with
-    # randomly rotated cubes of U, V, W lenghts equal to r 
-    optix.set_data("cubes", pos=cubes, r=rc, c=cc, geom="Parallelepipeds")
+    # randomly rotated cubes of U, V, W lenghts equal to r
+    rt.set_data("cubes", pos=cubes, r=rc, c=cc, geom="Parallelepipeds")
 
     # tetrahedrons look good as well, and they are really fast on RTX devices:
-    #optix.set_data("tetras", pos=cubes, r=rc, c=cc, geom="Tetrahedrons")
+    #rt.set_data("tetras", pos=cubes, r=rc, c=cc, geom="Tetrahedrons")
 
     # if you prefer cubes aligned with xyz:
-    #optix.set_data("cubes", pos=cubes, r=rc, c=cc, geom="Parallelepipeds", rnd=False)
+    #rt.set_data("cubes", pos=cubes, r=rc, c=cc, geom="Parallelepipeds", rnd=False)
 
-    # or if you'd like some edges fixed:
+    # or if you'd like to fix some edges:
     #v = np.zeros((rc.shape[0], 3)); v[:,1] = rc[:]
-    #optix.set_data("cubes", pos=cubes, u=[0.05,0,0], v=v, w=[0,0,0.05], c=cc, geom="Parallelepipeds")
+    #rt.set_data("cubes", pos=cubes, u=[0.05,0,0], v=v, w=[0,0,0.05], c=cc, geom="Parallelepipeds")
+    
+    # or maybe fix geometry of all primitives (note "ConstSize" in geom name):
+    #rt.set_data("cubes", pos=cubes, u=[0.02,0,0], v=[0,0.05,0], w=[0,0,0.08], c=cc, geom="ParallelepipedsConstSize")
+    # or, if cubes are needed, simpy:
+    #rt.set_data("cubes", pos=cubes, r=0.05, c=cc, geom="ParallelepipedsConstSize")
 
     # show coordinates box
-    optix.set_coordinates()
+    rt.set_coordinates()
 
     # show the UI window here - this method is calling some default
     # initialization for us, e.g. creates camera, so any modification
     # of these defaults should come below (or we provide on_initialization
     # callback)
-    optix.show()
+    rt.show()
 
     # camera and lighting configured by hand
-    optix.update_camera(eye=[5, 0, -8])
-    optix.setup_light("light1", color=10*np.array([0.99, 0.9, 0.7]), radius=2)
+    rt.update_camera(eye=[5, 0, -8])
+    rt.setup_light("light1", color=10*np.array([0.99, 0.9, 0.7]), radius=2)
 
     print("done")
 

examples/1_basics/1_scatter_plot_3d.py

@@ -0,0 +1,96 @@
+"""
+Opaque volume plot.
+
+This example shows how to:
+   - use const-sized cubes to plot volume shape (opaque)
+   - present data feature as a color
+   - use matplotlib color map (see https://matplotlib.org/users/colormaps.html)
+"""
+
+import numpy as np
+from plotoptix import TkOptiX
+from plotoptix.utils import map_to_colors  # feature to color conversion
+from plotoptix.enums import DenoiserKind   # deniser options
+
+from plotoptix.utils import simplex        # noise generator
+_ = simplex(np.zeros((3,3)))
+
+
+def main():
+
+    # Make some data first:
+
+    kx, ky, kz = (500, 500, 250)
+    scale = 0.02
+
+    x = np.linspace(0, kx, kx)
+    y = np.linspace(0, ky, ky)
+    z = np.linspace(0, kz, kz)
+    xv, yv, zv = np.meshgrid(x, y, z)
+    xyz = scale * np.stack((xv, yv, zv), axis=-1)
+
+    vol = simplex(xyz)
+    print("Volume shape:", vol.shape)
+    
+    vmin, vmax = (-0.1, 0.1)
+
+    selection = (vol > vmin) & (vol < vmax)
+    sel_cubes = xyz[selection]
+    colors = map_to_colors(vol[selection], "Reds")
+
+    print(f"{np.sum(selection) / 1.0e6 :.1f}M seleced cells.")
+
+    # Setup ray-tracing:
+
+    rt = TkOptiX() # create and configure, show the window later
+
+    max_frames = 32 # accumulation frames (rays/pixel in other words)
+    rt.set_param(
+        min_accumulation_step=4,
+        max_accumulation_frames=max_frames
+    )
+
+    rt.set_float("scene_epsilon", 1.0e-05) # expect small cubes, lower epsilon to ensure details are correctly presented
+    rt.set_uint("path_seg_range", 4, 16)   # shape can have copmplex cavities that look better with multiple ray scattering
+
+    rt.set_background(0.99) # plot background color
+    rt.set_ambient(0.8)     # uniform environment light
+
+    # setup tone mapping and denoiser for best image quality
+    exposure = 1.1
+    gamma = 2.2
+    rt.set_float("tonemap_exposure", exposure)
+    rt.set_float("tonemap_gamma", gamma)
+    rt.set_uint("denoiser_start", max_frames) # denoise only the final image
+    rt.set_int("denoiser_kind", DenoiserKind.RgbAlbedoNormal.value)
+    rt.add_postproc("OIDenoiser")
+
+    rt.setup_camera("cam1",
+        eye=scale * np.array([kx/2, ky/2, 5*kz]),
+        target=0.5 * scale * np.array([kx, ky, kz]),
+        up=[0, 1, 0],
+        fov=35
+    )
+    
+    # Create plot:
+    
+    rt.set_data(
+        "cubes", pos=sel_cubes,
+        r=scale, # equivalent to: u=[scale, 0, 0], v=[0, scale, 0], w=[0, 0, scale],
+    
+        # constant color:
+        #c=0.9,
+    
+        # or use color data for each cell:
+        c=0.95 * colors,
+    
+        # all cells will have the same shape and size:
+        geom="ParallelepipedsConstSize"
+    )
+    
+    rt.show()
+
+    print("done")
+
+if __name__ == '__main__':
+    main()