From d1b81ec6fa476d7f981153e040c38d62bb76d858 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Wed, 3 Jun 2026 19:24:57 -0600
Subject: [PATCH 01/64] Add OffscreenGLRenderer prototype (not yet wired into
 regression tests)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

OffscreenGLRenderer wraps SRInterface with a QOffscreenSurface +
QOpenGLContext + QOpenGLFramebufferObject so ViewScene can render
without a visible window. Compiles and context/FBO initialization works.

Not yet integrated into ViewSceneDialog: spire's VBOMan has a VBO-ID-
recycling bug where doFrame() runs the bootstrap (creates VBOs), GC frees
them, GL recycles those IDs, and a subsequent handleGeomObject call hits
addVBOAttributes with a recycled ID that still has a stale map entry with
different attribute layouts — throwing inside a noexcept context and
calling terminate().

Next steps:
1. Fix the stale-entry bug in spire VBOMan (remove map entry on GC free)
2. Wire OffscreenGLRenderer into ViewSceneDialog for regression mode
3. Add image-comparison tests using renderToImage()

Also: Screenshot::setImage() added for the eventual offscreen path.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/CMakeLists.txt   |   2 +
 .../Modules/Render/OffscreenGLRenderer.cc     | 123 ++++++++++++++++++
 .../Modules/Render/OffscreenGLRenderer.h      |  70 ++++++++++
 src/Interface/Modules/Render/Screenshot.h     |   1 +
 src/Interface/Modules/Render/ViewScene.cc     |   1 -
 5 files changed, 196 insertions(+), 1 deletion(-)
 create mode 100644 src/Interface/Modules/Render/OffscreenGLRenderer.cc
 create mode 100644 src/Interface/Modules/Render/OffscreenGLRenderer.h

diff --git a/src/Interface/Modules/Render/CMakeLists.txt b/src/Interface/Modules/Render/CMakeLists.txt
index 449c718938..2e8ee9529f 100644
--- a/src/Interface/Modules/Render/CMakeLists.txt
+++ b/src/Interface/Modules/Render/CMakeLists.txt
@@ -60,6 +60,7 @@ SET(Interface_Modules_Render_HEADERS_TO_MOC
   ViewSceneControlsDock.h
   ViewOspraySceneConfig.h
   GLWidget.h
+  OffscreenGLRenderer.h
   GLContextPlatformCompatibility.h
   Screenshot.h
   OsprayViewerDialog.h
@@ -97,6 +98,7 @@ SET(Interface_Modules_Render_SOURCES
   ViewSceneUtility.cc
   ViewSceneControlsDock.cc
   GLWidget.cc
+  OffscreenGLRenderer.cc
   Screenshot.cc
   OsprayViewerDialog.cc
   ViewOspraySceneConfig.cc
diff --git a/src/Interface/Modules/Render/OffscreenGLRenderer.cc b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
new file mode 100644
index 0000000000..8f59f5a138
--- /dev/null
+++ b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
@@ -0,0 +1,123 @@
+/*
+   For more information, please see: http://software.sci.utah.edu
+
+   The MIT License
+
+   Copyright (c) 2020 Scientific Computing and Imaging Institute,
+   University of Utah.
+
+   Permission is hereby granted, free of charge, to any person obtaining a
+   copy of this software and associated documentation files (the "Software"),
+   to deal in the Software without restriction, including without limitation
+   the rights to use, copy, modify, merge, publish, distribute, sublicense,
+   and/or sell copies of the Software, and to permit persons to whom the
+   Software is furnished to do so, subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+*/
+
+#include <Interface/Modules/Render/OffscreenGLRenderer.h>
+#include <Interface/Modules/Render/ES/SRInterface.h>
+#include <gl-platform/GLPlatform.hpp>
+#include <Core/Logging/Log.h>
+
+namespace SCIRun {
+namespace Gui {
+
+OffscreenGLRenderer::OffscreenGLRenderer(int width, int height)
+{
+  QSurfaceFormat format;
+  format.setDepthBufferSize(24);
+  format.setProfile(QSurfaceFormat::CoreProfile);
+  format.setVersion(2, 1);
+
+  surface_ = new QOffscreenSurface;
+  surface_->setFormat(format);
+  surface_->create();
+
+  if (!surface_->isValid())
+  {
+    logWarning("OffscreenGLRenderer: failed to create offscreen surface");
+    return;
+  }
+
+  context_ = new QOpenGLContext;
+  context_->setFormat(format);
+  if (!context_->create())
+  {
+    logWarning("OffscreenGLRenderer: failed to create OpenGL context");
+    return;
+  }
+
+  if (!context_->makeCurrent(surface_))
+  {
+    logWarning("OffscreenGLRenderer: failed to make context current");
+    return;
+  }
+
+  spire::glPlatformInit();
+
+  QOpenGLFramebufferObjectFormat fboFormat;
+  fboFormat.setAttachment(QOpenGLFramebufferObject::Depth);
+  fbo_ = new QOpenGLFramebufferObject(width, height, fboFormat);
+  fbo_->bind();
+
+  spire_.reset(new Render::SRInterface());
+  spire_->setContext(context_);
+  spire_->eventResize(static_cast<size_t>(width), static_cast<size_t>(height));
+
+  context_->doneCurrent();
+  initialized_ = true;
+}
+
+OffscreenGLRenderer::~OffscreenGLRenderer()
+{
+  if (context_ && surface_)
+    context_->makeCurrent(surface_);
+
+  spire_.reset();
+  delete fbo_;
+  fbo_ = nullptr;
+
+  if (context_)
+    context_->doneCurrent();
+
+  delete context_;
+  delete surface_;
+}
+
+bool OffscreenGLRenderer::isValid() const
+{
+  return initialized_ && context_ && context_->isValid() && fbo_ && fbo_->isValid();
+}
+
+QImage OffscreenGLRenderer::renderToImage()
+{
+  if (!isValid())
+    return {};
+
+  context_->makeCurrent(surface_);
+  fbo_->bind();
+
+  // Force shader promises to resolve by using a short delta time (same trick
+  // GLWidget::paintGL uses when frameRequested_ is true).
+  spire_->doFrame(0.2);
+  // A second frame ensures all deferred passes have actually executed.
+  spire_->doFrame(0.2);
+
+  QImage img = fbo_->toImage();
+  context_->doneCurrent();
+  return img;
+}
+
+} // namespace Gui
+} // namespace SCIRun
diff --git a/src/Interface/Modules/Render/OffscreenGLRenderer.h b/src/Interface/Modules/Render/OffscreenGLRenderer.h
new file mode 100644
index 0000000000..480b38602c
--- /dev/null
+++ b/src/Interface/Modules/Render/OffscreenGLRenderer.h
@@ -0,0 +1,70 @@
+/*
+   For more information, please see: http://software.sci.utah.edu
+
+   The MIT License
+
+   Copyright (c) 2020 Scientific Computing and Imaging Institute,
+   University of Utah.
+
+   Permission is hereby granted, free of charge, to any person obtaining a
+   copy of this software and associated documentation files (the "Software"),
+   to deal in the Software without restriction, including without limitation
+   the rights to use, copy, modify, merge, publish, distribute, sublicense,
+   and/or sell copies of the Software, and to permit persons to whom the
+   Software is furnished to do so, subject to the following conditions:
+
+   The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+   FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE.
+*/
+
+#ifndef INTERFACE_MODULES_RENDER_OFFSCREENGLRENDERER_H
+#define INTERFACE_MODULES_RENDER_OFFSCREENGLRENDERER_H
+
+#include <QImage>
+#include <QOffscreenSurface>
+#include <QOpenGLContext>
+#include <QOpenGLFramebufferObject>
+#include <Interface/Modules/Render/ES/RendererInterfaceFwd.h>
+#include <Interface/Modules/Render/share.h>
+
+namespace SCIRun {
+namespace Gui {
+
+// Wraps SRInterface with a QOffscreenSurface + QOpenGLContext so regression
+// tests can render without a visible window or display server.
+class SCISHARE OffscreenGLRenderer
+{
+public:
+  OffscreenGLRenderer(int width, int height);
+  ~OffscreenGLRenderer();
+
+  bool isValid() const;
+  QOpenGLContext* context() const { return context_; }
+  Render::RendererPtr renderer() const { return spire_; }
+
+  // Renders one frame and returns the pixel data. Returns a null QImage if
+  // the context is not valid.
+  QImage renderToImage();
+
+private:
+  QOffscreenSurface*         surface_ {nullptr};
+  QOpenGLContext*            context_ {nullptr};
+  QOpenGLFramebufferObject*  fbo_     {nullptr};
+  Render::RendererPtr        spire_;
+  bool                       initialized_ {false};
+
+  void initialize();
+};
+
+} // namespace Gui
+} // namespace SCIRun
+
+#endif // INTERFACE_MODULES_RENDER_OFFSCREENGLRENDERER_H
diff --git a/src/Interface/Modules/Render/Screenshot.h b/src/Interface/Modules/Render/Screenshot.h
index 7e69446e5a..e0cb40b420 100644
--- a/src/Interface/Modules/Render/Screenshot.h
+++ b/src/Interface/Modules/Render/Screenshot.h
@@ -46,6 +46,7 @@ namespace SCIRun
     public:
       explicit Screenshot(QOpenGLWidget *glwidget, QObject *parent = nullptr);
       void takeScreenshot();
+      void setImage(const QImage& img) { screenshot_ = img; } // used by offscreen renderer path
       QImage getScreenshot();
       void saveScreenshot(const QString& filename);
       Modules::Render::RGBMatrices toMatrix() const;
diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 5942e9ec13..86a4320965 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -2861,7 +2861,6 @@ void ViewSceneDialog::takeScreenshot()
 {
   if (!impl_->screenshotTaker_)
     impl_->screenshotTaker_ = new Screenshot(impl_->mGLWidget, this);
-
   impl_->screenshotTaker_->takeScreenshot();
 }
 

From 8b40b03c6acd2111520f9c3cbf6f22cf6e497ebe Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 01:02:49 -0600
Subject: [PATCH 02/64] Wire OffscreenGLRenderer into regression mode; fix
 spire buffer-recycling bugs
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All 61 Renderer regression tests now pass using offscreen rendering
(QOffscreenSurface + FBO) instead of a visible GLWidget. No window,
no display server, no window-system timing races.

Three spire/SRInterface fixes were required to make this work:

1. VBOMan::addInMemoryVBO — erase any stale map entry for a freshly
   generated buffer name before addVBOAttributes. GL guarantees a new
   glGenBuffers name is unused, so a lingering entry is always stale
   (the buffer was deleted by font rendering or the IBO manager, which
   call glGenBuffers/glDeleteBuffers directly and share GL's single
   buffer-name namespace). Previously this threw "Differing attributes"
   inside a noexcept context and aborted.

2. IBOMan::addInMemoryIBO — same fix; its insert() silently kept stale
   primitive data on a recycled id rather than crashing, a latent
   rendering bug.

3. SRInterface::addIBOToEntity — skip the IBO component when hasIBO()
   returns 0 instead of letting getIBOData() throw. A named IBO can be
   legitimately absent (GC'd between geometry updates); a missing index
   buffer should drop the pass, not abort.

ViewSceneDialog now constructs an OffscreenGLRenderer when
isRegressionMode() is set; the window path is unchanged. mGLWidget is
null in offscreen mode, so its dereferences are guarded.

Residual flakiness is down to ~0-1 of 61 per full run (different test
each time, all pass in isolation) — the same environmental async-
teardown class tracked separately, no longer a rendering problem.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Externals/spire/es-render/IBOMan.cpp      |  5 ++
 src/Externals/spire/es-render/VBOMan.cpp      |  9 ++
 .../Modules/Render/ES/SRInterface.cc          |  8 +-
 src/Interface/Modules/Render/ViewScene.cc     | 87 +++++++++++++------
 4 files changed, 82 insertions(+), 27 deletions(-)

diff --git a/src/Externals/spire/es-render/IBOMan.cpp b/src/Externals/spire/es-render/IBOMan.cpp
index 6545ac0868..dc2a614613 100644
--- a/src/Externals/spire/es-render/IBOMan.cpp
+++ b/src/Externals/spire/es-render/IBOMan.cpp
@@ -71,6 +71,11 @@ GLuint IBOMan::addInMemoryIBO(void* iboData, size_t iboDataSize, GLenum primMode
   GL(glBufferData(GL_ELEMENT_ARRAY_BUFFER, static_cast<GLsizeiptr>(iboDataSize),
                   iboData, GL_STATIC_DRAW));
 
+  // A freshly generated buffer name is guaranteed by GL to be unused. If we
+  // still hold a record for this id it is stale (the buffer was deleted outside
+  // IBOMan's bookkeeping and GL recycled the name). insert() would silently
+  // keep the stale primitive data, so erase first to force the new values in.
+  mIBOData.erase(glid);
   mIBOData.insert(std::make_pair(glid, IBOData(assetName, primMode, primType, numPrims)));
 
   return glid;
diff --git a/src/Externals/spire/es-render/VBOMan.cpp b/src/Externals/spire/es-render/VBOMan.cpp
index 3675d3402e..b78dd42656 100644
--- a/src/Externals/spire/es-render/VBOMan.cpp
+++ b/src/Externals/spire/es-render/VBOMan.cpp
@@ -134,6 +134,15 @@ GLuint VBOMan::addInMemoryVBO(void* vboData, size_t vboDataSize,
   GL(glBufferData(GL_ARRAY_BUFFER, static_cast<GLsizeiptr>(vboDataSize),
                   vboData, GL_STATIC_DRAW));
 
+  // A freshly generated buffer name is guaranteed by GL to be unused. If we
+  // still hold a record for this id, it is stale: the underlying buffer was
+  // deleted outside VBOMan's bookkeeping (font rendering and the IBO manager
+  // call glGenBuffers/glDeleteBuffers directly and share GL's single
+  // buffer-name namespace) and GL has now recycled the name. Drop the stale
+  // entry so addVBOAttributes inserts the correct attributes instead of
+  // throwing on a mismatch.
+  mVBOData.erase(glid);
+
   addVBOAttributes(glid, attribs, assetName);
 
   return glid;
diff --git a/src/Interface/Modules/Render/ES/SRInterface.cc b/src/Interface/Modules/Render/ES/SRInterface.cc
index efe87e2e1e..fe158a5326 100644
--- a/src/Interface/Modules/Render/ES/SRInterface.cc
+++ b/src/Interface/Modules/Render/ES/SRInterface.cc
@@ -1200,8 +1200,14 @@ glm::vec2 ScreenParams::positionFromClick(int x, int y) const
       const std::weak_ptr<ren::IBOMan> im = mCore.getStaticComponent<ren::StaticIBOMan>()->instance_;
       if (const auto iboMan = im.lock()) {
         ren::IBO ibo;
-        const auto iboData = iboMan->getIBOData(iboName);
+        // hasIBO returns 0 (never a valid glGenBuffers id) when the named IBO is
+        // not present. Skip rather than letting getIBOData throw — the IBO can be
+        // legitimately absent if it was garbage collected between geometry
+        // updates, and a missing index buffer should drop the pass, not abort.
         ibo.glid = iboMan->hasIBO(iboName);
+        if (ibo.glid == 0)
+          return;
+        const auto iboData = iboMan->getIBOData(iboName);
         ibo.primType = iboData.primType;
         ibo.primMode = iboData.primMode;
         ibo.numPrims = iboData.numPrims;
diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 86a4320965..5ae847aaae 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -37,6 +37,7 @@
 #include <Interface/Modules/Render/ES/RendererInterface.h>
 #include <Interface/Modules/Render/ES/comp/StaticClippingPlanes.h>
 #include <Interface/Modules/Render/GLWidget.h>
+#include <Interface/Modules/Render/OffscreenGLRenderer.h>
 #include <Interface/Modules/Render/Screenshot.h>
 #include <Interface/Modules/Render/ViewScene.h>
 #include <Interface/Modules/Render/ViewScenePlatformCompatibility.h>
@@ -157,7 +158,8 @@ namespace Gui {
   class ViewSceneDialogImpl
   {
   public:
-    GLWidget*                             mGLWidget                     {nullptr};  ///< GL widget containing context.
+    GLWidget*                             mGLWidget                     {nullptr};  ///< GL widget containing context (null in offscreen mode).
+    std::unique_ptr<OffscreenGLRenderer>  offscreenRenderer_;                       ///< Used instead of mGLWidget in regression mode.
     Render::RendererWeakPtr               mSpire                        {};         ///< Instance of Spire.
     QToolBar*                             toolBar1_                      {nullptr};  ///< Tool bar.
     QToolBar*                             toolBar2_                      {nullptr};  ///< Tool bar.
@@ -389,20 +391,29 @@ ViewSceneDialog::ViewSceneDialog(const std::string& name, ModuleStateHandle stat
 
   setupScaleBar();
 
-  impl_->mGLWidget = new GLWidget(parentWidget());
-  QSurfaceFormat format;
-  format.setDepthBufferSize(24);
-  format.setProfile(QSurfaceFormat::CoreProfile);
-  format.setVersion(2, 1);
-  impl_->mGLWidget->setFormat(format);
+  if (Application::Instance().parameters()->isRegressionMode())
+  {
+    impl_->offscreenRenderer_ = std::make_unique<OffscreenGLRenderer>(800, 600);
+    impl_->mSpire = impl_->offscreenRenderer_->renderer();
+  }
+  else
+  {
+    impl_->mGLWidget = new GLWidget(parentWidget());
+    QSurfaceFormat format;
+    format.setDepthBufferSize(24);
+    format.setProfile(QSurfaceFormat::CoreProfile);
+    format.setVersion(2, 1);
+    impl_->mGLWidget->setFormat(format);
+
+    connect(impl_->mGLWidget, &GLWidget::fatalError, this, &ViewSceneDialog::fatalError);
+    connect(impl_->mGLWidget, &GLWidget::finishedFrame, this, &ViewSceneDialog::frameFinished);
+
+    impl_->mSpire = RendererWeakPtr(impl_->mGLWidget->getSpire());
+  }
 
-  connect(impl_->mGLWidget, &GLWidget::fatalError, this, &ViewSceneDialog::fatalError);
-  connect(impl_->mGLWidget, &GLWidget::finishedFrame, this, &ViewSceneDialog::frameFinished);
   connect(this, &ViewSceneDialog::mousePressSignalForGeometryObjectFeedback,
           this, &ViewSceneDialog::sendGeometryFeedbackToState);
 
-  impl_->mSpire = RendererWeakPtr(impl_->mGLWidget->getSpire());
-
   //Set background Color
   const auto colorStr = state_->getValue(Parameters::BackgroundColor).toString();
   impl_->bgColor_ = checkColorSetting(colorStr, Qt::black);
@@ -452,7 +463,7 @@ ViewSceneDialog::ViewSceneDialog(const std::string& name, ModuleStateHandle stat
 
   {
     impl_->toolbarHolder_ = new QMainWindow;
-    impl_->toolbarHolder_->setCentralWidget(impl_->mGLWidget);
+    impl_->toolbarHolder_->setCentralWidget(impl_->mGLWidget ? static_cast<QWidget*>(impl_->mGLWidget) : new QWidget);
 
     impl_->toolBar1_ = new QToolBar;
     impl_->toolBar1_->setMovable(true);
@@ -1184,7 +1195,9 @@ void ViewSceneDialog::updateModifiedGeometries()
 void ViewSceneDialog::updateModifiedGeometriesAndSendScreenShot()
 {
   newGeometryValue(false, false);
-  if (impl_->mGLWidget->isVisible() && impl_->mGLWidget->isValid())
+  if (impl_->offscreenRenderer_)
+    frameFinished();
+  else if (impl_->mGLWidget->isVisible() && impl_->mGLWidget->isValid())
     impl_->mGLWidget->requestFrame();
   else
     unblockExecution();
@@ -1206,9 +1219,14 @@ void ViewSceneDialog::newGeometryValue(bool forceAllObjectsToUpdate, bool clippi
   if (!spire)
     return;
 
-  if (!impl_->mGLWidget->isValid())
-    return;
-  spire->setContext(impl_->mGLWidget->context());
+  if (impl_->offscreenRenderer_)
+    spire->setContext(impl_->offscreenRenderer_->context());
+  else
+  {
+    if (!impl_->mGLWidget->isValid())
+      return;
+    spire->setContext(impl_->mGLWidget->context());
+  }
 
   if (forceAllObjectsToUpdate)
     spire->removeAllGeomObjects();
@@ -1386,7 +1404,8 @@ void ViewSceneDialog::closeEvent(QCloseEvent *evt)
   // future. Kept for future reference.
   //glLayout->removeWidget(impl_->mGLWidget);
 
-  impl_->mGLWidget->close();
+  if (impl_->mGLWidget)
+    impl_->mGLWidget->close();
   ModuleDialogGeneric::closeEvent(evt);
 }
 
@@ -1770,41 +1789,50 @@ void ViewSceneDialog::toggleLockColor(bool locked)
 
 void ViewSceneDialog::lockRotationToggled()
 {
-  impl_->mGLWidget->setLockRotation(impl_->lockRotation_->isChecked());
+  if (impl_->mGLWidget)
+    impl_->mGLWidget->setLockRotation(impl_->lockRotation_->isChecked());
   toggleLockColor(impl_->lockRotation_->isChecked() || impl_->lockPan_->isChecked() || impl_->lockZoom_->isChecked());
 }
 
 void ViewSceneDialog::lockPanningToggled()
 {
-  impl_->mGLWidget->setLockPanning(impl_->lockPan_->isChecked());
+  if (impl_->mGLWidget)
+    impl_->mGLWidget->setLockPanning(impl_->lockPan_->isChecked());
   toggleLockColor(impl_->lockRotation_->isChecked() || impl_->lockPan_->isChecked() || impl_->lockZoom_->isChecked());
 }
 
 void ViewSceneDialog::lockZoomToggled()
 {
-  impl_->mGLWidget->setLockZoom(impl_->lockZoom_->isChecked());
+  if (impl_->mGLWidget)
+    impl_->mGLWidget->setLockZoom(impl_->lockZoom_->isChecked());
   toggleLockColor(impl_->lockRotation_->isChecked() || impl_->lockPan_->isChecked() || impl_->lockZoom_->isChecked());
 }
 
 void ViewSceneDialog::lockAllTriggered()
 {
   impl_->lockRotation_->setChecked(true);
-  impl_->mGLWidget->setLockRotation(true);
   impl_->lockPan_->setChecked(true);
-  impl_->mGLWidget->setLockPanning(true);
   impl_->lockZoom_->setChecked(true);
-  impl_->mGLWidget->setLockZoom(true);
+  if (impl_->mGLWidget)
+  {
+    impl_->mGLWidget->setLockRotation(true);
+    impl_->mGLWidget->setLockPanning(true);
+    impl_->mGLWidget->setLockZoom(true);
+  }
   toggleLockColor(true);
 }
 
 void ViewSceneDialog::unlockAllTriggered()
 {
   impl_->lockRotation_->setChecked(false);
-  impl_->mGLWidget->setLockRotation(false);
   impl_->lockPan_->setChecked(false);
-  impl_->mGLWidget->setLockPanning(false);
   impl_->lockZoom_->setChecked(false);
-  impl_->mGLWidget->setLockZoom(false);
+  if (impl_->mGLWidget)
+  {
+    impl_->mGLWidget->setLockRotation(false);
+    impl_->mGLWidget->setLockPanning(false);
+    impl_->mGLWidget->setLockZoom(false);
+  }
   toggleLockColor(false);
 }
 
@@ -2859,6 +2887,13 @@ void ViewSceneDialog::sendBugReport()
 
 void ViewSceneDialog::takeScreenshot()
 {
+  if (impl_->offscreenRenderer_)
+  {
+    if (!impl_->screenshotTaker_)
+      impl_->screenshotTaker_ = new Screenshot(nullptr, this);
+    impl_->screenshotTaker_->setImage(impl_->offscreenRenderer_->renderToImage());
+    return;
+  }
   if (!impl_->screenshotTaker_)
     impl_->screenshotTaker_ = new Screenshot(impl_->mGLWidget, this);
   impl_->screenshotTaker_->takeScreenshot();

From 6b5e26b83ec3541f33281ef330f1723e85c29dbd Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 01:15:45 -0600
Subject: [PATCH 03/64] Restore quick_exit in regression mode; fix Windows CI
 artifact path
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two CI fixes from the first regression-tests-ci run:

1. async1/async2_multiData hung for 1500s (CTest timeout) on the mac-gui
   job. These streaming-test networks keep a data-push thread alive; the
   30s in-app regression timeout fires but teardown then blocks forever
   waiting on the thread. quick_exit() was originally added for exactly
   this (commit c51b53778) and I removed it on regression-tests-ci on the
   mistaken theory that it caused ViewScene flakiness. The real cause of
   that flakiness was window/timing + spire buffer bugs, now fixed by
   offscreen rendering — so restore quick_exit() and keep both wins.
   Verified locally: async1/async2 now exit in ~2s, all 61 Renderer
   tests still pass.

2. Windows test-log upload failed: results were written to C:\ which is
   outside the workspace (D:\a\SCIRun\SCIRun), so upload-artifact
   rejected the path. Write to $env:GITHUB_WORKSPACE instead and
   reference workspace-relative paths in the upload step.

Also added --timeout 300 to all ctest invocations as a safety net so a
future hang is killed in minutes instead of eating the 1500s default.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml           | 18 +++++++++---------
 .../Application/SCIRunMainWindowQtOverrides.cc | 10 ++++++++++
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index fb4212dbf2..c88f8f6a3b 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -242,7 +242,7 @@ jobs:
         if: ${{ inputs.run-unit-tests && runner.os != 'Windows' }}
         working-directory: bin/SCIRun
         run: |
-          ctest --output-on-failure -j4 -E "\.Test\.ExampleNetwork\." \
+          ctest --output-on-failure --timeout 300 -j4 -E "\.Test\.ExampleNetwork\." \
             2>&1 | tee /tmp/unit-test-results.txt
         continue-on-error: true
 
@@ -250,7 +250,7 @@ jobs:
         if: ${{ inputs.run-regression-tests && runner.os != 'Windows' }}
         working-directory: bin/SCIRun
         run: |
-          ctest --output-on-failure -j1 -R "\.Test\.ExampleNetwork\." \
+          ctest --output-on-failure --timeout 300 -j1 -R "\.Test\.ExampleNetwork\." \
             2>&1 | tee /tmp/regression-test-results.txt
         continue-on-error: true
 
@@ -259,8 +259,8 @@ jobs:
         working-directory: build/SCIRun
         shell: pwsh
         run: |
-          ctest --output-on-failure -j4 -C Release -E "\.Test\.ExampleNetwork\." `
-            2>&1 | Tee-Object -FilePath C:\unit-test-results.txt
+          ctest --output-on-failure --timeout 300 -j4 -C Release -E "\.Test\.ExampleNetwork\." `
+            2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\unit-test-results.txt"
         continue-on-error: true
 
       - name: Run regression tests (Windows)
@@ -268,8 +268,8 @@ jobs:
         working-directory: build/SCIRun
         shell: pwsh
         run: |
-          ctest --output-on-failure -j1 -C Release -R "\.Test\.ExampleNetwork\." `
-            2>&1 | Tee-Object -FilePath C:\regression-test-results.txt
+          ctest --output-on-failure --timeout 300 -j1 -C Release -R "\.Test\.ExampleNetwork\." `
+            2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\regression-test-results.txt"
         continue-on-error: true
 
       - name: Upload test logs (Unix)
@@ -288,9 +288,9 @@ jobs:
         with:
           name: test-results-${{ runner.os }}-${{ inputs.variant }}
           path: |
-            C:\unit-test-results.txt
-            C:\regression-test-results.txt
-            build\SCIRun\Testing\Temporary\LastTest.log
+            unit-test-results.txt
+            regression-test-results.txt
+            build/SCIRun/Testing/Temporary/LastTest.log
 
       - name: Upload installer (optional)
         if: ${{ inputs.artifact-name != '' }}
diff --git a/src/Interface/Application/SCIRunMainWindowQtOverrides.cc b/src/Interface/Application/SCIRunMainWindowQtOverrides.cc
index 3712f2ce6d..e6dc4ece69 100644
--- a/src/Interface/Application/SCIRunMainWindowQtOverrides.cc
+++ b/src/Interface/Application/SCIRunMainWindowQtOverrides.cc
@@ -25,6 +25,7 @@
    DEALINGS IN THE SOFTWARE.
 */
 
+#include <cstdlib>
 #include <Core/Application/Application.h>
 #include <Core/Application/Preferences/Preferences.h>
 #include <Core/Logging/Log.h>
@@ -65,6 +66,15 @@ void SCIRunMainWindow::exitApplication(int code)
   if (Application::Instance().parameters()->saveViewSceneScreenshotsOnQuit())
   { networkEditor_->saveImages(); }
   returnCode_ = code;
+  // In regression mode, use quick_exit to avoid hangs/crashes in async teardown
+  // paths where streaming execution threads outlive the GUI objects (e.g. the
+  // async streaming test networks). The exit code is still propagated to CTest.
+  // ViewScene test stability is handled separately by offscreen rendering, so
+  // this no longer affects renderer test fidelity.
+  if (Application::Instance().parameters()->isRegressionMode())
+  {
+    std::quick_exit(code);
+  }
   close();
   qApp->exit(code);
 }

From 8f2bc57a1bb3e4b2b835839a5865456d234c9c07 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 01:28:30 -0600
Subject: [PATCH 04/64] Guard ModuleWidget::updateDockWidgetProperties against
 null dockable_
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes two consistent segfaults exposed by the offscreen ViewScene path:
editMeshBBox_trans_check (SEGFAULT) and additionalTypesOfVSObjectsSaved
(flaky SIGABRT) — both ViewScene modules in regression mode.

updateDockWidgetProperties is connected to the dock's topLevelChanged
signal inside configDockable(). For a ViewScene dialog in regression mode,
configDockable calls dockable->setFloating(true), which fires that signal
synchronously — but dockable_ is assigned only after config() returns from
makeOptionsDialog(). The slot then dereferenced a null dockable_.

This was latent before but masked: with the real GLWidget central widget
the dock's floating-state transition didn't re-fire during setup. The
offscreen path (no GLWidget) changed the dialog's layout/visibility timing
enough to trigger the signal, surfacing the null deref. Both tests passed
on regression-tests-ci (windowed) and crashed only with offscreen.

Guard: return early when dockable_ is not yet set; configDockable handles
the initial show/float itself, and later user-driven dock/float events
arrive after dockable_ is valid.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Application/ModuleWidget.cc | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Interface/Application/ModuleWidget.cc b/src/Interface/Application/ModuleWidget.cc
index c2e5a58b50..3c71c38770 100644
--- a/src/Interface/Application/ModuleWidget.cc
+++ b/src/Interface/Application/ModuleWidget.cc
@@ -1211,6 +1211,13 @@ QDialog* ModuleWidget::dialog()
 
 void ModuleWidget::updateDockWidgetProperties(bool isFloating)
 {
+  // This slot is connected to the dock's topLevelChanged signal inside
+  // configDockable(), which can fire (via setFloating) before makeOptionsDialog
+  // assigns dockable_. Bail out until the member is set; configDockable handles
+  // the initial show/float itself.
+  if (!dockable_)
+    return;
+
   if (isFloating)
   {
     dockable_->setWindowFlags(Qt::Window);

From 1f1127f2b3860ec6e528d0867958b25a89ff7bd4 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 07:44:45 -0600
Subject: [PATCH 05/64] Fix parallel regression crashes; enable parallel CI;
 add coverage tooling

The headline fix: ModuleWidget::dockable_ was an uninitialized raw pointer.
updateDockWidgetProperties() (connected to the dock's topLevelChanged signal
in configDockable) can fire before makeOptionsDialog assigns dockable_; the
slot null-checks it, but garbage in an uninitialized pointer passes the null
check and segfaults in QWidget::setWindowFlags. This was masked serially
(benign stack garbage) but crashed random tests under parallel load with
different memory contents. Null-initializing dockable_ makes the existing
guard correct and eliminates all the parallel segfaults (calcBundleDifference,
ResizeMatrixTest, PrintStringIntoString, uncertaintyTensorGlyphs, etc.).

Also fixed for parallel safety:
- Defer session-trace init to readCommandLine and skip it in regression mode.
  The trace DB wrote to a fixed shared path, causing SQLite corruption and
  SIGBUS (mmap) when test processes ran concurrently. Guard the destructor's
  endSession() since session() is now null in regression mode.
- Testing/CMakeLists.txt: give every ViewScene-containing network a shared
  RESOURCE_LOCK (gpu) so CTest never schedules two GPU tests at once; bump the
  in-app regression timeout 30->60s for headroom under load.
- reusable-build.yml: run the regression ctest step at -j3 (was -j1).

Coverage tooling (requested):
- ENABLE_COVERAGE CMake option: Clang source-based instrumentation
  (-fprofile-instr-generate -fcoverage-mapping) on both compile and link flags
  (the pre-existing ENABLE_GCOV_DATA_FILES set compile flags only).
- scripts/coverage.sh: runs ctest with per-process LLVM_PROFILE_FILE, merges
  with llvm-profdata, reports via llvm-cov (text + HTML) across all dylibs.

Results: full suite at -j6 went from ~4 segfaults + bus error to 0 crashes;
at -j3 (CI target) it is clean.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml     |  4 +-
 scripts/coverage.sh                      | 82 ++++++++++++++++++++++++
 src/CMakeLists.txt                       | 19 ++++++
 src/Core/Application/Application.cc      | 25 +++++++-
 src/Interface/Application/ModuleWidget.h |  6 +-
 src/Testing/CMakeLists.txt               | 19 +++++-
 6 files changed, 148 insertions(+), 7 deletions(-)
 create mode 100755 scripts/coverage.sh

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index c88f8f6a3b..3f93496107 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -250,7 +250,7 @@ jobs:
         if: ${{ inputs.run-regression-tests && runner.os != 'Windows' }}
         working-directory: bin/SCIRun
         run: |
-          ctest --output-on-failure --timeout 300 -j1 -R "\.Test\.ExampleNetwork\." \
+          ctest --output-on-failure --timeout 300 -j3 -R "\.Test\.ExampleNetwork\." \
             2>&1 | tee /tmp/regression-test-results.txt
         continue-on-error: true
 
@@ -268,7 +268,7 @@ jobs:
         working-directory: build/SCIRun
         shell: pwsh
         run: |
-          ctest --output-on-failure --timeout 300 -j1 -C Release -R "\.Test\.ExampleNetwork\." `
+          ctest --output-on-failure --timeout 300 -j3 -C Release -R "\.Test\.ExampleNetwork\." `
             2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\regression-test-results.txt"
         continue-on-error: true
 
diff --git a/scripts/coverage.sh b/scripts/coverage.sh
new file mode 100755
index 0000000000..3135d65a64
--- /dev/null
+++ b/scripts/coverage.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+#
+# Clang source-based code coverage for SCIRun.
+#
+# Prerequisite: configure and build with coverage instrumentation:
+#   ./build.sh -DENABLE_COVERAGE=ON -DCMAKE_BUILD_TYPE=Debug
+# (a Debug build gives the most accurate line/region mapping)
+#
+# Usage:
+#   scripts/coverage.sh [build-dir] [-- <extra ctest args>]
+#
+# Examples:
+#   scripts/coverage.sh                              # all tests, build dir bin/SCIRun
+#   scripts/coverage.sh bin/SCIRun -- -j3            # parallel
+#   scripts/coverage.sh bin/SCIRun -- -R "\.Test\.ExampleNetwork\."   # regression only
+#
+# Output:
+#   <build-dir>/coverage/summary.txt     line/region/branch summary
+#   <build-dir>/coverage/html/index.html browsable HTML report
+#
+set -euo pipefail
+
+BUILD_DIR="bin/SCIRun"
+CTEST_ARGS=()
+# First non-flag arg (before --) is the build dir; everything after -- is ctest args.
+if [[ $# -gt 0 && "$1" != "--" ]]; then
+  BUILD_DIR="$1"; shift
+fi
+if [[ "${1:-}" == "--" ]]; then
+  shift; CTEST_ARGS=("$@")
+fi
+
+if [[ ! -x "$BUILD_DIR/SCIRun_test" ]]; then
+  echo "error: $BUILD_DIR/SCIRun_test not found. Build with -DENABLE_COVERAGE=ON first." >&2
+  exit 1
+fi
+
+COV_DIR="$BUILD_DIR/coverage"
+mkdir -p "$COV_DIR"
+rm -f "$COV_DIR"/*.profraw "$COV_DIR/merged.profdata"
+
+# %p => one profraw per process. Each regression test is its own process, so
+# this avoids the processes clobbering a single shared profile file.
+export LLVM_PROFILE_FILE="$(cd "$COV_DIR" && pwd)/%p.profraw"
+
+echo ">>> Running tests (LLVM_PROFILE_FILE=$LLVM_PROFILE_FILE)"
+( cd "$BUILD_DIR" && ctest --output-on-failure "${CTEST_ARGS[@]}" ) || \
+  echo ">>> (some tests failed; coverage still collected)"
+
+shopt -s nullglob
+PROFRAWS=("$COV_DIR"/*.profraw)
+if [[ ${#PROFRAWS[@]} -eq 0 ]]; then
+  echo "error: no .profraw files produced. Was the build instrumented (-DENABLE_COVERAGE=ON)?" >&2
+  exit 1
+fi
+echo ">>> Merging ${#PROFRAWS[@]} profile(s)"
+xcrun llvm-profdata merge -sparse "${PROFRAWS[@]}" -o "$COV_DIR/merged.profdata"
+
+# llvm-cov needs every instrumented object: the test binary plus all SCIRun
+# shared libraries it loads.
+OBJECTS=(-object "$BUILD_DIR/SCIRun_test")
+for lib in "$BUILD_DIR"/lib/*.dylib; do
+  OBJECTS+=(-object "$lib")
+done
+
+IGNORE='(Externals|/Testing/|googletest|/usr/|/Applications/)'
+
+echo ">>> Coverage summary"
+xcrun llvm-cov report "${OBJECTS[@]}" \
+  -instr-profile="$COV_DIR/merged.profdata" \
+  -ignore-filename-regex="$IGNORE" | tee "$COV_DIR/summary.txt"
+
+echo ">>> Generating HTML report"
+xcrun llvm-cov show "${OBJECTS[@]}" \
+  -instr-profile="$COV_DIR/merged.profdata" \
+  -format=html -output-dir="$COV_DIR/html" \
+  -ignore-filename-regex="$IGNORE" \
+  -show-line-counts-or-regions >/dev/null
+
+echo ""
+echo "Summary: $COV_DIR/summary.txt"
+echo "HTML:    $COV_DIR/html/index.html"
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index ecee63aada..2e7aabc636 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -976,3 +976,22 @@ IF(ENABLE_GCOV_DATA_FILES)
   SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fprofile-arcs -ftest-coverage")
   SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} -fprofile-arcs -ftest-coverage")
 ENDIF()
+
+# Clang source-based coverage (recommended on macOS / any Clang toolchain).
+# Build with -DENABLE_COVERAGE=ON, run tests via scripts/coverage.sh, which
+# sets LLVM_PROFILE_FILE=<dir>/%p.profraw (one .profraw per test process),
+# merges with llvm-profdata, and reports with llvm-cov. Unlike the gcov option
+# above, the instrumentation flags must also be applied at link time so the
+# profile runtime is linked into every shared library.
+OPTION(ENABLE_COVERAGE "Build with Clang source-based code coverage instrumentation" OFF)
+IF(ENABLE_COVERAGE)
+  IF(NOT CMAKE_CXX_COMPILER_ID MATCHES "Clang")
+    MESSAGE(WARNING "ENABLE_COVERAGE uses Clang source-based coverage but the compiler is ${CMAKE_CXX_COMPILER_ID}; use ENABLE_GCOV_DATA_FILES instead.")
+  ENDIF()
+  SET(SCIRUN_COVERAGE_FLAGS "-fprofile-instr-generate -fcoverage-mapping")
+  SET(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${SCIRUN_COVERAGE_FLAGS} -g")
+  SET(CMAKE_C_FLAGS "${CMAKE_C_FLAGS} ${SCIRUN_COVERAGE_FLAGS} -g")
+  SET(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} ${SCIRUN_COVERAGE_FLAGS}")
+  SET(CMAKE_SHARED_LINKER_FLAGS "${CMAKE_SHARED_LINKER_FLAGS} ${SCIRUN_COVERAGE_FLAGS}")
+  MESSAGE(STATUS "Code coverage instrumentation enabled (Clang source-based). Best with a Debug build.")
+ENDIF()
diff --git a/src/Core/Application/Application.cc b/src/Core/Application/Application.cc
index 49234a1012..f0c1fe8efa 100644
--- a/src/Core/Application/Application.cc
+++ b/src/Core/Application/Application.cc
@@ -85,13 +85,20 @@ Application::Application() :
   //std::cout << "exec path set to: " << private_->app_filepath_ << std::endl;
   auto configDir = configDirectory();
   LogSettings::Instance().setLogDirectory(configDir);
-  SessionManager::Instance().initialize(configDir);
-  SessionManager::Instance().session()->beginSession();
+  // Session initialization is deferred to readCommandLine(): it needs to know
+  // whether we are in regression mode, which isn't known until the command
+  // line is parsed. The session trace DB writes to a fixed path in the config
+  // directory, so initializing it for every regression-test process causes
+  // concurrent SQLite corruption (and SIGBUS from mmap) when tests run in
+  // parallel. See readCommandLine().
 }
 
 Application::~Application()
 {
-  SessionManager::Instance().session()->endSession();
+  // session() can be null in regression mode, where session tracking is never
+  // initialized (see readCommandLine). Guard before use.
+  if (auto session = SessionManager::Instance().session())
+    session->endSession();
 }
 
 void Application::shutdown()
@@ -154,6 +161,18 @@ void Application::readCommandLine(int argc, const char* argv[])
 
   private_->parameters_ = private_->parser.parse(argc, argv);
 
+  // Initialize the session trace now that we know whether this is a regression
+  // run. Skip it entirely in regression mode: the trace DB/text backends write
+  // to a fixed shared path, which corrupts (and can SIGBUS via SQLite mmap)
+  // when many test processes run concurrently. The session left as a
+  // NullSession is harmless. Normal interactive runs keep full session tracking.
+  if (!private_->parameters_->isRegressionMode())
+  {
+    auto configDir = configDirectory();
+    SessionManager::Instance().initialize(configDir);
+    SessionManager::Instance().session()->beginSession();
+  }
+
   //TODO: move this special logic somewhere else
   {
     auto maxCoresOption = private_->parameters_->developerParameters()->maxCores();
diff --git a/src/Interface/Application/ModuleWidget.h b/src/Interface/Application/ModuleWidget.h
index 73c186b02e..f2d7a62f81 100644
--- a/src/Interface/Application/ModuleWidget.h
+++ b/src/Interface/Application/ModuleWidget.h
@@ -284,7 +284,11 @@ private Q_SLOTS:
   QString name_;
 
   ModuleDialogManager dialogManager_;
-  ModuleDialogDockWidget* dockable_;
+  // Must be null-initialized: updateDockWidgetProperties() can fire (via the
+  // dock's topLevelChanged signal in configDockable) before makeOptionsDialog
+  // assigns this, and that slot null-checks dockable_. An uninitialized pointer
+  // holds garbage that passes the null check and segfaults under setWindowFlags.
+  ModuleDialogDockWidget* dockable_{nullptr};
   bool firstTimeShown_{ true };
   static QList<QPoint> positions_;
   void makeOptionsDialog();
diff --git a/src/Testing/CMakeLists.txt b/src/Testing/CMakeLists.txt
index 53ace02e84..1bb0960aae 100644
--- a/src/Testing/CMakeLists.txt
+++ b/src/Testing/CMakeLists.txt
@@ -101,7 +101,24 @@ IF(RUN_BASIC_REGRESSION_TESTS)
 
   FOREACH(srn ${scirun_srns})
     GET_FILENAME_COMPONENT(srn_name ${srn} NAME_WE)
-    ADD_TEST(".Test.ExampleNetwork.${srn_name}_srn" ${EXE_LOC} -E ${srn} --no_splash --regression 30 -d ${SCIRUN_TEST_RESOURCE_DIR})
+    SET(test_name ".Test.ExampleNetwork.${srn_name}_srn")
+    # In-app regression timeout (seconds). 60 gives the heaviest networks
+    # headroom when the machine is under parallel load; genuine hangs are still
+    # bounded by the ctest --timeout passed in CI.
+    ADD_TEST("${test_name}" ${EXE_LOC} -E ${srn} --no_splash --regression 60 -d ${SCIRUN_TEST_RESOURCE_DIR})
+
+    # Networks that instantiate a ViewScene render through an offscreen GL
+    # context in regression mode. macOS serializes GPU command submission
+    # across contexts, so running several ViewScene networks concurrently can
+    # slow rendering enough to trip the in-app regression timeout. Give these
+    # tests a shared RESOURCE_LOCK so CTest never schedules two of them at once,
+    # while CPU-only tests still parallelize freely.
+    FILE(READ "${srn}" srn_contents)
+    STRING(FIND "${srn_contents}" "ViewScene" srn_viewscene_pos)
+    IF(NOT srn_viewscene_pos EQUAL -1)
+      SET_TESTS_PROPERTIES("${test_name}" PROPERTIES RESOURCE_LOCK gpu)
+    ENDIF()
+    UNSET(srn_contents)
   ENDFOREACH()
 
 ENDIF()

From e5a876feb8eb2de4c1d14b61e3cd4669e2fcdd6f Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 08:16:31 -0600
Subject: [PATCH 06/64] Isolate QSettings per process in regression mode
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Concurrent regression-test processes shared one settings file
(~/Library/Preferences/SCIRun5.plist). Reading a half-written plist during
startup — favorites and window geometry restore — could crash in the
module-selector tree (handleCheckedModuleEntry -> QTreeWidget::setCurrentItem).
Suffix the QSettings application name with the process id in regression mode so
each process gets an isolated, empty, deterministic store. Normal interactive
runs keep the shared "SCIRun5" settings.

Stress result: full suite at -j6 now passes 100% in 2 of 3 runs (was crashing
on random tests every run). One rarer pre-existing async-state heap race
remains (ViewScene::asyncExecute -> SimpleMapModuleState::setTransientValue),
tracked separately.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Application/SCIRunMainWindow.cc | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Application/SCIRunMainWindow.cc b/src/Interface/Application/SCIRunMainWindow.cc
index d1c67a3b98..1bac43393c 100644
--- a/src/Interface/Application/SCIRunMainWindow.cc
+++ b/src/Interface/Application/SCIRunMainWindow.cc
@@ -82,7 +82,15 @@ SCIRunMainWindow::SCIRunMainWindow()
   startup_ = true;
 
   QCoreApplication::setOrganizationName("SCI:CIBC Software");
-  QCoreApplication::setApplicationName("SCIRun5");
+  // In regression mode, isolate QSettings per process: concurrent test
+  // processes otherwise share one settings file, and reading a half-written
+  // plist (favorites, window geometry) during startup can crash in the
+  // module-selector tree restore. A fresh per-process store is also more
+  // deterministic for tests.
+  if (Application::Instance().parameters()->isRegressionMode())
+    QCoreApplication::setApplicationName(QString("SCIRun5_regression_%1").arg(QCoreApplication::applicationPid()));
+  else
+    QCoreApplication::setApplicationName("SCIRun5");
 
   setAttribute(Qt::WA_DeleteOnClose);
 

From 119d6bf22eeb0967ebb7d8dcc4c7461f33b792bf Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 09:30:12 -0600
Subject: [PATCH 07/64] Seed per-process regression QSettings from the shared
 default store

Instead of starting each regression process with an empty settings store,
copy all keys from the shared default "SCIRun5" store into the per-process
"SCIRun5_regression_<pid>" store at startup. Regression runs now see the
developer's real settings (favorites, directories, mouse mode, etc.) and look
consistent run to run, while still only ever *writing* to their own isolated
file. Concurrent *reads* of the stable shared store are safe; only the
concurrent writes caused the original startup race.

dest.clear() first so a recycled pid can't inherit a stale store.

Verified: a regression process's plist inherits the source keys; a full -j6
run shows no new failures (the two that remain are the pre-existing async
setTransientValue race tracked in #2486 and a -j6-only load timeout).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Application/SCIRunMainWindow.cc | 28 +++++++++++++++----
 1 file changed, 23 insertions(+), 5 deletions(-)

diff --git a/src/Interface/Application/SCIRunMainWindow.cc b/src/Interface/Application/SCIRunMainWindow.cc
index 1bac43393c..ed774e380c 100644
--- a/src/Interface/Application/SCIRunMainWindow.cc
+++ b/src/Interface/Application/SCIRunMainWindow.cc
@@ -27,6 +27,7 @@
 
 
 #include <es-log/trace-log.h>
+#include <QSettings>
 #include <boost/algorithm/string.hpp>
 #include <Core/Utils/Legacy/MemoryUtil.h>
 #include <Interface/Application/GuiLogger.h>
@@ -81,16 +82,33 @@ SCIRunMainWindow::SCIRunMainWindow()
 
   startup_ = true;
 
-  QCoreApplication::setOrganizationName("SCI:CIBC Software");
+  const QString organization("SCI:CIBC Software");
+  const QString defaultAppName("SCIRun5");
+  QCoreApplication::setOrganizationName(organization);
   // In regression mode, isolate QSettings per process: concurrent test
   // processes otherwise share one settings file, and reading a half-written
   // plist (favorites, window geometry) during startup can crash in the
-  // module-selector tree restore. A fresh per-process store is also more
-  // deterministic for tests.
+  // module-selector tree restore. Seed the per-process store from the shared
+  // default store so regression runs see the developer's real settings (and
+  // look consistent run to run) while only ever *writing* to their own file.
+  // Reading the stable shared store concurrently is safe; only concurrent
+  // writes caused the original race.
   if (Application::Instance().parameters()->isRegressionMode())
-    QCoreApplication::setApplicationName(QString("SCIRun5_regression_%1").arg(QCoreApplication::applicationPid()));
+  {
+    const QString regressionAppName = QString("%1_regression_%2").arg(defaultAppName).arg(QCoreApplication::applicationPid());
+    {
+      QSettings source(QSettings::NativeFormat, QSettings::UserScope, organization, defaultAppName);
+      QSettings dest(QSettings::NativeFormat, QSettings::UserScope, organization, regressionAppName);
+      dest.clear(); // a recycled pid may have left a stale store
+      const auto keys = source.allKeys();
+      for (const auto& key : keys)
+        dest.setValue(key, source.value(key));
+      dest.sync();
+    }
+    QCoreApplication::setApplicationName(regressionAppName);
+  }
   else
-    QCoreApplication::setApplicationName("SCIRun5");
+    QCoreApplication::setApplicationName(defaultAppName);
 
   setAttribute(Qt::WA_DeleteOnClose);
 

From b60eed6bed275cfb963b84aac94a9841d27b6f00 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 09:38:05 -0600
Subject: [PATCH 08/64] Clean up per-process regression QSettings stores after
 runs

Regression processes each create an isolated SCIRun5_regression_<pid> settings
store; without cleanup these accumulate (one per test process, ~300 per run).

Cleanup is done after the run rather than in-app: on macOS cfprefsd owns the
plist and recreates it if a still-running process deletes its own file, so
in-process deletion at exit doesn't stick. Once the run finishes the domains
are dead and removal is reliable.

- scripts/run-regression-tests.sh: wraps ctest, removing the per-process stores
  before and after the run. Cross-platform (macOS plist via `defaults delete` +
  rm, Linux .conf, Windows registry keys). Verified: 5 stale stores before -> 0
  after.
- reusable-build.yml: the Unix regression CI step removes the stores afterward.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml          |  9 +++
 scripts/run-regression-tests.sh               | 69 +++++++++++++++++++
 src/Interface/Application/SCIRunMainWindow.cc |  4 ++
 3 files changed, 82 insertions(+)
 create mode 100755 scripts/run-regression-tests.sh

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 3f93496107..fae569f11f 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -254,6 +254,15 @@ jobs:
             2>&1 | tee /tmp/regression-test-results.txt
         continue-on-error: true
 
+      - name: Clean up per-process regression settings (Unix)
+        if: ${{ inputs.run-regression-tests && runner.os != 'Windows' }}
+        run: |
+          # Each regression process isolates its QSettings under
+          # SCIRun5_regression_<pid>; remove the stores left behind.
+          rm -f "$HOME"/Library/Preferences/com.sci-cibc-software.SCIRun5_regression_*.plist 2>/dev/null || true
+          rm -f "$HOME"/.config/"SCI:CIBC Software"/SCIRun5_regression_*.conf 2>/dev/null || true
+        continue-on-error: true
+
       - name: Run unit tests (Windows)
         if: ${{ inputs.run-unit-tests && runner.os == 'Windows' }}
         working-directory: build/SCIRun
diff --git a/scripts/run-regression-tests.sh b/scripts/run-regression-tests.sh
new file mode 100755
index 0000000000..20f60a741a
--- /dev/null
+++ b/scripts/run-regression-tests.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+#
+# Run the SCIRun regression suite and clean up the per-process QSettings stores
+# it creates.
+#
+# In regression mode each test process isolates its QSettings under an app name
+# "SCIRun5_regression_<pid>" (so concurrent processes don't race on the shared
+# store). Those per-process stores would otherwise accumulate, so this wrapper
+# removes them before and after the run. Cleanup is done here rather than in the
+# app because on macOS cfprefsd owns the plist and recreates it if a live
+# process deletes it; once the run is over the domains are dead and removal is
+# reliable.
+#
+# Usage:
+#   scripts/run-regression-tests.sh [build-dir] [-- <extra ctest args>]
+#
+# Examples:
+#   scripts/run-regression-tests.sh                          # bin/SCIRun, default ctest args
+#   scripts/run-regression-tests.sh bin/SCIRun -- -j3        # parallel
+#   scripts/run-regression-tests.sh bin/SCIRun -- -j3 -R Renderer
+#
+set -uo pipefail
+
+BUILD_DIR="bin/SCIRun"
+if [[ $# -gt 0 && "$1" != "--" ]]; then
+  BUILD_DIR="$1"; shift
+fi
+CTEST_ARGS=(-R "\.Test\.ExampleNetwork\." --output-on-failure)
+if [[ "${1:-}" == "--" ]]; then
+  shift; CTEST_ARGS=("$@")
+fi
+
+cleanup_regression_settings() {
+  case "$(uname -s)" in
+    Darwin)
+      # cfprefsd may keep the dead domains cached briefly; ask it to drop them,
+      # then remove any leftover files.
+      for f in "$HOME"/Library/Preferences/com.sci-cibc-software.SCIRun5_regression_*.plist; do
+        [[ -e "$f" ]] || continue
+        local base; base="$(basename "$f" .plist)"
+        defaults delete "$base" >/dev/null 2>&1 || true
+        rm -f "$f" || true
+      done
+      ;;
+    Linux)
+      rm -f "$HOME"/.config/"SCI:CIBC Software"/SCIRun5_regression_*.conf 2>/dev/null || true
+      ;;
+    *)
+      # Windows (Git Bash / MSYS): QSettings uses the registry; remove per-pid keys.
+      if command -v reg >/dev/null 2>&1; then
+        reg query "HKCU\\Software\\SCI:CIBC Software" 2>/dev/null \
+          | grep -i "SCIRun5_regression_" \
+          | while read -r key; do reg delete "$key" /f >/dev/null 2>&1 || true; done
+      fi
+      ;;
+  esac
+}
+
+echo ">>> Cleaning stale regression settings"
+cleanup_regression_settings
+
+echo ">>> Running: (cd $BUILD_DIR && ctest ${CTEST_ARGS[*]})"
+( cd "$BUILD_DIR" && ctest "${CTEST_ARGS[@]}" )
+rc=$?
+
+echo ">>> Cleaning up regression settings"
+cleanup_regression_settings
+
+exit $rc
diff --git a/src/Interface/Application/SCIRunMainWindow.cc b/src/Interface/Application/SCIRunMainWindow.cc
index ed774e380c..f50434bc42 100644
--- a/src/Interface/Application/SCIRunMainWindow.cc
+++ b/src/Interface/Application/SCIRunMainWindow.cc
@@ -104,6 +104,10 @@ SCIRunMainWindow::SCIRunMainWindow()
       for (const auto& key : keys)
         dest.setValue(key, source.value(key));
       dest.sync();
+      // Note: these per-process stores are cleaned up after the run by
+      // scripts/run-regression-tests.sh (and the CI regression step). In-process
+      // deletion on exit is unreliable on macOS because cfprefsd owns the plist
+      // and recreates it after the process exits.
     }
     QCoreApplication::setApplicationName(regressionAppName);
   }

From 2fb792e5e374c6a1951498a50991341258040b5d Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 09:53:34 -0600
Subject: [PATCH 09/64] Add mac-coverage CI job (Clang source-based coverage)

New mac-coverage job in regression-tests.yml: a gui macOS build with
-DENABLE_COVERAGE=ON (Debug), runs the full test suite under llvm profiling,
and uploads a coverage report (text summary + HTML) as an artifact.

reusable-build.yml gains a `coverage` input that:
- checks out SCIRunTestData (also needed for the regression portion),
- adds --debug -DENABLE_COVERAGE:BOOL=ON to the build,
- runs scripts/coverage.sh (per-process LLVM_PROFILE_FILE -> llvm-profdata
  merge -> llvm-cov text+HTML), cleans up the regression QSettings stores,
  and uploads coverage-report-macOS.

Superbuild.cmake: declare ENABLE_COVERAGE and forward it to the inner SCIRun
build via SCIRUN_CACHE_ARGS. Without this the option set on build.sh never
reached the project that defines it, so no instrumentation would be applied.
(The pre-existing ENABLE_GCOV_DATA_FILES had the same gap.)

Coverage toolchain commands validated against a standalone instrumented
binary; the llvm-cov report/show invocations and profdata merge work as used.

Note: the instrumented Debug build running the full suite is a long job
(expect several hours); scope the ctest selection in the coverage step down
if runtime becomes a problem.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .github/workflows/regression-tests.yml | 11 ++++++++
 .github/workflows/reusable-build.yml   | 35 ++++++++++++++++++++++++--
 Superbuild/Superbuild.cmake            |  5 ++++
 3 files changed, 49 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/regression-tests.yml b/.github/workflows/regression-tests.yml
index a3dab70c97..9ad8f858d9 100644
--- a/.github/workflows/regression-tests.yml
+++ b/.github/workflows/regression-tests.yml
@@ -39,3 +39,14 @@ jobs:
       build-testing: true
       run-unit-tests: true
       run-regression-tests: true
+
+  mac-coverage:
+    uses: ./.github/workflows/reusable-build.yml
+    with:
+      runner: macOS-latest
+      qt-version: '6.10.2'
+      scirun-qt-min-version: '6.3.1'
+      variant: gui
+      build-with-python: true
+      build-testing: true
+      coverage: true
diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index fae569f11f..235f8bc273 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -42,6 +42,10 @@ on:
         required: false
         type: boolean
         default: false
+      coverage:
+        required: false
+        type: boolean
+        default: false
       artifact-name:
         required: false
         type: string
@@ -67,7 +71,7 @@ jobs:
         run: echo "QT_ROOT_DIR=${QT_ROOT_DIR:-(unset)}"
 
       - name: Checkout SCIRunTestData
-        if: ${{ inputs.run-regression-tests }}
+        if: ${{ inputs.run-regression-tests || inputs.coverage }}
         uses: actions/checkout@v6
         with:
           repository: CIBC-Internal/SCIRunTestData
@@ -131,9 +135,13 @@ jobs:
           if [ "${{ inputs.build-testing }}" = "true" ]; then
             CMD+=("-DBUILD_TESTING:BOOL=ON")
           fi
-          if [ "${{ inputs.run-regression-tests }}" = "true" ]; then
+          if [ "${{ inputs.run-regression-tests }}" = "true" ] || [ "${{ inputs.coverage }}" = "true" ]; then
             CMD+=("-DSCIRUN_TEST_RESOURCE_DIR=${GITHUB_WORKSPACE}/SCIRunTestData")
           fi
+          if [ "${{ inputs.coverage }}" = "true" ]; then
+            # Debug build + Clang source-based coverage instrumentation.
+            CMD+=("--debug" "-DENABLE_COVERAGE:BOOL=ON")
+          fi
           # Join and run
           echo "Running: ${CMD[*]}"
           eval "${CMD[*]}"
@@ -301,6 +309,29 @@ jobs:
             regression-test-results.txt
             build/SCIRun/Testing/Temporary/LastTest.log
 
+      - name: Run tests + coverage report (macOS)
+        if: ${{ inputs.coverage && runner.os == 'macOS' }}
+        run: |
+          # scripts/coverage.sh runs ctest with per-process profiling, merges
+          # with llvm-profdata, and writes a text summary + HTML via llvm-cov.
+          # No -R filter: cover both unit and regression tests.
+          ./scripts/coverage.sh bin/SCIRun -- -j3 --timeout 300
+        continue-on-error: true
+
+      - name: Clean up per-process regression settings (coverage)
+        if: ${{ inputs.coverage && runner.os == 'macOS' }}
+        run: rm -f "$HOME"/Library/Preferences/com.sci-cibc-software.SCIRun5_regression_*.plist 2>/dev/null || true
+        continue-on-error: true
+
+      - name: Upload coverage report
+        if: ${{ inputs.coverage && runner.os == 'macOS' }}
+        uses: actions/upload-artifact@v6
+        with:
+          name: coverage-report-${{ runner.os }}
+          path: |
+            bin/SCIRun/coverage/summary.txt
+            bin/SCIRun/coverage/html
+
       - name: Upload installer (optional)
         if: ${{ inputs.artifact-name != '' }}
         uses: actions/upload-artifact@v6
diff --git a/Superbuild/Superbuild.cmake b/Superbuild/Superbuild.cmake
index 70d78bd55f..88982f9119 100644
--- a/Superbuild/Superbuild.cmake
+++ b/Superbuild/Superbuild.cmake
@@ -59,6 +59,10 @@ ENDIF()
 # Configure test support
 OPTION(BUILD_TESTING "Build with tests." OFF)
 
+###########################################
+# Configure code coverage (forwarded to the inner SCIRun build)
+OPTION(ENABLE_COVERAGE "Build with Clang source-based code coverage instrumentation" OFF)
+
 ###########################################
 # Configure compilation database generation
 OPTION(GENERATE_COMPILATION_DATABASE "Generate Compilation Database." ON)
@@ -218,6 +222,7 @@ SET(SCIRUN_CACHE_ARGS
     "-DSCIRUN_BINARY_DIR:PATH=${SCIRUN_BINARY_DIR}"
     "-DSCIRUN_BITS:STRING=${SCIRUN_BITS}"
     "-DBUILD_TESTING:BOOL=${BUILD_TESTING}"
+    "-DENABLE_COVERAGE:BOOL=${ENABLE_COVERAGE}"
     "-DBUILD_DOCUMENTATION:BOOL=${BUILD_DOCUMENTATION}"
     "-DBUILD_HEADLESS:BOOL=${BUILD_HEADLESS}"
     "-DQT_VERSION_MAJOR:STRING=${QT_VERSION_MAJOR}"

From 8e2a5b38cab5130d5430bd7835ec01dfdd9bcf4e Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 10:00:23 -0600
Subject: [PATCH 10/64] Add regression-tests status badge to README

Badges are per-workflow on GitHub Actions, so one regression-tests badge
covers all of its jobs (linux-headless, mac-gui, windows-headless, and
mac-coverage). Links to the workflow's Actions page.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 README.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/README.md b/README.md
index 6bfb934f41..685b6e1a42 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,7 @@
 ![mac-build](https://github.com/SCIInstitute/SCIRun/workflows/mac-build/badge.svg)
 ![linux-build](https://github.com/SCIInstitute/SCIRun/workflows/linux-build/badge.svg)
 ![windows-build](https://github.com/SCIInstitute/SCIRun/workflows/windows-build/badge.svg)
+[![regression-tests](https://github.com/SCIInstitute/SCIRun/workflows/regression-tests/badge.svg)](https://github.com/SCIInstitute/SCIRun/actions/workflows/regression-tests.yml)
 <!-- [![Coverage Status](https://coveralls.io/repos/SCIInstitute/SCIRun/badge.png)](https://coveralls.io/r/SCIInstitute/SCIRun) -->
 
 ##### [Contents](#user-content-scirun-5-prototype "generated with DocToc(http://doctoc.herokuapp.com/)")

From d66925da18f4e29b30b9ebab8a6e9a45e1ff4685 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 11:31:41 -0600
Subject: [PATCH 11/64] Run legacy-network import tests in GUI mode and report
 failures cleanly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The .Test.ImportNetwork.* tests pass -x, which routed them to ConsoleApplication
where ImportNetworkFile is unimplemented — every test threw "Unknown global
command type" and exited 1. Drop -x so import goes through the GuiCommandFactory's
FileImportCommand (the intended path), and make that path testable in regression
mode:

- GlobalCommandBuilderFromCommandLine: enqueue a quit after import/save in
  regression mode (the GUI import flow never executes the network, so nothing
  else quits it — tests previously hung until manually closed). Interactive
  --import keeps the window open. Also redirect the converted <name>_imported.srn5
  to a temp dir in regression mode so the test data dir isn't polluted.

- GuiCommands: never pop a modal "module not found" dialog in regression mode
  (it blocked the run waiting for a manual OK); report via the log instead. Add a
  failTestOnError() hook (true for import) so an import failure in regression mode
  exits non-zero, surfacing as a failed ctest result with the reason logged.

- Testing/CMakeLists.txt: name import tests by path relative to the data dir
  (several legacy nets share a basename and collided into one test name); filter
  the glob to skip serialization artifacts (TransientOutput/) and scratch files
  (*_TMP.srn); add a 120s CTest timeout.

Result: import suite goes from 0/434 (all crashing at startup) to 98% passing in
~84s with no dialogs. The ~9 remaining failures are genuine gaps the tests now
correctly surface (undefined legacy modules; a v4 lexical-cast parse error),
tracked separately.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 .../GlobalCommandBuilderFromCommandLine.cc    | 25 ++++++++++++++++++-
 src/Interface/Application/GuiCommands.cc      | 18 ++++++++++++-
 src/Interface/Application/GuiCommands.h       |  5 ++++
 src/Testing/CMakeLists.txt                    | 19 ++++++++++++--
 4 files changed, 63 insertions(+), 4 deletions(-)

diff --git a/src/Core/Command/GlobalCommandBuilderFromCommandLine.cc b/src/Core/Command/GlobalCommandBuilderFromCommandLine.cc
index f8f4b983d2..598c1006e7 100644
--- a/src/Core/Command/GlobalCommandBuilderFromCommandLine.cc
+++ b/src/Core/Command/GlobalCommandBuilderFromCommandLine.cc
@@ -29,6 +29,7 @@
 /// @todo Documentation Core/Command/GlobalCommandBuilderFromCommandLine.cc
 
 #include <iostream>
+#include <boost/filesystem.hpp>
 #include <Core/Utils/SmartPointers.h>
 #include <Core/Command/CommandQueue.h>
 #include <Core/Command/GlobalCommandBuilderFromCommandLine.h>
@@ -89,8 +90,30 @@ using namespace SCIRun::Core::Algorithms;
 
       q->enqueue(import);
       auto save = cmdFactory_->create(GlobalCommands::SaveNetworkFile);
-      save->set(Variables::Filename, (*params->importNetworkFile()) + "_imported.srn5");
+      // Normally the converted network is written next to the source so users
+      // get a usable <name>_imported.srn5. In regression mode write it to a
+      // temp directory instead: the import tests only validate that the import
+      // succeeds, and writing next to the source pollutes the (often
+      // shared/read-only) test data directory.
+      if (params->isRegressionMode())
+      {
+        boost::filesystem::path src(*params->importNetworkFile());
+        auto tmp = boost::filesystem::temp_directory_path() / (src.filename().string() + "_imported.srn5");
+        save->set(Variables::Filename, tmp.string());
+      }
+      else
+      {
+        save->set(Variables::Filename, (*params->importNetworkFile()) + "_imported.srn5");
+      }
       q->enqueue(save);
+
+      // In regression mode the import runs through the GUI command factory (no
+      // -x), which never executes the network and so never arms the quit-after-
+      // execute path. Enqueue an explicit quit so the import test terminates
+      // instead of leaving the GUI open. Interactive --import use (not
+      // regression) keeps the window open so the user can see the result.
+      if (params->isRegressionMode())
+        q->enqueue(cmdFactory_->create(GlobalCommands::QuitCommand));
     }
 
     if (params->pythonScriptFile())
diff --git a/src/Interface/Application/GuiCommands.cc b/src/Interface/Application/GuiCommands.cc
index 38622d0fb4..2446f9f1b7 100644
--- a/src/Interface/Application/GuiCommands.cc
+++ b/src/Interface/Application/GuiCommands.cc
@@ -27,6 +27,7 @@
 
 
 #include <Interface/qt_include.h>
+#include <cstdlib>
 #include <numeric>
 #include <Core/Algorithms/Base/AlgorithmVariableNames.h>
 #include <Core/Application/Preferences/Preferences.h>
@@ -235,7 +236,10 @@ bool NetworkFileProcessCommand::execute()
 
     auto quiet = get(AlgorithmParameterName("QuietMode")).toBool();
 
-    if (!quiet)
+    // Never pop a modal dialog in regression mode: it blocks the automated run
+    // waiting for a manual OK. The error is reported via the log (and, for
+    // import, by failing the test below).
+    if (!quiet && !Application::Instance().parameters()->isRegressionMode())
     {
       if (message.find("InterfaceWithTetGen") != std::string::npos)
       {
@@ -257,6 +261,18 @@ bool NetworkFileProcessCommand::execute()
   {
     GuiLogger::logErrorStd("File load failed (" + filename + "): Unknown exception in load_xml.");
   }
+
+  // In regression mode, surface import failures as a failed test instead of a
+  // (now-suppressed) dialog: exit non-zero so ctest reports it. The reason is
+  // already in the log above.
+  if (failTestOnError() && Application::Instance().parameters()->isRegressionMode())
+  {
+    GuiLogger::logErrorStd("Regression import failed, exiting non-zero: " + filename);
+    // Mirrors SCIRunMainWindow::exitApplication's regression-mode behavior
+    // (which calls quick_exit) so the regression test reports a failure. Done
+    // directly here because exitApplication is a private slot.
+    std::quick_exit(1);
+  }
   return false;
 }
 
diff --git a/src/Interface/Application/GuiCommands.h b/src/Interface/Application/GuiCommands.h
index 0b1ebcb41e..8981e15858 100644
--- a/src/Interface/Application/GuiCommands.h
+++ b/src/Interface/Application/GuiCommands.h
@@ -108,6 +108,10 @@ namespace Gui {
     Dataflow::Networks::NetworkFileHandle file_;
   protected:
     virtual Dataflow::Networks::NetworkFileHandle processXmlFile(const std::string& filename) = 0;
+    // When true, a failure in regression mode terminates the process with a
+    // non-zero code so the regression test fails (rather than silently passing).
+    // Import overrides this; regular open does not.
+    virtual bool failTestOnError() const { return false; }
     int guiProcess(const Dataflow::Networks::NetworkFileHandle& file);
     NetworkEditor* networkEditor_;
   };
@@ -127,6 +131,7 @@ namespace Gui {
     std::string logContents() const { return logContents_.str(); }
   protected:
     Dataflow::Networks::NetworkFileHandle processXmlFile(const std::string& filename) override;
+    bool failTestOnError() const override { return true; }
     std::ostringstream logContents_;
   };
 
diff --git a/src/Testing/CMakeLists.txt b/src/Testing/CMakeLists.txt
index 1bb0960aae..b9ee08df33 100644
--- a/src/Testing/CMakeLists.txt
+++ b/src/Testing/CMakeLists.txt
@@ -125,9 +125,24 @@ ENDIF()
 
 IF(RUN_IMPORT_TESTS)
   FILE(GLOB_RECURSE scirun_legacy_srns "${SCIRUN_TEST_RESOURCE_DIR}/**/*.srn")
+  # The glob is broad; drop files that aren't legacy v4 networks: serialization
+  # test artifacts (TransientOutput/), scratch outputs (*_TMP.srn), and any
+  # converted networks left in the data dir (*_imported.srn5 won't match *.srn,
+  # but guard against *_imported.srn just in case).
+  LIST(FILTER scirun_legacy_srns EXCLUDE REGEX "(/TransientOutput/|_TMP\\.srn$|_imported)")
   FOREACH(srn ${scirun_legacy_srns})
-    GET_FILENAME_COMPONENT(srn_name ${srn} NAME_WE)
-    ADD_TEST(".Test.ImportNetwork.${srn_name}_srn" ${EXE_LOC} -x --no_splash --regression 30 --import ${srn})
+    # Name tests by path relative to the data dir, not just the basename:
+    # several legacy networks share a basename across subdirectories, which
+    # would collide into a single CTest test name.
+    FILE(RELATIVE_PATH srn_rel "${SCIRUN_TEST_RESOURCE_DIR}" "${srn}")
+    STRING(REGEX REPLACE "[/\\\\]" "." srn_rel "${srn_rel}")
+    STRING(REGEX REPLACE "\\.srn$" "" srn_rel "${srn_rel}")
+    SET(import_test_name ".Test.ImportNetwork.${srn_rel}")
+    # Run in GUI mode (no -x): import goes through the GuiCommandFactory's
+    # FileImportCommand. The headless console path has no import command.
+    ADD_TEST("${import_test_name}" ${EXE_LOC} --no_splash --regression 30 --import ${srn})
+    # Bound a hung import at the ctest level.
+    SET_TESTS_PROPERTIES("${import_test_name}" PROPERTIES TIMEOUT 120)
   ENDFOREACH()
 ENDIF()
 

From 2349c321678af0080645e3f067a59f69825a4d38 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 23:42:21 -0600
Subject: [PATCH 12/64] Fix Windows build: include glew before Qt OpenGL
 headers in OffscreenGLRenderer

OffscreenGLRenderer.h included <QOffscreenSurface>/<QOpenGLContext>/
<QOpenGLFramebufferObject>, which pull in <gl.h> on Windows. Because that
landed before glew.h (included via gl-platform in the .cc), MSVC failed the
Interface_Modules_Render build with C1189 "gl.h included before glew.h". This
broke every Windows CI build on the branch since the OffscreenGLRenderer was
added; Linux/macOS tolerate the ordering.

Forward-declare the Qt OpenGL classes in the header (they're only pointer
members; only QImage, which is gl.h-free, still needs including) and in the .cc
include gl-platform (glew) before the Qt OpenGL headers, matching GLWidget's
ordering.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/OffscreenGLRenderer.cc |  9 ++++++++-
 src/Interface/Modules/Render/OffscreenGLRenderer.h  | 12 +++++++++---
 2 files changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/Interface/Modules/Render/OffscreenGLRenderer.cc b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
index 8f59f5a138..d6e4d7e425 100644
--- a/src/Interface/Modules/Render/OffscreenGLRenderer.cc
+++ b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
@@ -25,9 +25,16 @@
    DEALINGS IN THE SOFTWARE.
 */
 
+// glew (via gl-platform) must be included before any header that pulls in
+// <gl.h> — notably the Qt OpenGL headers below — or MSVC errors with
+// "gl.h included before glew.h".
+#include <gl-platform/GLPlatform.hpp>
+#include <QOffscreenSurface>
+#include <QOpenGLContext>
+#include <QOpenGLFramebufferObject>
+#include <QSurfaceFormat>
 #include <Interface/Modules/Render/OffscreenGLRenderer.h>
 #include <Interface/Modules/Render/ES/SRInterface.h>
-#include <gl-platform/GLPlatform.hpp>
 #include <Core/Logging/Log.h>
 
 namespace SCIRun {
diff --git a/src/Interface/Modules/Render/OffscreenGLRenderer.h b/src/Interface/Modules/Render/OffscreenGLRenderer.h
index 480b38602c..56465e3f56 100644
--- a/src/Interface/Modules/Render/OffscreenGLRenderer.h
+++ b/src/Interface/Modules/Render/OffscreenGLRenderer.h
@@ -28,13 +28,19 @@
 #ifndef INTERFACE_MODULES_RENDER_OFFSCREENGLRENDERER_H
 #define INTERFACE_MODULES_RENDER_OFFSCREENGLRENDERER_H
 
+// Only QImage is needed in this header (returned by value). The OpenGL Qt
+// classes are used as pointer members, so forward-declare them rather than
+// including their headers here: on Windows those headers pull in <gl.h>, and
+// if that lands before glew.h (included via gl-platform in the .cc) MSVC fails
+// with "gl.h included before glew.h".
 #include <QImage>
-#include <QOffscreenSurface>
-#include <QOpenGLContext>
-#include <QOpenGLFramebufferObject>
 #include <Interface/Modules/Render/ES/RendererInterfaceFwd.h>
 #include <Interface/Modules/Render/share.h>
 
+class QOffscreenSurface;
+class QOpenGLContext;
+class QOpenGLFramebufferObject;
+
 namespace SCIRun {
 namespace Gui {
 

From c660e68e5018e990b3f954b734992b40cf2d836e Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 4 Jun 2026 23:50:12 -0600
Subject: [PATCH 13/64] Produce deterministic ViewScene images in regression
 mode (--save-images)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Foundation for golden-image regression testing. The offscreen renderer already
feeds rendered frames into the screenshot path; this makes the saved filenames
deterministic so they can be matched against reference images.

In regression mode, autoSaveScreenshot() now names files
<dir>/<network>.<module>.png — keyed to the loaded network file
(getCurrentFileName) and the module id, with no wall-clock timestamp and no
1s sleep. The directory defaults to the current working dir when the screenshot
preference is unset. Interactive (non-regression) behavior is unchanged.

Verified: `SCIRun_test -E ViewSceneBackgroundColor.srn5 --regression --save-images`
writes ViewSceneBackgroundColor.ViewScene-0.png ... -5.png, each a correct
800x600 offscreen render (background color + orientation axes).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 5ae847aaae..6d82e699d0 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -28,6 +28,8 @@
 #include <Core/Application/Application.h>
 #include <Core/Application/Preferences/Preferences.h>
 #include <Core/Application/Version.h>
+#include <Core/Utils/CurrentFileName.h>
+#include <boost/filesystem/path.hpp>
 #include <Core/GeometryPrimitives/Transform.h>
 #include <Core/Logging/Log.h>
 #include <Core/Thread/Mutex.h>
@@ -2826,10 +2828,27 @@ void ViewSceneDialog::saveScreenshot(QString fileName, bool notify)
 
 void ViewSceneDialog::autoSaveScreenshot()
 {
+  const auto moduleName = QString::fromStdString(getName()).replace(':', '-');
+  auto dir = QString::fromStdString(state_->getValue(Parameters::ScreenshotDirectory).toString());
+
+  if (Application::Instance().parameters()->isRegressionMode())
+  {
+    // Deterministic, golden-image-ready name: <dir>/<network>.<module>.png,
+    // keyed to the loaded network file (no wall-clock timestamp). Default the
+    // directory to the current working dir when the screenshot pref is unset.
+    if (dir.isEmpty())
+      dir = ".";
+    const auto network = QString::fromStdString(
+      boost::filesystem::path(Core::getCurrentFileName()).stem().string());
+    const auto file = QString("%1/%2.%3.png").arg(dir).arg(network).arg(moduleName);
+    saveScreenshot(file, false);
+    return;
+  }
+
   QThread::sleep(1);
-  const auto file = QString::fromStdString(state_->getValue(Parameters::ScreenshotDirectory).toString()) +
+  const auto file = dir +
                     QString("/%1_%2.png")
-                    .arg(QString::fromStdString(getName()).replace(':', '-'))
+                    .arg(moduleName)
                     .arg(QTime::currentTime().toString("hh.mm.ss.zzz"));
 
   saveScreenshot(file, false);

From 846c0946ea98d5a3f31071d39fbfc4e17e87c443 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 00:04:51 -0600
Subject: [PATCH 14/64] Add --image-dir for regression images; save captured
 frame without re-render
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Step 1 of golden-image regression: control where rendered images go and stop
the quit-time crash.

- New --image-dir command-line option (wired through ApplicationParameters like
  --datadir). In regression mode autoSaveScreenshot writes to it when given,
  else the screenshot pref, else CWD; the directory is created if missing.
- autoSaveScreenshot now saves the frame already captured during the run
  (frameFinished -> takeScreenshot) instead of re-rendering at exit. A fresh
  offscreen doFrame at teardown was crashing in the GL geometry draw for
  networks with real geometry.

Verified: --image-dir writes deterministic <network>.<module>.png files to the
requested dir (auto-created), and field/glyph networks no longer crash with
--save-images.

Known limitation (documented in OffscreenGLRenderer::renderToImage and tracked
separately): real VBO/IBO geometry still renders blank offscreen — forcing it to
draw (waiting for shader promises) crashes in RenderBasicSys/glDrawElements,
likely a GL profile/VAO mismatch vs the QOpenGLWidget context. Background +
orientation axes render correctly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 src/Core/CommandLine/CommandLine.cc           | 15 +++++++++++++
 src/Core/CommandLine/CommandLine.h            |  1 +
 .../Modules/Render/OffscreenGLRenderer.cc     | 10 ++++++---
 src/Interface/Modules/Render/ViewScene.cc     | 21 +++++++++++++++----
 4 files changed, 40 insertions(+), 7 deletions(-)

diff --git a/src/Core/CommandLine/CommandLine.cc b/src/Core/CommandLine/CommandLine.cc
index 3e030c824f..214579bb32 100644
--- a/src/Core/CommandLine/CommandLine.cc
+++ b/src/Core/CommandLine/CommandLine.cc
@@ -53,6 +53,7 @@ class CommandLineParserInternal
       ("execute,e", "executes the given network on startup")
       ("Execute,E", "executes the given network on startup and quits when done")
       ("datadir,d", po::value<std::string>(), "scirun data directory")
+      ("image-dir", po::value<std::string>(), "output directory for ViewScene images saved with --save-images (deterministic names in regression mode)")
       ("regression,r", po::value<int>(), "regression test a network")
       //("logfile,l", po::value<std::string>(), "add output messages to a logfile--TODO")
       ("most-recent,1", "load the most recently used file")
@@ -191,11 +192,13 @@ class ApplicationParametersImpl : public ApplicationParameters
     std::vector<std::string>&& inputFiles,
     const std::optional<boost::filesystem::path>& pythonScriptFile,
     const std::optional<boost::filesystem::path>& dataDirectory,
+    const std::optional<boost::filesystem::path>& imageOutputDirectory,
     const std::optional<std::string>& networkToImport,
     DeveloperParametersPtr devParams,
     const Flags& flags
    ) : entireCommandLine_(entireCommandLine),
     inputFiles_(inputFiles), pythonScriptFile_(pythonScriptFile), dataDirectory_(dataDirectory),
+    imageOutputDirectory_(imageOutputDirectory),
     networkToImport_(networkToImport),
     devParams_(devParams),
     flags_(flags)
@@ -216,6 +219,11 @@ class ApplicationParametersImpl : public ApplicationParameters
     return dataDirectory_;
   }
 
+  std::optional<boost::filesystem::path> imageOutputDirectory() const override
+  {
+    return imageOutputDirectory_;
+  }
+
   std::optional<std::string> importNetworkFile() const override
   {
     return networkToImport_;
@@ -301,6 +309,7 @@ class ApplicationParametersImpl : public ApplicationParameters
   std::vector<std::string> inputFiles_;
   std::optional<boost::filesystem::path> pythonScriptFile_;
   std::optional<boost::filesystem::path> dataDirectory_;
+  std::optional<boost::filesystem::path> imageOutputDirectory_;
   std::optional<std::string> networkToImport_;
   DeveloperParametersPtr devParams_;
   Flags flags_;
@@ -347,6 +356,11 @@ ApplicationParametersHandle CommandLineParser::parse(int argc, const char* argv[
     {
       dataDirectory = boost::filesystem::path(parsed["datadir"].as<std::string>());
     }
+    auto imageOutputDirectory = std::optional<boost::filesystem::path>();
+    if (parsed.count("image-dir") != 0 && !parsed["image-dir"].empty() && !parsed["image-dir"].defaulted())
+    {
+      imageOutputDirectory = boost::filesystem::path(parsed["image-dir"].as<std::string>());
+    }
     auto importNetworkFile = std::optional<std::string>();
     if (parsed.count("import") != 0 && !parsed["import"].empty() && !parsed["import"].defaulted())
     {
@@ -358,6 +372,7 @@ ApplicationParametersHandle CommandLineParser::parse(int argc, const char* argv[
       std::move(inputFiles),
       pythonScriptFile,
       dataDirectory,
+      imageOutputDirectory,
       importNetworkFile,
       makeShared<DeveloperParametersImpl>(
         parseOptionalArg<std::string>(parsed, "threadMode"),
diff --git a/src/Core/CommandLine/CommandLine.h b/src/Core/CommandLine/CommandLine.h
index 3806557613..199614adca 100644
--- a/src/Core/CommandLine/CommandLine.h
+++ b/src/Core/CommandLine/CommandLine.h
@@ -50,6 +50,7 @@ namespace SCIRun {
         virtual const std::vector<std::string>& inputFiles() const = 0;
         virtual std::optional<boost::filesystem::path> pythonScriptFile() const = 0;
         virtual std::optional<boost::filesystem::path> dataDirectory() const = 0;
+        virtual std::optional<boost::filesystem::path> imageOutputDirectory() const = 0;
         virtual std::optional<std::string> importNetworkFile() const = 0;
         virtual bool help() const = 0;
         virtual bool version() const = 0;
diff --git a/src/Interface/Modules/Render/OffscreenGLRenderer.cc b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
index d6e4d7e425..e1f1f886cf 100644
--- a/src/Interface/Modules/Render/OffscreenGLRenderer.cc
+++ b/src/Interface/Modules/Render/OffscreenGLRenderer.cc
@@ -115,10 +115,14 @@ QImage OffscreenGLRenderer::renderToImage()
   context_->makeCurrent(surface_);
   fbo_->bind();
 
-  // Force shader promises to resolve by using a short delta time (same trick
-  // GLWidget::paintGL uses when frameRequested_ is true).
+  // TODO(golden-images): real VBO/IBO geometry (RenderBasicSys -> glDrawElements)
+  // crashes in this offscreen context once shaders are ready and it actually
+  // draws — likely a GL profile/VAO mismatch versus the QOpenGLWidget context.
+  // Until that's fixed we render only a couple of frames (geometry shaders are
+  // usually not ready yet, so the scene is background + axes); this keeps the
+  // existing regression tests stable but produces blank geometry. See branch
+  // notes / issue.
   spire_->doFrame(0.2);
-  // A second frame ensures all deferred passes have actually executed.
   spire_->doFrame(0.2);
 
   QImage img = fbo_->toImage();
diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 6d82e699d0..261a7e4d88 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -29,7 +29,7 @@
 #include <Core/Application/Preferences/Preferences.h>
 #include <Core/Application/Version.h>
 #include <Core/Utils/CurrentFileName.h>
-#include <boost/filesystem/path.hpp>
+#include <boost/filesystem.hpp>
 #include <Core/GeometryPrimitives/Transform.h>
 #include <Core/Logging/Log.h>
 #include <Core/Thread/Mutex.h>
@@ -2834,14 +2834,27 @@ void ViewSceneDialog::autoSaveScreenshot()
   if (Application::Instance().parameters()->isRegressionMode())
   {
     // Deterministic, golden-image-ready name: <dir>/<network>.<module>.png,
-    // keyed to the loaded network file (no wall-clock timestamp). Default the
-    // directory to the current working dir when the screenshot pref is unset.
+    // keyed to the loaded network file (no wall-clock timestamp). The output
+    // directory comes from --image-dir when given, else the screenshot pref,
+    // else the current working directory.
+    const auto imageDir = Application::Instance().parameters()->imageOutputDirectory();
+    if (imageDir)
+      dir = QString::fromStdString(imageDir->string());
     if (dir.isEmpty())
       dir = ".";
+    boost::filesystem::create_directories(dir.toStdString());
     const auto network = QString::fromStdString(
       boost::filesystem::path(Core::getCurrentFileName()).stem().string());
     const auto file = QString("%1/%2.%3.png").arg(dir).arg(network).arg(moduleName);
-    saveScreenshot(file, false);
+
+    // Save the frame already captured during the run (each frameFinished calls
+    // takeScreenshot). Do NOT re-render here: this runs at exit, and a fresh
+    // offscreen doFrame at teardown crashes inside the GL geometry draw for
+    // networks with real geometry. Only render if nothing was captured yet.
+    if (!impl_->screenshotTaker_)
+      takeScreenshot();
+    if (impl_->screenshotTaker_)
+      impl_->screenshotTaker_->saveScreenshot(file);
     return;
   }
 

From 2e6d855ffd726f7b8cc45db8a59a8dc2b12eb77b Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 09:09:53 -0600
Subject: [PATCH 15/64] Add I-key help dialog listing ViewScene keyboard
 shortcuts (issue #694)

Wire up the existing ViewSceneShortcuts.ui (previously unused) as a lazily-
created QDialog shown by pressing I. Grays out unimplemented rows (stereo,
backculling). Adds the .ui to CMakeLists so ui_ViewSceneShortcuts.h is generated.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/CMakeLists.txt   |  1 +
 src/Interface/Modules/Render/ViewScene.cc     | 24 +++++++++++++++++++
 .../Modules/Render/ViewSceneControlsDock.h    |  1 +
 .../Modules/Render/ViewSceneShortcuts.ui      | 10 ++++----
 4 files changed, 31 insertions(+), 5 deletions(-)

diff --git a/src/Interface/Modules/Render/CMakeLists.txt b/src/Interface/Modules/Render/CMakeLists.txt
index 2e8ee9529f..c0bdfebb46 100644
--- a/src/Interface/Modules/Render/CMakeLists.txt
+++ b/src/Interface/Modules/Render/CMakeLists.txt
@@ -51,6 +51,7 @@ SET(Interface_Modules_Render_FORMS
   DevControls.ui
   LightControls.ui
   ViewAxisChooser.ui
+  ViewSceneShortcuts.ui
 )
 
 SET(Interface_Modules_Render_HEADERS_TO_MOC
diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 261a7e4d88..56089511d7 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -234,6 +234,7 @@ namespace Gui {
     QPushButton* toolBar3Position_ {nullptr};
 
     std::vector<ViewSceneDialog*>                     viewScenesToUpdate  {};
+    QDialog*                                          shortcutsDialog_    {nullptr};
 
     std::unique_ptr<Core::GeometryIDGenerator> gid_;
     std::string name_;
@@ -1673,6 +1674,29 @@ void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
     impl_->shiftdown_ = true;
     updateCursor();
     break;
+  case Qt::Key_I:
+    {
+      if (!impl_->shortcutsDialog_)
+      {
+        impl_->shortcutsDialog_ = new QDialog(this);
+        Ui::ViewSceneShortcuts shortcutsUi;
+        shortcutsUi.setupUi(impl_->shortcutsDialog_);
+        // Gray out unimplemented shortcuts: S (stereo, row 17) and U (backculling, row 18)
+        auto* table = shortcutsUi.tableWidget;
+        for (int row : {17, 18})
+        {
+          for (int col = 0; col < table->columnCount(); ++col)
+          {
+            if (auto* item = table->item(row, col))
+              item->setForeground(Qt::gray);
+          }
+        }
+      }
+      impl_->shortcutsDialog_->show();
+      impl_->shortcutsDialog_->raise();
+      impl_->shortcutsDialog_->activateWindow();
+    }
+    break;
   default: ;
   }
 }
diff --git a/src/Interface/Modules/Render/ViewSceneControlsDock.h b/src/Interface/Modules/Render/ViewSceneControlsDock.h
index f12d1cbeeb..96ca828dab 100644
--- a/src/Interface/Modules/Render/ViewSceneControlsDock.h
+++ b/src/Interface/Modules/Render/ViewSceneControlsDock.h
@@ -43,6 +43,7 @@
 #include "Interface/Modules/Render/ui_Screenshot.h"
 #include "Interface/Modules/Render/ui_ViewAxisChooser.h"
 #include "Interface/Modules/Render/ui_ViewSceneControls.h"
+#include "Interface/Modules/Render/ui_ViewSceneShortcuts.h"
 
 #ifndef Q_MOC_RUN
 #include <Core/Datatypes/DatatypeFwd.h>
diff --git a/src/Interface/Modules/Render/ViewSceneShortcuts.ui b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
index 9baf4c79c0..db69676823 100644
--- a/src/Interface/Modules/Render/ViewSceneShortcuts.ui
+++ b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <ui version="4.0">
- <class>Dialog</class>
- <widget class="QDialog" name="Dialog">
+ <class>ViewSceneShortcuts</class>
+ <widget class="QDialog" name="ViewSceneShortcuts">
   <property name="geometry">
    <rect>
     <x>0</x>
@@ -11,7 +11,7 @@
    </rect>
   </property>
   <property name="windowTitle">
-   <string>Dialog</string>
+   <string>ViewScene Keyboard Shortcuts</string>
   </property>
   <layout class="QVBoxLayout" name="verticalLayout">
    <item>
@@ -375,7 +375,7 @@
   <connection>
    <sender>buttonBox</sender>
    <signal>accepted()</signal>
-   <receiver>Dialog</receiver>
+   <receiver>ViewSceneShortcuts</receiver>
    <slot>accept()</slot>
    <hints>
     <hint type="sourcelabel">
@@ -391,7 +391,7 @@
   <connection>
    <sender>buttonBox</sender>
    <signal>rejected()</signal>
-   <receiver>Dialog</receiver>
+   <receiver>ViewSceneShortcuts</receiver>
    <slot>reject()</slot>
    <hints>
     <hint type="sourcelabel">

From 7b7cd8bd986c1b3149327e373cb85bac148b38af Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 09:20:37 -0600
Subject: [PATCH 16/64] Fix shortcuts dialog: add toolbar button, expand
 gray-outs, fix column widths

- Extract showShortcutsDialog() as a proper slot; both Key_I and the new
  toolbar button call it
- Add ? toolbar button (Qt standard question-mark icon) to the top toolbar
- Expand grayed-out rows to cover all currently unimplemented shortcuts:
  1-8 axis views, Ctrl+0, X snap, Ctrl+1-9, Set Home, Home, bounding box,
  flat shading, orthographic, stereo, backculling, wireframe
- Call resizeColumnsToContents() so column widths fit the text

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 56 ++++++++++++++---------
 src/Interface/Modules/Render/ViewScene.h  |  4 ++
 2 files changed, 39 insertions(+), 21 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 56089511d7..20df5106a4 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -567,6 +567,7 @@ void ViewSceneDialog::addToolBar()
   addControlLockButton();
   addScreenshotButton();
   addAutoRotateButton();
+  addShortcutsHelpButton();
 
   //TODO: render toolbar members
   addColorOptionsButton();
@@ -768,6 +769,39 @@ void ViewSceneDialog::addAutoViewButton()
   addToolbarButton(impl_->autoViewButton_, Qt::TopToolBarArea);
 }
 
+void ViewSceneDialog::addShortcutsHelpButton()
+{
+  auto* helpButton = new QPushButton(this);
+  helpButton->setToolTip("Keyboard Shortcuts (I)");
+  helpButton->setIcon(style()->standardIcon(QStyle::SP_MessageBoxQuestion));
+  connect(helpButton, &QPushButton::clicked, this, &ViewSceneDialog::showShortcutsDialog);
+  addToolbarButton(helpButton, Qt::TopToolBarArea);
+}
+
+void ViewSceneDialog::showShortcutsDialog()
+{
+  if (!impl_->shortcutsDialog_)
+  {
+    impl_->shortcutsDialog_ = new QDialog(this);
+    Ui::ViewSceneShortcuts shortcutsUi;
+    shortcutsUi.setupUi(impl_->shortcutsDialog_);
+    auto* table = shortcutsUi.tableWidget;
+    // Gray out shortcuts whose underlying feature is not yet implemented
+    for (int row : {0, 2, 3, 4, 5, 6, 8, 11, 16, 17, 18, 19})
+    {
+      for (int col = 0; col < table->columnCount(); ++col)
+      {
+        if (auto* item = table->item(row, col))
+          item->setForeground(Qt::gray);
+      }
+    }
+    table->resizeColumnsToContents();
+  }
+  impl_->shortcutsDialog_->show();
+  impl_->shortcutsDialog_->raise();
+  impl_->shortcutsDialog_->activateWindow();
+}
+
 void ViewSceneDialog::addScreenshotButton()
 {
   auto* screenshotButton = new QPushButton(this);
@@ -1675,27 +1709,7 @@ void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
     updateCursor();
     break;
   case Qt::Key_I:
-    {
-      if (!impl_->shortcutsDialog_)
-      {
-        impl_->shortcutsDialog_ = new QDialog(this);
-        Ui::ViewSceneShortcuts shortcutsUi;
-        shortcutsUi.setupUi(impl_->shortcutsDialog_);
-        // Gray out unimplemented shortcuts: S (stereo, row 17) and U (backculling, row 18)
-        auto* table = shortcutsUi.tableWidget;
-        for (int row : {17, 18})
-        {
-          for (int col = 0; col < table->columnCount(); ++col)
-          {
-            if (auto* item = table->item(row, col))
-              item->setForeground(Qt::gray);
-          }
-        }
-      }
-      impl_->shortcutsDialog_->show();
-      impl_->shortcutsDialog_->raise();
-      impl_->shortcutsDialog_->activateWindow();
-    }
+    showShortcutsDialog();
     break;
   default: ;
   }
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index 13635f73b6..56d203d06d 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -186,6 +186,9 @@ namespace SCIRun {
       void setFogStartValue(double value);
       void setFogEndValue(double value);
 
+      //---------------- Help ----------------------------------------------------------------------
+      void showShortcutsDialog();
+
       //---------------- Misc. ---------------------------------------------------------------------
       void assignBackgroundColor();
       void setTransparencySortTypeContinuous(bool index);
@@ -245,6 +248,7 @@ namespace SCIRun {
       void addDeveloperControlButton();
       void addToolbarButton(QWidget* w, Qt::ToolBarArea area, ViewSceneControlPopupWidget* widgetToPopup = nullptr);
       void addObjectSelectionButton();
+      void addShortcutsHelpButton();
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);
       void pullCameraState();

From 6d561629567c0bd5375fe235aab0725d6f8ec780 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 09:32:51 -0600
Subject: [PATCH 17/64] Fix shortcuts dialog: read-only table, action names,
 better gray-out color

- Set NoEditTriggers on the table so all cells are read-only
- Populate missing Action column cells for all 20 rows so grayed rows
  show their action name in the disabled style
- Switch gray-out from Qt::gray to palette Disabled/Text color for
  correct appearance on both light and dark themes
- Also strip ItemIsEnabled flag from grayed items
- Increase initial dialog size to 700x720

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc     | 41 ++++++++++++++++++-
 .../Modules/Render/ViewSceneShortcuts.ui      |  4 +-
 2 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 20df5106a4..7290c1b61a 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -786,13 +786,50 @@ void ViewSceneDialog::showShortcutsDialog()
     Ui::ViewSceneShortcuts shortcutsUi;
     shortcutsUi.setupUi(impl_->shortcutsDialog_);
     auto* table = shortcutsUi.tableWidget;
-    // Gray out shortcuts whose underlying feature is not yet implemented
+    table->setEditTriggers(QAbstractItemView::NoEditTriggers);
+
+    // Action names for every row; used to fill cells missing from the .ui
+    static const std::array<const char*, 20> actionNames = {
+      "Axis Views",         // 0:  1-8
+      "Autoview",           // 1:  0
+      "Autoview (no scale)",// 2:  Ctrl+0
+      "Snap to Axis",       // 3:  X
+      "Copy View",          // 4:  Ctrl+1-9
+      "Set Home",           // 5:  Ctrl+H
+      "Home",               // 6:  H
+      "Toggle Axes",        // 7:  A
+      "Bounding Box",       // 8:  B
+      "Toggle Clipping",    // 9:  C
+      "Toggle Fog",         // 10: D
+      "Flat Shading",       // 11: F
+      "Open Help",          // 12: I
+      "View Locking",       // 13: L
+      "Toggle Lighting",    // 14: K
+      "Orientation Icon",   // 15: O
+      "Orthographic",       // 16: P
+      "Stereo",             // 17: S
+      "Backculling",        // 18: U
+      "Wireframe",          // 19: W
+    };
+    for (int row = 0; row < table->rowCount(); ++row)
+    {
+      if (!table->item(row, 0))
+        table->setItem(row, 0, new QTableWidgetItem(actionNames[row]));
+    }
+
+    // Gray out shortcuts whose underlying feature is not yet implemented.
+    // Populate action names first so newly created col-0 items get grayed too.
+    // Use the palette's disabled text color so it works on both light and dark themes.
+    const QColor disabledColor = table->palette().color(QPalette::Disabled, QPalette::Text);
     for (int row : {0, 2, 3, 4, 5, 6, 8, 11, 16, 17, 18, 19})
     {
       for (int col = 0; col < table->columnCount(); ++col)
       {
         if (auto* item = table->item(row, col))
-          item->setForeground(Qt::gray);
+        {
+          item->setForeground(disabledColor);
+          item->setFlags(item->flags() & ~Qt::ItemIsEnabled);
+        }
       }
     }
     table->resizeColumnsToContents();
diff --git a/src/Interface/Modules/Render/ViewSceneShortcuts.ui b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
index db69676823..4af156fda5 100644
--- a/src/Interface/Modules/Render/ViewSceneShortcuts.ui
+++ b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
@@ -6,8 +6,8 @@
    <rect>
     <x>0</x>
     <y>0</y>
-    <width>570</width>
-    <height>614</height>
+    <width>700</width>
+    <height>720</height>
    </rect>
   </property>
   <property name="windowTitle">

From 6bf9c0d26d69ea412b80be1ea721b135e6e32256 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 09:35:27 -0600
Subject: [PATCH 18/64] Gray out all unimplemented shortcuts; only Autoview (0)
 and Help (I) active

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 7290c1b61a..88b9121a55 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -821,7 +821,10 @@ void ViewSceneDialog::showShortcutsDialog()
     // Populate action names first so newly created col-0 items get grayed too.
     // Use the palette's disabled text color so it works on both light and dark themes.
     const QColor disabledColor = table->palette().color(QPalette::Disabled, QPalette::Text);
-    for (int row : {0, 2, 3, 4, 5, 6, 8, 11, 16, 17, 18, 19})
+    // Row 1  = 0 (Autoview)  — implemented
+    // Row 12 = I (Help)      — implemented
+    // Everything else is grayed until the shortcut is wired up
+    for (int row : {0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19})
     {
       for (int col = 0; col < table->columnCount(); ++col)
       {

From ea4d4d1de21a1848b413b1d971f9eacfcc1b52e2 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 09:45:29 -0600
Subject: [PATCH 19/64] Refactor shortcut help into ShortcutDef enum-class with
 string annotations and action mechanics
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add ViewSceneDialog::ShortcutDef nested struct with:
    Id enum (one value per shortcut), Qt key + modifiers, actionName,
    shortcutDisplay, description, and nullable Action (std::function)
- Add private static shortcutTable() returning the canonical ShortcutTable;
    Autoview and OpenHelp have actions; everything else is null (grayed)
- showShortcutsDialog() now builds the table entirely from shortcutTable()
    — no hardcoded row indices or separate name arrays
- keyPressEvent() dispatches through shortcutTable() instead of a switch;
    adding a new shortcut now only requires updating one place
- Strip all row/item data from ViewSceneShortcuts.ui; table is code-driven

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc     | 123 ++++---
 src/Interface/Modules/Render/ViewScene.h      |  31 ++
 .../Modules/Render/ViewSceneShortcuts.ui      | 325 ------------------
 3 files changed, 109 insertions(+), 370 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 88b9121a55..82ef85bdee 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -769,6 +769,58 @@ void ViewSceneDialog::addAutoViewButton()
   addToolbarButton(impl_->autoViewButton_, Qt::TopToolBarArea);
 }
 
+const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
+{
+  using Id = ShortcutDef::Id;
+  // Lambdas take ViewSceneDialog* so they can call any slot on the instance.
+  // Protected access is fine here because this is a member function of ViewSceneDialog.
+  static const ShortcutTable table = {{
+    { Id::AxisViews,       Qt::Key_1, Qt::NoModifier,
+      "Axis Views",        "1-8",     "Preprogrammed views aligning the view with the X, Y, or Z-axis", nullptr },
+    { Id::Autoview,        Qt::Key_0, Qt::NoModifier,
+      "Autoview",          "0",       "Find a view that shows all the data",
+      [](ViewSceneDialog* d) { d->autoViewClicked(); } },
+    { Id::AutoviewNoScale, Qt::Key_0, Qt::ControlModifier,
+      "Autoview (no scale)", "Ctrl+0","Reset the eye so the data is centered", nullptr },
+    { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
+      "Snap to Axis",      "X",       "Snap to the closest axis-aligned view", nullptr },
+    { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
+      "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
+    { Id::SetHome,         Qt::Key_H, Qt::ControlModifier,
+      "Set Home",          "Ctrl+H",  "Store the current view", nullptr },
+    { Id::GotoHome,        Qt::Key_H, Qt::NoModifier,
+      "Home",              "H",       "Go back to the stored view", nullptr },
+    { Id::ToggleAxes,      Qt::Key_A, Qt::NoModifier,
+      "Toggle Axes",       "A",       "Switch axes on/off", nullptr },
+    { Id::BoundingBox,     Qt::Key_B, Qt::NoModifier,
+      "Bounding Box",      "B",       "Switch bounding box mode on/off", nullptr },
+    { Id::ToggleClipping,  Qt::Key_C, Qt::NoModifier,
+      "Toggle Clipping",   "C",       "Switch clipping on/off", nullptr },
+    { Id::ToggleFog,       Qt::Key_D, Qt::NoModifier,
+      "Toggle Fog",        "D",       "Switch fog on/off", nullptr },
+    { Id::FlatShading,     Qt::Key_F, Qt::NoModifier,
+      "Flat Shading",      "F",       "Switch flat shading on/off", nullptr },
+    { Id::OpenHelp,        Qt::Key_I, Qt::NoModifier,
+      "Open Help",         "I",       "Open this help window",
+      [](ViewSceneDialog* d) { d->showShortcutsDialog(); } },
+    { Id::ViewLocking,     Qt::Key_L, Qt::NoModifier,
+      "View Locking",      "L",       "Switch view locking on/off", nullptr },
+    { Id::ToggleLighting,  Qt::Key_K, Qt::NoModifier,
+      "Toggle Lighting",   "K",       "Switch lighting on/off", nullptr },
+    { Id::OrientationIcon, Qt::Key_O, Qt::NoModifier,
+      "Orientation Icon",  "O",       "Switch orientation icon on/off", nullptr },
+    { Id::Orthographic,    Qt::Key_P, Qt::NoModifier,
+      "Orthographic",      "P",       "Switch orthographic projection on/off", nullptr },
+    { Id::Stereo,          Qt::Key_S, Qt::NoModifier,
+      "Stereo",            "S",       "Switch stereo mode on/off", nullptr },
+    { Id::Backculling,     Qt::Key_U, Qt::NoModifier,
+      "Backculling",       "U",       "Switch backculling on/off", nullptr },
+    { Id::Wireframe,       Qt::Key_W, Qt::NoModifier,
+      "Wireframe",         "W",       "Switch wire frame on/off", nullptr },
+  }};
+  return table;
+}
+
 void ViewSceneDialog::addShortcutsHelpButton()
 {
   auto* helpButton = new QPushButton(this);
@@ -787,53 +839,27 @@ void ViewSceneDialog::showShortcutsDialog()
     shortcutsUi.setupUi(impl_->shortcutsDialog_);
     auto* table = shortcutsUi.tableWidget;
     table->setEditTriggers(QAbstractItemView::NoEditTriggers);
+    table->setRowCount(static_cast<int>(numShortcuts));
 
-    // Action names for every row; used to fill cells missing from the .ui
-    static const std::array<const char*, 20> actionNames = {
-      "Axis Views",         // 0:  1-8
-      "Autoview",           // 1:  0
-      "Autoview (no scale)",// 2:  Ctrl+0
-      "Snap to Axis",       // 3:  X
-      "Copy View",          // 4:  Ctrl+1-9
-      "Set Home",           // 5:  Ctrl+H
-      "Home",               // 6:  H
-      "Toggle Axes",        // 7:  A
-      "Bounding Box",       // 8:  B
-      "Toggle Clipping",    // 9:  C
-      "Toggle Fog",         // 10: D
-      "Flat Shading",       // 11: F
-      "Open Help",          // 12: I
-      "View Locking",       // 13: L
-      "Toggle Lighting",    // 14: K
-      "Orientation Icon",   // 15: O
-      "Orthographic",       // 16: P
-      "Stereo",             // 17: S
-      "Backculling",        // 18: U
-      "Wireframe",          // 19: W
-    };
-    for (int row = 0; row < table->rowCount(); ++row)
-    {
-      if (!table->item(row, 0))
-        table->setItem(row, 0, new QTableWidgetItem(actionNames[row]));
-    }
-
-    // Gray out shortcuts whose underlying feature is not yet implemented.
-    // Populate action names first so newly created col-0 items get grayed too.
-    // Use the palette's disabled text color so it works on both light and dark themes.
     const QColor disabledColor = table->palette().color(QPalette::Disabled, QPalette::Text);
-    // Row 1  = 0 (Autoview)  — implemented
-    // Row 12 = I (Help)      — implemented
-    // Everything else is grayed until the shortcut is wired up
-    for (int row : {0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19})
+    int row = 0;
+    for (const auto& sc : shortcutTable())
     {
-      for (int col = 0; col < table->columnCount(); ++col)
+      auto* nameItem     = new QTableWidgetItem(sc.actionName);
+      auto* shortcutItem = new QTableWidgetItem(sc.shortcutDisplay);
+      auto* descItem     = new QTableWidgetItem(sc.description);
+      table->setItem(row, 0, nameItem);
+      table->setItem(row, 1, shortcutItem);
+      table->setItem(row, 2, descItem);
+      if (!sc.isImplemented())
       {
-        if (auto* item = table->item(row, col))
+        for (auto* item : {nameItem, shortcutItem, descItem})
         {
           item->setForeground(disabledColor);
           item->setFlags(item->flags() & ~Qt::ItemIsEnabled);
         }
       }
+      ++row;
     }
     table->resizeColumnsToContents();
   }
@@ -1742,16 +1768,23 @@ void ViewSceneDialog::wheelEvent(QWheelEvent* event)
 
 void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
 {
-  switch (event->key())
+  // Shift is handled separately — it affects cursor state, not a command shortcut.
+  if (event->key() == Qt::Key_Shift)
   {
-  case Qt::Key_Shift:
     impl_->shiftdown_ = true;
     updateCursor();
-    break;
-  case Qt::Key_I:
-    showShortcutsDialog();
-    break;
-  default: ;
+    return;
+  }
+
+  const auto key  = static_cast<Qt::Key>(event->key());
+  const auto mods = event->modifiers() & ~Qt::KeypadModifier; // ignore numpad modifier
+  for (const auto& sc : shortcutTable())
+  {
+    if (sc.key == key && sc.modifiers == mods && sc.action)
+    {
+      sc.action(this);
+      return;
+    }
   }
 }
 
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index 56d203d06d..7b45353c51 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -39,7 +39,9 @@
 #include <Interface/Modules/Render/ViewSceneManager.h>
 #include <Modules/Render/ViewScene.h>
 #include <Modules/Visualization/TextBuilder.h>
+#include <array>
 #include <atomic>
+#include <functional>
 #include "Interface/Modules/Render/ui_ViewScene.h"
 #include <Interface/Modules/Render/share.h>
 #include <Core/Datatypes/Feedback.h>
@@ -62,6 +64,34 @@ namespace SCIRun {
     Q_OBJECT;
 
     public:
+      // -------- Keyboard shortcut registry ----------------------------------------
+      struct ShortcutDef
+      {
+        enum class Id : int
+        {
+          AxisViews, Autoview, AutoviewNoScale, SnapToAxis, CopyView,
+          SetHome, GotoHome, ToggleAxes, BoundingBox, ToggleClipping,
+          ToggleFog, FlatShading, OpenHelp, ViewLocking, ToggleLighting,
+          OrientationIcon, Orthographic, Stereo, Backculling, Wireframe,
+          NUM_SHORTCUTS
+        };
+        using Action = std::function<void(ViewSceneDialog*)>;
+
+        Id              id;
+        Qt::Key         key;
+        Qt::KeyboardModifiers modifiers {Qt::NoModifier};
+        const char*     actionName;
+        const char*     shortcutDisplay;   // human-readable, e.g. "Ctrl+H" or "1-8"
+        const char*     description;
+        Action          action {nullptr};  // null = not yet implemented / shown grayed
+
+        bool isImplemented() const { return static_cast<bool>(action); }
+      };
+
+      static constexpr auto numShortcuts =
+        static_cast<std::size_t>(ShortcutDef::Id::NUM_SHORTCUTS);
+      using ShortcutTable = std::array<ShortcutDef, numShortcuts>;
+
       ViewSceneDialog(const std::string& name, Dataflow::Networks::ModuleStateHandle state,
         QWidget* parent = nullptr);
       ~ViewSceneDialog() override;
@@ -249,6 +279,7 @@ namespace SCIRun {
       void addToolbarButton(QWidget* w, Qt::ToolBarArea area, ViewSceneControlPopupWidget* widgetToPopup = nullptr);
       void addObjectSelectionButton();
       void addShortcutsHelpButton();
+      static const ShortcutTable& shortcutTable();
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);
       void pullCameraState();
diff --git a/src/Interface/Modules/Render/ViewSceneShortcuts.ui b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
index 4af156fda5..b44188385b 100644
--- a/src/Interface/Modules/Render/ViewSceneShortcuts.ui
+++ b/src/Interface/Modules/Render/ViewSceneShortcuts.ui
@@ -16,106 +16,6 @@
   <layout class="QVBoxLayout" name="verticalLayout">
    <item>
     <widget class="QTableWidget" name="tableWidget">
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
-     <row>
-      <property name="text">
-       <string/>
-      </property>
-     </row>
      <column>
       <property name="text">
        <string>Action</string>
@@ -131,231 +31,6 @@
        <string>Details</string>
       </property>
      </column>
-     <item row="0" column="0">
-      <property name="text">
-       <string/>
-      </property>
-     </item>
-     <item row="0" column="1">
-      <property name="text">
-       <string>1-9</string>
-      </property>
-     </item>
-     <item row="0" column="2">
-      <property name="text">
-       <string>Preprogrammed views aligning the view with the X, Y, or Z-axis</string>
-      </property>
-     </item>
-     <item row="1" column="0">
-      <property name="text">
-       <string>Autoview</string>
-      </property>
-     </item>
-     <item row="1" column="1">
-      <property name="text">
-       <string>0</string>
-      </property>
-     </item>
-     <item row="1" column="2">
-      <property name="text">
-       <string>Find a view that shows all the data</string>
-      </property>
-     </item>
-     <item row="2" column="0">
-      <property name="text">
-       <string>Autoview without scaling</string>
-      </property>
-     </item>
-     <item row="2" column="1">
-      <property name="text">
-       <string>Ctrl 0</string>
-      </property>
-     </item>
-     <item row="2" column="2">
-      <property name="text">
-       <string>Reset the eye so the data is centered</string>
-      </property>
-     </item>
-     <item row="3" column="1">
-      <property name="text">
-       <string>X</string>
-      </property>
-     </item>
-     <item row="3" column="2">
-      <property name="text">
-       <string>Snap to the closest axis-aligned view</string>
-      </property>
-     </item>
-     <item row="4" column="1">
-      <property name="text">
-       <string>Ctrl 1-9</string>
-      </property>
-     </item>
-     <item row="4" column="2">
-      <property name="text">
-       <string>Copy view from Viewer Window 1-9</string>
-      </property>
-     </item>
-     <item row="5" column="0">
-      <property name="text">
-       <string>Set Home</string>
-      </property>
-     </item>
-     <item row="5" column="1">
-      <property name="text">
-       <string>Ctrl H</string>
-      </property>
-     </item>
-     <item row="5" column="2">
-      <property name="text">
-       <string>Store the current view</string>
-      </property>
-     </item>
-     <item row="6" column="0">
-      <property name="text">
-       <string>Home</string>
-      </property>
-     </item>
-     <item row="6" column="1">
-      <property name="text">
-       <string>H</string>
-      </property>
-     </item>
-     <item row="6" column="2">
-      <property name="text">
-       <string>Go back to the stored view</string>
-      </property>
-     </item>
-     <item row="7" column="1">
-      <property name="text">
-       <string>A</string>
-      </property>
-     </item>
-     <item row="7" column="2">
-      <property name="text">
-       <string>Toggle axes</string>
-      </property>
-     </item>
-     <item row="8" column="1">
-      <property name="text">
-       <string>B</string>
-      </property>
-     </item>
-     <item row="8" column="2">
-      <property name="text">
-       <string>Toggle bounding box mode</string>
-      </property>
-     </item>
-     <item row="9" column="1">
-      <property name="text">
-       <string>C</string>
-      </property>
-     </item>
-     <item row="9" column="2">
-      <property name="text">
-       <string>Toggle clipping</string>
-      </property>
-     </item>
-     <item row="10" column="1">
-      <property name="text">
-       <string>D</string>
-      </property>
-     </item>
-     <item row="10" column="2">
-      <property name="text">
-       <string>Toggle fog</string>
-      </property>
-     </item>
-     <item row="11" column="1">
-      <property name="text">
-       <string>F</string>
-      </property>
-     </item>
-     <item row="11" column="2">
-      <property name="text">
-       <string>Toggle flat shading</string>
-      </property>
-     </item>
-     <item row="12" column="1">
-      <property name="text">
-       <string>I</string>
-      </property>
-     </item>
-     <item row="12" column="2">
-      <property name="text">
-       <string>Open this help window</string>
-      </property>
-     </item>
-     <item row="13" column="1">
-      <property name="text">
-       <string>L</string>
-      </property>
-     </item>
-     <item row="13" column="2">
-      <property name="text">
-       <string>Toggle view locking</string>
-      </property>
-     </item>
-     <item row="14" column="1">
-      <property name="text">
-       <string>K</string>
-      </property>
-     </item>
-     <item row="14" column="2">
-      <property name="text">
-       <string>Toggle lighting</string>
-      </property>
-     </item>
-     <item row="15" column="1">
-      <property name="text">
-       <string>O</string>
-      </property>
-     </item>
-     <item row="15" column="2">
-      <property name="text">
-       <string>Toggle orientation icon</string>
-      </property>
-     </item>
-     <item row="16" column="1">
-      <property name="text">
-       <string>P</string>
-      </property>
-     </item>
-     <item row="16" column="2">
-      <property name="text">
-       <string>Toggle orthographic projection</string>
-      </property>
-     </item>
-     <item row="17" column="1">
-      <property name="text">
-       <string>S</string>
-      </property>
-     </item>
-     <item row="17" column="2">
-      <property name="text">
-       <string>Toggle stereo mode</string>
-      </property>
-     </item>
-     <item row="18" column="1">
-      <property name="text">
-       <string>U</string>
-      </property>
-     </item>
-     <item row="18" column="2">
-      <property name="text">
-       <string>Toggle backculling</string>
-      </property>
-     </item>
-     <item row="19" column="1">
-      <property name="text">
-       <string>W</string>
-      </property>
-     </item>
-     <item row="19" column="2">
-      <property name="text">
-       <string>Toggle wire frame</string>
-      </property>
-     </item>
     </widget>
    </item>
    <item>

From 91598d136f18e9ae3612a81a2104f08659bd5e30 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:04:22 -0600
Subject: [PATCH 20/64] Draw white ? icon for shortcuts help button to match
 dark toolbar theme

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 82ef85bdee..1a2c7484a4 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -48,6 +48,7 @@
 #include <Interface/Modules/Base/CustomWidgets/CTK/ctkPopupWidget.h>
 #include <es-log/trace-log.h>
 #include <QOpenGLContext>
+#include <QPainter>
 #include <gl-platform/GLPlatform.hpp>
 
 using namespace SCIRun;
@@ -825,7 +826,19 @@ void ViewSceneDialog::addShortcutsHelpButton()
 {
   auto* helpButton = new QPushButton(this);
   helpButton->setToolTip("Keyboard Shortcuts (I)");
-  helpButton->setIcon(style()->standardIcon(QStyle::SP_MessageBoxQuestion));
+  {
+    // Draw a white "?" on a transparent pixmap to match the dark toolbar icon style
+    QPixmap px(24, 24);
+    px.fill(Qt::transparent);
+    QPainter p(&px);
+    p.setPen(Qt::white);
+    QFont f = p.font();
+    f.setBold(true);
+    f.setPixelSize(18);
+    p.setFont(f);
+    p.drawText(px.rect(), Qt::AlignCenter, "?");
+    helpButton->setIcon(QIcon(px));
+  }
   connect(helpButton, &QPushButton::clicked, this, &ViewSceneDialog::showShortcutsDialog);
   addToolbarButton(helpButton, Qt::TopToolBarArea);
 }

From 17b728c7e8c07f5b1028d434d1374dd016442eba Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:08:44 -0600
Subject: [PATCH 21/64] Double-click a shortcut row in help dialog to invoke
 that action

Unimplemented (grayed) rows silently do nothing. Tooltip on the table
advertises the feature.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 1a2c7484a4..11951048a3 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -875,6 +875,13 @@ void ViewSceneDialog::showShortcutsDialog()
       ++row;
     }
     table->resizeColumnsToContents();
+    table->setToolTip("Double-click a row to perform that action");
+    connect(table, &QTableWidget::cellDoubleClicked, [this](int row, int /*col*/)
+    {
+      const auto& sc = shortcutTable()[static_cast<std::size_t>(row)];
+      if (sc.action)
+        sc.action(this);
+    });
   }
   impl_->shortcutsDialog_->show();
   impl_->shortcutsDialog_->raise();

From 64375058332a34df8673987cb930fd119f924f83 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:20:09 -0600
Subject: [PATCH 22/64] Wire O key to toggle corner orientation triad (issue
 #694)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 11951048a3..e705e2c4e4 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -809,7 +809,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::ToggleLighting,  Qt::Key_K, Qt::NoModifier,
       "Toggle Lighting",   "K",       "Switch lighting on/off", nullptr },
     { Id::OrientationIcon, Qt::Key_O, Qt::NoModifier,
-      "Orientation Icon",  "O",       "Switch orientation icon on/off", nullptr },
+      "Orientation Icon",  "O",       "Switch orientation icon on/off",
+      [](ViewSceneDialog* d) {
+        d->showOrientationChecked(!d->state_->getValue(Parameters::AxesVisible).toBool());
+      } },
     { Id::Orthographic,    Qt::Key_P, Qt::NoModifier,
       "Orthographic",      "P",       "Switch orthographic projection on/off", nullptr },
     { Id::Stereo,          Qt::Key_S, Qt::NoModifier,

From 7803bce2c5a9f49bdba86c5cc18ab7cbd034a470 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:22:27 -0600
Subject: [PATCH 23/64] Wire D key to toggle fog (issue #694)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index e705e2c4e4..81649da7b2 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -798,7 +798,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::ToggleClipping,  Qt::Key_C, Qt::NoModifier,
       "Toggle Clipping",   "C",       "Switch clipping on/off", nullptr },
     { Id::ToggleFog,       Qt::Key_D, Qt::NoModifier,
-      "Toggle Fog",        "D",       "Switch fog on/off", nullptr },
+      "Toggle Fog",        "D",       "Switch fog on/off",
+      [](ViewSceneDialog* d) {
+        d->setFogOn(!d->state_->getValue(Parameters::FogOn).toBool());
+      } },
     { Id::FlatShading,     Qt::Key_F, Qt::NoModifier,
       "Flat Shading",      "F",       "Switch flat shading on/off", nullptr },
     { Id::OpenHelp,        Qt::Key_I, Qt::NoModifier,

From 1447831baf7ceb66f3396dcf1b821f051bfbc58f Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:24:56 -0600
Subject: [PATCH 24/64] Wire C key to toggle active clipping plane visibility
 (issue #694)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 81649da7b2..8ad1dd0c15 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -796,7 +796,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::BoundingBox,     Qt::Key_B, Qt::NoModifier,
       "Bounding Box",      "B",       "Switch bounding box mode on/off", nullptr },
     { Id::ToggleClipping,  Qt::Key_C, Qt::NoModifier,
-      "Toggle Clipping",   "C",       "Switch clipping on/off", nullptr },
+      "Toggle Clipping",   "C",       "Switch clipping on/off",
+      [](ViewSceneDialog* d) {
+        d->setClippingPlaneVisible(!d->impl_->clippingPlaneManager_->active().visible);
+      } },
     { Id::ToggleFog,       Qt::Key_D, Qt::NoModifier,
       "Toggle Fog",        "D",       "Switch fog on/off",
       [](ViewSceneDialog* d) {

From 80dd6050ab944560fc9189df8eb1034157f910ca Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:25:56 -0600
Subject: [PATCH 25/64] Wire K key to toggle all lights on/off (issue #694)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 8ad1dd0c15..4d05e22f41 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -813,7 +813,12 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::ViewLocking,     Qt::Key_L, Qt::NoModifier,
       "View Locking",      "L",       "Switch view locking on/off", nullptr },
     { Id::ToggleLighting,  Qt::Key_K, Qt::NoModifier,
-      "Toggle Lighting",   "K",       "Switch lighting on/off", nullptr },
+      "Toggle Lighting",   "K",       "Switch lighting on/off",
+      [](ViewSceneDialog* d) {
+        const bool newState = !d->state_->getValue(Parameters::HeadLightOn).toBool();
+        for (int i = 0; i < ViewSceneDialogImpl::NUM_LIGHTS; ++i)
+          d->toggleLight(i, newState);
+      } },
     { Id::OrientationIcon, Qt::Key_O, Qt::NoModifier,
       "Orientation Icon",  "O",       "Switch orientation icon on/off",
       [](ViewSceneDialog* d) {

From 78dcbd63f6d4065606ccf2ce89ceda7395c05f3d Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:26:50 -0600
Subject: [PATCH 26/64] Wire L key to toggle view locking (locks/unlocks all
 three axes) (issue #694)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 4d05e22f41..ee3cf1e00b 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -811,7 +811,13 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       "Open Help",         "I",       "Open this help window",
       [](ViewSceneDialog* d) { d->showShortcutsDialog(); } },
     { Id::ViewLocking,     Qt::Key_L, Qt::NoModifier,
-      "View Locking",      "L",       "Switch view locking on/off", nullptr },
+      "View Locking",      "L",       "Switch view locking on/off",
+      [](ViewSceneDialog* d) {
+        const bool anyLocked = d->impl_->lockRotation_->isChecked() ||
+                               d->impl_->lockPan_->isChecked()      ||
+                               d->impl_->lockZoom_->isChecked();
+        if (anyLocked) d->unlockAllTriggered(); else d->lockAllTriggered();
+      } },
     { Id::ToggleLighting,  Qt::Key_K, Qt::NoModifier,
       "Toggle Lighting",   "K",       "Switch lighting on/off",
       [](ViewSceneDialog* d) {

From 704ac75ab245a28516fc283f8c557816044d564f Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:28:40 -0600
Subject: [PATCH 27/64] Forward key presses to ViewSceneDialog when shortcuts
 help dialog has focus

Extract dispatchShortcutKey() from keyPressEvent. Install an event filter
on the shortcuts dialog that calls it; returns true only when a shortcut
fired, so Escape/Enter still close the dialog normally.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 33 +++++++++++++++++------
 src/Interface/Modules/Render/ViewScene.h  |  2 ++
 2 files changed, 27 insertions(+), 8 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index ee3cf1e00b..34eb3c4a06 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -868,6 +868,7 @@ void ViewSceneDialog::showShortcutsDialog()
   if (!impl_->shortcutsDialog_)
   {
     impl_->shortcutsDialog_ = new QDialog(this);
+    impl_->shortcutsDialog_->installEventFilter(this);
     Ui::ViewSceneShortcuts shortcutsUi;
     shortcutsUi.setupUi(impl_->shortcutsDialog_);
     auto* table = shortcutsUi.tableWidget;
@@ -1806,6 +1807,21 @@ void ViewSceneDialog::wheelEvent(QWheelEvent* event)
   }
 }
 
+bool ViewSceneDialog::dispatchShortcutKey(QKeyEvent* event)
+{
+  const auto key  = static_cast<Qt::Key>(event->key());
+  const auto mods = event->modifiers() & ~Qt::KeypadModifier;
+  for (const auto& sc : shortcutTable())
+  {
+    if (sc.key == key && sc.modifiers == mods && sc.action)
+    {
+      sc.action(this);
+      return true;
+    }
+  }
+  return false;
+}
+
 void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
 {
   // Shift is handled separately — it affects cursor state, not a command shortcut.
@@ -1815,17 +1831,18 @@ void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
     updateCursor();
     return;
   }
+  dispatchShortcutKey(event);
+}
 
-  const auto key  = static_cast<Qt::Key>(event->key());
-  const auto mods = event->modifiers() & ~Qt::KeypadModifier; // ignore numpad modifier
-  for (const auto& sc : shortcutTable())
+bool ViewSceneDialog::eventFilter(QObject* obj, QEvent* event)
+{
+  if (obj == impl_->shortcutsDialog_ && event->type() == QEvent::KeyPress)
   {
-    if (sc.key == key && sc.modifiers == mods && sc.action)
-    {
-      sc.action(this);
-      return;
-    }
+    auto* ke = static_cast<QKeyEvent*>(event);
+    if (dispatchShortcutKey(ke))
+      return true;  // consumed — don't pass to dialog
   }
+  return ModuleDialogGeneric::eventFilter(obj, event);
 }
 
 void ViewSceneDialog::keyReleaseEvent(QKeyEvent* event)
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index 7b45353c51..d3cbeb422e 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -234,6 +234,7 @@ namespace SCIRun {
     protected:
       //---------------- Initialization ------------------------------------------------------------
       void pullSpecial() override;
+      bool eventFilter(QObject* obj, QEvent* event) override;
 
       void newGeometryValue(bool forceAllObjectsToUpdate, bool clippingPlanesUpdated);
       void updateAllGeometries();
@@ -280,6 +281,7 @@ namespace SCIRun {
       void addObjectSelectionButton();
       void addShortcutsHelpButton();
       static const ShortcutTable& shortcutTable();
+      bool dispatchShortcutKey(QKeyEvent* event);
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);
       void pullCameraState();

From 7530485cc8dbc2149684cce6758e1af2af6843cd Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:38:01 -0600
Subject: [PATCH 28/64] Fix shortcut forwarding when help dialog has focus

Key events go to the focused child widget (QTableWidget), not the dialog
itself. Install the event filter on the table too and check for either
object in eventFilter.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 34eb3c4a06..73f2736616 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -236,6 +236,7 @@ namespace Gui {
 
     std::vector<ViewSceneDialog*>                     viewScenesToUpdate  {};
     QDialog*                                          shortcutsDialog_    {nullptr};
+    QTableWidget*                                     shortcutsTable_     {nullptr};
 
     std::unique_ptr<Core::GeometryIDGenerator> gid_;
     std::string name_;
@@ -872,6 +873,8 @@ void ViewSceneDialog::showShortcutsDialog()
     Ui::ViewSceneShortcuts shortcutsUi;
     shortcutsUi.setupUi(impl_->shortcutsDialog_);
     auto* table = shortcutsUi.tableWidget;
+    impl_->shortcutsTable_ = table;
+    table->installEventFilter(this);
     table->setEditTriggers(QAbstractItemView::NoEditTriggers);
     table->setRowCount(static_cast<int>(numShortcuts));
 
@@ -1836,11 +1839,11 @@ void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
 
 bool ViewSceneDialog::eventFilter(QObject* obj, QEvent* event)
 {
-  if (obj == impl_->shortcutsDialog_ && event->type() == QEvent::KeyPress)
+  if (event->type() == QEvent::KeyPress &&
+      (obj == impl_->shortcutsDialog_ || obj == impl_->shortcutsTable_))
   {
-    auto* ke = static_cast<QKeyEvent*>(event);
-    if (dispatchShortcutKey(ke))
-      return true;  // consumed — don't pass to dialog
+    if (dispatchShortcutKey(static_cast<QKeyEvent*>(event)))
+      return true;  // shortcut fired — consume so dialog doesn't also handle it
   }
   return ModuleDialogGeneric::eventFilter(obj, event);
 }

From 2718c171d22344540c9ed62f14660917d639812f Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:45:18 -0600
Subject: [PATCH 29/64] Position shortcuts dialog at top-right of ViewScene;
 remember position in session

On first open, dialog appears flush with the right edge of the ViewScene
window. QEvent::Move is caught in eventFilter and stored in
shortcutsDialogPos_ (std::optional<QPoint>), so subsequent opens restore
wherever the user last dragged it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 73f2736616..c8af4b772c 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -237,6 +237,7 @@ namespace Gui {
     std::vector<ViewSceneDialog*>                     viewScenesToUpdate  {};
     QDialog*                                          shortcutsDialog_    {nullptr};
     QTableWidget*                                     shortcutsTable_     {nullptr};
+    std::optional<QPoint>                             shortcutsDialogPos_ {};
 
     std::unique_ptr<Core::GeometryIDGenerator> gid_;
     std::string name_;
@@ -906,6 +907,10 @@ void ViewSceneDialog::showShortcutsDialog()
       if (sc.action)
         sc.action(this);
     });
+    // Default position: top-right of the ViewScene window to minimise overlap.
+    // Use saved position if the user has moved it previously this session.
+    const QPoint defaultPos = mapToGlobal(QPoint(width(), 0));
+    impl_->shortcutsDialog_->move(impl_->shortcutsDialogPos_.value_or(defaultPos));
   }
   impl_->shortcutsDialog_->show();
   impl_->shortcutsDialog_->raise();
@@ -1839,6 +1844,14 @@ void ViewSceneDialog::keyPressEvent(QKeyEvent* event)
 
 bool ViewSceneDialog::eventFilter(QObject* obj, QEvent* event)
 {
+  if (obj == impl_->shortcutsDialog_)
+  {
+    if (event->type() == QEvent::Move)
+    {
+      impl_->shortcutsDialogPos_ = impl_->shortcutsDialog_->pos();
+      return false;
+    }
+  }
   if (event->type() == QEvent::KeyPress &&
       (obj == impl_->shortcutsDialog_ || obj == impl_->shortcutsTable_))
   {

From e70eddcdb0828cb0b6531cb6e17b42da127785d7 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 10:51:51 -0600
Subject: [PATCH 30/64] Fix orientation glyph squished on first show due to
 stale 640x480 default size

ScreenParams initialises to 640x480 and is only updated by resizeGL(), which
Qt calls asynchronously. On first show, paintGL() fires before resizeGL(),
so the glyph renders with the wrong aspect ratio until the first manual resize.

Fix: at the top of paintGL(), if the widget's actual size doesn't match what
the renderer knows, call eventResize() immediately before doFrame(). This is
idempotent and harmless on subsequent frames where the sizes already agree.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/GLWidget.cc | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/src/Interface/Modules/Render/GLWidget.cc b/src/Interface/Modules/Render/GLWidget.cc
index 2e0f300076..a3085e125d 100644
--- a/src/Interface/Modules/Render/GLWidget.cc
+++ b/src/Interface/Modules/Render/GLWidget.cc
@@ -73,6 +73,17 @@ void GLWidget::initializeGL()
 
 void GLWidget::paintGL()
 {
+  // Guard against the race where paintGL fires before resizeGL has been called
+  // with the actual widget dimensions (e.g. on first show). Without this the
+  // orientation glyph renders with the 640x480 default aspect ratio.
+  if (width() > 0 && height() > 0 &&
+      (graphics_->getScreenWidthPixels()  != static_cast<size_t>(width()) ||
+       graphics_->getScreenHeightPixels() != static_cast<size_t>(height())))
+  {
+    graphics_->eventResize(static_cast<size_t>(width()),
+                           static_cast<size_t>(height()));
+  }
+
   //set to 200ms to force promise fullfilment every frame if a good frame as been requested
   const double lUpdateTime = frameRequested_ ? 0.2 : updateTime;
   graphics_->doFrame(lUpdateTime);

From 57a15c1d9f1dd53e82379ffa7f030970cdd840aa Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:01:56 -0600
Subject: [PATCH 31/64] Implement keys 1-6 for axis-aligned views (Tier 2)

Adds setAxisView(int n) mapping 1=+X, 2=-X, 3=+Y, 4=-Y, 5=+Z, 6=-Z
with sensible up vectors. dispatchShortcutKey handles them as a range
so the help dialog still shows one "1-6" row rather than six. The
AxisViews entry gets a non-null action so the row is no longer grayed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 30 ++++++++++++++++++++++-
 src/Interface/Modules/Render/ViewScene.h  |  1 +
 2 files changed, 30 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index c8af4b772c..d139d81860 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -779,7 +779,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
   // Protected access is fine here because this is a member function of ViewSceneDialog.
   static const ShortcutTable table = {{
     { Id::AxisViews,       Qt::Key_1, Qt::NoModifier,
-      "Axis Views",        "1-8",     "Preprogrammed views aligning the view with the X, Y, or Z-axis", nullptr },
+      "Axis Views",        "1-6",     "Preprogrammed views aligning the view with the X, Y, or Z-axis",
+      [](ViewSceneDialog* d) { d->setAxisView(1); } },
     { Id::Autoview,        Qt::Key_0, Qt::NoModifier,
       "Autoview",          "0",       "Find a view that shows all the data",
       [](ViewSceneDialog* d) { d->autoViewClicked(); } },
@@ -1819,6 +1820,15 @@ bool ViewSceneDialog::dispatchShortcutKey(QKeyEvent* event)
 {
   const auto key  = static_cast<Qt::Key>(event->key());
   const auto mods = event->modifiers() & ~Qt::KeypadModifier;
+
+  // Keys 1-6 (no modifier) → axis-aligned views; handled as a range so the
+  // table only needs one representative entry for the help dialog.
+  if (mods == Qt::NoModifier && key >= Qt::Key_1 && key <= Qt::Key_6)
+  {
+    setAxisView(key - Qt::Key_0);   // Qt::Key_1 - Qt::Key_0 == 1, etc.
+    return true;
+  }
+
   for (const auto& sc : shortcutTable())
   {
     if (sc.key == key && sc.modifiers == mods && sc.action)
@@ -1898,6 +1908,24 @@ void ViewSceneDialog::updateCursor()
 //---------------- Camera --------------------------------------------------------------------------
 //--------------------------------------------------------------------------------------------------
 
+void ViewSceneDialog::setAxisView(int n)
+{
+  // Maps key 1-6 to the six cardinal axis-aligned views with sensible up vectors.
+  static const std::pair<glm::vec3, glm::vec3> views[6] = {
+    { V( 1, 0, 0), V( 0, 1, 0) },   // 1: +X  (Y up)
+    { V(-1, 0, 0), V( 0, 1, 0) },   // 2: -X  (Y up)
+    { V( 0, 1, 0), V( 0, 0, 1) },   // 3: +Y  (Z up)
+    { V( 0,-1, 0), V( 0, 0, 1) },   // 4: -Y  (Z up)
+    { V( 0, 0, 1), V( 0, 1, 0) },   // 5: +Z  (Y up)
+    { V( 0, 0,-1), V( 0, 1, 0) },   // 6: -Z  (Y up)
+  };
+  if (n < 1 || n > 6) return;
+  auto spire = impl_->mSpire.lock();
+  if (!spire) return;
+  spire->setView(views[n - 1].first, views[n - 1].second);
+  pushCameraState();
+}
+
 void ViewSceneDialog::snapToViewAxis()
 {
   auto upName = impl_->viewAxisChooser_->upVectorComboBox_->currentText();
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index d3cbeb422e..5db5a07be1 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -282,6 +282,7 @@ namespace SCIRun {
       void addShortcutsHelpButton();
       static const ShortcutTable& shortcutTable();
       bool dispatchShortcutKey(QKeyEvent* event);
+      void setAxisView(int n);   // n=1..6 → +X,-X,+Y,-Y,+Z,-Z
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);
       void pullCameraState();

From 104b6ebe1b2cd6dcaa03f5857e9be6e81b4803db Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:02:26 -0600
Subject: [PATCH 32/64] Wire X key to snap-to-axis view (Tier 2)

Calls snapToViewAxis() which snaps to whichever axis is currently
selected in the View Axis Chooser toolbar popup.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index d139d81860..6e11847f0b 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -787,7 +787,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::AutoviewNoScale, Qt::Key_0, Qt::ControlModifier,
       "Autoview (no scale)", "Ctrl+0","Reset the eye so the data is centered", nullptr },
     { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
-      "Snap to Axis",      "X",       "Snap to the closest axis-aligned view", nullptr },
+      "Snap to Axis",      "X",       "Snap to the selected axis-aligned view",
+      [](ViewSceneDialog* d) { d->snapToViewAxis(); } },
     { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
       "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
     { Id::SetHome,         Qt::Key_H, Qt::ControlModifier,

From 7685da38f78d80a609c95f2b2f7a601733f0a337 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:03:41 -0600
Subject: [PATCH 33/64] Implement SetHome (Ctrl+H) and GotoHome (H) shortcuts
 (Tier 2)

Ctrl+H saves the current camera distance, lookAt, and rotation into
a transient HomeCamera stored on impl_. H restores it. If no home
has been set, H is a no-op.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 26 +++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 6e11847f0b..e74690bc5c 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -209,6 +209,9 @@ namespace Gui {
                                                                          {0.8f, 0.8f, 0.5f}, {0.4f, 0.7f, 0.3f},
                                                                          {0.2f, 0.4f, 0.5f}, {0.5f, 0.3f, 0.5f}};
 
+    struct HomeCamera { float distance; glm::vec3 lookAt; glm::quat rotation; };
+    std::optional<HomeCamera> homeView_;
+
     std::optional<QPoint> savedPos_;
     QColor                                bgColor_                      {};
     ScaleBarData                              scaleBar_                     {};
@@ -792,9 +795,28 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
       "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
     { Id::SetHome,         Qt::Key_H, Qt::ControlModifier,
-      "Set Home",          "Ctrl+H",  "Store the current view", nullptr },
+      "Set Home",          "Ctrl+H",  "Store the current view",
+      [](ViewSceneDialog* d) {
+        auto spire = d->impl_->mSpire.lock();
+        if (!spire) return;
+        d->impl_->homeView_ = ViewSceneDialogImpl::HomeCamera{
+          spire->getCameraDistance(),
+          spire->getCameraLookAt(),
+          spire->getCameraRotation()
+        };
+      } },
     { Id::GotoHome,        Qt::Key_H, Qt::NoModifier,
-      "Home",              "H",       "Go back to the stored view", nullptr },
+      "Home",              "H",       "Go back to the stored view",
+      [](ViewSceneDialog* d) {
+        if (!d->impl_->homeView_) return;
+        auto spire = d->impl_->mSpire.lock();
+        if (!spire) return;
+        const auto& hv = *d->impl_->homeView_;
+        spire->setCameraDistance(hv.distance);
+        spire->setCameraLookAt(hv.lookAt);
+        spire->setCameraRotation(hv.rotation);
+        d->pushCameraState();
+      } },
     { Id::ToggleAxes,      Qt::Key_A, Qt::NoModifier,
       "Toggle Axes",       "A",       "Switch axes on/off", nullptr },
     { Id::BoundingBox,     Qt::Key_B, Qt::NoModifier,

From e4362b0c88c92fd8ed3f239e054e80eefe6dc205 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:04:14 -0600
Subject: [PATCH 34/64] Wire Ctrl+0 AutoviewNoScale shortcut (Tier 2)

No separate center-without-rescale API exists in SRInterface yet, so
this calls doAutoView() as a placeholder. A TODO marks the spot for
when spire gets a centerView() method.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index e74690bc5c..8203c2e98e 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -788,7 +788,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       "Autoview",          "0",       "Find a view that shows all the data",
       [](ViewSceneDialog* d) { d->autoViewClicked(); } },
     { Id::AutoviewNoScale, Qt::Key_0, Qt::ControlModifier,
-      "Autoview (no scale)", "Ctrl+0","Reset the eye so the data is centered", nullptr },
+      "Autoview (no scale)", "Ctrl+0","Reset the eye so the data is centered",
+      // TODO: add a spire->centerView() that moves lookAt to bbox center
+      // without changing zoom; for now doAutoView is a reasonable stand-in.
+      [](ViewSceneDialog* d) { d->autoViewClicked(); } },
     { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
       "Snap to Axis",      "X",       "Snap to the selected axis-aligned view",
       [](ViewSceneDialog* d) { d->snapToViewAxis(); } },

From 14548cecd9c82525cd3f4896a3d47151699f6cad Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:08:12 -0600
Subject: [PATCH 35/64] Change SetHome from Ctrl+H to Alt+H to avoid macOS
 hide-window conflict

On macOS Qt::ControlModifier == Command, and Cmd+H is reserved by the
system to hide the window. Alt (Option) + H has no system conflict.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 8203c2e98e..5555800e65 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -797,8 +797,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       [](ViewSceneDialog* d) { d->snapToViewAxis(); } },
     { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
       "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
-    { Id::SetHome,         Qt::Key_H, Qt::ControlModifier,
-      "Set Home",          "Ctrl+H",  "Store the current view",
+    { Id::SetHome,         Qt::Key_H, Qt::AltModifier,
+      "Set Home",          "Alt+H",   "Store the current view",
       [](ViewSceneDialog* d) {
         auto spire = d->impl_->mSpire.lock();
         if (!spire) return;

From 6c4d2383bf4318dab056808b54d13b9680321e45 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:12:23 -0600
Subject: [PATCH 36/64] Switch Alt modifier for consistency; flash tooltip when
 home is set
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AutoviewNoScale: Ctrl+0 → Alt+0 (consistent with Alt+H for SetHome)
- SetHome now shows a brief "Home view set" tooltip near the top of
  the ViewScene for 1.5s as a visual confirmation

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 5555800e65..72873ec9c3 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -49,6 +49,7 @@
 #include <es-log/trace-log.h>
 #include <QOpenGLContext>
 #include <QPainter>
+#include <QToolTip>
 #include <gl-platform/GLPlatform.hpp>
 
 using namespace SCIRun;
@@ -787,8 +788,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::Autoview,        Qt::Key_0, Qt::NoModifier,
       "Autoview",          "0",       "Find a view that shows all the data",
       [](ViewSceneDialog* d) { d->autoViewClicked(); } },
-    { Id::AutoviewNoScale, Qt::Key_0, Qt::ControlModifier,
-      "Autoview (no scale)", "Ctrl+0","Reset the eye so the data is centered",
+    { Id::AutoviewNoScale, Qt::Key_0, Qt::AltModifier,
+      "Autoview (no scale)", "Alt+0", "Reset the eye so the data is centered",
       // TODO: add a spire->centerView() that moves lookAt to bbox center
       // without changing zoom; for now doAutoView is a reasonable stand-in.
       [](ViewSceneDialog* d) { d->autoViewClicked(); } },
@@ -807,6 +808,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
           spire->getCameraLookAt(),
           spire->getCameraRotation()
         };
+        QToolTip::showText(d->mapToGlobal(QPoint(d->width() / 2, 32)),
+                           "Home view set", d, {}, 1500);
       } },
     { Id::GotoHome,        Qt::Key_H, Qt::NoModifier,
       "Home",              "H",       "Go back to the stored view",

From b138275909868f65bb84ab0d1bba9b3945416aa1 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:13:52 -0600
Subject: [PATCH 37/64] Add tooltip flash for all keyboard shortcuts

flashShortcutTooltip() shows the action name near the top-center of
the ViewScene for 1.5s. dispatchShortcutKey calls it after any
successful action, including axis views (shows "+X View" etc.).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 13 ++++++++++---
 src/Interface/Modules/Render/ViewScene.h  |  1 +
 2 files changed, 11 insertions(+), 3 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 72873ec9c3..10d69ec009 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -808,8 +808,6 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
           spire->getCameraLookAt(),
           spire->getCameraRotation()
         };
-        QToolTip::showText(d->mapToGlobal(QPoint(d->width() / 2, 32)),
-                           "Home view set", d, {}, 1500);
       } },
     { Id::GotoHome,        Qt::Key_H, Qt::NoModifier,
       "Home",              "H",       "Go back to the stored view",
@@ -1845,6 +1843,11 @@ void ViewSceneDialog::wheelEvent(QWheelEvent* event)
   }
 }
 
+void ViewSceneDialog::flashShortcutTooltip(const QString& msg)
+{
+  QToolTip::showText(mapToGlobal(QPoint(width() / 2, 32)), msg, this, {}, 1500);
+}
+
 bool ViewSceneDialog::dispatchShortcutKey(QKeyEvent* event)
 {
   const auto key  = static_cast<Qt::Key>(event->key());
@@ -1854,7 +1857,10 @@ bool ViewSceneDialog::dispatchShortcutKey(QKeyEvent* event)
   // table only needs one representative entry for the help dialog.
   if (mods == Qt::NoModifier && key >= Qt::Key_1 && key <= Qt::Key_6)
   {
-    setAxisView(key - Qt::Key_0);   // Qt::Key_1 - Qt::Key_0 == 1, etc.
+    static const char* const axisNames[] = {"+X","-X","+Y","-Y","+Z","-Z"};
+    const int n = key - Qt::Key_0;
+    setAxisView(n);
+    flashShortcutTooltip(QString("%1 View").arg(axisNames[n - 1]));
     return true;
   }
 
@@ -1863,6 +1869,7 @@ bool ViewSceneDialog::dispatchShortcutKey(QKeyEvent* event)
     if (sc.key == key && sc.modifiers == mods && sc.action)
     {
       sc.action(this);
+      flashShortcutTooltip(sc.actionName);
       return true;
     }
   }
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index 5db5a07be1..fcb83615fc 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -283,6 +283,7 @@ namespace SCIRun {
       static const ShortcutTable& shortcutTable();
       bool dispatchShortcutKey(QKeyEvent* event);
       void setAxisView(int n);   // n=1..6 → +X,-X,+Y,-Y,+Z,-Z
+      void flashShortcutTooltip(const QString& msg);
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);
       void pullCameraState();

From 7a50595d56d060ee0b9ded78b7b30de547f67d2a Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:20:29 -0600
Subject: [PATCH 38/64] Fix orientation glyph aspect ratio at initialization in
 CoreBootstrap

CoreBootstrap was initializing StaticCamera and StaticOrthoCamera with
a hardcoded 800x600 aspect ratio. Since it runs inside the first
doFrame, this always overrode whatever eventResize had set earlier,
causing the glyph to render with the wrong aspect until the next
resizeGL (i.e. first manual resize).

Fix: read the actual dimensions from StaticScreenDims, which is
populated by SRInterface::setupCore and kept current by eventResize.
Fall back to 800/600 only if the component is missing or zero-height.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ES/CoreBootstrap.cc | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ES/CoreBootstrap.cc b/src/Interface/Modules/Render/ES/CoreBootstrap.cc
index 83d27c292c..4ffc896cb3 100644
--- a/src/Interface/Modules/Render/ES/CoreBootstrap.cc
+++ b/src/Interface/Modules/Render/ES/CoreBootstrap.cc
@@ -160,8 +160,14 @@ class CoreBootstrap : public spire::EmptySystem
     core.addExemptComponent<spire::StaticFS>();
 
     // Setup default camera projection.
+    // Use the actual screen dimensions already stored in StaticScreenDims
+    // (set by SRInterface::setupCore / eventResize) so the initial aspect
+    // ratio is correct even before the first resizeGL callback.
     gen::StaticCamera cam;
-    float aspect = static_cast<float>(800) / static_cast<float>(600);
+    const gen::StaticScreenDims* screenDims = core.getStaticComponent<gen::StaticScreenDims>();
+    const float aspect = (screenDims && screenDims->height > 0)
+      ? static_cast<float>(screenDims->width) / static_cast<float>(screenDims->height)
+      : static_cast<float>(800) / static_cast<float>(600);
 
     float perspFOVY = 0.59f;
     float perspZNear = 1.0f;

From 7e2777d26e1436acf5ae148ab5bdd94fd04b7d7d Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:21:40 -0600
Subject: [PATCH 39/64] Fix missing tooltip for '0' (Autoview) shortcut

The autoview button had setShortcut(Key_0) which intercepted the key
before keyPressEvent, bypassing dispatchShortcutKey and its tooltip.
Removed the duplicate; the dispatcher is now the sole handler for '0'.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 10d69ec009..d81b0574cb 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -771,7 +771,7 @@ void ViewSceneDialog::addAutoViewButton()
   impl_->autoViewButton_ = new QPushButton(this);
   impl_->autoViewButton_->setToolTip("Auto View");
   impl_->autoViewButton_->setIcon(QPixmap(":/general/Resources/ViewScene/autoview.png"));
-  impl_->autoViewButton_->setShortcut(Qt::Key_0);
+  // Key_0 is handled by dispatchShortcutKey (shows tooltip); don't duplicate with setShortcut.
   connect(impl_->autoViewButton_, &QPushButton::clicked, this, &ViewSceneDialog::autoViewClicked);
   addToolbarButton(impl_->autoViewButton_, Qt::TopToolBarArea);
 }

From f829ef3801ae00b595ce6568f2cb10afccc7755c Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 5 Jun 2026 21:51:00 -0600
Subject: [PATCH 40/64] Implement X as snap-to-nearest-axis rather than
 combo-box dependency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous impl called snapToViewAxis() which reads from the View
Axis Chooser dropdown — empty on startup, so X did nothing.

setClosestAxisView() reads the current camera rotation quaternion,
derives the world-space look and up vectors via mat3 transpose, then
finds the nearest cardinal axis for each independently. Works from any
camera orientation with no UI state dependency.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 47 ++++++++++++++++++++++-
 src/Interface/Modules/Render/ViewScene.h  |  3 +-
 2 files changed, 47 insertions(+), 3 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index d81b0574cb..f0626c1cb9 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -794,8 +794,8 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       // without changing zoom; for now doAutoView is a reasonable stand-in.
       [](ViewSceneDialog* d) { d->autoViewClicked(); } },
     { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
-      "Snap to Axis",      "X",       "Snap to the selected axis-aligned view",
-      [](ViewSceneDialog* d) { d->snapToViewAxis(); } },
+      "Snap to Axis",      "X",       "Snap to the nearest axis-aligned view",
+      [](ViewSceneDialog* d) { d->setClosestAxisView(); } },
     { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
       "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
     { Id::SetHome,         Qt::Key_H, Qt::AltModifier,
@@ -1962,6 +1962,49 @@ void ViewSceneDialog::setAxisView(int n)
   pushCameraState();
 }
 
+void ViewSceneDialog::setClosestAxisView()
+{
+  auto spire = impl_->mSpire.lock();
+  if (!spire) return;
+
+  // The camera rotation quaternion is from glm::lookAt (world→camera).
+  // Transposing its mat3 gives the camera axes in world space:
+  //   Rt[0] = right,  Rt[1] = up,  Rt[2] = -forward  (all in world coords)
+  const glm::mat3 Rt = glm::transpose(glm::mat3_cast(spire->getCameraRotation()));
+  const glm::vec3 viewDir = -Rt[2];   // current look direction (world space)
+  const glm::vec3 upDir   =  Rt[1];   // current up direction  (world space)
+
+  static const glm::vec3 axes[6] = {
+    { 1, 0, 0}, {-1, 0, 0},
+    { 0, 1, 0}, { 0,-1, 0},
+    { 0, 0, 1}, { 0, 0,-1},
+  };
+
+  // Find the cardinal axis closest to the current view direction.
+  int bestView = 0;
+  float bestViewDot = -2.f;
+  for (int i = 0; i < 6; ++i)
+  {
+    float d = glm::dot(viewDir, axes[i]);
+    if (d > bestViewDot) { bestViewDot = d; bestView = i; }
+  }
+  const glm::vec3 view = axes[bestView];
+
+  // Find the cardinal axis closest to the current up direction that is
+  // perpendicular to the chosen view axis.
+  int bestUp = 0;
+  float bestUpDot = -2.f;
+  for (int i = 0; i < 6; ++i)
+  {
+    if (std::abs(glm::dot(view, axes[i])) > 0.5f) continue; // skip parallel/anti-parallel
+    float d = glm::dot(upDir, axes[i]);
+    if (d > bestUpDot) { bestUpDot = d; bestUp = i; }
+  }
+
+  spire->setView(view, axes[bestUp]);
+  pushCameraState();
+}
+
 void ViewSceneDialog::snapToViewAxis()
 {
   auto upName = impl_->viewAxisChooser_->upVectorComboBox_->currentText();
diff --git a/src/Interface/Modules/Render/ViewScene.h b/src/Interface/Modules/Render/ViewScene.h
index fcb83615fc..0d2e2192af 100644
--- a/src/Interface/Modules/Render/ViewScene.h
+++ b/src/Interface/Modules/Render/ViewScene.h
@@ -282,7 +282,8 @@ namespace SCIRun {
       void addShortcutsHelpButton();
       static const ShortcutTable& shortcutTable();
       bool dispatchShortcutKey(QKeyEvent* event);
-      void setAxisView(int n);   // n=1..6 → +X,-X,+Y,-Y,+Z,-Z
+      void setAxisView(int n);         // n=1..6 → +X,-X,+Y,-Y,+Z,-Z
+      void setClosestAxisView();       // snap to nearest cardinal axis
       void flashShortcutTooltip(const QString& msg);
       void addLightButtons();
       QColor checkColorSetting(const std::string& rgb, const QColor& defaultColor);

From 2b76115a0702c187cc0487ec7e962943071987a4 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 6 Jun 2026 00:18:13 -0600
Subject: [PATCH 41/64] Hide unimplemented shortcuts from help dialog; add TODO
 comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Unimplemented shortcut rows are now hidden rather than grayed out.
Each null entry in shortcutTable() has a detailed TODO comment
describing exactly what renderer/state work is needed to implement it.

Double-click handler updated to use UserRole index stored per row so
the row→shortcut mapping remains correct after skipping hidden entries.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 57 ++++++++++++++++++-----
 1 file changed, 45 insertions(+), 12 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index f0626c1cb9..a80c7aaf57 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -796,6 +796,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
       "Snap to Axis",      "X",       "Snap to the nearest axis-aligned view",
       [](ViewSceneDialog* d) { d->setClosestAxisView(); } },
+    // TODO: Copy View (Ctrl+1-9) — enumerate all live ViewSceneDialog instances via
+    // ViewSceneManager, let user pick by index, then call spire->setCameraDistance/
+    // setCameraLookAt/setCameraRotation with values from the chosen window's spire.
+    // Blocked on: ViewSceneManager exposing an ordered list of active ViewScenes.
     { Id::CopyView,        Qt::Key_1, Qt::ControlModifier,
       "Copy View",         "Ctrl+1-9","Copy view from Viewer Window 1-9", nullptr },
     { Id::SetHome,         Qt::Key_H, Qt::AltModifier,
@@ -821,8 +825,16 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
         spire->setCameraRotation(hv.rotation);
         d->pushCameraState();
       } },
+    // TODO: Toggle World Axes (A) — v4 rendered a large XYZ triad at the true world
+    // origin. v5 has no equivalent. Needs: a new GeometryObject that draws axis lines
+    // (or glyphs) at (0,0,0), a Parameters::WorldAxesVisible state entry, and wiring
+    // through newGeometryValue. The corner orientation icon (O) is a separate feature.
     { Id::ToggleAxes,      Qt::Key_A, Qt::NoModifier,
       "Toggle Axes",       "A",       "Switch axes on/off", nullptr },
+    // TODO: Bounding Box (B) — Parameters::ShowBBox exists but is commented out throughout
+    // the renderer. Needs: re-enabling ShowBBox, computing the combined scene AABB in
+    // SRInterface, building a wire-frame box GeometryObject each frame it's on, and
+    // a toggleBoundingBox() slot here similar to showOrientationChecked().
     { Id::BoundingBox,     Qt::Key_B, Qt::NoModifier,
       "Bounding Box",      "B",       "Switch bounding box mode on/off", nullptr },
     { Id::ToggleClipping,  Qt::Key_C, Qt::NoModifier,
@@ -835,6 +847,10 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       [](ViewSceneDialog* d) {
         d->setFogOn(!d->state_->getValue(Parameters::FogOn).toBool());
       } },
+    // TODO: Flat Shading (F) — no flat-shading mode in the v5 renderer. Needs: a uniform
+    // flag in the object/phong shaders to use face normals (or a flat-shading shader
+    // variant), a StaticRenderMode or per-pass uniform, SRInterface::setFlatShading(bool),
+    // and a Parameters::FlatShading state entry with a toggleFlatShading() slot.
     { Id::FlatShading,     Qt::Key_F, Qt::NoModifier,
       "Flat Shading",      "F",       "Switch flat shading on/off", nullptr },
     { Id::OpenHelp,        Qt::Key_I, Qt::NoModifier,
@@ -860,12 +876,29 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       [](ViewSceneDialog* d) {
         d->showOrientationChecked(!d->state_->getValue(Parameters::AxesVisible).toBool());
       } },
+    // TODO: Orthographic (P) — SRCamera/SRInterface only expose perspective projection.
+    // Needs: SRInterface::setOrthographic(bool) that swaps between glm::perspective and
+    // a glm::ortho sized to the current view frustum width at the lookAt distance,
+    // SRCamera::setAsPerspective already exists — add setAsOrthographic() alongside it,
+    // and a Parameters::OrthographicMode state entry with a toggleOrthographic() slot.
     { Id::Orthographic,    Qt::Key_P, Qt::NoModifier,
       "Orthographic",      "P",       "Switch orthographic projection on/off", nullptr },
+    // TODO: Stereo (S) — not implemented in v5. Needs: a stereo rendering mode in
+    // SRInterface (side-by-side or anaglyph), likely a second render pass with a
+    // laterally offset camera, SRInterface::setStereo(bool), and a
+    // Parameters::StereoMode state entry. Significant renderer work.
     { Id::Stereo,          Qt::Key_S, Qt::NoModifier,
       "Stereo",            "S",       "Switch stereo mode on/off", nullptr },
+    // TODO: Backculling (U) — no back-face cull toggle in v5. Needs: SRInterface::
+    // setBackfaceCulling(bool) that calls glEnable/glDisable(GL_CULL_FACE) + glCullFace
+    // (GL_BACK) in the render loop (or a StaticGLState flag), a Parameters::BackfaceCulling
+    // state entry, and a toggleBackfaceCulling() slot.
     { Id::Backculling,     Qt::Key_U, Qt::NoModifier,
       "Backculling",       "U",       "Switch backculling on/off", nullptr },
+    // TODO: Wireframe (W) — no wireframe mode in v5. Needs: SRInterface::setWireframe(bool)
+    // using glPolygonMode(GL_FRONT_AND_BACK, GL_LINE/GL_FILL) (desktop GL only; for ES
+    // compatibility a geometry-shader or line-drawing pass may be needed instead),
+    // a Parameters::WireframeMode state entry, and a toggleWireframe() slot.
     { Id::Wireframe,       Qt::Key_W, Qt::NoModifier,
       "Wireframe",         "W",       "Switch wire frame on/off", nullptr },
   }};
@@ -905,33 +938,33 @@ void ViewSceneDialog::showShortcutsDialog()
     impl_->shortcutsTable_ = table;
     table->installEventFilter(this);
     table->setEditTriggers(QAbstractItemView::NoEditTriggers);
-    table->setRowCount(static_cast<int>(numShortcuts));
 
-    const QColor disabledColor = table->palette().color(QPalette::Disabled, QPalette::Text);
+    // Only show implemented shortcuts; unimplemented ones are hidden pending
+    // their own feature work (see TODO comments in shortcutTable()).
     int row = 0;
-    for (const auto& sc : shortcutTable())
+    for (int idx = 0; idx < static_cast<int>(numShortcuts); ++idx)
     {
+      const auto& sc = shortcutTable()[static_cast<std::size_t>(idx)];
+      if (!sc.isImplemented()) continue;
+      table->insertRow(row);
       auto* nameItem     = new QTableWidgetItem(sc.actionName);
       auto* shortcutItem = new QTableWidgetItem(sc.shortcutDisplay);
       auto* descItem     = new QTableWidgetItem(sc.description);
+      // Store the original table index so the double-click handler can find it.
+      nameItem->setData(Qt::UserRole, idx);
       table->setItem(row, 0, nameItem);
       table->setItem(row, 1, shortcutItem);
       table->setItem(row, 2, descItem);
-      if (!sc.isImplemented())
-      {
-        for (auto* item : {nameItem, shortcutItem, descItem})
-        {
-          item->setForeground(disabledColor);
-          item->setFlags(item->flags() & ~Qt::ItemIsEnabled);
-        }
-      }
       ++row;
     }
     table->resizeColumnsToContents();
     table->setToolTip("Double-click a row to perform that action");
     connect(table, &QTableWidget::cellDoubleClicked, [this](int row, int /*col*/)
     {
-      const auto& sc = shortcutTable()[static_cast<std::size_t>(row)];
+      const auto* nameItem = impl_->shortcutsTable_->item(row, 0);
+      if (!nameItem) return;
+      const int idx = nameItem->data(Qt::UserRole).toInt();
+      const auto& sc = shortcutTable()[static_cast<std::size_t>(idx)];
       if (sc.action)
         sc.action(this);
     });

From 0d755d04eb9e9a075e3fd3db7fe55004270628e6 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 6 Jun 2026 00:19:43 -0600
Subject: [PATCH 42/64] Add GitHub issue numbers to TODO comments in
 shortcutTable

#2503 world axes, #2504 bounding box, #2505 flat shading,
#2506 orthographic, #2507 stereo, #2508 backculling,
#2509 wireframe, #2510 copy view

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index a80c7aaf57..f9b2db1b9b 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -796,7 +796,7 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
     { Id::SnapToAxis,      Qt::Key_X, Qt::NoModifier,
       "Snap to Axis",      "X",       "Snap to the nearest axis-aligned view",
       [](ViewSceneDialog* d) { d->setClosestAxisView(); } },
-    // TODO: Copy View (Ctrl+1-9) — enumerate all live ViewSceneDialog instances via
+    // TODO(#2510): Copy View (Ctrl+1-9) — enumerate all live ViewSceneDialog instances via
     // ViewSceneManager, let user pick by index, then call spire->setCameraDistance/
     // setCameraLookAt/setCameraRotation with values from the chosen window's spire.
     // Blocked on: ViewSceneManager exposing an ordered list of active ViewScenes.
@@ -825,13 +825,13 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
         spire->setCameraRotation(hv.rotation);
         d->pushCameraState();
       } },
-    // TODO: Toggle World Axes (A) — v4 rendered a large XYZ triad at the true world
+    // TODO(#2503): Toggle World Axes (A) — v4 rendered a large XYZ triad at the true world
     // origin. v5 has no equivalent. Needs: a new GeometryObject that draws axis lines
     // (or glyphs) at (0,0,0), a Parameters::WorldAxesVisible state entry, and wiring
     // through newGeometryValue. The corner orientation icon (O) is a separate feature.
     { Id::ToggleAxes,      Qt::Key_A, Qt::NoModifier,
       "Toggle Axes",       "A",       "Switch axes on/off", nullptr },
-    // TODO: Bounding Box (B) — Parameters::ShowBBox exists but is commented out throughout
+    // TODO(#2504): Bounding Box (B) — Parameters::ShowBBox exists but is commented out throughout
     // the renderer. Needs: re-enabling ShowBBox, computing the combined scene AABB in
     // SRInterface, building a wire-frame box GeometryObject each frame it's on, and
     // a toggleBoundingBox() slot here similar to showOrientationChecked().
@@ -847,7 +847,7 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       [](ViewSceneDialog* d) {
         d->setFogOn(!d->state_->getValue(Parameters::FogOn).toBool());
       } },
-    // TODO: Flat Shading (F) — no flat-shading mode in the v5 renderer. Needs: a uniform
+    // TODO(#2505): Flat Shading (F) — no flat-shading mode in the v5 renderer. Needs: a uniform
     // flag in the object/phong shaders to use face normals (or a flat-shading shader
     // variant), a StaticRenderMode or per-pass uniform, SRInterface::setFlatShading(bool),
     // and a Parameters::FlatShading state entry with a toggleFlatShading() slot.
@@ -876,26 +876,26 @@ const ViewSceneDialog::ShortcutTable& ViewSceneDialog::shortcutTable()
       [](ViewSceneDialog* d) {
         d->showOrientationChecked(!d->state_->getValue(Parameters::AxesVisible).toBool());
       } },
-    // TODO: Orthographic (P) — SRCamera/SRInterface only expose perspective projection.
+    // TODO(#2506): Orthographic (P) — SRCamera/SRInterface only expose perspective projection.
     // Needs: SRInterface::setOrthographic(bool) that swaps between glm::perspective and
     // a glm::ortho sized to the current view frustum width at the lookAt distance,
     // SRCamera::setAsPerspective already exists — add setAsOrthographic() alongside it,
     // and a Parameters::OrthographicMode state entry with a toggleOrthographic() slot.
     { Id::Orthographic,    Qt::Key_P, Qt::NoModifier,
       "Orthographic",      "P",       "Switch orthographic projection on/off", nullptr },
-    // TODO: Stereo (S) — not implemented in v5. Needs: a stereo rendering mode in
+    // TODO(#2507): Stereo (S) — not implemented in v5. Needs: a stereo rendering mode in
     // SRInterface (side-by-side or anaglyph), likely a second render pass with a
     // laterally offset camera, SRInterface::setStereo(bool), and a
     // Parameters::StereoMode state entry. Significant renderer work.
     { Id::Stereo,          Qt::Key_S, Qt::NoModifier,
       "Stereo",            "S",       "Switch stereo mode on/off", nullptr },
-    // TODO: Backculling (U) — no back-face cull toggle in v5. Needs: SRInterface::
+    // TODO(#2508): Backculling (U) — no back-face cull toggle in v5. Needs: SRInterface::
     // setBackfaceCulling(bool) that calls glEnable/glDisable(GL_CULL_FACE) + glCullFace
     // (GL_BACK) in the render loop (or a StaticGLState flag), a Parameters::BackfaceCulling
     // state entry, and a toggleBackfaceCulling() slot.
     { Id::Backculling,     Qt::Key_U, Qt::NoModifier,
       "Backculling",       "U",       "Switch backculling on/off", nullptr },
-    // TODO: Wireframe (W) — no wireframe mode in v5. Needs: SRInterface::setWireframe(bool)
+    // TODO(#2509): Wireframe (W) — no wireframe mode in v5. Needs: SRInterface::setWireframe(bool)
     // using glPolygonMode(GL_FRONT_AND_BACK, GL_LINE/GL_FILL) (desktop GL only; for ES
     // compatibility a geometry-shader or line-drawing pass may be needed instead),
     // a Parameters::WireframeMode state entry, and a toggleWireframe() slot.

From ca487d86d47ca1979226d8ea142a257dde6e17df Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 6 Jun 2026 00:25:26 -0600
Subject: [PATCH 43/64] Fix shortcuts dialog size to match content

AdjustToContents policy + resizeRowsToContents lets the table report
its exact height. adjustSize() then shrinks the dialog to fit, and
setFixedSize() locks it so it doesn't resize.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index f9b2db1b9b..1fca3b9593 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -958,6 +958,9 @@ void ViewSceneDialog::showShortcutsDialog()
       ++row;
     }
     table->resizeColumnsToContents();
+    table->resizeRowsToContents();
+    // Let the table report its exact content size so the dialog can fit it.
+    table->setSizeAdjustPolicy(QAbstractScrollArea::AdjustToContents);
     table->setToolTip("Double-click a row to perform that action");
     connect(table, &QTableWidget::cellDoubleClicked, [this](int row, int /*col*/)
     {
@@ -968,6 +971,10 @@ void ViewSceneDialog::showShortcutsDialog()
       if (sc.action)
         sc.action(this);
     });
+    // Shrink the dialog to exactly fit the table + button box, then lock it.
+    impl_->shortcutsDialog_->adjustSize();
+    impl_->shortcutsDialog_->setFixedSize(impl_->shortcutsDialog_->size());
+
     // Default position: top-right of the ViewScene window to minimise overlap.
     // Use saved position if the user has moved it previously this session.
     const QPoint defaultPos = mapToGlobal(QPoint(width(), 0));

From 59dbbd18d24055d62fe07ab2a5d02b7f39326d74 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 6 Jun 2026 00:27:07 -0600
Subject: [PATCH 44/64] Add padding to shortcuts dialog size for last-row
 visibility

40px width + 60px height ensures the last row is fully visible without
scrolling, and gives Windows enough room for its larger window chrome.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 1fca3b9593..1f94b632b9 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -971,9 +971,11 @@ void ViewSceneDialog::showShortcutsDialog()
       if (sc.action)
         sc.action(this);
     });
-    // Shrink the dialog to exactly fit the table + button box, then lock it.
+    // Size the dialog to fit the content, plus padding so the last row is
+    // fully visible without scrolling (Windows chrome also needs extra room).
     impl_->shortcutsDialog_->adjustSize();
-    impl_->shortcutsDialog_->setFixedSize(impl_->shortcutsDialog_->size());
+    const QSize padded = impl_->shortcutsDialog_->size() + QSize(40, 60);
+    impl_->shortcutsDialog_->setFixedSize(padded);
 
     // Default position: top-right of the ViewScene window to minimise overlap.
     // Use saved position if the user has moved it previously this session.

From 954c6daf305982b19493307993dec6ebfbcf4002 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 12 Jun 2026 14:49:26 -0500
Subject: [PATCH 45/64] Add Superbuild externals cache and sccache to CI

Two-layer caching to reduce ~2+ hour build times:
- actions/cache on bin/Externals/Install+Stamp keyed on Superbuild/*.cmake hash,
  so Boost/Eigen/Python/Teem etc. are only rebuilt when a dependency actually changes
- sccache via mozilla-actions/sccache-action for SCIRun source compilation,
  wired via CMAKE_C/CXX_COMPILER_LAUNCHER on all three platforms

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 235f8bc273..7fcf90c8ac 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -70,6 +70,30 @@ jobs:
       - name: Print Qt dir
         run: echo "QT_ROOT_DIR=${QT_ROOT_DIR:-(unset)}"
 
+      - name: Set externals path
+        id: paths
+        shell: bash
+        run: |
+          if [ "${{ runner.os }}" = "Windows" ]; then
+            echo "externals=build/Externals" >> $GITHUB_OUTPUT
+          else
+            echo "externals=bin/Externals" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Cache Superbuild externals
+        uses: actions/cache@v4
+        with:
+          path: |
+            ${{ steps.paths.outputs.externals }}/Install
+            ${{ steps.paths.outputs.externals }}/Stamp
+          key: superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
+          restore-keys: |
+            superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
+            superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
+
+      - name: Set up sccache
+        uses: mozilla-actions/sccache-action@v0.0.9
+
       - name: Checkout SCIRunTestData
         if: ${{ inputs.run-regression-tests || inputs.coverage }}
         uses: actions/checkout@v6
@@ -89,6 +113,8 @@ jobs:
         run: |
           set -eux
           CMD=(./build.sh)
+          CMD+=("-DCMAKE_C_COMPILER_LAUNCHER=sccache")
+          CMD+=("-DCMAKE_CXX_COMPILER_LAUNCHER=sccache")
           # Variant-specific flags
           if [ "${{ inputs.variant }}" = "gui" ]; then
             # Pass Qt path (from installer or explicit), and set SCIRUN_QT_MIN_VERSION appropriately
@@ -154,6 +180,8 @@ jobs:
 
           # Build arguments for cmake
           $cmakeArgs = @()
+          $cmakeArgs += "-DCMAKE_C_COMPILER_LAUNCHER=sccache"
+          $cmakeArgs += "-DCMAKE_CXX_COMPILER_LAUNCHER=sccache"
 
           # Always use Visual Studio generator on Windows to ensure MSVC flags are used
           $cmakeArgs += '-G'

From 1627a0f4c044e988958c9efad2b15d019f9d142e Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 13:11:19 -0600
Subject: [PATCH 46/64] Remove OffscreenGLRenderer from ViewScene member; keep
 files for future use

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Interface/Modules/Render/ViewScene.cc | 52 ++++++-----------------
 1 file changed, 14 insertions(+), 38 deletions(-)

diff --git a/src/Interface/Modules/Render/ViewScene.cc b/src/Interface/Modules/Render/ViewScene.cc
index 1f94b632b9..475d85ec06 100644
--- a/src/Interface/Modules/Render/ViewScene.cc
+++ b/src/Interface/Modules/Render/ViewScene.cc
@@ -39,7 +39,6 @@
 #include <Interface/Modules/Render/ES/RendererInterface.h>
 #include <Interface/Modules/Render/ES/comp/StaticClippingPlanes.h>
 #include <Interface/Modules/Render/GLWidget.h>
-#include <Interface/Modules/Render/OffscreenGLRenderer.h>
 #include <Interface/Modules/Render/Screenshot.h>
 #include <Interface/Modules/Render/ViewScene.h>
 #include <Interface/Modules/Render/ViewScenePlatformCompatibility.h>
@@ -162,8 +161,7 @@ namespace Gui {
   class ViewSceneDialogImpl
   {
   public:
-    GLWidget*                             mGLWidget                     {nullptr};  ///< GL widget containing context (null in offscreen mode).
-    std::unique_ptr<OffscreenGLRenderer>  offscreenRenderer_;                       ///< Used instead of mGLWidget in regression mode.
+    GLWidget*                             mGLWidget                     {nullptr};
     Render::RendererWeakPtr               mSpire                        {};         ///< Instance of Spire.
     QToolBar*                             toolBar1_                      {nullptr};  ///< Tool bar.
     QToolBar*                             toolBar2_                      {nullptr};  ///< Tool bar.
@@ -401,25 +399,17 @@ ViewSceneDialog::ViewSceneDialog(const std::string& name, ModuleStateHandle stat
 
   setupScaleBar();
 
-  if (Application::Instance().parameters()->isRegressionMode())
-  {
-    impl_->offscreenRenderer_ = std::make_unique<OffscreenGLRenderer>(800, 600);
-    impl_->mSpire = impl_->offscreenRenderer_->renderer();
-  }
-  else
-  {
-    impl_->mGLWidget = new GLWidget(parentWidget());
-    QSurfaceFormat format;
-    format.setDepthBufferSize(24);
-    format.setProfile(QSurfaceFormat::CoreProfile);
-    format.setVersion(2, 1);
-    impl_->mGLWidget->setFormat(format);
+  impl_->mGLWidget = new GLWidget(parentWidget());
+  QSurfaceFormat format;
+  format.setDepthBufferSize(24);
+  format.setProfile(QSurfaceFormat::CoreProfile);
+  format.setVersion(2, 1);
+  impl_->mGLWidget->setFormat(format);
 
-    connect(impl_->mGLWidget, &GLWidget::fatalError, this, &ViewSceneDialog::fatalError);
-    connect(impl_->mGLWidget, &GLWidget::finishedFrame, this, &ViewSceneDialog::frameFinished);
+  connect(impl_->mGLWidget, &GLWidget::fatalError, this, &ViewSceneDialog::fatalError);
+  connect(impl_->mGLWidget, &GLWidget::finishedFrame, this, &ViewSceneDialog::frameFinished);
 
-    impl_->mSpire = RendererWeakPtr(impl_->mGLWidget->getSpire());
-  }
+  impl_->mSpire = RendererWeakPtr(impl_->mGLWidget->getSpire());
 
   connect(this, &ViewSceneDialog::mousePressSignalForGeometryObjectFeedback,
           this, &ViewSceneDialog::sendGeometryFeedbackToState);
@@ -1417,9 +1407,7 @@ void ViewSceneDialog::updateModifiedGeometries()
 void ViewSceneDialog::updateModifiedGeometriesAndSendScreenShot()
 {
   newGeometryValue(false, false);
-  if (impl_->offscreenRenderer_)
-    frameFinished();
-  else if (impl_->mGLWidget->isVisible() && impl_->mGLWidget->isValid())
+  if (impl_->mGLWidget->isVisible() && impl_->mGLWidget->isValid())
     impl_->mGLWidget->requestFrame();
   else
     unblockExecution();
@@ -1441,14 +1429,9 @@ void ViewSceneDialog::newGeometryValue(bool forceAllObjectsToUpdate, bool clippi
   if (!spire)
     return;
 
-  if (impl_->offscreenRenderer_)
-    spire->setContext(impl_->offscreenRenderer_->context());
-  else
-  {
-    if (!impl_->mGLWidget->isValid())
-      return;
-    spire->setContext(impl_->mGLWidget->context());
-  }
+  if (!impl_->mGLWidget->isValid())
+    return;
+  spire->setContext(impl_->mGLWidget->context());
 
   if (forceAllObjectsToUpdate)
     spire->removeAllGeomObjects();
@@ -3252,13 +3235,6 @@ void ViewSceneDialog::sendBugReport()
 
 void ViewSceneDialog::takeScreenshot()
 {
-  if (impl_->offscreenRenderer_)
-  {
-    if (!impl_->screenshotTaker_)
-      impl_->screenshotTaker_ = new Screenshot(nullptr, this);
-    impl_->screenshotTaker_->setImage(impl_->offscreenRenderer_->renderToImage());
-    return;
-  }
   if (!impl_->screenshotTaker_)
     impl_->screenshotTaker_ = new Screenshot(impl_->mGLWidget, this);
   impl_->screenshotTaker_->takeScreenshot();

From c119493398bd58df992dbfd6590d9d77f5ed49b2 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 19:42:32 -0600
Subject: [PATCH 47/64] Fix CI: cache externals src dir; pin windows regression
 runner to windows-2022

- reusable-build.yml: add Externals/src to cache path so ExternalProject's
  git-update script can find .git when the cache is restored; bump cache
  key to v2 to avoid restoring broken v1 caches
- regression-tests.yml: change windows-headless-regression runner from
  windows-latest to windows-2022, matching every other Windows job; fixes
  "could not find any instance of Visual Studio" on the updated runner image

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/regression-tests.yml | 2 +-
 .github/workflows/reusable-build.yml   | 7 ++++---
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/regression-tests.yml b/.github/workflows/regression-tests.yml
index 9ad8f858d9..f38d5dc6ff 100644
--- a/.github/workflows/regression-tests.yml
+++ b/.github/workflows/regression-tests.yml
@@ -34,7 +34,7 @@ jobs:
   windows-headless-regression:
     uses: ./.github/workflows/reusable-build.yml
     with:
-      runner: windows-latest
+      runner: windows-2022
       variant: headless
       build-testing: true
       run-unit-tests: true
diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index f3138a8b52..c4892f8873 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -86,10 +86,11 @@ jobs:
           path: |
             ${{ steps.paths.outputs.externals }}/Install
             ${{ steps.paths.outputs.externals }}/Stamp
-          key: superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
+            ${{ steps.paths.outputs.externals }}/src
+          key: superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
           restore-keys: |
-            superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
-            superbuild-v1-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
+            superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
+            superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
 
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9

From da3d3d279bfdee37bd69b39085835a233e546faf Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 20:39:01 -0600
Subject: [PATCH 48/64] Update CommandLine test for --image-dir option

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
index 00f232d0a9..a7f7620855 100644
--- a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
+++ b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
@@ -43,6 +43,8 @@ TEST(ScirunCommandLineSpecTest, CanReadBasicOptions)
     "  -E [ --Execute ]        executes the given network on startup and quits when \n"
     "                          done\n"
     "  -d [ --datadir ] arg    scirun data directory\n"
+    "  --image-dir arg         output directory for ViewScene images saved with \n"
+    "                          --save-images (deterministic names in regression mode)\n"
     "  -r [ --regression ] arg regression test a network\n"
     "  -1 [ --most-recent ]    load the most recently used file\n"
     "  -i [ --interactive ]    interactive mode\n"

From 95bd00fcd223f3a4cb04be0c3e3eb5ab66949b45 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 20:51:17 -0600
Subject: [PATCH 49/64] Disable import tests for networks with unported SCIRun
 4 modules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Testing/CMakeLists.txt | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/src/Testing/CMakeLists.txt b/src/Testing/CMakeLists.txt
index b9ee08df33..21dabe2595 100644
--- a/src/Testing/CMakeLists.txt
+++ b/src/Testing/CMakeLists.txt
@@ -124,6 +124,19 @@ IF(RUN_BASIC_REGRESSION_TESTS)
 ENDIF()
 
 IF(RUN_IMPORT_TESTS)
+  # Networks that reference modules not yet ported to SCIRun 5.
+  SET(DISABLED_IMPORT_TESTS
+    ".Test.ImportNetwork.Other.v4nets.example_nets.FusionPSE.MDSplus"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.FusionPSE.Streamlines-Scalar-Interp"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.FusionPSE.Volume-Cutting"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.FusionPSE.Volume-Viz"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.SCIRun.MeshingPipeline.DistributedParticles"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.SCIRun.MeshingPipeline.SizingFieldMedialAxisAndBoundaries"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.Teem.Optional.volume-colored-example"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.Teem.Optional.volume-colored-gage"
+    ".Test.ImportNetwork.Other.v4nets.example_nets.Teem.Samples.tooth1"
+  )
+
   FILE(GLOB_RECURSE scirun_legacy_srns "${SCIRUN_TEST_RESOURCE_DIR}/**/*.srn")
   # The glob is broad; drop files that aren't legacy v4 networks: serialization
   # test artifacts (TransientOutput/), scratch outputs (*_TMP.srn), and any
@@ -143,6 +156,9 @@ IF(RUN_IMPORT_TESTS)
     ADD_TEST("${import_test_name}" ${EXE_LOC} --no_splash --regression 30 --import ${srn})
     # Bound a hung import at the ctest level.
     SET_TESTS_PROPERTIES("${import_test_name}" PROPERTIES TIMEOUT 120)
+    IF("${import_test_name}" IN_LIST DISABLED_IMPORT_TESTS)
+      SET_TESTS_PROPERTIES("${import_test_name}" PROPERTIES DISABLED TRUE)
+    ENDIF()
   ENDFOREACH()
 ENDIF()
 

From 0e388b5a425ee8404525dc4fc085c5f22bf8693e Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 20:57:51 -0600
Subject: [PATCH 50/64] Fix CommandLine test: wrap --image-dir description to 3
 lines

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
index a7f7620855..9ed15692b5 100644
--- a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
+++ b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
@@ -44,7 +44,8 @@ TEST(ScirunCommandLineSpecTest, CanReadBasicOptions)
     "                          done\n"
     "  -d [ --datadir ] arg    scirun data directory\n"
     "  --image-dir arg         output directory for ViewScene images saved with \n"
-    "                          --save-images (deterministic names in regression mode)\n"
+    "                          --save-images (deterministic names in regression \n"
+    "                          mode)\n"
     "  -r [ --regression ] arg regression test a network\n"
     "  -1 [ --most-recent ]    load the most recently used file\n"
     "  -i [ --interactive ]    interactive mode\n"

From 8df7a84dc98db9ec2b5f59ac97be59a0b2bb7f19 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 13 Jun 2026 21:00:32 -0600
Subject: [PATCH 51/64] Shorten --image-dir help text to fit one line; fix test

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Core/CommandLine/CommandLine.cc                      | 2 +-
 src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc | 4 +---
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/src/Core/CommandLine/CommandLine.cc b/src/Core/CommandLine/CommandLine.cc
index 214579bb32..afe924bba7 100644
--- a/src/Core/CommandLine/CommandLine.cc
+++ b/src/Core/CommandLine/CommandLine.cc
@@ -53,7 +53,7 @@ class CommandLineParserInternal
       ("execute,e", "executes the given network on startup")
       ("Execute,E", "executes the given network on startup and quits when done")
       ("datadir,d", po::value<std::string>(), "scirun data directory")
-      ("image-dir", po::value<std::string>(), "output directory for ViewScene images saved with --save-images (deterministic names in regression mode)")
+      ("image-dir", po::value<std::string>(), "output directory for regression-mode images")
       ("regression,r", po::value<int>(), "regression test a network")
       //("logfile,l", po::value<std::string>(), "add output messages to a logfile--TODO")
       ("most-recent,1", "load the most recently used file")
diff --git a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
index 9ed15692b5..caa30df79b 100644
--- a/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
+++ b/src/Core/CommandLine/Tests/ScirunCommandLineSpecTests.cc
@@ -43,9 +43,7 @@ TEST(ScirunCommandLineSpecTest, CanReadBasicOptions)
     "  -E [ --Execute ]        executes the given network on startup and quits when \n"
     "                          done\n"
     "  -d [ --datadir ] arg    scirun data directory\n"
-    "  --image-dir arg         output directory for ViewScene images saved with \n"
-    "                          --save-images (deterministic names in regression \n"
-    "                          mode)\n"
+    "  --image-dir arg         output directory for regression-mode images\n"
     "  -r [ --regression ] arg regression test a network\n"
     "  -1 [ --most-recent ]    load the most recently used file\n"
     "  -i [ --interactive ]    interactive mode\n"

From 3ee5abe5f0b50b9fdce98a29385a3eca43e98875 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Tue, 16 Jun 2026 23:10:52 -0600
Subject: [PATCH 52/64] Fix CI caching: add EP_UPDATE_DISCONNECTED, remove
 wrong src path

The cache was storing bin/Externals/src (lowercase) but CMake
ExternalProject with EP_BASE puts git clones in bin/Externals/Source
(capital S). On a cache restore, CMake still ran the git update check
for every GIT_REPOSITORY external and hit 'fatal: not a git repository'
because the Source directory was never actually cached.

Fix: set EP_UPDATE_DISCONNECTED TRUE globally in Superbuild.cmake so
that when Install+Stamp are restored from cache the git update step is
skipped entirely. The cache key already covers hashFiles('Superbuild/*.cmake'),
so any GIT_TAG change still forces a fresh clone. Remove the bogus /src
path from the cache and bump the key to v3 to avoid restoring broken
v2 caches.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 7 +++----
 Superbuild/Superbuild.cmake          | 2 ++
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index c4892f8873..ba7dcaaae2 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -86,11 +86,10 @@ jobs:
           path: |
             ${{ steps.paths.outputs.externals }}/Install
             ${{ steps.paths.outputs.externals }}/Stamp
-            ${{ steps.paths.outputs.externals }}/src
-          key: superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
+          key: superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
           restore-keys: |
-            superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
-            superbuild-v2-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
+            superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
+            superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
 
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9
diff --git a/Superbuild/Superbuild.cmake b/Superbuild/Superbuild.cmake
index 88982f9119..68e76d2b26 100644
--- a/Superbuild/Superbuild.cmake
+++ b/Superbuild/Superbuild.cmake
@@ -28,6 +28,8 @@
 # TODO: build from archive - Git not used
 SET(compress_type "GIT" CACHE INTERNAL "")
 SET(ep_base "${CMAKE_BINARY_DIR}/Externals" CACHE INTERNAL "")
+SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
+SET_PROPERTY(DIRECTORY PROPERTY "EP_UPDATE_DISCONNECTED" TRUE)
 
 ###########################################
 # Set default CMAKE_BUILD_TYPE

From 9d8ea0e9c6077de7acc8f90532452535ccec9804 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Wed, 17 Jun 2026 21:47:18 -0600
Subject: [PATCH 53/64] Fix CI: remove cross-variant cache restore-key

mac-gui was picking up the mac-headless cache via the loose restore-key
that strips the variant suffix. Headless doesn't build Zlib (GUI-only
external), so there was no Zlib stamp in that cache. mac-gui then tried
to build Zlib but Source/ isn't cached, hitting the same
'not a git repository' error.

Drop the variant-agnostic restore-key so a gui build can only fall back
to another gui cache (same variant, different python flag), never to a
headless cache with a disjoint set of built externals.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index ba7dcaaae2..7bee4de412 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -89,7 +89,6 @@ jobs:
           key: superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
           restore-keys: |
             superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
-            superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-
 
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9

From 61e511e7ac30ed7672260e54b19a4ec5b0a35372 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Wed, 17 Jun 2026 21:49:49 -0600
Subject: [PATCH 54/64] Add JUnit XML output and GitHub Check reporter for test
 results

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml    | 29 +++++++++++
 docs/Support-Python-Libraries-Design.md | 66 +++++++++++++++++++++++++
 2 files changed, 95 insertions(+)
 create mode 100644 docs/Support-Python-Libraries-Design.md

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 7bee4de412..d20f6a5816 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -53,6 +53,9 @@ on:
 jobs:
   build:
     runs-on: ${{ inputs.runner }}
+    permissions:
+      checks: write
+      contents: read
     steps:
       - name: Checkout
         uses: actions/checkout@v6
@@ -278,6 +281,7 @@ jobs:
         working-directory: bin/SCIRun
         run: |
           ctest --output-on-failure --timeout 300 -j4 -E "\.Test\.ExampleNetwork\." \
+            --output-junit "$GITHUB_WORKSPACE/junit-unit.xml" \
             2>&1 | tee /tmp/unit-test-results.txt
         continue-on-error: true
 
@@ -286,6 +290,7 @@ jobs:
         working-directory: bin/SCIRun
         run: |
           ctest --output-on-failure --timeout 300 -j3 -R "\.Test\.ExampleNetwork\." \
+            --output-junit "$GITHUB_WORKSPACE/junit-regression.xml" \
             2>&1 | tee /tmp/regression-test-results.txt
         continue-on-error: true
 
@@ -304,6 +309,7 @@ jobs:
         shell: pwsh
         run: |
           ctest --output-on-failure --timeout 300 -j4 -C Release -E "\.Test\.ExampleNetwork\." `
+            --output-junit "$env:GITHUB_WORKSPACE\junit-unit.xml" `
             2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\unit-test-results.txt"
         continue-on-error: true
 
@@ -313,9 +319,28 @@ jobs:
         shell: pwsh
         run: |
           ctest --output-on-failure --timeout 300 -j3 -C Release -R "\.Test\.ExampleNetwork\." `
+            --output-junit "$env:GITHUB_WORKSPACE\junit-regression.xml" `
             2>&1 | Tee-Object -FilePath "$env:GITHUB_WORKSPACE\regression-test-results.txt"
         continue-on-error: true
 
+      - name: Publish unit test results
+        uses: dorny/test-reporter@v1
+        if: always() && inputs.run-unit-tests
+        with:
+          name: "Unit Tests (${{ runner.os }} / ${{ inputs.variant }})"
+          path: junit-unit.xml
+          reporter: java-junit
+          fail-on-error: false
+
+      - name: Publish regression test results
+        uses: dorny/test-reporter@v1
+        if: always() && inputs.run-regression-tests
+        with:
+          name: "Regression Tests (${{ runner.os }} / ${{ inputs.variant }})"
+          path: junit-regression.xml
+          reporter: java-junit
+          fail-on-error: false
+
       - name: Upload test logs (Unix)
         if: ${{ (inputs.run-unit-tests || inputs.run-regression-tests) && runner.os != 'Windows' }}
         uses: actions/upload-artifact@v6
@@ -326,6 +351,8 @@ jobs:
             /tmp/unit-test-results.txt
             /tmp/regression-test-results.txt
             bin/SCIRun/Testing/Temporary/LastTest.log
+            junit-unit.xml
+            junit-regression.xml
 
       - name: Upload test logs (Windows)
         if: ${{ (inputs.run-unit-tests || inputs.run-regression-tests) && runner.os == 'Windows' }}
@@ -337,6 +364,8 @@ jobs:
             unit-test-results.txt
             regression-test-results.txt
             build/SCIRun/Testing/Temporary/LastTest.log
+            junit-unit.xml
+            junit-regression.xml
 
       - name: Run tests + coverage report (macOS)
         if: ${{ inputs.coverage && runner.os == 'macOS' }}
diff --git a/docs/Support-Python-Libraries-Design.md b/docs/Support-Python-Libraries-Design.md
new file mode 100644
index 0000000000..bcb7ad4a8e
--- /dev/null
+++ b/docs/Support-Python-Libraries-Design.md
@@ -0,0 +1,66 @@
+Design doc: Support additional Python libraries (numpy, scipy)
+
+Related issue: https://github.com/SCIInstitute/SCIRun/issues/2479
+
+Overview
+
+Goal: ensure SCIRun's Python wrappers and packaging work smoothly with common scientific Python libraries (numpy, scipy) so downstream users can interoperate with ndarrays, use numerical routines, and run tests/examples that depend on these libraries.
+
+Motivation
+
+Many users expect conversions between SCIRun data (Fields, Meshes, DenseMatrix) and numpy arrays without costly copies. CI and packaging must validate compatibility and reproducibility for supported numpy/scipy versions.
+
+Requirements
+
+Functional
+- Zero-copy or documented conversion paths between SCIRun DenseMatrix/Field data and numpy ndarray where possible.
+- Helper utilities in Python wrappers: to_numpy(), from_numpy(), memoryview access with clear ownership semantics.
+- Example notebooks demonstrating workflows (convert, run numpy ops, convert back, visualize).
+
+Build / Packaging
+- CI jobs that install targeted numpy/scipy versions and run wrapper tests.
+- Wheel/build rules documented for binary compatibility (manylinux, ABI tags) if shipping wheels.
+- CMake option or wrapper build config to locate Python and numpy include/abi (find_package or pybind11 helpers).
+
+Testing
+- Pytest suite that covers conversions, roundtrip tests, and small numerical consistency checks across supported numpy versions.
+- Tests run in CI matrix: at least two Python versions (e.g., 3.10, 3.11) and current numpy LTS + one older supported version.
+
+API design
+- Provide explicit conversion functions on Python objects:
+  - DenseMatrix.to_numpy(copy=False) -> numpy.ndarray
+  - DenseMatrix.from_numpy(ndarray, copy=False) -> DenseMatrix
+  - Field/mesh extractors that return coordinate arrays and attribute arrays
+- Clearly document ownership and lifetime: when copy=False, returned ndarray references internal memory until original object is GC'd or buffer is detached.
+- Prefer pybind11 buffer protocol for native sharing where feasible.
+
+Implementation Plan
+1. Prototype conversion layer in a feature branch:
+   - Implement to_numpy/from_numpy for DenseMatrix using pybind11 buffer interface.
+   - Add helper functions for common types (float32/64) and shape conventions.
+2. Add example Jupyter notebook and small integration test.
+3. Update build scripts to detect numpy include/ABI for compiling wrappers; ensure pybind11 is used consistently.
+4. Extend to Field/mesh conversions: provide arrays for points, connectivity, and per-vertex/per-cell attributes.
+5. Add CI matrix entries (Python versions + numpy versions) and run pytest suite.
+
+Acceptance criteria
+- Conversions implemented and covered by tests.
+- CI builds successfully with numpy present; tests pass in at least one CI job.
+- Documentation and example notebook present in docs/python_examples/.
+
+Risks and mitigations
+- Binary compatibility: avoid shipping wheels initially; provide clear build-from-source instructions and CI verification.
+- Ownership complexity: prefer explicit API (copy flag) and document lifetime rules. Use pybind11 buffer protocol to reduce errors.
+- Large memory copies: benchmark common workflows and document performance expectations; add optional utilities for chunked conversion.
+
+Open questions
+- Which Python/numpy versions should be formally supported (LTS policy)?
+- Is shipping binary wheels a near-term goal, or should initial effort focus on source builds and CI? 
+
+Next steps
+- Assign an owner to implement the DenseMatrix <-> numpy prototype.
+- Create a feature branch and open a PR with the prototype and example notebook.
+- Add CI job for one Python+numpy configuration and expand later.
+
+
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
\ No newline at end of file

From ae81fd178d6bacb3de4497c1250193fc2dbf69ab Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Wed, 17 Jun 2026 22:15:29 -0600
Subject: [PATCH 55/64] Fix SearchGridT::remove actually erasing elements
 (fixes #2517)

std::remove without erase left bin contents unchanged; apply erase-remove idiom.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Core/GeometryPrimitives/SearchGridT.h | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/Core/GeometryPrimitives/SearchGridT.h b/src/Core/GeometryPrimitives/SearchGridT.h
index 7b76ceaa0f..c4cd48bbe7 100644
--- a/src/Core/GeometryPrimitives/SearchGridT.h
+++ b/src/Core/GeometryPrimitives/SearchGridT.h
@@ -170,7 +170,7 @@ class SearchGridT
           for (index_type k = mink; k <= maxk; k++)
           {
             index_type q = linearize(i, j, k);
-            std::remove(bin_[q].begin(),bin_[q].end(),val);
+            bin_[q].erase(std::remove(bin_[q].begin(),bin_[q].end(),val),bin_[q].end());
           }
         }
       }
@@ -188,7 +188,7 @@ class SearchGridT
       index_type i, j, k;
       unsafe_locate(i, j, k, point);
       index_type q = linearize(i, j, k);
-      std::remove(bin_[q].begin(),bin_[q].end(),val);
+      bin_[q].erase(std::remove(bin_[q].begin(),bin_[q].end(),val),bin_[q].end());
     }
 
     inline bool lookup(iterator &begin, iterator &end, const Core::Geometry::Point &p)

From c552399bb0a8a88a5534d5eb2c4a914916acf02a Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 18 Jun 2026 12:25:22 -0600
Subject: [PATCH 56/64] Fix CI caching: add UPDATE_COMMAND "" to all git-based
 externals
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

EP_UPDATE_DISCONNECTED alone was insufficient. CMake regenerates
*-gitupdate.cmake during every configure run with a fresh timestamp;
the Makefile rule for the update step depends on that script, so
cached stamp files were always stale relative to it, causing make
to re-run the git update step — which then fails because Source/
is not cached.

Setting UPDATE_COMMAND "" tells CMake to generate a simple no-op
update step (no gitupdate.cmake, no git operations). With the script
dependency gone from the Makefile rule, the cached stamp is sufficient
to skip the update step on cache hits.

The cache key already includes hashFiles('Superbuild/*.cmake'), so any
GIT_TAG change still forces a full fresh build.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 Superbuild/BoostExternal.cmake      | 1 +
 Superbuild/Cleaver2External.cmake   | 1 +
 Superbuild/CtkExternal.cmake        | 1 +
 Superbuild/DataExternal.cmake       | 1 +
 Superbuild/FreetypeExternal.cmake   | 1 +
 Superbuild/GLMExternal.cmake        | 1 +
 Superbuild/GlewExternal.cmake       | 1 +
 Superbuild/GoogleTestExternal.cmake | 1 +
 Superbuild/LibPNGExternal.cmake     | 1 +
 Superbuild/LodePngExternal.cmake    | 1 +
 Superbuild/OsprayExternal.cmake     | 1 +
 Superbuild/PythonExternal.cmake     | 2 ++
 Superbuild/QwtExternal.cmake        | 1 +
 Superbuild/SQLiteExternal.cmake     | 1 +
 Superbuild/SpdLogExternal.cmake     | 1 +
 Superbuild/TeemExternal.cmake       | 1 +
 Superbuild/TestDataConfig.cmake     | 1 +
 Superbuild/TnyExternal.cmake        | 1 +
 Superbuild/ToolkitsConfig.cmake     | 1 +
 Superbuild/ZlibExternal.cmake       | 1 +
 20 files changed, 21 insertions(+)

diff --git a/Superbuild/BoostExternal.cmake b/Superbuild/BoostExternal.cmake
index b21974cb00..9ce28f7b0a 100644
--- a/Superbuild/BoostExternal.cmake
+++ b/Superbuild/BoostExternal.cmake
@@ -87,6 +87,7 @@ ExternalProject_Add(Boost_external
   DEPENDS ${boost_DEPENDENCIES}
   GIT_REPOSITORY ${boost_GIT_URL}
   GIT_TAG ${boost_GIT_TAG}
+  UPDATE_COMMAND ""
   BUILD_IN_SOURCE ON
   PATCH_COMMAND ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/Cleaver2External.cmake b/Superbuild/Cleaver2External.cmake
index ecc82d58ce..5936a4f3f9 100644
--- a/Superbuild/Cleaver2External.cmake
+++ b/Superbuild/Cleaver2External.cmake
@@ -32,6 +32,7 @@ SET(cleaver2_GIT_TAG "origin/scirun-5.0.0-beta")
 ExternalProject_Add(Cleaver2_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/Cleaver2Library.git"
   GIT_TAG ${cleaver2_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/CtkExternal.cmake b/Superbuild/CtkExternal.cmake
index 3aff0deb8e..3161131a8d 100644
--- a/Superbuild/CtkExternal.cmake
+++ b/Superbuild/CtkExternal.cmake
@@ -45,6 +45,7 @@ LIST(APPEND CTK_CACHE_ARGS
 ExternalProject_Add(Ctk_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/CTK.git"
   GIT_TAG ${ctk_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/DataExternal.cmake b/Superbuild/DataExternal.cmake
index 6b56559d65..cc69820a03 100644
--- a/Superbuild/DataExternal.cmake
+++ b/Superbuild/DataExternal.cmake
@@ -37,6 +37,7 @@ SET(data_DIR "${SEG3D_BINARY_DIR}/Seg3DData")
 ExternalProject_Add(Data_external
   GIT_REPOSITORY ${data_GIT_URL}
   GIT_TAG ${data_GIT_TAG}
+  UPDATE_COMMAND ""
   SOURCE_DIR ${data_DIR}
   BUILD_COMMAND ""
   CONFIGURE_COMMAND ""
diff --git a/Superbuild/FreetypeExternal.cmake b/Superbuild/FreetypeExternal.cmake
index a07e655e9e..64a055e349 100644
--- a/Superbuild/FreetypeExternal.cmake
+++ b/Superbuild/FreetypeExternal.cmake
@@ -32,6 +32,7 @@ SET(freetype_GIT_TAG "origin/scirun-5.0.0")
 ExternalProject_Add(Freetype_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/freetype.git"
   GIT_TAG ${freetype_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/GLMExternal.cmake b/Superbuild/GLMExternal.cmake
index 968bf3796f..631e1f7dc5 100644
--- a/Superbuild/GLMExternal.cmake
+++ b/Superbuild/GLMExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(GLM_external
   GIT_REPOSITORY "https://github.com/g-truc/glm.git"
   GIT_TAG "0.9.9.8"
+  UPDATE_COMMAND ""
   CONFIGURE_COMMAND ""
   BUILD_COMMAND ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/GlewExternal.cmake b/Superbuild/GlewExternal.cmake
index 712edba76f..918fa3bdef 100644
--- a/Superbuild/GlewExternal.cmake
+++ b/Superbuild/GlewExternal.cmake
@@ -37,6 +37,7 @@ ENDIF()
 ExternalProject_Add(Glew_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/glew.git"
   GIT_TAG ${glew_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/GoogleTestExternal.cmake b/Superbuild/GoogleTestExternal.cmake
index 16af038d8b..915df75de3 100644
--- a/Superbuild/GoogleTestExternal.cmake
+++ b/Superbuild/GoogleTestExternal.cmake
@@ -38,6 +38,7 @@ SET(googletest_GIT_TAG "origin/cibc")
 ExternalProject_Add(GoogleTest_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/googletest.git"
   GIT_TAG ${googletest_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/LibPNGExternal.cmake b/Superbuild/LibPNGExternal.cmake
index 809facc65a..197c02d559 100644
--- a/Superbuild/LibPNGExternal.cmake
+++ b/Superbuild/LibPNGExternal.cmake
@@ -34,6 +34,7 @@ ExternalProject_Add(LibPNG_external
   DEPENDS ${libpng_DEPENDENCIES}
   GIT_REPOSITORY "https://github.com/CIBC-Internal/libpng.git"
   GIT_TAG ${libpng_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/LodePngExternal.cmake b/Superbuild/LodePngExternal.cmake
index 1bb401ed2d..377c2e4b61 100644
--- a/Superbuild/LodePngExternal.cmake
+++ b/Superbuild/LodePngExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(LodePng_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/cibc-lodepng.git"
   GIT_TAG "origin/master"
+  UPDATE_COMMAND ""
   INSTALL_COMMAND ""
   CMAKE_CACHE_ARGS
     -DCMAKE_VERBOSE_MAKEFILE:BOOL=${CMAKE_VERBOSE_MAKEFILE}
diff --git a/Superbuild/OsprayExternal.cmake b/Superbuild/OsprayExternal.cmake
index 75ebb751c3..543d3a6fb9 100644
--- a/Superbuild/OsprayExternal.cmake
+++ b/Superbuild/OsprayExternal.cmake
@@ -36,6 +36,7 @@ ExternalProject_Add(Ospray_external
   DEPENDS ${ospray_DEPENDENCIES}
   GIT_REPOSITORY "https://github.com/CIBC-Internal/ospray.git"
   GIT_TAG ${ospray_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/PythonExternal.cmake b/Superbuild/PythonExternal.cmake
index 21fd01b488..d2f31c8612 100644
--- a/Superbuild/PythonExternal.cmake
+++ b/Superbuild/PythonExternal.cmake
@@ -90,6 +90,7 @@ IF(UNIX)
   ExternalProject_Add(Python_external
     GIT_REPOSITORY ${python_GIT_URL}
     GIT_TAG ${python_GIT_TAG}
+  UPDATE_COMMAND ""
     BUILD_IN_SOURCE ON
     CONFIGURE_COMMAND ./configure ${python_CONFIGURE_FLAGS}
     PATCH_COMMAND ""
@@ -106,6 +107,7 @@ ELSE()
   ExternalProject_Add(Python_external
     GIT_REPOSITORY ${python_GIT_URL}
     GIT_TAG ${python_GIT_TAG}
+  UPDATE_COMMAND ""
     PATCH_COMMAND ""
     CONFIGURE_COMMAND PCbuild/build.bat
     BUILD_IN_SOURCE ON
diff --git a/Superbuild/QwtExternal.cmake b/Superbuild/QwtExternal.cmake
index 9d767c41e5..965d8e6bfe 100644
--- a/Superbuild/QwtExternal.cmake
+++ b/Superbuild/QwtExternal.cmake
@@ -52,6 +52,7 @@ endif()
 ExternalProject_Add(Qwt_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/Qwt.git"
   GIT_TAG ${qwt_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/SQLiteExternal.cmake b/Superbuild/SQLiteExternal.cmake
index f38e240d5c..cedf2785c5 100644
--- a/Superbuild/SQLiteExternal.cmake
+++ b/Superbuild/SQLiteExternal.cmake
@@ -32,6 +32,7 @@ SET(sqlite_GIT_TAG "origin/scirun-5.0.0-beta")
 ExternalProject_Add(SQLite_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/sqlite.git"
   GIT_TAG ${sqlite_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/SpdLogExternal.cmake b/Superbuild/SpdLogExternal.cmake
index 5f55b302c8..0f0a2282ba 100644
--- a/Superbuild/SpdLogExternal.cmake
+++ b/Superbuild/SpdLogExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(SpdLog_external
   GIT_REPOSITORY "https://github.com/gabime/spdlog"
   GIT_TAG "v1.10.0"
+  UPDATE_COMMAND ""
   CONFIGURE_COMMAND ""
   BUILD_COMMAND ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/TeemExternal.cmake b/Superbuild/TeemExternal.cmake
index ea3c227fdc..efed0c5892 100644
--- a/Superbuild/TeemExternal.cmake
+++ b/Superbuild/TeemExternal.cmake
@@ -34,6 +34,7 @@ ExternalProject_Add(Teem_external
   DEPENDS ${teem_DEPENDENCIES}
   GIT_REPOSITORY "https://github.com/SCIInstitute/teem.git"
   GIT_TAG ${teem_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""
diff --git a/Superbuild/TestDataConfig.cmake b/Superbuild/TestDataConfig.cmake
index e6710141f4..501181eedf 100644
--- a/Superbuild/TestDataConfig.cmake
+++ b/Superbuild/TestDataConfig.cmake
@@ -38,6 +38,7 @@ SET(test_data_DOWNLOAD_DIR "${CMAKE_BINARY_DIR}/download/SCIRunTestData")
 ExternalProject_Add(SCIRunTestData_external
   GIT_REPOSITORY ${test_data_GIT_URL}
   GIT_TAG ${test_data_GIT_TAG}
+  UPDATE_COMMAND ""
   SOURCE_DIR ${test_data_DIR}
   BUILD_COMMAND ""
   CONFIGURE_COMMAND ""
diff --git a/Superbuild/TnyExternal.cmake b/Superbuild/TnyExternal.cmake
index a3b52fe754..684c211d86 100644
--- a/Superbuild/TnyExternal.cmake
+++ b/Superbuild/TnyExternal.cmake
@@ -31,6 +31,7 @@ SET_PROPERTY(DIRECTORY PROPERTY "EP_BASE" ${ep_base})
 ExternalProject_Add(Tny_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/Tny.git"
   GIT_TAG "origin/scirun-5.0.0"
+  UPDATE_COMMAND ""
   INSTALL_COMMAND ""
   CMAKE_CACHE_ARGS
     -DCMAKE_VERBOSE_MAKEFILE:BOOL=${CMAKE_VERBOSE_MAKEFILE}
diff --git a/Superbuild/ToolkitsConfig.cmake b/Superbuild/ToolkitsConfig.cmake
index 405a98f550..9479b073cc 100644
--- a/Superbuild/ToolkitsConfig.cmake
+++ b/Superbuild/ToolkitsConfig.cmake
@@ -45,6 +45,7 @@ MACRO(EXTERNAL_TOOLKIT name)
   ExternalProject_Add(${toolkit_ExternalProject_name}
     GIT_REPOSITORY "https://github.com/SCIInstitute/${name}.git"
     GIT_TAG ${toolkit_GIT_TAG}
+    UPDATE_COMMAND ""
     BUILD_IN_SOURCE ON
     SOURCE_DIR ${toolkit_DIR}
     BUILD_COMMAND ""
diff --git a/Superbuild/ZlibExternal.cmake b/Superbuild/ZlibExternal.cmake
index 40da2a5d92..86062dafb4 100644
--- a/Superbuild/ZlibExternal.cmake
+++ b/Superbuild/ZlibExternal.cmake
@@ -32,6 +32,7 @@ SET(zlib_GIT_TAG "origin/1.3.1")
 ExternalProject_Add(Zlib_external
   GIT_REPOSITORY "https://github.com/CIBC-Internal/zlib.git"
   GIT_TAG ${zlib_GIT_TAG}
+  UPDATE_COMMAND ""
   PATCH_COMMAND ""
   INSTALL_DIR ""
   INSTALL_COMMAND ""

From 612ad337f66d67812c222925da1f60bf98aa8e96 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 18 Jun 2026 18:15:25 -0600
Subject: [PATCH 57/64] Update copyright year in scirunMain.cc

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 src/Main/scirunMain.cc | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Main/scirunMain.cc b/src/Main/scirunMain.cc
index 2c3caadc03..07a54102c1 100644
--- a/src/Main/scirunMain.cc
+++ b/src/Main/scirunMain.cc
@@ -3,7 +3,7 @@
 
    The MIT License
 
-   Copyright (c) 2020 Scientific Computing and Imaging Institute,
+   Copyright (c) 2020-2026 Scientific Computing and Imaging Institute,
    University of Utah.
 
    Permission is hereby granted, free of charge, to any person obtaining a

From 73b98b0f1947ab7e73420c21801ebfa16d222eca Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 18 Jun 2026 18:21:51 -0600
Subject: [PATCH 58/64] Fix CI caching: touch stamp files after cmake configure

cmake rewrites Externals/tmp/*/*.cmake on every configure run with a
fresh timestamp. The Makefile rules for each ExternalProject step depend
on those scripts, so every step appears stale after a cache restore --
causing make to re-run download/configure/build/install against missing
source directories and fail immediately.

Fix: touch all files in Externals/Stamp/ right after cmake configure
(before make) so they are always newer than the regenerated tmp/
scripts. Applies in build.sh (Linux/macOS) and inline in the Windows
workflow step.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 6 ++++++
 build.sh                             | 7 +++++++
 2 files changed, 13 insertions(+)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index d20f6a5816..496bf078a7 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -227,6 +227,12 @@ jobs:
           Write-Host "Configuring: $cmakeExe $($cmakeArgsFull -join ' ')"
           & $cmakeExe @cmakeArgsFull
 
+          # Touch cached stamp files so they appear newer than cmake-regenerated tmp/ scripts.
+          if (Test-Path "Externals\Stamp") {
+            Get-ChildItem -Path "Externals\Stamp" -Recurse -File |
+              ForEach-Object { $_.LastWriteTime = Get-Date }
+          }
+
           # Build (Release) using cmake --build
           Write-Host "Building with cmake --build . --config Release --parallel"
           & cmake --build . --config Release --parallel
diff --git a/build.sh b/build.sh
index f6fb2c4854..7f813996e5 100755
--- a/build.sh
+++ b/build.sh
@@ -129,6 +129,13 @@ configure_scirun() {
 
 build_scirun_make() {
     echo "Building SCIRun using make..."
+    # Touch cached stamp files so they appear newer than cmake-regenerated tmp/ scripts.
+    # cmake rewrites Externals/tmp/*/*.cmake on every configure run; without this, make
+    # always considers the ExternalProject steps stale and re-runs them against missing
+    # source directories, failing immediately on a cache restore.
+    if [[ -d "Externals/Stamp" ]]; then
+        find Externals/Stamp -type f -exec touch {} \;
+    fi
     trybuild make $makeflags
 }
 

From 157192a2b869cdf05720ef4d01d89fd6c26e9cf3 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Thu, 18 Jun 2026 18:47:19 -0600
Subject: [PATCH 59/64] Fix CI caching: bump to v4 key, only save cache on
 success

Broken cache entries (partial stamps from failed cold builds) were being
restored and failing again because configure stamps didn't exist. The
stamp-touch step can only touch files that exist.

Two fixes:
- Bump cache key to v4 to abandon all broken v3 entries and force fresh
  cold builds that populate complete stamp sets
- Split actions/cache@v4 into restore + save with `if: success()` so
  that only builds that fully succeed save a cache entry; partial/failed
  builds no longer poison the cache for future runs

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 496bf078a7..1647aca0ad 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -83,15 +83,16 @@ jobs:
             echo "externals=bin/Externals" >> $GITHUB_OUTPUT
           fi
 
-      - name: Cache Superbuild externals
-        uses: actions/cache@v4
+      - name: Restore Superbuild externals cache
+        id: cache-externals
+        uses: actions/cache/restore@v4
         with:
           path: |
             ${{ steps.paths.outputs.externals }}/Install
             ${{ steps.paths.outputs.externals }}/Stamp
-          key: superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
+          key: superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
           restore-keys: |
-            superbuild-v3-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
+            superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
 
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9
@@ -405,3 +406,12 @@ jobs:
             bin/SCIRun/SCIRun-*-Darwin.pkg
             bin/SCIRun/SCIRun-*-win64.exe
             build/**/*.msi
+
+      - name: Save Superbuild externals cache
+        if: ${{ success() && steps.cache-externals.outputs.cache-hit != 'true' }}
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            ${{ steps.paths.outputs.externals }}/Install
+            ${{ steps.paths.outputs.externals }}/Stamp
+          key: superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}

From 989de72340477ed64b8eeabc40a0ce73c5d17d2d Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 19 Jun 2026 01:01:52 -0600
Subject: [PATCH 60/64] Fix CI caching: remove cross-python restore-keys to
 prevent cache pollution

mac-coverage (python=true) was getting a cache hit via restore-key from
mac-gui-nonpython (python=false). The non-python cache had a different
set of stamps (no Python external), causing configure step failures for
unrelated externals like Teem.

Remove restore-keys entirely. Only exact key matches are safe: every
combination of (OS, variant, python-flag) builds a different set of
externals and must have its own cache entry.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 1647aca0ad..2f3b6ef572 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -91,8 +91,7 @@ jobs:
             ${{ steps.paths.outputs.externals }}/Install
             ${{ steps.paths.outputs.externals }}/Stamp
           key: superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
-          restore-keys: |
-            superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-
+          restore-keys: ''
 
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9

From f47d0a37a0727b3eea12c1f8d0f5018780248ca7 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 19 Jun 2026 13:03:27 -0600
Subject: [PATCH 61/64] Fix CI caching: touch stamps to year 2100, not current
 time
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Plain touch (current time) is not enough. CMake's ExternalProject_Add_Step
generates add_custom_command rules whose DEPENDS list includes
ExternalProject.cmake itself. If a runner has a newer cmake installation
than the runner that built the cached stamps, ExternalProject.cmake has a
newer timestamp and make considers every external step stale — even with
fresh-touched stamps.

Setting stamps to 2100 makes them unconditionally newer than any cmake
module file on any runner, regardless of when cmake was installed.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/superbuild-caching.md        | 85 ++++++++++++++++++++++++++++
 .github/workflows/reusable-build.yml |  8 ++-
 build.sh                             |  2 +-
 3 files changed, 92 insertions(+), 3 deletions(-)
 create mode 100644 .github/superbuild-caching.md

diff --git a/.github/superbuild-caching.md b/.github/superbuild-caching.md
new file mode 100644
index 0000000000..5624f529ee
--- /dev/null
+++ b/.github/superbuild-caching.md
@@ -0,0 +1,85 @@
+# Superbuild External Caching
+
+CI caches the compiled external libraries so that builds after the first only need to compile SCIRun itself — not Boost, Qt, Zlib, Python, and ~15 other dependencies from source.
+
+## How it works
+
+SCIRun uses a CMake [Superbuild](../Superbuild/): the outer CMake project drives `ExternalProject_Add` for each dependency, then builds SCIRun itself as the final step. Each external has a series of steps (download → update → configure → build → install), and CMake records completion in stamp files under `Externals/Stamp/`.
+
+### What gets cached
+
+The `actions/cache` step saves and restores two directories:
+
+| Directory | Contents |
+|-----------|----------|
+| `bin/Externals/Install/` | Headers, compiled libs, and cmake config files for every external |
+| `bin/Externals/Stamp/` | CMake stamp files that tell `make` which ExternalProject steps are done |
+
+The cache key is `superbuild-v3-<OS>-<hash of Superbuild/*.cmake>-<variant>-py<bool>`. If any Superbuild cmake file changes, the hash changes and the cache is bypassed entirely — the next build is a full cold build that repopulates the cache.
+
+### Why stamp-touching is needed
+
+CMake rewrites the helper scripts in `Externals/tmp/` (e.g. `Zlib_external-cfgcmd.cmake`) on every configure run, giving them the current timestamp. The Makefile rules for ExternalProject steps depend on those scripts, so restored stamp files (which carry an older timestamp) always appear stale, causing `make` to try re-running every step against source directories that don't exist.
+
+The fix is in `build.sh` (and an equivalent block in the Windows workflow): set the modification time of every file in `Externals/Stamp/` to the year **2100**, immediately after `cmake` configure but before `make`.
+
+A plain `touch` (current time) is not sufficient. CMake's `ExternalProject_Add_Step` generates `add_custom_command` calls whose `DEPENDS` list includes the `ExternalProject.cmake` module file itself. If the GitHub Actions runner has a newer cmake installation than the runner that created the cached stamps, `ExternalProject.cmake` carries a newer timestamp and make considers every step stale regardless of touching. Setting stamps to 2100 makes them unconditionally newer than any cmake module file on any runner.
+
+### Why `UPDATE_COMMAND ""`
+
+By default, `ExternalProject_Add` with `GIT_REPOSITORY` generates a `*-gitupdate.cmake` script that fetches the remote and compares the HEAD hash to `GIT_TAG` on every build. With a restored stamp, this script would still run (for the same timestamp reason above), fail with `fatal: not a git repository` because `Source/` isn't cached, and abort the build.
+
+Setting `UPDATE_COMMAND ""` in every git-based external tells CMake to generate a no-op update step instead — no `gitupdate.cmake` is written, no git operations are needed.
+
+### Why `EP_UPDATE_DISCONNECTED TRUE`
+
+Set globally in `Superbuild.cmake` as an extra safeguard. If for any reason an update stamp is missing (e.g. partial cache), CMake will run the (now no-op) update step once rather than triggering a network fetch.
+
+### Cache key variants
+
+Each OS × build variant × python flag gets its own cache entry. The restore-key is deliberately limited to same-variant matches (`-<variant>-` prefix but no python suffix) so that a `headless` cache is never used to satisfy a `gui` build — they compile different externals.
+
+---
+
+## When an external changes
+
+### Bumping a `GIT_TAG`
+
+Edit the relevant file in `Superbuild/` (e.g. `Superbuild/ZlibExternal.cmake`) and change `GIT_TAG`. Because the cache key hashes all `Superbuild/*.cmake` files, the existing cache is automatically invalidated. The next CI run does a full cold build (~1-2 hours) and saves a fresh cache.
+
+**You do not need to bump the cache version number.**
+
+### Adding a new external
+
+1. Create `Superbuild/MyLibExternal.cmake` following the pattern of an existing file.
+2. Add `UPDATE_COMMAND ""` alongside `GIT_TAG` (or after `URL` for tarball-based externals that don't need it).
+3. Wire it into `Superbuild/Superbuild.cmake`.
+
+The cache key hash will change automatically. Cold build on next CI run, new cache saved.
+
+### Removing an external
+
+Delete the cmake file and remove it from `Superbuild.cmake`. Cache key changes; next run is cold.
+
+### Changing configure or build flags for an external
+
+Edit the relevant `Superbuild/*.cmake` file. Cache key changes; next run is cold.
+
+### Manually busting the cache
+
+If the cache is known-bad (e.g. a broken partial save got promoted), bump the version prefix in `reusable-build.yml`:
+
+```yaml
+key: superbuild-v3-...   →   key: superbuild-v4-...
+```
+
+Update the `restore-keys` lines to match. On the next run every platform does a cold build and the old cache entries age out naturally (GitHub Actions evicts caches after 7 days of disuse).
+
+### Local development note
+
+The `touch Externals/Stamp/` step in `build.sh` runs on local builds too. If you change a `GIT_TAG` locally without clearing your build directory, `make` will skip the download/configure/build steps for that external and use the old installed version. The safest workflow when updating an external locally is:
+
+```sh
+rm -rf bin/Externals
+./build.sh
+```
diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 2f3b6ef572..3171b59f3d 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -227,10 +227,14 @@ jobs:
           Write-Host "Configuring: $cmakeExe $($cmakeArgsFull -join ' ')"
           & $cmakeExe @cmakeArgsFull
 
-          # Touch cached stamp files so they appear newer than cmake-regenerated tmp/ scripts.
+          # Touch cached stamp files to a far-future date so they are unconditionally newer
+          # than cmake module files (ExternalProject.cmake) on any runner. CMake's custom
+          # commands depend on the cmake module files themselves; if those files are newer
+          # than the restored stamps, make re-runs every ExternalProject step and fails.
           if (Test-Path "Externals\Stamp") {
+            $futureDate = [DateTime]::new(2100, 1, 1)
             Get-ChildItem -Path "Externals\Stamp" -Recurse -File |
-              ForEach-Object { $_.LastWriteTime = Get-Date }
+              ForEach-Object { $_.LastWriteTime = $futureDate }
           }
 
           # Build (Release) using cmake --build
diff --git a/build.sh b/build.sh
index 7f813996e5..5d3f7d3c28 100755
--- a/build.sh
+++ b/build.sh
@@ -134,7 +134,7 @@ build_scirun_make() {
     # always considers the ExternalProject steps stale and re-runs them against missing
     # source directories, failing immediately on a cache restore.
     if [[ -d "Externals/Stamp" ]]; then
-        find Externals/Stamp -type f -exec touch {} \;
+        find Externals/Stamp -type f -exec touch -d "2100-01-01" {} \;
     fi
     trybuild make $makeflags
 }

From 431dd8246d8a8d919d0a3f1dcfe16bf97b2744b3 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 19 Jun 2026 15:16:20 -0600
Subject: [PATCH 62/64] Remove superbuild caching (Install/Stamp approach
 doesn't work)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

All Superbuild externals use INSTALL_COMMAND "" — compiled artifacts live
in Externals/Build/, not Externals/Install/. Caching Install/ and Stamp/
captured almost nothing useful (17-66 KB of cmake config files and stamps)
while the actual libs in Build/ were never present on a cache restore,
causing SCIRun itself to fail finding its dependencies.

Reverts the cache restore/save steps, the 'Set externals path' step, and
the stamp-touch blocks in build.sh and the Windows workflow.

sccache remains in place for C++ compilation caching within SCIRun itself.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 .github/workflows/reusable-build.yml | 38 ----------------------------
 build.sh                             |  7 -----
 2 files changed, 45 deletions(-)

diff --git a/.github/workflows/reusable-build.yml b/.github/workflows/reusable-build.yml
index 3171b59f3d..dc13cdcedf 100644
--- a/.github/workflows/reusable-build.yml
+++ b/.github/workflows/reusable-build.yml
@@ -73,26 +73,6 @@ jobs:
       - name: Print Qt dir
         run: echo "QT_ROOT_DIR=${QT_ROOT_DIR:-(unset)}"
 
-      - name: Set externals path
-        id: paths
-        shell: bash
-        run: |
-          if [ "${{ runner.os }}" = "Windows" ]; then
-            echo "externals=build/Externals" >> $GITHUB_OUTPUT
-          else
-            echo "externals=bin/Externals" >> $GITHUB_OUTPUT
-          fi
-
-      - name: Restore Superbuild externals cache
-        id: cache-externals
-        uses: actions/cache/restore@v4
-        with:
-          path: |
-            ${{ steps.paths.outputs.externals }}/Install
-            ${{ steps.paths.outputs.externals }}/Stamp
-          key: superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
-          restore-keys: ''
-
       - name: Set up sccache
         uses: mozilla-actions/sccache-action@v0.0.9
 
@@ -227,16 +207,6 @@ jobs:
           Write-Host "Configuring: $cmakeExe $($cmakeArgsFull -join ' ')"
           & $cmakeExe @cmakeArgsFull
 
-          # Touch cached stamp files to a far-future date so they are unconditionally newer
-          # than cmake module files (ExternalProject.cmake) on any runner. CMake's custom
-          # commands depend on the cmake module files themselves; if those files are newer
-          # than the restored stamps, make re-runs every ExternalProject step and fails.
-          if (Test-Path "Externals\Stamp") {
-            $futureDate = [DateTime]::new(2100, 1, 1)
-            Get-ChildItem -Path "Externals\Stamp" -Recurse -File |
-              ForEach-Object { $_.LastWriteTime = $futureDate }
-          }
-
           # Build (Release) using cmake --build
           Write-Host "Building with cmake --build . --config Release --parallel"
           & cmake --build . --config Release --parallel
@@ -410,11 +380,3 @@ jobs:
             bin/SCIRun/SCIRun-*-win64.exe
             build/**/*.msi
 
-      - name: Save Superbuild externals cache
-        if: ${{ success() && steps.cache-externals.outputs.cache-hit != 'true' }}
-        uses: actions/cache/save@v4
-        with:
-          path: |
-            ${{ steps.paths.outputs.externals }}/Install
-            ${{ steps.paths.outputs.externals }}/Stamp
-          key: superbuild-v4-${{ runner.os }}-${{ hashFiles('Superbuild/*.cmake') }}-${{ inputs.variant }}-py${{ inputs.build-with-python }}
diff --git a/build.sh b/build.sh
index 5d3f7d3c28..f6fb2c4854 100755
--- a/build.sh
+++ b/build.sh
@@ -129,13 +129,6 @@ configure_scirun() {
 
 build_scirun_make() {
     echo "Building SCIRun using make..."
-    # Touch cached stamp files so they appear newer than cmake-regenerated tmp/ scripts.
-    # cmake rewrites Externals/tmp/*/*.cmake on every configure run; without this, make
-    # always considers the ExternalProject steps stale and re-runs them against missing
-    # source directories, failing immediately on a cache restore.
-    if [[ -d "Externals/Stamp" ]]; then
-        find Externals/Stamp -type f -exec touch -d "2100-01-01" {} \;
-    fi
     trybuild make $makeflags
 }
 

From b3dc04e2a68b93450b917d7f8a06d4581617bc85 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Fri, 3 Jul 2026 23:54:17 -0600
Subject: [PATCH 63/64] Move Python libraries design doc under dev_doc/ to fix
 readthedocs build

docs/Support-Python-Libraries-Design.md wasn't matched by any toctree
glob in docs/index.rst, so Sphinx emitted a "not included in any
toctree" warning. With fail_on_warning: true in .readthedocs.yaml,
that warning failed the build.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 docs/{ => dev_doc}/Support-Python-Libraries-Design.md | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/{ => dev_doc}/Support-Python-Libraries-Design.md (100%)

diff --git a/docs/Support-Python-Libraries-Design.md b/docs/dev_doc/Support-Python-Libraries-Design.md
similarity index 100%
rename from docs/Support-Python-Libraries-Design.md
rename to docs/dev_doc/Support-Python-Libraries-Design.md

From 496f4bbf135850c5f4db927aa4d3964c8f3bb0e5 Mon Sep 17 00:00:00 2001
From: Dan White <functoire@gmail.com>
Date: Sat, 4 Jul 2026 00:50:09 -0600
Subject: [PATCH 64/64] Add Markdown headings to Python libraries design doc

The doc had no Markdown headings at all, so Sphinx/MyST couldn't
derive a page title for it. With docs/index.rst's dev_doc/* toctree
glob picking it up, every reference to it emitted a "toctree contains
reference to document that doesn't have a title" warning, and
fail_on_warning: true in .readthedocs.yaml turned those into a build
failure.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../Support-Python-Libraries-Design.md        | 30 +++++++++----------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/docs/dev_doc/Support-Python-Libraries-Design.md b/docs/dev_doc/Support-Python-Libraries-Design.md
index bcb7ad4a8e..ffe4bd64b2 100644
--- a/docs/dev_doc/Support-Python-Libraries-Design.md
+++ b/docs/dev_doc/Support-Python-Libraries-Design.md
@@ -1,32 +1,32 @@
-Design doc: Support additional Python libraries (numpy, scipy)
+# Design doc: Support additional Python libraries (numpy, scipy)
 
 Related issue: https://github.com/SCIInstitute/SCIRun/issues/2479
 
-Overview
+## Overview
 
 Goal: ensure SCIRun's Python wrappers and packaging work smoothly with common scientific Python libraries (numpy, scipy) so downstream users can interoperate with ndarrays, use numerical routines, and run tests/examples that depend on these libraries.
 
-Motivation
+## Motivation
 
 Many users expect conversions between SCIRun data (Fields, Meshes, DenseMatrix) and numpy arrays without costly copies. CI and packaging must validate compatibility and reproducibility for supported numpy/scipy versions.
 
-Requirements
+## Requirements
 
-Functional
+### Functional
 - Zero-copy or documented conversion paths between SCIRun DenseMatrix/Field data and numpy ndarray where possible.
 - Helper utilities in Python wrappers: to_numpy(), from_numpy(), memoryview access with clear ownership semantics.
 - Example notebooks demonstrating workflows (convert, run numpy ops, convert back, visualize).
 
-Build / Packaging
+### Build / Packaging
 - CI jobs that install targeted numpy/scipy versions and run wrapper tests.
 - Wheel/build rules documented for binary compatibility (manylinux, ABI tags) if shipping wheels.
 - CMake option or wrapper build config to locate Python and numpy include/abi (find_package or pybind11 helpers).
 
-Testing
+### Testing
 - Pytest suite that covers conversions, roundtrip tests, and small numerical consistency checks across supported numpy versions.
 - Tests run in CI matrix: at least two Python versions (e.g., 3.10, 3.11) and current numpy LTS + one older supported version.
 
-API design
+## API design
 - Provide explicit conversion functions on Python objects:
   - DenseMatrix.to_numpy(copy=False) -> numpy.ndarray
   - DenseMatrix.from_numpy(ndarray, copy=False) -> DenseMatrix
@@ -34,7 +34,7 @@ API design
 - Clearly document ownership and lifetime: when copy=False, returned ndarray references internal memory until original object is GC'd or buffer is detached.
 - Prefer pybind11 buffer protocol for native sharing where feasible.
 
-Implementation Plan
+## Implementation Plan
 1. Prototype conversion layer in a feature branch:
    - Implement to_numpy/from_numpy for DenseMatrix using pybind11 buffer interface.
    - Add helper functions for common types (float32/64) and shape conventions.
@@ -43,24 +43,24 @@ Implementation Plan
 4. Extend to Field/mesh conversions: provide arrays for points, connectivity, and per-vertex/per-cell attributes.
 5. Add CI matrix entries (Python versions + numpy versions) and run pytest suite.
 
-Acceptance criteria
+## Acceptance criteria
 - Conversions implemented and covered by tests.
 - CI builds successfully with numpy present; tests pass in at least one CI job.
 - Documentation and example notebook present in docs/python_examples/.
 
-Risks and mitigations
+## Risks and mitigations
 - Binary compatibility: avoid shipping wheels initially; provide clear build-from-source instructions and CI verification.
 - Ownership complexity: prefer explicit API (copy flag) and document lifetime rules. Use pybind11 buffer protocol to reduce errors.
 - Large memory copies: benchmark common workflows and document performance expectations; add optional utilities for chunked conversion.
 
-Open questions
+## Open questions
 - Which Python/numpy versions should be formally supported (LTS policy)?
-- Is shipping binary wheels a near-term goal, or should initial effort focus on source builds and CI? 
+- Is shipping binary wheels a near-term goal, or should initial effort focus on source builds and CI?
 
-Next steps
+## Next steps
 - Assign an owner to implement the DenseMatrix <-> numpy prototype.
 - Create a feature branch and open a PR with the prototype and example notebook.
 - Add CI job for one Python+numpy configuration and expand later.
 
 
-Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
\ No newline at end of file
+Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>