stage_parameters.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
 
// Machine-readable description of the parameters each runnable stage accepts
// (#305).
//
// `run_stage()` reads a job's `parameters` JSON object with `param_or(params,
// "<key>", <option-struct field>)`, so the *authority* on what a knob is called
// and what it defaults to has always been the library option struct. Until now
// that authority was unreadable from outside: a front end wanting to render a
// parameter form had no choice but to hard-code the keys and re-type the
// defaults, which is exactly the duplication STANDARDS §4 forbids.
//
// This table closes that hole. It is built by *default-constructing the option
// struct and reading its fields* — never by copying literals — so a default
// that moves in `segmentation/` moves here, and in every UI, without anyone
// remembering to. `tests/unit/pipeline/test_stage_parameters.cpp` asserts that
// correspondence field by field.
//
// Layering: this lives in `pipeline` (Layer 4) because that is where the
// option structs are already assembled from JSON; `core` could not reach
// `segmentation` to read the defaults.
 
#include <reusex/pipeline/stages.hpp>
 
#include <optional>
#include <string>
#include <string_view>
#include <variant>
#include <vector>
 
namespace reusex::pipeline {

enum class ParameterType {
  number,       
  integer,      
  boolean,      
  string,       
  integer_list, 
};

std::string_view to_string(ParameterType type);

using ParameterDefault =
    std::variant<std::monostate, double, long long, bool, std::string>;

struct ParameterDescriptor {
  std::string key;
  ParameterType type = ParameterType::number;
  std::string label;
  std::string description;
  ParameterDefault default_value;
  std::optional<double> minimum;
  std::optional<double> maximum;
  bool presence_sensitive = false;
};

const std::vector<ParameterDescriptor> &stage_parameters(JobStage stage);

inline constexpr std::string_view kDefaultSemanticCloud = "labels";
inline constexpr std::string_view kDefaultInstanceCloud = "instances";
 
} // namespace reusex::pipeline