convenience method to update area light

Author: robertsulej

CHANGELOG.rst

@@ -1,6 +1,14 @@
 Release history
 ===============
 
+v0.8.2 - unreleased
+-------------------
+
+Added
+~~~~~
+
+- method to update parallelogram light using center/target 3D points and scalar lengths of u/v sides (missing in v0.8.0)
+
 `v0.8.1`_ - 2020-06-14
 ----------------------
 

README.rst

@@ -52,12 +52,12 @@ Features
 - pinhole camera, thin-lens camera with depth of field simulation, panoramic camera for making 360 deg environment maps
 - geometries: particle (sphere), parallelepiped, parallelogram, tetrahedron, bezier line, mesh (generated from parametric surface or f(x,y) plots; defined with vertices and faces; import from Wavefront .obj file)
 - parameterized materials shading: flat, diffuse, reflective, refractive; including: light dispersion, surface roughness, subsurface scattering, and nested volumes
-- spherical and parallelogram light sources
-- environmental light and ambient occlusion
+- spherical and parallelogram light sources, light emission in volumes
+- environmental light, environmetn maps, and ambient occlusion
 - post-processing: tonal correction curves, levels adjustment, apply mask/overlay, AI denoiser
 - GPU acceleration using RT Cores and everything else what comes with `OptiX 7 <https://developer.nvidia.com/optix>`__
 - callbacks at the scene initialization, start and end of each frame raytracing, end of progressive accumulation
-- 8/16/32bps image output to `numpy <http://www.numpy.org>`__ array, or save to popular image file formats
+- 8/16/32bps(hdr) image output to `numpy <http://www.numpy.org>`__ array, or save to popular image file formats
 - hardware accelerated video output to MP4 file format using `NVENC 9.0 <https://developer.nvidia.com/nvidia-video-codec-sdk>`__
 - Tkinter based simple GUI window or headless raytracer
 - configurable multi-GPU support

docs/npoptix_lights.rst

@@ -23,6 +23,7 @@ Setup and update lighting
 .. automethod:: plotoptix.NpOptiX.setup_parallelogram_light
 .. automethod:: plotoptix.NpOptiX.setup_area_light
 .. automethod:: plotoptix.NpOptiX.update_light
+.. automethod:: plotoptix.NpOptiX.update_area_light
 .. automethod:: plotoptix.NpOptiX.light_fit
 
 Read back light properties

plotoptix/__init__.py

@@ -12,8 +12,8 @@
 
 __author__  = "Robert Sulej, R&D Team <dev@rnd.team>"
 __status__  = "beta"
-__version__ = "0.8.1"
-__date__    = "14 June 2020"
+__version__ = "0.8.2"
+__date__    = "22 June 2020"
 
 import logging
 

plotoptix/npoptix.py

@@ -2880,7 +2880,7 @@ def update_light(self, name: str,
 
         Parameters
         ----------
-        name : string, optional
+        name : string
             Name of the light.
         pos : array_like, optional
             3D position.
@@ -2930,6 +2930,74 @@ def update_light(self, name: str,
             self._logger.error(msg)
             if self._raise_on_error: raise RuntimeError(msg)
 
+    def update_area_light(self, name: str,
+                          center: Optional[Any] = None, target: Optional[Any] = None,
+                          u: Optional[float] = None, v: Optional[float] = None,
+                          color: Optional[Any] = None) -> None:
+        """Setup new area (parallelogram) light.
+
+        Convenience method to update parallelogram light with ``center`` and ``target`` 3D points,
+        and scalar lenghts of sides ``u`` and ``v``.
+
+        Parameters
+        ----------
+        name : string
+            Name of the new light.
+        center : array_like, optional
+            3D position of the light center.
+        target : array_like, optional
+            3D position of the light target.
+        u : float, optional
+            Horizontal side length.
+        v : float, optional
+            Vertical side length.
+        color : Any, optional
+            RGB color of the light; single value is gray, array_like is RGB
+            color components. Color value range is (0; inf) as it means the
+            light intensity.
+        """
+        if name is None: raise ValueError()
+
+        if not isinstance(name, str): name = str(name)
+
+        if name not in self.light_handles:
+            msg = "Light %s does not exists." % name
+            self._logger.error(msg)
+            if self._raise_on_error: raise ValueError(msg)
+            return
+
+        if u is None:
+            u = np.linalg.norm(self.get_light_u(name))
+
+        if v is None:
+            v = np.linalg.norm(self.get_light_v(name))
+
+        if center is None:
+            center = self.get_light_pos(name) + 0.5 * (self.get_light_u(name) + self.get_light_v(name))
+
+        if target is None:
+            n = np.cross(self.get_light_u(name), self.get_light_v(name))
+            target = center + 100 * n
+
+        center = _make_contiguous_vector(center, 3)
+        target = _make_contiguous_vector(target, 3)
+
+        n = target - center
+        n = n / np.linalg.norm(n)
+
+        uvec = np.cross(n, [0, 1, 0])
+        uvec = uvec / np.linalg.norm(uvec)
+
+        vvec = np.cross(uvec, n)
+        vvec = vvec / np.linalg.norm(vvec)
+
+        uvec *= -u
+        vvec *= v
+
+        pos = center - 0.5 * (vvec + uvec)
+
+        self.update_light(name, pos=pos, color=color, u=uvec, v=vvec)
+
     def light_fit(self, light: str,
                   camera: Optional[str] = None,
                   horizontal_rot: float = 45,

setup.py

@@ -119,7 +119,7 @@ def get_tag(self):
 
 
 setup(name='plotoptix',
-      version='0.8.1',
+      version='0.8.2',
       url='https://rnd.team/project/plotoptix',
       project_urls={
           'Documentation': 'https://plotoptix.rnd.team',