stages.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
 
// Database-level pipeline stage execution (#265, Phase 1).
//
// The algorithms in segmentation/ and reconstruction/ are pure functions over
// PCL clouds; the "load the named clouds out of a ProjectDB, run the algorithm,
// write the results back, record it in pipeline_log" wrapper used to live only
// inside apps/rux/src/create/*.cpp. This header lifts that wrapper DOWN into
// the library so both `rux create <stage>` and the GUI/daemon job runners drive
// the exact same code path (issue #265: "shared logic goes DOWN into the
// library, not sideways between apps").
//
// Layering: this is the `pipeline` module, which sits ABOVE the Layer-3 peers
// (segmentation / reconstruction / slam / io) — it is the one place allowed to
// link several of them at once. See docs/STANDARDS.md §1.
 
#include <atomic>
#include <cstdint>
#include <filesystem>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
namespace reusex {
class ProjectDB;
}
 
namespace reusex::pipeline {

enum class JobStage {
  clouds,    
  planes,    
  rooms,     
  instances, 
};

std::string_view to_string(JobStage stage);

std::string_view pipeline_log_name(JobStage stage);

std::optional<JobStage> parse_job_stage(std::string_view name);

std::vector<std::string> job_stage_names();

bool stage_supports_cancellation(JobStage stage);

struct StageArtifact {
  std::string kind;
  std::string name;
  int64_t count = -1;
};

struct StageResult {
  bool ok = false;        
  bool cancelled = false; 
  bool invalid_input = false;
  std::string message; 
  std::vector<StageArtifact> outputs;
 
  static StageResult success(std::string message = {});
  static StageResult success(std::string message,
                             std::vector<StageArtifact> outputs);
  static StageResult failure(std::string message);
  static StageResult invalid(std::string message);
  static StageResult cancel(std::string message = "cancelled");
};

struct StageContext {
  std::filesystem::path project;
  JobStage stage = JobStage::clouds;
  std::string parameters;
  const std::atomic_bool *cancel_token = nullptr;
  std::string job_id;

  bool is_cancelled() const noexcept;
};

StageResult run_stage(ProjectDB &db, const StageContext &ctx);

StageResult run_stage(const StageContext &ctx);

using StageExecutor = std::function<StageResult(const StageContext &)>;

StageExecutor default_stage_executor();
 
} // namespace reusex::pipeline