ENH: Improve camera clipping

- Change layer manager to add one camera per renderer
  and reset clipping per renderer
- Add tests for camera clipping
- Add utility function to take screenshots from RW to
  avoid unwanted behavior with existing VTK vtkWindowToImageFilter

Author: Thibault-Pelletier

Docs/index.md

@@ -13,6 +13,7 @@ introduction
 getting_started
 displayable_manager_reminders
 extension_architecture
+renderers_and_cameras
 examples
 api/library_root
 ```

Docs/renderers_and_cameras.md

@@ -0,0 +1,50 @@
+# Renderers and Cameras
+
+## First renderer
+
+The LayerDM library creates and manages a list of renderers. The first renderer is considered not managed by the
+library for compatibility reasons with existing 3D Slicer behaviors.
+
+The first renderer has an active camera and the active camera is supposed to be managed by a dedicated pipeline
+(usually a camera pipeline).
+
+## Managed renderer lifetime
+
+Pipelines will be grouped to renderers given their `GetRenderOrder` and `GetCustomCamera` values.
+
+If the renderer order is 0 and custom camera is set to default (nullptr), the pipelines will be be set to the default
+renderer. Otherwise, new renderers, managed by the library will be created and the pipelines will be attached to them.
+
+When new pipelines are added and removed from the DM, the created renderers will be updated.
+
+## Managed renderers and default camera
+
+If pipelines don't return any `GetCustomCamera` instances, they will use the default camera.
+
+The default camera is updating following two strategies:
+
+- Default strategy (3D camera)
+- Slice view strategy
+
+In the default synchronization strategy, when the first renderer's camera is updated, the default camera is updated
+to follow the first camera.
+
+For the slice view, the synchronization synchronizes the default camera to the current slice node view configuration.
+The Slice view's renderer 0 camera is not configured nor modified during camera changes.
+
+To simplify adding new pipelines, the sync adjusts the default camera to render in parallel projection in the correct
+orientation with respect to the current node configuration.
+
+Clipping range is configured to show all actors attached to the default camera.
+If clipping is required, then it should be done inside the specific pipeline.
+
+## Unmanaged cameras
+
+Pipelines with a `GetCustomCamera` cameras are managed by their pipelines or pipeline logics.
+
+The camera update can be made to update when the default camera is updated using the `OnDefaultCameraModified` method.
+
+## Reset clipping range
+
+To simplify integration, before request render is triggered, the cameras clipping range will be updated to encompass
+the visible actors as present in the different layers regardless of managed or unmanaged cameras.

LayerDM/MRMLDM/vtkMRMLLayerDMCameraSynchronizer.cxx

@@ -16,11 +16,15 @@
 // STL includes
 #include <array>
 
+/// \brief Abstract class for the camera strategies.
+/// Implements only the reset camera clipping range logic for the layer cameras.
+/// Other methods are expected to be implemented by deriving classes.
 class CameraSynchronizeStrategy
 {
 public:
-  explicit CameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera)
+  explicit CameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera, std::function<void()> invokeModifiedEvent)
     : m_camera(camera)
+    , m_invokeModifiedEvent{ std::move(invokeModifiedEvent) }
   {
   }
   virtual ~CameraSynchronizeStrategy() = default;
@@ -29,26 +33,25 @@ class CameraSynchronizeStrategy
 protected:
   vtkSmartPointer<vtkCamera> m_camera;
   vtkNew<vtkMRMLLayerDMObjectEventObserver> m_eventObserver;
+  std::function<void()> m_invokeModifiedEvent;
 };
 
+/// Default camera synchronization consists in updating the camera when the first renderer active camera is updated.
 class DefaultCameraSynchronizeStrategy : public CameraSynchronizeStrategy
 {
 public:
-  explicit DefaultCameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera, vtkRenderer* renderer)
-    : CameraSynchronizeStrategy(camera)
+  explicit DefaultCameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera, vtkRenderer* renderer, std::function<void()> invokeModifiedEvent)
+    : CameraSynchronizeStrategy(camera, std::move(invokeModifiedEvent))
     , m_renderer(renderer)
   {
     this->m_eventObserver->SetUpdateCallback(
       [this](vtkObject* object)
       {
-        if (object == this->m_observedCamera)
-        {
-          this->UpdateCamera();
-        }
         if (object == this->m_renderer)
         {
           this->ObserveActiveCamera();
         }
+        this->UpdateCamera();
       });
 
     this->m_eventObserver->UpdateObserver(nullptr, this->m_renderer, vtkCommand::ActiveCameraEvent);
@@ -57,11 +60,13 @@ class DefaultCameraSynchronizeStrategy : public CameraSynchronizeStrategy
 
   void UpdateCamera() override
   {
-    if (this->m_observedCamera)
+    if (!this->m_observedCamera)
     {
-      this->m_camera->DeepCopy(this->m_observedCamera);
-      this->m_camera->Modified();
+      return;
     }
+
+    this->m_camera->DeepCopy(this->m_observedCamera);
+    this->m_invokeModifiedEvent();
   }
 
 private:
@@ -76,18 +81,26 @@ class DefaultCameraSynchronizeStrategy : public CameraSynchronizeStrategy
 
     this->m_eventObserver->UpdateObserver(this->m_observedCamera, camera);
     this->m_observedCamera = camera;
-    this->UpdateCamera();
   }
 
   vtkWeakPointer<vtkRenderer> m_renderer;
   vtkWeakPointer<vtkCamera> m_observedCamera;
 };
 
+/// Synchronizes the default camera to the current slice node view configuration.
+/// The Slice renderer 0 camera is not configured nor modified during camera changes.
+/// All of its actors are set to render in 2D.
+///
+/// To simplify adding new pipelines, the sync adjusts the default camera to render in parallel projection in the correct
+/// orientation with respect to the current node configuration.
+///
+/// Clipping range is configured to show all actors attached to the default camera.
+/// If clipping is required, then it should be done inside the specific pipeline.
 class SliceViewCameraSynchronizeStrategy : public CameraSynchronizeStrategy
 {
 public:
-  explicit SliceViewCameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera, vtkMRMLSliceNode* sliceNode)
-    : CameraSynchronizeStrategy(camera)
+  explicit SliceViewCameraSynchronizeStrategy(const vtkSmartPointer<vtkCamera>& camera, vtkMRMLSliceNode* sliceNode, std::function<void()> invokeModifiedEvent)
+    : CameraSynchronizeStrategy(camera, std::move(invokeModifiedEvent))
     , m_sliceNode{ sliceNode }
   {
     this->m_eventObserver->SetUpdateCallback(
@@ -142,6 +155,7 @@ class SliceViewCameraSynchronizeStrategy : public CameraSynchronizeStrategy
     vtkMath::Cross(vRight.data(), vUp.data(), normal.data());
     double position[3] = { viewCenterRAS[0] + normal[0] * d, viewCenterRAS[1] + normal[1] * d, viewCenterRAS[2] + normal[2] * d };
     this->m_camera->SetPosition(position);
+    this->m_invokeModifiedEvent();
   }
 
 private:
@@ -199,13 +213,29 @@ void vtkMRMLLayerDMCameraSynchronizer::UpdateStrategy()
     return;
   }
 
+  const auto invokeModifiedEvent = [this]
+  {
+    if (this->m_isBlocked)
+    {
+      return;
+    }
+    this->Modified();
+  };
+
   if (auto sliceNode = vtkMRMLSliceNode::SafeDownCast(this->m_viewNode))
   {
-    this->m_syncStrategy = std::make_unique<SliceViewCameraSynchronizeStrategy>(this->m_defaultCamera, sliceNode);
+    this->m_syncStrategy = std::make_unique<SliceViewCameraSynchronizeStrategy>(this->m_defaultCamera, sliceNode, invokeModifiedEvent);
   }
   else
   {
-    this->m_syncStrategy = std::make_unique<DefaultCameraSynchronizeStrategy>(this->m_defaultCamera, this->m_renderer);
+    this->m_syncStrategy = std::make_unique<DefaultCameraSynchronizeStrategy>(this->m_defaultCamera, this->m_renderer, invokeModifiedEvent);
   }
   this->m_syncStrategy->UpdateCamera();
 }
+
+bool vtkMRMLLayerDMCameraSynchronizer::SetBlocked(bool isBlocked)
+{
+  bool wasBlocked = this->m_isBlocked;
+  m_isBlocked = isBlocked;
+  return wasBlocked;
+}

LayerDM/MRMLDM/vtkMRMLLayerDMCameraSynchronizer.h

@@ -38,6 +38,10 @@ class VTK_SLICER_LAYERDM_MODULE_MRMLDISPLAYABLEMANAGER_EXPORT vtkMRMLLayerDMCame
   /// The renderer active camera will be monitored for change when applicable (for instance 3D views).
   void SetRenderer(vtkRenderer* renderer);
 
+  /// Set camera update blocked.
+  /// @return previous blocked state.
+  bool SetBlocked(bool isBlocked);
+
 protected:
   vtkMRMLLayerDMCameraSynchronizer();
   ~vtkMRMLLayerDMCameraSynchronizer() override;
@@ -50,4 +54,5 @@ class VTK_SLICER_LAYERDM_MODULE_MRMLDISPLAYABLEMANAGER_EXPORT vtkMRMLLayerDMCame
   vtkWeakPointer<vtkRenderer> m_renderer;
   vtkWeakPointer<vtkMRMLAbstractViewNode> m_viewNode;
   std::unique_ptr<CameraSynchronizeStrategy> m_syncStrategy;
+  bool m_isBlocked{ false };
 };

LayerDM/MRMLDM/vtkMRMLLayerDMLayerManager.cxx

@@ -4,7 +4,6 @@
 #include "vtkMRMLLayerDMPipelineI.h"
 
 // VTK includes
-#include <vtkBoundingBox.h>
 #include <vtkCamera.h>
 #include <vtkObjectFactory.h>
 #include <vtkRenderWindow.h>
@@ -74,21 +73,6 @@ void vtkMRMLLayerDMLayerManager::RemovePipeline(vtkMRMLLayerDMPipelineI* pipelin
   this->UpdateLayers();
 }
 
-void vtkMRMLLayerDMLayerManager::ResetCameraClippingRange() const
-{
-  // Reset first renderer clipping range
-  if (auto defaultRenderer = this->GetDefaultRenderer())
-  {
-    defaultRenderer->ResetCameraClippingRange();
-  }
-
-  // Reset the managed renderers grouped by common cameras
-  for (const auto& pair : m_cameraRendererMap)
-  {
-    this->ResetRenderersCameraClippingRange(pair.second, this->ComputeRenderersVisibleBounds(pair.second));
-  }
-}
-
 void vtkMRMLLayerDMLayerManager::SetRenderWindow(vtkRenderWindow* renderWindow)
 {
   if (this->m_renderWindow == renderWindow)
@@ -101,14 +85,17 @@ void vtkMRMLLayerDMLayerManager::SetRenderWindow(vtkRenderWindow* renderWindow)
   this->UpdateLayers();
 }
 
-void vtkMRMLLayerDMLayerManager::SetDefaultCamera(const vtkSmartPointer<vtkCamera>& camera)
+void vtkMRMLLayerDMLayerManager::OnDefaultCameraModified(vtkCamera* defaultCamera) const
 {
-  if (this->m_defaultCamera == camera)
+  if (!defaultCamera)
   {
     return;
   }
-  this->m_defaultCamera = camera;
-  this->UpdateLayers();
+
+  for (const auto& camera : this->m_managedCameras)
+  {
+    camera->DeepCopy(defaultCamera);
+  }
 }
 
 vtkMRMLLayerDMLayerManager::vtkMRMLLayerDMLayerManager()
@@ -157,22 +144,17 @@ void vtkMRMLLayerDMLayerManager::AddMissingLayers()
   }
 }
 
-std::array<double, 6> vtkMRMLLayerDMLayerManager::ComputeRenderersVisibleBounds(const std::set<vtkWeakPointer<vtkRenderer>>& renderers)
+void vtkMRMLLayerDMLayerManager::ResetCameraClippingRange() const
 {
-  vtkBoundingBox bbox;
-
-  for (const auto& renderer : renderers)
+  if (const auto defaultRenderer = this->GetDefaultRenderer())
   {
-    if (!renderer)
-    {
-      continue;
-    }
-    bbox.AddBounds(renderer->ComputeVisiblePropBounds());
+    defaultRenderer->ResetCameraClippingRange();
   }
 
-  std::array<double, 6> bounds{};
-  bbox.GetBounds(bounds.data());
-  return bounds;
+  for (const auto& renderer : m_renderers)
+  {
+    renderer->ResetCameraClippingRange();
+  }
 }
 
 bool vtkMRMLLayerDMLayerManager::ContainsLayerKey(const LayerKey& key)
@@ -189,12 +171,12 @@ std::uintptr_t vtkMRMLLayerDMLayerManager::GetCameraId(vtkCamera* camera)
   return reinterpret_cast<std::uintptr_t>(camera);
 }
 
-vtkCamera* vtkMRMLLayerDMLayerManager::GetCameraForLayer(const LayerKey& key, const std::set<vtkWeakPointer<vtkMRMLLayerDMPipelineI>>& pipelines) const
+vtkCamera* vtkMRMLLayerDMLayerManager::GetCameraForLayer(const LayerKey& key, const std::set<vtkWeakPointer<vtkMRMLLayerDMPipelineI>>& pipelines)
 {
   auto cameraId = std::get<1>(key);
   if (cameraId == 0)
   {
-    return this->m_defaultCamera;
+    return nullptr;
   }
 
   for (const auto& pipeline : pipelines)
@@ -290,18 +272,6 @@ void vtkMRMLLayerDMLayerManager::RemoveRenderer(const vtkSmartPointer<vtkRendere
   this->m_renderers.erase(std::find(this->m_renderers.begin(), this->m_renderers.end(), renderer));
 }
 
-void vtkMRMLLayerDMLayerManager::ResetRenderersCameraClippingRange(const std::set<vtkWeakPointer<vtkRenderer>>& renderers, const std::array<double, 6>& bounds)
-{
-  for (const auto& renderer : renderers)
-  {
-    if (!renderer)
-    {
-      continue;
-    }
-    renderer->ResetCameraClippingRange(bounds.data());
-  }
-}
-
 void vtkMRMLLayerDMLayerManager::SynchronizePipelineRenderers()
 {
   for (const auto& pair : m_pipelineLayers)
@@ -368,18 +338,23 @@ void vtkMRMLLayerDMLayerManager::UpdateRendererCamera()
 {
   // Set the camera for the managed renderers
   // Layer 0 is unmanaged and its camera is left unchanged by the layer manager
-  // Pipelines with no explicit camera map to the default camera
+  // Pipelines with no explicit camera map to a new camera synchronized to the default camera on update
   // Pipelines with custom camera are grouped and use their cameras
-  this->m_cameraRendererMap.clear();
+  this->m_managedCameras.clear();
 
   int iRenderer = -1;
   for (const auto& pair : m_pipelineLayers)
   {
     if (iRenderer >= 0 && iRenderer < this->GetNumberOfRenderers())
     {
       auto camera = this->GetCameraForLayer(pair.first, pair.second);
+      if (!camera)
+      {
+        auto newCam = vtkSmartPointer<vtkCamera>::New();
+        this->m_managedCameras.emplace_back(newCam);
+        camera = newCam;
+      }
       this->m_renderers[iRenderer]->SetActiveCamera(camera);
-      this->m_cameraRendererMap[camera].emplace(this->m_renderers[iRenderer]);
     }
 
     iRenderer++;