Feature/timeseries loading

.github/agents/reviewer.agent.md

@@ -30,6 +30,7 @@ When invoked, determine what to review:
 ### Architecture
 
 - `renderlib/` must not depend on Qt. Flag any `Q*` types, `QObject`, signals/slots, or Qt headers leaking into `renderlib/`.
+- `renderlib/gfxOpenGL/` and `renderlib/gfxVulkan/` are the only places that should contain graphics API calls. Flag any OpenGL or Vulkan calls outside those directories.
 - GUI logic belongs in `agave_app/`. Rendering, I/O, scene, and serialization belong in `renderlib/`. It is preferable to have anything not necessary for the GUI to be pushed down into `renderlib/`.
 - New commands must be added to **all** of: `renderlib/command.h`, `renderlib/command.cpp`, `agave_app/commandBuffer.cpp`, `test/test_commands.cpp`, `agave_pyclient/agave_pyclient/commandbuffer.py`, `agave_pyclient/agave_pyclient/agave.py`, `webclient/src/commandbuffer.ts`, `webclient/src/agave.ts`. Verify the integer ID is unique and consistent, and that the argument list/order matches across all locations.
 

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

agave_app/CacheSettings.cpp → agave_app/AgaveSettings.cpp

@@ -1,4 +1,4 @@
-#include "CacheSettings.h"
+#include "AgaveSettings.h"
 
 #include "renderlib/CacheManager.h"
 #include "renderlib/Logging.h"
@@ -10,6 +10,8 @@
 
 #include <nlohmann/json.hpp>
 
+#include <algorithm>
+
 namespace {
 
 ::CacheConfig
@@ -50,19 +52,38 @@ toRenderlibConfig(const CacheSettingsData& data)
   return config;
 }
 
+const nlohmann::json*
+objectIfPresent(const nlohmann::json& parent, const char* key)
+{
+  auto it = parent.find(key);
+  if (it != parent.end() && it->is_object()) {
+    return &(*it);
+  }
+  return nullptr;
+}
+
+template<typename T>
+void
+readIfPresent(const nlohmann::json& object, const char* key, T& value)
+{
+  if (object.contains(key)) {
+    value = object[key].get<T>();
+  }
+}
+
 } // namespace
 
-CacheSettings::CacheSettings() = default;
+AgaveSettings::AgaveSettings() = default;
 
-CacheSettingsData
-CacheSettings::defaultSettings() const
+AgaveSettingsData
+AgaveSettings::defaultSettings() const
 {
-  // Tunable defaults come from CacheSettingsData's in-class initializers.
+  // Tunable defaults come from the settings structs' in-class initializers.
   return {};
 }
 
 std::string
-CacheSettings::configPath() const
+AgaveSettings::configPath() const
 {
   QString baseDir = QStandardPaths::writableLocation(QStandardPaths::AppConfigLocation);
   if (baseDir.isEmpty()) {
@@ -72,52 +93,70 @@ CacheSettings::configPath() const
     baseDir = QDir::currentPath();
   }
   QDir().mkpath(baseDir);
-  return QDir(baseDir).filePath("cache_settings.json").toStdString();
+  return QDir(baseDir).filePath("agave_settings.json").toStdString();
 }
 
-CacheSettingsData
-CacheSettings::load()
+void
+AgaveSettings::load()
 {
-  CacheSettingsData data = defaultSettings();
+  AgaveSettingsData data = defaultSettings();
   QString path = QString::fromStdString(configPath());
   QFile file(path);
   if (!file.exists()) {
-    return data;
+    m_data = data;
+    return;
   }
   if (!file.open(QIODevice::ReadOnly)) {
-    return data;
+    m_data = data;
+    return;
   }
 
   QByteArray raw = file.readAll();
   try {
     nlohmann::json doc = nlohmann::json::parse(raw.toStdString());
-    if (doc.contains("enabled")) {
-      data.enabled = doc["enabled"].get<bool>();
-    }
-    if (doc.contains("enableDisk")) {
-      data.enableDisk = doc["enableDisk"].get<bool>();
+    if (const nlohmann::json* cache = objectIfPresent(doc, "cache")) {
+      readIfPresent(*cache, "enabled", data.cache.enabled);
+      readIfPresent(*cache, "enableDisk", data.cache.enableDisk);
+      readIfPresent(*cache, "maxRamBytes", data.cache.maxRamBytes);
+      readIfPresent(*cache, "maxDiskBytes", data.cache.maxDiskBytes);
     }
-    if (doc.contains("maxRamBytes")) {
-      data.maxRamBytes = doc["maxRamBytes"].get<std::uint64_t>();
-    }
-    if (doc.contains("maxDiskBytes")) {
-      data.maxDiskBytes = doc["maxDiskBytes"].get<std::uint64_t>();
+
+    if (const nlohmann::json* timeSeries = objectIfPresent(doc, "timeSeries")) {
+      readIfPresent(*timeSeries, "prefetchEnabled", data.timeSeries.prefetchEnabled);
+
+      if (const nlohmann::json* playback = objectIfPresent(*timeSeries, "playback")) {
+        readIfPresent(*playback, "fps", data.timeSeries.playback.fps);
+        readIfPresent(*playback, "loop", data.timeSeries.playback.loop);
+        readIfPresent(*playback, "dropFrames", data.timeSeries.playback.dropFrames);
+      }
     }
   } catch (...) {
-    return defaultSettings();
+    m_data = defaultSettings();
+    return;
   }
 
-  return data;
+  m_data = data;
 }
 
 bool
-CacheSettings::save(const CacheSettingsData& data) const
+AgaveSettings::save() const
 {
   nlohmann::json doc;
-  doc["enabled"] = data.enabled;
-  doc["enableDisk"] = data.enableDisk;
-  doc["maxRamBytes"] = data.maxRamBytes;
-  doc["maxDiskBytes"] = data.maxDiskBytes;
+  doc["cache"] = {
+    { "enabled", m_data.cache.enabled },
+    { "enableDisk", m_data.cache.enableDisk },
+    { "maxRamBytes", m_data.cache.maxRamBytes },
+    { "maxDiskBytes", m_data.cache.maxDiskBytes },
+  };
+  doc["timeSeries"] = {
+    { "prefetchEnabled", m_data.timeSeries.prefetchEnabled },
+    { "playback",
+      {
+        { "fps", m_data.timeSeries.playback.fps },
+        { "loop", m_data.timeSeries.playback.loop },
+        { "dropFrames", m_data.timeSeries.playback.dropFrames },
+      } },
+  };
 
   QString path = QString::fromStdString(configPath());
   QFile file(path);
@@ -130,13 +169,13 @@ CacheSettings::save(const CacheSettingsData& data) const
 }
 
 void
-CacheSettings::applyToRenderlib(const CacheSettingsData& data) const
+AgaveSettings::applyCacheToRenderlib() const
 {
   // The cache directory (and its writability) is settled once at startup in
   // CacheManager::initialize(); if it wasn't writable the manager left its root
   // unset, so a disk-enabled config here is simply honored as RAM-only. We only
   // push the runtime tunables.
-  ::CacheConfig config = toRenderlibConfig(data);
+  ::CacheConfig config = toRenderlibConfig(m_data.cache);
   LOG_INFO << "Cache config: enabled=" << (config.enabled ? 1 : 0) << " ram_bytes=" << config.maxRamBytes
            << " disk_enabled=" << (config.enableDisk ? 1 : 0) << " disk_bytes=" << config.maxDiskBytes
            << " cache_dir=" << CacheManager::instance().getCacheDirectory();

agave_app/AgaveSettings.h

@@ -0,0 +1,57 @@
+#pragma once
+
+#include <cstdint>
+#include <string>
+
+struct CacheSettingsData
+{
+  bool enabled = true;
+  bool enableDisk = true;
+  std::uint64_t maxRamBytes = 4ULL * 1024ULL * 1024ULL * 1024ULL;
+  std::uint64_t maxDiskBytes = 100ULL * 1024ULL * 1024ULL * 1024ULL;
+};
+
+struct PlaybackSettingsData
+{
+  float fps = 10.0f;
+  bool loop = true;
+  // True keeps a steady frame rate by skipping time steps that are not loaded;
+  // false waits for every one.
+  bool dropFrames = false;
+};
+
+struct TimeSeriesSettingsData
+{
+  // Fill memory and disk with time steps in the background. With this off,
+  // slider-driven loads are still cached in both tiers. How much gets warmed is
+  // bounded by the RAM and disk cache limits, so there is no separate depth or
+  // fill-cache setting.
+  bool prefetchEnabled = true;
+  PlaybackSettingsData playback;
+};
+
+struct AgaveSettingsData
+{
+  CacheSettingsData cache;
+  TimeSeriesSettingsData timeSeries;
+};
+
+class AgaveSettings
+{
+public:
+  AgaveSettings();
+
+  void load();
+  bool save() const;
+
+  void applyCacheToRenderlib() const;
+
+  AgaveSettingsData& data() { return m_data; }
+  const AgaveSettingsData& data() const { return m_data; }
+
+  AgaveSettingsData defaultSettings() const;
+  std::string configPath() const;
+
+private:
+  AgaveSettingsData m_data;
+};

agave_app/CMakeLists.txt

@@ -46,12 +46,14 @@ target_sources(agaveapp PRIVATE
 	"${CMAKE_CURRENT_SOURCE_DIR}/CameraDockWidget.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CameraWidget.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CameraWidget.h"
-	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettings.cpp"
-	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettings.h"
+	"${CMAKE_CURRENT_SOURCE_DIR}/AgaveSettings.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/AgaveSettings.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettingsDockWidget.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettingsDockWidget.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettingsWidget.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/CacheSettingsWidget.h"
+	"${CMAKE_CURRENT_SOURCE_DIR}/TimeSlider.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/TimeSlider.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/citationDialog.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/citationDialog.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/cgiparser.cpp"
@@ -103,6 +105,8 @@ target_sources(agaveapp PRIVATE
 	"${CMAKE_CURRENT_SOURCE_DIR}/streamtestclient.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/TimelineDockWidget.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/TimelineDockWidget.h"
+	"${CMAKE_CURRENT_SOURCE_DIR}/TimeSeriesLoaderBridge.cpp"
+	"${CMAKE_CURRENT_SOURCE_DIR}/TimeSeriesLoaderBridge.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/ViewerState.cpp"
 	"${CMAKE_CURRENT_SOURCE_DIR}/ViewerState.h"
 	"${CMAKE_CURRENT_SOURCE_DIR}/ViewToolbar.cpp"

agave_app/CacheSettingsDockWidget.cpp

@@ -1,7 +1,8 @@
 #include "CacheSettingsDockWidget.h"
 
-CacheSettingsDockWidget::CacheSettingsDockWidget(QWidget* parent)
+CacheSettingsDockWidget::CacheSettingsDockWidget(QWidget* parent, AgaveSettingsData* settings)
   : QDockWidget(parent)
+  , m_settingsWidget(this, settings)
 {
   setWindowTitle(tr("Advanced Cache Settings"));
   setWidget(&m_settingsWidget);

agave_app/CacheSettingsDockWidget.h

@@ -9,7 +9,7 @@ class CacheSettingsDockWidget : public QDockWidget
   Q_OBJECT
 
 public:
-  explicit CacheSettingsDockWidget(QWidget* parent = nullptr);
+  explicit CacheSettingsDockWidget(QWidget* parent = nullptr, AgaveSettingsData* settings = nullptr);
 
   CacheSettingsWidget* widget() { return &m_settingsWidget; }
 

agave_app/CacheSettingsWidget.cpp

@@ -4,8 +4,9 @@
 
 #include <QFormLayout>
 
-CacheSettingsWidget::CacheSettingsWidget(QWidget* parent)
+CacheSettingsWidget::CacheSettingsWidget(QWidget* parent, AgaveSettingsData* settings)
   : QWidget(parent)
+  , m_settings(settings)
 {
   auto* layout = new QFormLayout(this);
 
@@ -31,32 +32,55 @@ CacheSettingsWidget::CacheSettingsWidget(QWidget* parent)
   m_applyButton = new QPushButton(tr("Apply"), this);
   m_clearDiskButton = new QPushButton(tr("Clear disk cache"), this);
 
+  m_prefetchEnabled = new QCheckBox(tr("Prefetch time steps"), this);
+  m_prefetchEnabled->setToolTip(
+    tr("Fill memory and disk with time steps ahead of the current one, in the background. How far ahead is bounded by "
+       "the RAM and disk limits above."));
+  m_prefetchEnabled->setStatusTip(
+    tr("Fill memory and disk with time steps ahead of the current one, in the background"));
+
+  connect(m_enableCache, &QCheckBox::toggled, this, [this](bool) { writeToSettings(); });
+  connect(m_enableDisk, &QCheckBox::toggled, this, [this](bool) { writeToSettings(); });
+  connect(m_ramLimitMB, QOverload<int>::of(&QSpinBox::valueChanged), this, [this](int) { writeToSettings(); });
+  connect(m_diskLimitGB, QOverload<int>::of(&QSpinBox::valueChanged), this, [this](int) { writeToSettings(); });
+  connect(m_prefetchEnabled, &QCheckBox::toggled, this, [this](bool) { writeToSettings(); });
+
   layout->addRow(m_enableCache);
   layout->addRow(m_enableDisk);
   layout->addRow(tr("RAM limit"), m_ramLimitMB);
   layout->addRow(tr("Disk limit"), m_diskLimitGB);
   layout->addRow(tr("Cache directory"), m_cacheDirLabel);
+  layout->addRow(new QLabel(tr("<b>Prefetch</b>"), this));
+  layout->addRow(m_prefetchEnabled);
   layout->addRow(QString(), m_applyButton);
   layout->addRow(QString(), m_clearDiskButton);
   setLayout(layout);
 }
 
 void
-CacheSettingsWidget::setSettings(const CacheSettingsData& data)
+CacheSettingsWidget::updateUiFromSettings()
 {
-  m_enableCache->setChecked(data.enabled);
-  m_enableDisk->setChecked(data.enableDisk);
-  m_ramLimitMB->setValue(static_cast<int>(data.maxRamBytes / (1024ULL * 1024ULL)));
-  m_diskLimitGB->setValue(static_cast<int>(data.maxDiskBytes / (1024ULL * 1024ULL * 1024ULL)));
+  if (!m_settings) {
+    return;
+  }
+  m_refreshingSettings = true;
+  m_enableCache->setChecked(m_settings->cache.enabled);
+  m_enableDisk->setChecked(m_settings->cache.enableDisk);
+  m_ramLimitMB->setValue(static_cast<int>(m_settings->cache.maxRamBytes / (1024ULL * 1024ULL)));
+  m_diskLimitGB->setValue(static_cast<int>(m_settings->cache.maxDiskBytes / (1024ULL * 1024ULL * 1024ULL)));
+  m_prefetchEnabled->setChecked(m_settings->timeSeries.prefetchEnabled);
+  m_refreshingSettings = false;
 }
 
-CacheSettingsData
-CacheSettingsWidget::getSettings() const
+void
+CacheSettingsWidget::writeToSettings()
 {
-  CacheSettingsData data;
-  data.enabled = m_enableCache->isChecked();
-  data.enableDisk = m_enableDisk->isChecked();
-  data.maxRamBytes = static_cast<std::uint64_t>(m_ramLimitMB->value()) * 1024ULL * 1024ULL;
-  data.maxDiskBytes = static_cast<std::uint64_t>(m_diskLimitGB->value()) * 1024ULL * 1024ULL * 1024ULL;
-  return data;
+  if (!m_settings || m_refreshingSettings) {
+    return;
+  }
+  m_settings->cache.enabled = m_enableCache->isChecked();
+  m_settings->cache.enableDisk = m_enableDisk->isChecked();
+  m_settings->cache.maxRamBytes = static_cast<std::uint64_t>(m_ramLimitMB->value()) * 1024ULL * 1024ULL;
+  m_settings->cache.maxDiskBytes = static_cast<std::uint64_t>(m_diskLimitGB->value()) * 1024ULL * 1024ULL * 1024ULL;
+  m_settings->timeSeries.prefetchEnabled = m_prefetchEnabled->isChecked();
 }