First Stage of the KDE Rendering API

docs/examples/viz_kde_render.py

@@ -2,10 +2,11 @@
 ======================================================================
 Fury Kernel Density Estimation rendering Actor
 ======================================================================
-This example shows how to use the KDE actor. This is a special actor in Fury that works
-with post-processing effects to render kernel density estimations of a given set of points
-in real-time to the screen. For better understanding on KDEs, check this
-`Wikipedia page <https://en.wikipedia.org/wiki/Kernel_density_estimation>`_ about it.
+This example shows how to use the KDE effect. This is a feature in Fury
+that uses a post-processing stage to render kernel density estimations of a 
+given set of points in real-time to the screen. For better understanding 
+on KDEs, check this `Wikipedia page <https://en.wikipedia.org/wiki/Kernel_density_estimation>`_ 
+about it.
 
 For this example, you will only need the modules below:
 """
@@ -56,10 +57,8 @@ def normalize(array : np.array, min : float = 0.0, max : float = 1.0, axis : int
 manager = ShowManager(
     scene,
     "KDE Render",
-    (size[0],
-     size[1]))
+    size)
 
-manager.initialize()
 
 ####################################################################
 # ``numpy.random.rand`` will be used to generate random points, which
@@ -80,7 +79,6 @@ def normalize(array : np.array, min : float = 0.0, max : float = 1.0, axis : int
 
 bandwidths = normalize(np.random.rand(n_points, 1), 0.05, 0.2)
 
-
 ###################################################################
 # Now, for the KDE render, a special class is needed, the
 # ``EffectManager``. This class is needed to manage the post-processing
@@ -90,19 +88,22 @@ def normalize(array : np.array, min : float = 0.0, max : float = 1.0, axis : int
 # worry, none of this will need to be setup by you! Just call the
 # ``EffectManager`` like below, passing the manager to it:
 
-effects = EffectManager(manager)
+effects_m = EffectManager(manager)
 
 ###################################################################
-# After having the ``effects`` setup, just call the kde actor method
-# from it, passing the points, bandwidth, and other optional options
-# if wished, like the kernel to be used or the colormap desired.
-# The colormaps are by default taken from *matplotlib*, but a
-# custom one can be passed. After calling it, just pass the actor
-# to the scene, and start it as usual.
-
-#kde_actor = effects.kde(points, bandwidths, kernel="gaussian", colormap="inferno")
-kde_effect = KDE(points, bandwidths, kernel="gaussian", colormap="inferno")
-effects.add(kde_effect)
+# After having the ``effects_m`` setup, we can add effects to it.
+# Here, we will use the ``KDE`` effect, that comes from ``fury.effects.effects``
+# module. When we call it, we pass the points, bandwidth, and other optional options
+# if wished, like the kernel to be used or the colormap desired. The available kernels
+# can be found inside KDE's description. The colormaps are by default taken from *matplotlib*, 
+# but a custom one can be passed. After calling it, it returns the KDE class, that will
+# then need to be added to the ``EffectManager`` with the ``add()`` method.
+
+kde_effect = KDE(points, bandwidths, kernel="exponential", colormap="inferno")
+effects_m.add(kde_effect)
+
+####################################################################
+# Having that setup, just start the rendering process to see the results, and we are done here!
 
 interactive = True
 

fury/effects/effect_manager.py

@@ -11,6 +11,7 @@ class EffectManager():
         Target manager that will render post processed actors."""
 
     def __init__(self, manager : ShowManager):
+        manager.initialize()
         self.scene = Scene()
         cam_params = manager.scene.get_camera()
         self.scene.set_camera(*cam_params)
@@ -22,43 +23,44 @@ def __init__(self, manager : ShowManager):
         self._n_active_effects = 0
         self._active_effects = {}
 
-    def add(self, effect):
+    def add(self, effect : callable):
+        """Add an effect to the EffectManager. The effect must have a callable property,
+        that will act as the callback for the interactor. Check the KDE effect for reference.
+
+        Parameters
+        ----------
+        effect : callable
+            Effect to be added to the `EffectManager`.
+        """
         callback = partial(
             effect,
             off_manager=self.off_manager,
             on_manager=self.on_manager
         )
         if hasattr(effect, "apply"):
-            effect.apply(
-                off_manager = self.off_manager,
-                n_active_effects = self._n_active_effects
-            )
+            effect.apply(self)
 
         callback()
         callback_id = self.on_manager.add_iren_callback(callback, "RenderEvent")
 
-
-        self._active_effects[effect.textured_billboard] = (callback_id, effect.bill)
+        self._active_effects[effect] = (callback_id, effect._offscreen_actor)
         self._n_active_effects += 1
-        self.on_manager.scene.add(effect.textured_billboard)
-
-        return effect.textured_billboard
+        self.on_manager.scene.add(effect._onscreen_actor)
 
-    def remove_effect(self, effect_actor):
-        """Remove an existing effect from the effects manager.
-        Beware that the effect and the actor will be removed from the rendering pipeline
-        and shall not work after this action.
+    def remove_effect(self, effect):
+        """
+        Remove an existing effect from the effect manager.
 
         Parameters
         ----------
-        effect_actor : actor.Actor
-            Actor of effect to be removed.
+        effect_actor : callable
+            Effect to be removed.
         """
         if self._n_active_effects > 0:
-            self.on_manager.iren.RemoveObserver(self._active_effects[effect_actor][0])
-            self.off_manager.scene.RemoveActor(self._active_effects[effect_actor][1])
-            self.on_manager.scene.RemoveActor(effect_actor)
-            self._active_effects.pop(effect_actor)
+            self.on_manager.iren.RemoveObserver(self._active_effects[effect][0])
+            self.off_manager.scene.RemoveActor(self._active_effects[effect][1])
+            self.on_manager.scene.RemoveActor(effect._onscreen_actor)
+            self._active_effects.pop(effect)
             self._n_active_effects -= 1
         else:
             raise IndexError("Manager has no active effects.")