init commit

data_acq_and_processing/preprocessing/reference_master/include/reference_master.hpp

@@ -0,0 +1,30 @@
+#pragma once
+
+#include <string>
+#include <unordered_map>
+#include <vector>
+
+#include "shared_types.hpp"
+
+namespace radar::preprocessing {
+
+class CalibrationMaster;
+
+class ReferenceMaster {
+  public:
+    // Loads a serialized raw sweep bundle with one reference trace per combo.
+    void load_bundle(const std::string& path);
+    // Builds calibrated references in memory using currently loaded raw references.
+    // Must be called after load_bundle() and after calibration standards are loaded.
+    void prepare_calibrated(const CalibrationMaster& calibration_master);
+    // Ensures all runtime combos are present in loaded references.
+    void validate_combos(const std::vector<ipc::ComboKey>& combos) const;
+    // Subtracts per-combo reference trace from calibrated trace.
+    [[nodiscard]] auto apply(const ipc::SweepTraceBlock& calibrated_trace) const -> ipc::SweepTraceBlock;
+
+  private:
+    std::unordered_map<ipc::ComboKey, ipc::SweepTraceBlock, ipc::ComboKeyHash> raw_references_by_combo_{};
+    std::unordered_map<ipc::ComboKey, ipc::SweepTraceBlock, ipc::ComboKeyHash> calibrated_references_by_combo_{};
+};
+
+}  // namespace radar::preprocessing

data_acq_and_processing/preprocessing/reference_master/src/reference_master.cpp

@@ -0,0 +1,141 @@
+#include "reference_master.hpp"
+
+#include <cstdint>
+#include <fstream>
+#include <iterator>
+#include <stdexcept>
+#include <string>
+#include <utility>
+#include <vector>
+
+#include <Eigen/Core>
+
+#include "calibration_master.hpp"
+
+namespace radar::preprocessing {
+namespace {
+
+[[nodiscard]] auto combo_to_string(const ipc::ComboKey& combo) -> std::string {
+    return "input=" + std::to_string(combo.input_pos) + " output=" + std::to_string(combo.output_pos);
+}
+
+[[nodiscard]] auto read_binary_file(const std::string& path, const std::string& bundle_label)
+    -> std::vector<std::uint8_t> {
+    std::ifstream stream(path, std::ios::binary);
+    if (!stream.is_open()) {
+        throw std::runtime_error("Failed to open " + bundle_label + " bundle: " + path);
+    }
+
+    return std::vector<std::uint8_t>(std::istreambuf_iterator<char>(stream), std::istreambuf_iterator<char>());
+}
+
+void validate_trace_layout(const ipc::SweepTraceBlock& trace, const std::string& trace_label) {
+    if (trace.frequency_hz.size() != trace.s21.size()) {
+        throw std::runtime_error(
+            trace_label + " frequency/complex vector size mismatch for combo " + combo_to_string(trace.combo)
+        );
+    }
+}
+
+}  // namespace
+
+void ReferenceMaster::load_bundle(const std::string& path) {
+    if (path.empty()) {
+        throw std::runtime_error("Reference bundle path must not be empty");
+    }
+
+    const auto bytes = read_binary_file(path, "reference");
+    if (bytes.empty()) {
+        throw std::runtime_error("Reference bundle is empty: " + path);
+    }
+
+    const auto collection = ipc::deserialize_raw_collection(bytes);
+    raw_references_by_combo_.clear();
+    raw_references_by_combo_.reserve(collection.traces.size());
+    calibrated_references_by_combo_.clear();
+    for (const auto& trace : collection.traces) {
+        validate_trace_layout(trace, "Reference trace");
+        raw_references_by_combo_.insert_or_assign(trace.combo, trace);
+    }
+
+    if (raw_references_by_combo_.empty()) {
+        throw std::runtime_error("Reference bundle does not contain traces: " + path);
+    }
+}
+
+void ReferenceMaster::prepare_calibrated(const CalibrationMaster& calibration_master) {
+    if (raw_references_by_combo_.empty()) {
+        throw std::runtime_error("Reference bundle must be loaded before prepare_calibrated()");
+    }
+
+    calibrated_references_by_combo_.clear();
+    calibrated_references_by_combo_.reserve(raw_references_by_combo_.size());
+    for (const auto& [combo, raw_reference] : raw_references_by_combo_) {
+        auto calibrated = calibration_master.apply(raw_reference);
+        calibrated.combo = combo;
+        calibrated_references_by_combo_.insert_or_assign(combo, std::move(calibrated));
+    }
+}
+
+void ReferenceMaster::validate_combos(const std::vector<ipc::ComboKey>& combos) const {
+    if (calibrated_references_by_combo_.empty()) {
+        throw std::runtime_error(
+            "Calibrated references are not prepared. Call ReferenceMaster::prepare_calibrated() at startup."
+        );
+    }
+
+    for (const auto& combo : combos) {
+        if (!raw_references_by_combo_.contains(combo)) {
+            throw std::runtime_error("Raw reference data is missing for combo " + combo_to_string(combo));
+        }
+        if (!calibrated_references_by_combo_.contains(combo)) {
+            throw std::runtime_error("Calibrated reference data is missing for combo " + combo_to_string(combo));
+        }
+    }
+}
+
+auto ReferenceMaster::apply(const ipc::SweepTraceBlock& calibrated_trace) const -> ipc::SweepTraceBlock {
+    validate_trace_layout(calibrated_trace, "Calibrated trace");
+
+    const auto found = calibrated_references_by_combo_.find(calibrated_trace.combo);
+    if (found == calibrated_references_by_combo_.end()) {
+        throw std::runtime_error(
+            "Calibrated reference trace is missing for combo " + combo_to_string(calibrated_trace.combo)
+        );
+    }
+
+    const auto& reference = found->second;
+    validate_trace_layout(reference, "Calibrated reference trace");
+    if (calibrated_trace.s21.size() != reference.s21.size()) {
+        throw std::runtime_error(
+            "Reference point count mismatch for combo " + combo_to_string(calibrated_trace.combo)
+        );
+    }
+
+    ipc::SweepTraceBlock output{};
+    output.combo = calibrated_trace.combo;
+    output.frequency_hz = calibrated_trace.frequency_hz;
+    output.s21.resize(calibrated_trace.s21.size());
+
+    static_assert(sizeof(ipc::Complex32) == sizeof(float) * 2U, "Complex32 layout must be two contiguous floats");
+    using InterleavedComplexView = Eigen::Matrix<float, Eigen::Dynamic, 2, Eigen::RowMajor>;
+    const auto point_count = static_cast<Eigen::Index>(calibrated_trace.s21.size());
+
+    Eigen::Map<const InterleavedComplexView> calibrated_view(
+        reinterpret_cast<const float*>(calibrated_trace.s21.data()),
+        point_count,
+        2
+    );
+    Eigen::Map<const InterleavedComplexView> reference_view(
+        reinterpret_cast<const float*>(reference.s21.data()),
+        point_count,
+        2
+    );
+    Eigen::Map<InterleavedComplexView> output_view(reinterpret_cast<float*>(output.s21.data()), point_count, 2);
+
+    output_view = calibrated_view - reference_view;
+
+    return output;
+}
+
+}  // namespace radar::preprocessing