ProjectDB.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2025 Povl Filip Sonne-Frederiksen
//
// SPDX-License-Identifier: GPL-3.0-or-later
 
#pragma once
// Point-cloud aliases (Cloud/CloudN/CloudL and pcl::PointCloud<pcl::PointXYZ>)
// are part of the public signatures below, so the point-type header stays.
// The heavier OpenCV and PCL mesh headers are only needed by the .cpp: they
// are forward-declared here (cv::Mat by value/reference, mesh types via
// std::shared_ptr) to keep DB clients from transitively compiling them.
#include "reusex/core/component_record.hpp"
#include "reusex/types/point_types.hpp"
 
#include <array>
#include <cstdint>
#include <filesystem>
#include <map>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
// Forward declarations for heavy third-party types used only by-value or via
// shared_ptr in the public API (definitions pulled in by ProjectDB.cpp).
namespace cv {
class Mat;
} // namespace cv
namespace pcl {
struct PolygonMesh;
struct TextureMesh;
} // namespace pcl
 
namespace reusex {
 
// Forward declarations
namespace core {
struct MaterialPassport;
struct MaterialPassportMetadata;
struct SensorIntrinsics;
} // namespace core
 
class ProjectDB {
    public:
  explicit ProjectDB(std::filesystem::path dbPath, bool readOnly = false);
  ~ProjectDB();
 
  // Non-copyable (RAII resource management)
  ProjectDB(const ProjectDB &) = delete;
  ProjectDB &operator=(const ProjectDB &) = delete;
 
  // Movable
  ProjectDB(ProjectDB &&) noexcept;
  ProjectDB &operator=(ProjectDB &&) noexcept;
 
  // --- Core Database Operations ---
 
  bool is_open() const noexcept;
  const std::filesystem::path &path() const noexcept;
  int schema_version() const;
  void validate_schema() const;
 
  // --- Sensor Frame Operations ---
 
  void save_sensor_frame(int nodeId, const cv::Mat &colorImage);
 
  void save_sensor_frame(int nodeId, const cv::Mat &color, const cv::Mat &depth,
                         const cv::Mat &confidence,
                         const std::array<double, 16> &worldPose,
                         const core::SensorIntrinsics &intrinsics,
                         double timestamp = -1.0);

  void update_sensor_frame_pose(int nodeId,
                                const std::array<double, 16> &worldPose);
 
  std::vector<int> sensor_frame_ids() const;
  cv::Mat sensor_frame_image(int nodeId) const;
  cv::Mat sensor_frame_depth(int nodeId) const;
  cv::Mat sensor_frame_confidence(int nodeId) const;
  std::array<double, 16> sensor_frame_pose(int nodeId) const;

  bool has_sensor_frame_pose(int nodeId) const;
 
  core::SensorIntrinsics sensor_frame_intrinsics(int nodeId) const;
  bool has_sensor_frame(int nodeId) const;

  double sensor_frame_timestamp(int nodeId) const;

  int nearest_sensor_frame_by_timestamp(double timestamp) const;
 
  // --- Panoramic Image Operations ---
 
  struct PanoramicImage {
    int id;
    std::string filename;
    double timestamp; // -1.0 if unknown
    int node_id;      // -1 if unmatched
    // Refined 6-DoF pose from content-based alignment (`rux align 360`). When
    // has_pose is false the panorama has only its timestamp-matched frame pose.
    bool has_pose = false;
    std::array<double, 16> pose = {1, 0, 0, 0, 0, 1, 0, 0,
                                   0, 0, 1, 0, 0, 0, 0, 1}; // row-major world
    std::string pose_source = "timestamp"; // "timestamp" | "aligned"
    int align_inliers = -1;                // RANSAC inliers, -1 if not aligned
    // Angular RMS of the inlier bearings after resection, in degrees
    // (PanoramaAlignmentResult::rms_deg). -1 if not aligned.
    double align_rms = -1.0;
  };
 
  void save_panoramic_image(const std::string &filename,
                            const std::vector<uint8_t> &jpeg_data,
                            double timestamp = -1.0, int nodeId = -1);
 
  cv::Mat panoramic_image(int id) const;
  cv::Mat panoramic_image(std::string_view filename) const;
  bool has_panoramic_image(std::string_view filename) const;
  void delete_panoramic_image(int id);
  void delete_panoramic_image(std::string_view filename);
  std::vector<PanoramicImage> list_panoramic_images() const;
  int panoramic_image_count() const;

  void save_panorama_pose(int id, const std::array<double, 16> &pose,
                          int inliers, double rms);
 
  // --- Panorama Segmentation Operations ---
 
  bool has_panorama_segmentation(int panoId) const;
  cv::Mat panorama_segmentation(int panoId) const;
  void save_panorama_segmentation(int panoId, const cv::Mat &labels);
 
  // --- Segmentation Image Operations ---
 
  bool has_segmentation_image(int nodeId) const;
  cv::Mat segmentation_image(int nodeId) const;
  std::vector<int> segmentation_image_ids() const;
  void save_segmentation_image(int nodeId, const cv::Mat &labels);
  void save_segmentation_images(const std::vector<int> &nodeIds,
                                const std::vector<cv::Mat> &labels);
 
  // --- Point Cloud Operations ---
 
  void save_point_cloud(std::string_view name, const Cloud &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name, const CloudN &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name, const CloudL &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  void save_point_cloud(std::string_view name,
                        const pcl::PointCloud<pcl::PointXYZ> &cloud,
                        std::string_view stage = "",
                        std::string_view paramsJson = "");
 
  CloudPtr point_cloud_xyzrgb(std::string_view name) const;
  CloudNPtr point_cloud_normal(std::string_view name) const;
  CloudLPtr point_cloud_label(std::string_view name) const;
  pcl::PointCloud<pcl::PointXYZ>::Ptr
  point_cloud_xyz(std::string_view name) const;
 
  bool has_point_cloud(std::string_view name) const;
  void delete_point_cloud(std::string_view name);
  std::vector<std::string> list_point_clouds() const;
  std::string point_cloud_type(std::string_view name) const;

  struct CloudPage {
    std::string point_type;
    uint32_t point_step = 0; 
    uint64_t offset = 0;     
    uint64_t count = 0;      
    uint64_t total = 0;      
    std::vector<uint8_t> data;
  };

  CloudPage point_cloud_page(std::string_view name, uint64_t offset,
                             uint64_t limit) const;
 
  // --- Label Definitions ---
 
  void save_label_definitions(std::string_view cloudName,
                              const std::map<int, std::string> &labelMap);
 
  std::map<int, std::string>
  label_definitions(std::string_view cloudName) const;
 
  // --- Instances (stable identity) ---

  struct InstanceRecord {
    uint32_t instance_id = 0; 
    std::string guid;         
    int semantic_class = -1;  
    int point_count = 0;      
  };

  void save_instances(const std::string &cloud_name,
                      const std::vector<InstanceRecord> &records);

  std::vector<InstanceRecord> instances(const std::string &cloud_name) const;

  std::string instance_guid(const std::string &cloud_name,
                            uint32_t instance_id) const;
 
  // --- Instance ↔ Material Links ---

  void set_instance_material(std::string_view cloudName, int instanceId,
                             std::string_view materialGuid);

  std::optional<std::string> instance_material_guid(std::string_view cloudName,
                                                    int instanceId) const;

  std::map<int, std::string>
  instance_materials(std::string_view cloudName) const;
 
  // --- Mesh Operations ---
 
  void save_mesh(std::string_view name, const pcl::PolygonMesh &mesh,
                 std::string_view stage = "", std::string_view paramsJson = "");
 
  void save_mesh(std::string_view name, const pcl::TextureMesh &mesh,
                 std::string_view stage = "", std::string_view paramsJson = "");
 
  std::shared_ptr<pcl::PolygonMesh> mesh(std::string_view name) const;
  std::shared_ptr<pcl::TextureMesh> texture_mesh(std::string_view name) const;
  bool has_mesh(std::string_view name) const;
  std::vector<std::string> list_meshes() const;
  std::string mesh_format(std::string_view name) const;
 
  struct MeshMetadata {
    std::string name, format, stage, parameters, created_at;
    int vertex_count = 0, face_count = 0;
  };
  MeshMetadata mesh_metadata(std::string_view name) const;
 
  std::vector<uint8_t> mesh_data_blob(std::string_view name) const;
 
  struct MeshTextureInfo {
    std::string tex_name, format;
    std::vector<uint8_t> image_data;
    int width, height;
  };
  std::vector<MeshTextureInfo> mesh_texture_blobs(std::string_view name) const;
 
  struct MeshTextureMetadata {
    std::string tex_name, format;
    int width, height;
  };
  std::vector<MeshTextureMetadata>
  mesh_texture_metadata(std::string_view name) const;
 
  // --- Gaussian Splat Operations ---
  //
  // A trained splat is stored verbatim, as the INRIA `.ply` bytes, chunked
  // across `gaussian_splat_data` rows the same way point clouds are: a splat
  // is routinely hundreds of MB and SQLite materializes a whole blob column
  // on read, so a single-row layout would cost peak memory proportional to
  // the entire file even to answer "how many Gaussians".
  //
  // The bytes are opaque to core — nothing here inflates a splat into a
  // geometry type. What core *does* own is the guarantee that the bytes are a
  // splat at all: `save_gaussian_splat()` parses the PLY header
  // (core/gaussian_splat.hpp) and refuses anything else, so the point-cloud
  // PLY that `rux export ply` writes is rejected at the door instead of
  // reaching a renderer that would draw nothing and say nothing.

  struct GaussianSplatMetadata {
    std::string name;
    std::string format; 
    std::uint64_t gaussian_count = 0;
    int sh_degree = 0;           
    std::uint64_t byte_size = 0; 
    std::string created_at;
    std::string stage;      
    std::string parameters; 
  };

  void save_gaussian_splat(std::string_view name,
                           const std::vector<uint8_t> &ply,
                           std::string_view stage = "",
                           std::string_view parameters = "");

  bool has_gaussian_splat(std::string_view name) const;

  std::vector<std::string> list_gaussian_splats() const;

  GaussianSplatMetadata gaussian_splat_metadata(std::string_view name) const;

  std::vector<uint8_t> gaussian_splat_blob(std::string_view name) const;

  bool delete_gaussian_splat(std::string_view name);
 
  // --- Building Component Operations ---
  //
  // Persistence speaks only core::ComponentRecord (see
  // reusex/core/component_record.hpp), so core stays free of geometry types
  // (#227). To store/load a geometry::BuildingComponent, use the mapping and
  // convenience free functions in reusex/geometry/component_persistence.hpp.

  void save_component_record(const core::ComponentRecord &record);
  void update_component_record_by_guid(const core::ComponentRecord &record);
  core::ComponentRecord component_record(std::string_view name) const;
  bool has_building_component(std::string_view name) const;
  void delete_building_component(std::string_view name);
  std::vector<std::string> list_building_components() const;
  std::vector<std::string>
  list_building_components(std::string_view type) const;
  int building_component_count() const;
 
  // --- Pipeline Log ---
 
  int log_pipeline_start(std::string_view stage,
                         std::string_view paramsJson = "");
 
  void log_pipeline_end(int logId, bool success,
                        std::string_view errorMsg = "");
 
  struct PipelineLogEntry {
    int id;
    std::string stage;
    std::string started_at;
    std::string finished_at; // Empty if still running
    std::string parameters;  // JSON string
    std::string status;      // "running", "success", "failed"
    std::string error_msg;   // Empty if no error
  };
 
  std::vector<PipelineLogEntry> pipeline_log(int limit = 0) const;
 
  // --- Project Summary ---
 
  struct ProjectSummary {
    struct CloudInfo {
      std::string name;
      std::string type; // "PointXYZRGB", "Normal", "Label", "PointXYZ"
      size_t point_count;
      size_t width;
      size_t height;
      bool organized;                    // height > 1
      std::map<int, std::string> labels; // Only for Label clouds
    };
 
    struct MeshInfo {
      std::string name;
      int vertex_count;
      int face_count;
    };
 
    struct SensorFrameInfo {
      int total_count;
      int width;           // 0 if no frames
      int height;          // 0 if no frames
      int segmented_count; // frames with segmentation
    };
 
    struct PanoramicInfo {
      int total_count = 0;
      int matched_count = 0; // images linked to a sensor frame
    };
 
    struct ComponentInfo {
      int total_count = 0;
      std::map<std::string, int> count_by_type;
    };
 
    struct MaterialInfo {
      std::string id;
      std::string guid;
      int property_count = 0;
      std::string created_at;     // ISO 8601 timestamp
      std::string version_number; // Semver (e.g., "0.1.1")
    };
 
    struct ProjectInfo {
      std::string id;
      std::string name;
      std::string building_address;
      int year_of_construction = 0; // 0 = not set
      std::string survey_date;
      std::string survey_organisation;
      std::string notes;
    };
 
    std::filesystem::path path;
    int schema_version;
    std::vector<ProjectInfo> projects;
    std::vector<CloudInfo> clouds;
    std::vector<MeshInfo> meshes;
    std::vector<GaussianSplatMetadata> gaussian_splats;
    SensorFrameInfo sensor_frames;
    PanoramicInfo panoramic_images;
    ComponentInfo components;
    std::vector<MaterialInfo> materials;
  };
 
  ProjectSummary project_summary() const;
 
  // --- Material Passport Operations ---
 
  core::MaterialPassport material_passport(std::string_view documentGuid) const;
  std::vector<core::MaterialPassport> all_material_passports() const;
 
  void add_material_passport(const core::MaterialPassport &passport,
                             std::string_view projectId);

  void add_material_passport(const core::MaterialPassport &passport,
                             std::string_view projectId, std::string_view id);

  void delete_material_passport(std::string_view documentGuid);

  std::vector<std::string> list_passport_guids() const;

  std::map<std::string, std::string>
  passport_stored_properties(std::string_view documentGuid) const;

  std::string passport_property_value(std::string_view documentGuid,
                                      std::string_view fieldName) const;

  std::optional<int>
  passport_linked_node_id(std::string_view documentGuid) const;

  core::MaterialPassportMetadata
  passport_metadata(std::string_view documentGuid) const;

  void set_passport_metadata_field(std::string_view documentGuid,
                                   std::string_view column,
                                   std::string_view value);

  void set_passport_property(std::string_view documentGuid,
                             std::string_view fieldName,
                             std::string_view value);

  void delete_passport_property(std::string_view documentGuid,
                                std::string_view fieldName);
 
  // --- Project Metadata Operations ---
 
  struct ProjectMetadata {
    std::string id;
    std::string name;
    std::string building_address;
    int year_of_construction = 0; // 0 = not set
    std::string survey_date;
    std::string survey_organisation;
    std::string notes;
  };

  ProjectMetadata get_project_metadata(std::string_view projectId) const;

  void update_project_metadata(const ProjectMetadata &metadata);

  std::vector<std::string> list_project_ids() const;
 
    private:
  class Impl;
  std::unique_ptr<Impl> impl_;
};
} // namespace reusex