merge: Merge pull request #11 from DigitalHolography/feat/sliding-average-vsh

fix: skip deterministic VSH warm-up frames

Author: JulesGuillou

doc/mkdocs/docs/holovibes/tasks/asyncs/sliding_average.md

@@ -14,7 +14,11 @@ The tensor must be 32-bit floating point (`float32`) data already located in dev
 
 An optional second input may provide a host `uint8` scalar with shape `(1)`. A zero value discards
 the associated frame without advancing the averaging window; a nonzero value accepts it. This is
-used to suppress invalid warm-up frames from centered correction pipelines.
+available for data-dependent filtering.
+
+`discard_first` deterministically discards the requested number of initial accepted frames without
+advancing the averaging window. The VSH correction pipeline uses this to suppress its known
+`window_size - 1` alignment warm-up without adding a validity edge to the graph.
 
 ## Outputs
 After the warm-up period required to enqueue the first `window_size` frames, each pop exposes one tensor of shape `(1, H, W)` with the same dtype and memory location as the input. 

src/holotask/include/holotask/asyncs/slide_avg.hh

@@ -28,6 +28,7 @@ namespace holotask::asyncs {
 struct SlidingAverageSettings {
   size_t target_capacity;
   size_t window_size;
+  size_t discard_first = 0;
 
   bool operator==(const SlidingAverageSettings &) const = default;
 };

src/holotask/src/asyncs/slide_avg.cu

@@ -36,12 +36,15 @@ namespace holotask::asyncs {
 template <typename T> using DevPtr = curaii::unique_device_ptr<T>;
 
 void to_json(nlohmann::json &j, const SlidingAverageSettings &s) {
-  j = nlohmann::json{{"target_capacity", s.target_capacity}, {"window_size", s.window_size}};
+  j = nlohmann::json{{"target_capacity", s.target_capacity},
+                     {"window_size", s.window_size},
+                     {"discard_first", s.discard_first}};
 }
 
 void from_json(const nlohmann::json &j, SlidingAverageSettings &s) {
   j.at("target_capacity").get_to(s.target_capacity);
   j.at("window_size").get_to(s.window_size);
+  s.discard_first = j.value("discard_first", size_t{0});
 }
 
 namespace {
@@ -85,6 +88,7 @@ private:
   size_t                 element_size_;
   DevPtr<std::byte>      d_buffer_;
   DevPtr<float>          d_running_avg_;
+  size_t                 discarded_ = 0;
   alignas(CACHE_LINE_SIZE) std::atomic<size_t> avg_idx_;
   alignas(CACHE_LINE_SIZE) std::atomic<size_t> write_idx_;
   alignas(CACHE_LINE_SIZE) std::atomic<size_t> read_idx_;
@@ -178,8 +182,12 @@ void SlidingAverage::release_output(int index) {
 }
 
 holoflow::core::OpResult SlidingAverage::try_push(holoflow::core::AsyncPushCtx &ctx) {
-  if (ctx.inputs.size() == 2 &&
-      *reinterpret_cast<const std::uint8_t *>(ctx.inputs[1].data()) == std::uint8_t{0}) {
+  const bool invalid = ctx.inputs.size() == 2 && *reinterpret_cast<const std::uint8_t *>(
+                                                     ctx.inputs[1].data()) == std::uint8_t{0};
+  if (invalid || discarded_ < settings_.discard_first) {
+    if (!invalid) {
+      ++discarded_;
+    }
     storage_access().owned_input_storage(0).ptr = nullptr;
     return holoflow::core::OpResult::Ok;
   }

src/holovibes/schemas/tasks/asyncs/sliding_average_settings.json

@@ -14,6 +14,12 @@
       "type": "integer",
       "minimum": 1,
       "description": "Number of frames included in each running average. Must satisfy:\n- window_size > 0"
+    },
+    "discard_first": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Number of initial accepted input frames to discard before filling the averaging window."
     }
   },
   "required": [
@@ -23,7 +29,8 @@
   "examples": [
     {
       "target_capacity": 32,
-      "window_size": 8
+      "window_size": 8,
+      "discard_first": 0
     }
   ]
 }

src/holovibes/src/pipeline/graph_builder.cc

@@ -133,9 +133,8 @@ holoflow::core::GraphSpec GraphBuilder::build() {
                                       .target_capacity = std::max<size_t>(2, 2 * FH.shape.at(0)),
                                       .window_size     = static_cast<size_t>(s_.pp_accumulation),
                                   });
-  TDesc                FH_current = timing_outputs.at(0);
-  const TDesc          FH_delayed = timing_outputs.at(1);
-  std::optional<TDesc> valid;
+  TDesc       FH_current = timing_outputs.at(0);
+  const TDesc FH_delayed = timing_outputs.at(1);
 
   if (s_.autofocus_enabled) {
     if (s_.autofocus_nb_iter <= 0) {
@@ -146,7 +145,6 @@ holoflow::core::GraphSpec GraphBuilder::build() {
           "sliding Shack-Hartmann correction only supports one autofocus iteration");
     }
 
-    valid = timing_outputs.at(2);
     ShackHartmannIterationState shack_hartmann_iteration_state;
     for (int pass = 0; pass < s_.autofocus_nb_iter; ++pass) {
       const TDesc &delayed = pass == 0 ? FH_delayed : FH_current;
@@ -157,7 +155,7 @@ holoflow::core::GraphSpec GraphBuilder::build() {
 
   TDesc FH_z = build_spatial_propagation(FH_current);
 
-  build_xy_view(FH_z, valid);
+  build_xy_view(FH_z);
 
   if (s_.view_3d_cuts) {
     build_3d_cuts(FH_z);
@@ -473,6 +471,7 @@ GraphBuilder::build_shack_hartmann(const TDesc &FH_current, const TDesc &FH_dela
                                                        s_.autofocus_zernike_orders,
                                                        s_.signal_plot_time_window_seconds,
                                                        s_.signal_plot_sample_time_seconds(),
+                                                       static_cast<size_t>(s_.pp_accumulation - 1),
                                                    });
     }
 
@@ -602,7 +601,7 @@ GraphBuilder::TDesc GraphBuilder::build_freq_weights() {
   return freqs;
 }
 
-void GraphBuilder::build_xy_view(const TDesc &FH_z, const std::optional<TDesc> &valid) {
+void GraphBuilder::build_xy_view(const TDesc &FH_z) {
   using Target = holotask::syncs::ConversionSettings::Target;
   using Strat  = holotask::syncs::ConversionSettings::Strategy;
   auto Host    = holotask::syncs::MemcpySettings::Target::Host;
@@ -649,13 +648,10 @@ void GraphBuilder::build_xy_view(const TDesc &FH_z, const std::optional<TDesc> &
   const holotask::asyncs::SlidingAverageSettings slide_settings{
       .target_capacity = static_cast<size_t>(std::max(1, s_.gpu_out_size)),
       .window_size     = static_cast<size_t>(s_.pp_accumulation),
+      .discard_first =
+          s_.autofocus_enabled ? static_cast<size_t>(s_.pp_accumulation - 1) : size_t{0},
   };
-  if (valid.has_value()) {
-    auto stable_valid = memcpy(*valid, {holotask::syncs::MemcpySettings::Target::Host});
-    result            = slide_avg(result, stable_valid, slide_settings);
-  } else {
-    result = slide_avg(result, slide_settings);
-  }
+  result = slide_avg(result, slide_settings);
 
   if (s_.pp_convolution) {
     throw std::logic_error{"Convolution is currently not supported"};

src/holovibes/src/pipeline/graph_builder.hh

@@ -67,7 +67,7 @@ private:
                              ShackHartmannIterationState &iteration_state);
   TDesc build_spatial_propagation(const TDesc &FH);
   TDesc build_spatial_filter(const TDesc &FH_z);
-  void  build_xy_view(const TDesc &FH_z, const std::optional<TDesc> &valid);
+  void  build_xy_view(const TDesc &FH_z);
   void  build_3d_cuts(const TDesc &FH_z);
   TDesc build_freq_weights();
 

src/holovibes/src/tasks/sinks/display_signal_history.cc

@@ -130,6 +130,10 @@ class DisplaySignalHistoryTask : public holoflow::core::ISyncTask {
   }
 
   holoflow::core::OpResult execute(holoflow::core::SyncCtx &ctx) override {
+    if (received_sample_index_++ < settings_.discard_first) {
+      return holoflow::core::OpResult::Ok;
+    }
+
     auto              &input = ctx.inputs[0];
     const auto        &desc  = input.desc;
     const auto         count = settings_.indexes.size();
@@ -173,7 +177,8 @@ class DisplaySignalHistoryTask : public holoflow::core::ISyncTask {
   holoflow::core::TDesc                    idesc_;
   std::shared_ptr<SignalHistoryDispatcher> dispatcher_;
   cudaStream_t                             stream_;
-  uint64_t                                 valid_sample_index_ = 0;
+  uint64_t                                 received_sample_index_ = 0;
+  uint64_t                                 valid_sample_index_    = 0;
 };
 
 } // namespace
@@ -183,13 +188,15 @@ void to_json(nlohmann::json &j, const DisplaySignalHistorySettings &settings) {
       {"indexes", settings.indexes},
       {"time_window_seconds", settings.time_window_seconds},
       {"sample_time_seconds", settings.sample_time_seconds},
+      {"discard_first", settings.discard_first},
   };
 }
 
 void from_json(const nlohmann::json &j, DisplaySignalHistorySettings &settings) {
   j.at("indexes").get_to(settings.indexes);
   j.at("time_window_seconds").get_to(settings.time_window_seconds);
   j.at("sample_time_seconds").get_to(settings.sample_time_seconds);
+  settings.discard_first = j.value("discard_first", size_t{0});
 }
 
 DisplaySignalHistoryFactory::DisplaySignalHistoryFactory(

src/holovibes/src/tasks/sinks/display_signal_history.hh

@@ -38,6 +38,9 @@ struct DisplaySignalHistorySettings {
   // acquisition or pipeline time, not processing completion or GUI refresh time.
   double sample_time_seconds = 1.0 / 15.0;
 
+  // Known pipeline warm-up samples are discarded before the logical plot timeline starts.
+  size_t discard_first = 0;
+
   bool operator==(const DisplaySignalHistorySettings &) const = default;
 };
 

test/holotask/sliding_average_test.cu

@@ -246,4 +246,50 @@ TEST(SlidingAverageTest, DiscardsInvalidInputsBeforeFullWindowWarmup) {
   EXPECT_EQ(output_count, 2);
 }
 
+TEST(SlidingAverageTest, DiscardsConfiguredInitialFramesWithoutValidityInput) {
+  const TDesc                                    image_desc({1, 1, 1}, DType::F32, MemLoc::Device);
+  const std::array                               input_descs{image_desc};
+  const holotask::asyncs::SlidingAverageSettings settings{
+      .target_capacity = 4,
+      .window_size     = 3,
+      .discard_first   = 2,
+  };
+  holotask::asyncs::SlidingAverageFactory factory;
+  const auto infer = factory.infer(input_descs, nlohmann::json(settings));
+
+  curaii::CudaStream producer_stream;
+  curaii::CudaStream consumer_stream;
+  auto               task = factory.create(input_descs, nlohmann::json(settings),
+                                           {producer_stream.get(), consumer_stream.get()});
+  task->bind_logger(spdlog::default_logger());
+  TestStorageAccess storage_access(infer.input_descs, infer.output_descs);
+  task->bind_storage_access(&storage_access);
+
+  std::array output_views{TView{infer.output_descs[0], &storage_access.owned_output_storage(0)}};
+  std::atomic<bool>           cancelled{false};
+  holoflow::core::AsyncPopCtx pop_ctx{output_views, &cancelled};
+  const std::array            values{100.0f, 200.0f, 3.0f, 5.0f, 7.0f};
+
+  for (size_t i = 0; i < values.size(); ++i) {
+    auto acquired = task->acquire_input(0);
+    ASSERT_TRUE(acquired.has_value());
+    CUDA_CHECK(cudaMemcpy(acquired->data(), &values[i], sizeof(float), cudaMemcpyHostToDevice));
+    std::array                   input_views{*acquired};
+    holoflow::core::AsyncPushCtx push_ctx{input_views, &cancelled};
+    ASSERT_EQ(task->try_push(push_ctx), OpResult::Ok);
+
+    const auto pop_result = task->try_pop(pop_ctx);
+    if (i + 1 < values.size()) {
+      EXPECT_EQ(pop_result, OpResult::NotReady);
+      continue;
+    }
+
+    ASSERT_EQ(pop_result, OpResult::Ok);
+    float actual = 0.0f;
+    CUDA_CHECK(cudaMemcpy(&actual, output_views[0].data(), sizeof(float), cudaMemcpyDeviceToHost));
+    EXPECT_FLOAT_EQ(actual, 5.0f);
+    task->release_output(0);
+  }
+}
+
 } // namespace