#include <ProjectDB.hpp>

Classes
struct	OpenOptions
	How a connection is opened. More...
struct	IntegrityReport
	Result of check_integrity(). More...
struct	ProbeResult
	What probe() found, without opening a full ProjectDB. More...
class	Transaction
	One write transaction (BEGIN IMMEDIATE ... COMMIT), rolled back unless commit() is called. More...
struct	PanoramicImage
struct	CloudPage
	A contiguous window of one cloud's stored records, still in storage layout — no PCL type has been inflated. More...
struct	InstanceRecord
	One row of the instances table: a spatially-distinct object within an instance-label cloud, carrying a stable GUID that survives regeneration. More...
struct	MaterialAnnotation
	A free-text description plus an arbitrary, prompt-driven set of key/value attributes for one material passport, as extracted by a vision-language model (rux create attributes, #373). More...
struct	MeshMetadata
struct	MeshTextureInfo
struct	MeshTextureMetadata
struct	GaussianSplatMetadata
	One row of the gaussian_splats table, minus the payload. More...
struct	PoseGraphEdge
	One directed edge stored in pose_graph_edges. More...
struct	ScanRecord
	One row of the scans table. More...
struct	PipelineLogEntry
struct	TableInfo
	One user table and its row count. sqlite_* internals are excluded. More...
struct	TableColumn
	One column of a table, as PRAGMA table_info reports it. More...
struct	TableCell
	One cell of table_rows(). More...
struct	ProjectSummary
struct	PropertyDefinition
	A user-defined column in the Notion-like material editor. More...
struct	ReportPdfRecord
	Metadata for one stored report PDF version. More...
struct	ResourceTemplateRecord
	One row of templates (resources/templates spec §5.1). More...
struct	ResourceTemplatePatch
struct	SurveyTypeRecord
struct	SurveyTypePatch
	Sparse update; an engaged optional sets the field. More...
struct	SurveyPartRecord
struct	SurveyPartPatch
struct	SampleRecord
struct	SamplePatch
struct	ProjectMetadata

Public Types
enum class	PipelineOutcome { success , failed , cancelled }
	How a pipeline stage run ended. More...

Public Member Functions
	ProjectDB (std::filesystem::path dbPath, bool readOnly=false)
	Opens a ReUseX project database and validates its schema.
	ProjectDB (std::filesystem::path dbPath, OpenOptions options)
bool	is_read_only () const noexcept
	~ProjectDB ()
	Destructor closes database connection.
	ProjectDB (const ProjectDB &)=delete
ProjectDB &	operator= (const ProjectDB &)=delete
	ProjectDB (ProjectDB &&) noexcept
ProjectDB &	operator= (ProjectDB &&) noexcept
bool	is_open () const noexcept
const std::filesystem::path &	path () const noexcept
int	schema_version () const
void	validate_schema () const
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, int scan_id=-1)
void	update_sensor_frame_pose (int nodeId, const std::array< double, 16 > &worldPose)
	Update only the stored world pose (transform) of an existing sensor frame.
std::vector< int >	sensor_frame_ids () const
std::vector< std::pair< int, int > >	sensor_frame_ids_with_scan () const
	Returns {node_id, scan_id} pairs ordered by node_id.
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
	The stored world pose, verbatim — row-major 4x4, identity when the row is missing, the transform is NULL, or the blob is the wrong size.
bool	has_sensor_frame_pose (int nodeId) const
	True when this frame carries a usable stored world pose.
core::SensorIntrinsics	sensor_frame_intrinsics (int nodeId) const
bool	has_sensor_frame (int nodeId) const
double	sensor_frame_timestamp (int nodeId) const
	Get the timestamp (epoch seconds) of a sensor frame.
int	nearest_sensor_frame_by_timestamp (double timestamp) const
	Find the sensor frame with the closest timestamp to the given value.
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)
	Store a content-aligned pose (row-major 4x4 world) for a panorama.
bool	has_panorama_segmentation (int panoId) const
cv::Mat	panorama_segmentation (int panoId) const
void	save_panorama_segmentation (int panoId, const cv::Mat &labels)
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)
bool	has_glass_confidence_image (int nodeId) const
cv::Mat	glass_confidence_image (int nodeId) const
std::vector< int >	glass_confidence_image_ids () const
void	save_glass_confidence_image (int nodeId, const cv::Mat &confidence)
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
std::string	point_cloud_storage_order (std::string_view name) const
	Returns the "storage_order" value from the cloud's parameters JSON, or an empty string when the key is absent or the JSON is unparseable.
std::pair< std::string, std::string >	point_cloud_provenance (std::string_view name) const
	The stage and parameters (JSON, may be empty) the cloud was last saved with — so an in-place edit can save it again without erasing how it was produced.
void	save_tile_index (std::string_view name, const std::vector< uint8_t > &blob)
	Save a serialized tile index blob for the named cloud.
std::vector< uint8_t >	tile_index (std::string_view name) const
	Load the tile index blob, or empty if not set.
CloudPage	point_cloud_page (std::string_view name, uint64_t offset, uint64_t limit) const
	Read one page of a point cloud without materializing the cloud.
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
void	save_instances (const std::string &cloud_name, const std::vector< InstanceRecord > &records)
	Replace the full set of instance rows for a cloud (transactional).
std::vector< InstanceRecord >	instances (const std::string &cloud_name) const
	All instance rows for a cloud, ordered by instance_id.
void	add_instance (const std::string &cloud_name, const InstanceRecord &record)
	Insert one instance row, leaving the cloud's other rows (and their instance_materials links, which a save_instances() delete cascades away) untouched.
void	set_instance_point_count (const std::string &cloud_name, uint32_t instance_id, int point_count)
	Update one instance row's point_count in place (no delete/re-insert).
std::string	instance_guid (const std::string &cloud_name, uint32_t instance_id) const
	Stable GUID of a single instance.
void	set_instance_material (std::string_view cloudName, int instanceId, std::string_view materialGuid)
	Link an instance (a row in the instances table) to a material passport by its document guid.
std::optional< std::string >	instance_material_guid (std::string_view cloudName, int instanceId) const
	Material passport guid linked to an instance, or nullopt if unlinked.
std::map< int, std::string >	instance_materials (std::string_view cloudName) const
	All instance_id → material_guid links for a cloud.
void	save_material_annotation (std::string_view materialGuid, const MaterialAnnotation &annotation)
	Upsert the VLM annotation for one material passport (keyed on its document GUID).
std::optional< MaterialAnnotation >	material_annotation (std::string_view materialGuid) const
	The stored annotation for one material passport, or nullopt when none was saved.
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
MeshMetadata	mesh_metadata (std::string_view name) const
std::vector< uint8_t >	mesh_data_blob (std::string_view name) const
std::vector< MeshTextureInfo >	mesh_texture_blobs (std::string_view name) const
std::vector< MeshTextureMetadata >	mesh_texture_metadata (std::string_view name) const
void	save_gaussian_splat (std::string_view name, const std::vector< uint8_t > &ply, std::string_view stage="", std::string_view parameters="")
	Store an INRIA-format 3DGS .ply under `name`, replacing any splat already stored under it (chunks of the previous payload are dropped, so a re-save never leaves orphaned rows behind).
bool	has_gaussian_splat (std::string_view name) const
	False — not an error — on a project whose schema predates the splat tables, which is what a read-only open of an old project looks like (read-only opens never migrate).
std::vector< std::string >	list_gaussian_splats () const
	Empty on a pre-v12 schema, for the same reason as has_gaussian_splat().
GaussianSplatMetadata	gaussian_splat_metadata (std::string_view name) const
std::vector< uint8_t >	gaussian_splat_blob (std::string_view name) const
	The stored bytes, reassembled from their chunks — byte-for-byte what save_gaussian_splat() was given.
bool	delete_gaussian_splat (std::string_view name)
	Deleting the metadata row cascades to its data chunks.
void	save_pose_graph_edges (const std::vector< PoseGraphEdge > &edges)
	Replace the stored pose graph atomically (delete-then-insert inside one transaction).
std::vector< PoseGraphEdge >	list_pose_graph_edges () const
	All stored edges, in insertion order.
bool	has_pose_graph () const
	True when the pose graph table exists and has at least one edge.
int	add_pose_graph_edge (const PoseGraphEdge &edge)
	Insert a single edge and return its row id.
int	delete_pose_graph_edges (int from_node_id, int to_node_id, std::string_view edge_type="")
	Delete edges matching `from_node_id` and `to_node_id`.
ScanRecord	create_scan (const std::string &source_path, const std::string &provenance_json="{}")
	Creates a new scan record.
std::vector< ScanRecord >	scans () const
	Returns all scan records ordered by id.
void	save_component_record (const core::ComponentRecord &record)
	Insert or replace the component row identified by record.name.
void	update_component_record_by_guid (const core::ComponentRecord &record)
	Update an existing component's mutable fields (name, type, parent_id, confidence, metadata, notes), matched by its immutable guid.
core::ComponentRecord	component_record (std::string_view name) const
	Load the component row with the given name. Throws if absent.
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
	Names of the components whose stored type discriminator equals type.
int	building_component_count () const
int	log_pipeline_start (std::string_view stage, std::string_view paramsJson="")
void	log_pipeline_end (int logId, PipelineOutcome outcome, std::string_view errorMsg="")
void	log_pipeline_end (int logId, bool success, std::string_view errorMsg="")
	Shim for the two-outcome form: success maps to PipelineOutcome:: success, !success to PipelineOutcome::failed.
std::vector< PipelineLogEntry >	pipeline_log (int limit=0) const
std::vector< TableInfo >	list_tables () const
	Every user table, sorted by name, with its row count.
std::int64_t	table_row_count (std::string_view table) const
	Rows in `table` now (COUNT(*)).
std::vector< TableColumn >	table_columns (std::string_view table) const
	The columns of `table`, in declaration order.
std::vector< std::vector< TableCell > >	table_rows (std::string_view table, std::int64_t offset, std::int64_t limit, std::size_t text_limit=256) const
	Rows [`offset`, `offset` + `limit`) of `table` in rowid order (or primary-key order for a WITHOUT ROWID table), one TableCell per column of table_columns().
ProjectSummary	project_summary () const
std::vector< PropertyDefinition >	list_property_definitions () const
	List all user-defined material column definitions.
std::string	add_property_definition (const std::string &name, const std::string &type, const std::vector< std::string > &options, int sort_order, int width=200)
	Add a new material column definition.
void	update_property_definition (const std::string &id, const std::string &name, const std::string &type, const std::vector< std::string > &options, int sort_order, int width)
	Overwrite an existing material column definition.
void	delete_property_definition (const std::string &id)
	Delete a material column definition by id.
std::optional< std::pair< std::vector< std::uint8_t >, std::string > >	material_thumbnail (const std::string &guid) const
	Fetch a material's thumbnail blob and its MIME type.
void	set_material_thumbnail (const std::string &guid, const std::vector< std::uint8_t > &blob, const std::string &mime_type)
	Insert or replace a material's thumbnail blob.
void	delete_material_thumbnail (const std::string &guid)
	Delete a material's thumbnail if present (no-op when absent).
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)
	Add a material passport with a custom row ID.
void	delete_material_passport (std::string_view documentGuid)
	Delete a material passport by GUID.
std::vector< std::string >	list_passport_guids () const
	List document GUIDs ordered by created_at.
std::map< std::string, std::string >	passport_stored_properties (std::string_view documentGuid) const
	Get stored property field_name→string pairs for a passport.
std::string	passport_property_value (std::string_view documentGuid, std::string_view fieldName) const
	Get a single passport property value by field name.
std::optional< int >	passport_linked_node_id (std::string_view documentGuid) const
	Return the sensor frame node_id this passport was linked to.
core::MaterialPassportMetadata	passport_metadata (std::string_view documentGuid) const
	Get passport metadata without loading all properties.
void	set_passport_metadata_field (std::string_view documentGuid, std::string_view column, std::string_view value)
	Set a metadata column on a material passport.
void	set_passport_property (std::string_view documentGuid, std::string_view fieldName, std::string_view value)
	Set a single property value by field name (upsert).
void	delete_passport_property (std::string_view documentGuid, std::string_view fieldName)
	Delete a single property value by field name.
ReportPdfRecord	add_report_pdf (const std::vector< std::uint8_t > &pdf, const std::string &label="", std::optional< int > blocking_types=std::nullopt)
	Store a PDF blob and return its record (id, created_at, size).
std::vector< ReportPdfRecord >	list_report_pdfs () const
	List all stored report PDFs, newest first.
std::optional< std::vector< std::uint8_t > >	report_pdf (int64_t id) const
	Fetch one stored PDF blob by id.
std::vector< ResourceTemplateRecord >	resource_templates () const
	By id. Empty on a read-only open of a pre-v25 project.
std::optional< ResourceTemplateRecord >	resource_template (int64_t id) const
ResourceTemplateRecord	add_resource_template (const ResourceTemplateRecord &rec)
	id/timestamps are ignored.
ResourceTemplateRecord	update_resource_template (int64_t id, const ResourceTemplatePatch &patch)
bool	delete_resource_template (int64_t id)
SurveyTypeRecord	add_survey_type (const SurveyTypeRecord &rec)
std::vector< SurveyTypeRecord >	survey_types () const
std::optional< SurveyTypeRecord >	survey_type (int64_t id) const
SurveyTypeRecord	update_survey_type (int64_t id, const SurveyTypePatch &patch)
void	add_survey_part (const SurveyPartRecord &rec)
std::vector< SurveyPartRecord >	survey_parts () const
std::optional< SurveyPartRecord >	survey_part (std::string_view code) const
SurveyPartRecord	update_survey_part (std::string_view code, const SurveyPartPatch &patch)
void	set_survey_part_quantities (const std::vector< std::pair< std::string, double > > &code_quantities)
	Set several parts' quantities in one transaction — all or nothing.
bool	has_survey_part_for (std::string_view cloud_name, std::uint32_t instance_id) const
int	max_survey_part_number () const
std::string	ensure_resource_passport (std::string_view code)
	Resource storage (schema v25).
void	delete_survey_part (std::string_view code)
void	delete_survey_type (int64_t id)
	Deletes a survey type; its parts and sample links cascade.
void	dismiss_instance (std::string_view instance_guid)
	Tombstones (schema v26, survey_dismissed_instances): instance guids whose survey part the user deleted, so sync_survey does not re-create it.
bool	is_instance_dismissed (std::string_view instance_guid) const
	False on a read-only open of a pre-v26 project (no table).
std::vector< std::string >	dismissed_instances () const
	Every dismissed instance guid, ascending. Empty before v26.
bool	unlink_instance_material (std::string_view cloud_name, int instance_id)
	Removes the instance_materials link of (`cloud_name`, `instance_id`).
void	rename_passport_field (std::string_view old_name, std::string_view new_name)
	Call inside a Transaction.
bool	has_passport_field_values (std::string_view name) const
	True when any passport stores a value under the field name `name` (a leksikon name_en or a user column's display name) — including values a deleted user column left behind.
std::size_t	delete_passport_field_values (std::string_view name)
	Call inside a Transaction.
bool	is_passport_linked (std::string_view guid) const
	True when a survey part or an instance link still references `guid`.
SampleRecord	add_sample (std::string_view title, std::string_view what, const std::vector< int64_t > &type_ids={}, core::SampleStage stage=core::SampleStage::planlagt)
	Register a sample, its type links and its initial stage in one transaction (duplicate type ids collapse).
std::vector< SampleRecord >	samples () const
std::optional< SampleRecord >	sample (int64_t id) const
SampleRecord	update_sample (int64_t id, const SamplePatch &patch)
bool	delete_sample (int64_t id)
void	set_sample_links (int64_t id, const std::vector< int64_t > &type_ids)
std::vector< SampleRecord >	samples_for_type (int64_t type_id) const
ProjectMetadata	get_project_metadata (std::string_view projectId) const
	Get project metadata by project ID.
void	update_project_metadata (const ProjectMetadata &metadata)
	Update project metadata.
std::vector< std::string >	list_project_ids () const
	List all project IDs in the database.

Static Public Member Functions
static void	set_hardened_by_default (bool on) noexcept
	Process-wide default for OpenOptions::hardened, used by the (path, readOnly) constructor — and so by every open in this process that does not pass options, pipeline stages included.
static bool	hardened_by_default () noexcept
static IntegrityReport	check_integrity (const std::filesystem::path &file)
	Checks a file before a server adopts it, on a hardened read-only connection that runs no migration: PRAGMA quick_check, then that the schema holds no trigger and no view.
static int	latest_schema_version () noexcept
static ProbeResult	probe (const std::filesystem::path &path) noexcept
	Is `path` a ReUseX project, and at which schema?

Detailed Description

Definition at line 45 of file ProjectDB.hpp.

Member Enumeration Documentation

◆ PipelineOutcome

enum class reusex::ProjectDB::PipelineOutcome

strong

How a pipeline stage run ended.

cancelled is distinct from failed so a user-requested cancel is never shown as an error.

Enumerator
success
failed
cancelled

Definition at line 695 of file ProjectDB.hpp.

Constructor & Destructor Documentation

◆ ProjectDB() [1/4]

reusex::ProjectDB::ProjectDB	(	std::filesystem::path	dbPath,
		bool	readOnly = false )

explicit

Opens a ReUseX project database and validates its schema.

Creates the following tables if they don't exist (write mode only):

projects: Project metadata (building info, survey details)
property_definitions: Leksikon-based property definitions
material_passports: Material passport documents
passport_property_values: Property values for each passport
passport_log: Audit log for tracking changes
schema_version: Schema version tracking
point_clouds / point_cloud_data: Point cloud storage
label_definitions: Semantic label lookup
meshes: Mesh storage
gaussian_splats / gaussian_splat_data: Gaussian splat storage
sensor_frames: Imported sensor frame color images
segmentation_images: Per-frame semantic label images
pipeline_log: Pipeline provenance log

Parameters

dbPath Path to the database file

readOnly If true, opens database in read-only mode. In a directory the user cannot write (a read-only mount), and with no live -wal beside the file, the open is sqlite-immutable: a WAL-mode file is unreadable there otherwise (sqlite must create -shm even to read), and nobody can be writing it through that directory. Elsewhere a read-only open is a plain one and, like any WAL reader, may create the -shm / -wal sidecars. Trade-off: "nobody can be writing" holds for THIS user only. On a shared drive where a colleague has write access, an immutable connection never sees their WAL and takes no locks, so it can read stale data or a page mid-checkpoint (SQLITE_CORRUPT). Reopen to see their changes. A non-empty -wal in such a directory (an unfinished write) cannot be read at all and fails to open.

Exceptions

std::runtime_error if database cannot be opened or schema is invalid

Referenced by operator=(), operator=(), reusex::ProjectDB::Transaction::operator=(), ProjectDB(), ProjectDB(), reusex::ProjectDB::Transaction::Transaction(), and ~ProjectDB().

◆ ProjectDB() [2/4]

reusex::ProjectDB::ProjectDB	(	std::filesystem::path	dbPath,
		OpenOptions	options )

◆ ~ProjectDB()

reusex::ProjectDB::~ProjectDB ( )

Destructor closes database connection.

References ProjectDB().

◆ ProjectDB() [3/4]

reusex::ProjectDB::ProjectDB ( const ProjectDB & )

delete

References ProjectDB().

◆ ProjectDB() [4/4]

reusex::ProjectDB::ProjectDB ( ProjectDB && )

noexcept

References ProjectDB().

Member Function Documentation

◆ add_instance()

void reusex::ProjectDB::add_instance	(	const std::string &	cloud_name,
		const InstanceRecord &	record )

Insert one instance row, leaving the cloud's other rows (and their instance_materials links, which a save_instances() delete cascades away) untouched.

Nests inside a Transaction. Throws on an empty or already-used guid, or an instance_id the cloud already has.

◆ add_material_passport() [1/2]

void reusex::ProjectDB::add_material_passport	(	const core::MaterialPassport &	passport,
		std::string_view	projectId )

◆ add_material_passport() [2/2]

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

Add a material passport with a custom row ID.

The id parameter overrides the material_passports.id column value (normally set to document_guid). Use this to link a passport to a sensor frame by setting id to the frame's node_id.

Parameters

passport	Material passport data
projectId	Project identifier (may be empty)
id	Custom row ID for the material_passports.id column

◆ add_pose_graph_edge()

int reusex::ProjectDB::add_pose_graph_edge ( const PoseGraphEdge & edge )

Insert a single edge and return its row id.

Used by the GUI editor to add manual loop-closure edges without disturbing the rest of the graph. Unlike save_pose_graph_edges(), this does not replace the whole table — it appends exactly one row.

◆ add_property_definition()

std::string reusex::ProjectDB::add_property_definition	(	const std::string &	name,
		const std::string &	type,
		const std::vector< std::string > &	options,
		int	sort_order,
		int	width = 200 )

Add a new material column definition.

Parameters

name	Column display name
type	One of text/number/date/boolean/select
options	Choices, only meaningful for the "select" type
sort_order	Display order

Returns: The freshly minted definition id (GUID)

◆ add_report_pdf()

ReportPdfRecord reusex::ProjectDB::add_report_pdf	(	const std::vector< std::uint8_t > &	pdf,
		const std::string &	label = "",
		std::optional< int >	blocking_types = std::nullopt )

Store a PDF blob and return its record (id, created_at, size).

Parameters

pdf	Raw PDF bytes
label	Optional human-readable label stored alongside the blob
blocking_types	Survey types that still blocked the report (schema v23); nullopt stores NULL

Returns: The new record (does not include the blob payload)

◆ add_resource_template()

ResourceTemplateRecord reusex::ProjectDB::add_resource_template ( const ResourceTemplateRecord & rec )

id/timestamps are ignored.

Exceptions

core::NameConflictError

◆ add_sample()

SampleRecord reusex::ProjectDB::add_sample	(	std::string_view	title,
		std::string_view	what,
		const std::vector< int64_t > &	type_ids = {},
		core::SampleStage	stage = core::SampleStage::planlagt )

Register a sample, its type links and its initial stage in one transaction (duplicate type ids collapse).

Exceptions

std::out_of_range	when a type_ids entry names no survey type.
std::invalid_argument	when stage is not planlagt/udtaget. Nothing is written (and no P-## code consumed) when it throws.

◆ add_survey_part()

void reusex::ProjectDB::add_survey_part ( const SurveyPartRecord & rec )

◆ add_survey_type()

SurveyTypeRecord reusex::ProjectDB::add_survey_type ( const SurveyTypeRecord & rec )

◆ all_material_passports()

std::vector< core::MaterialPassport > reusex::ProjectDB::all_material_passports ( ) const

◆ building_component_count()

int reusex::ProjectDB::building_component_count ( ) const

◆ check_integrity()

IntegrityReport reusex::ProjectDB::check_integrity ( const std::filesystem::path & file )

static

Checks a file before a server adopts it, on a hardened read-only connection that runs no migration: PRAGMA quick_check, then that the schema holds no trigger and no view.

Takes time linear in the file size (minutes for tens of GB). Never throws for a bad file.

◆ component_record()

core::ComponentRecord reusex::ProjectDB::component_record ( std::string_view name ) const

Load the component row with the given name. Throws if absent.

Referenced by reusex::geometry::building_component().

◆ create_scan()

ScanRecord reusex::ProjectDB::create_scan	(	const std::string &	source_path,
		const std::string &	provenance_json = "{}" )

Creates a new scan record.

Computes id_offset = MAX(node_id) from sensor_frames at call time (0 if empty). Warns if source_path already appears in the scans table (duplicate import guard).

◆ delete_building_component()

void reusex::ProjectDB::delete_building_component ( std::string_view name )

◆ delete_gaussian_splat()

bool reusex::ProjectDB::delete_gaussian_splat ( std::string_view name )

Deleting the metadata row cascades to its data chunks.

Returns: false when there was nothing to delete.

◆ delete_material_passport()

void reusex::ProjectDB::delete_material_passport ( std::string_view documentGuid )

Delete a material passport by GUID.

Parameters

documentGuid Document GUID to delete

Exceptions

std::runtime_error if passport does not exist

◆ delete_material_thumbnail()

void reusex::ProjectDB::delete_material_thumbnail ( const std::string & guid )

Delete a material's thumbnail if present (no-op when absent).

◆ delete_panoramic_image() [1/2]

void reusex::ProjectDB::delete_panoramic_image ( int id )

◆ delete_panoramic_image() [2/2]

void reusex::ProjectDB::delete_panoramic_image ( std::string_view filename )

◆ delete_passport_field_values()

std::size_t reusex::ProjectDB::delete_passport_field_values ( std::string_view name )

Call inside a Transaction.

Deletes every value stored under the user column field name name, and its "custom:" definition, so the name is free again. Leksikon fields are never touched. Returns the number of values deleted.

◆ delete_passport_property()

void reusex::ProjectDB::delete_passport_property	(	std::string_view	documentGuid,
		std::string_view	fieldName )

Delete a single property value by field name.

Parameters

documentGuid	Document GUID
fieldName	Property field name (name_en)

Exceptions

std::runtime_error if passport or property not found

◆ delete_point_cloud()

void reusex::ProjectDB::delete_point_cloud ( std::string_view name )

◆ delete_pose_graph_edges()

int reusex::ProjectDB::delete_pose_graph_edges	(	int	from_node_id,
		int	to_node_id,
		std::string_view	edge_type = "" )

Delete edges matching from_node_id and to_node_id.

When edge_type is non-empty, only edges of that type are removed so the caller can target a single loop-closure without touching an odometry edge that happens to share the same endpoint pair.

Returns: the number of rows deleted (0 when nothing matched).

◆ delete_property_definition()

void reusex::ProjectDB::delete_property_definition ( const std::string & id )

Delete a material column definition by id.

Exceptions

std::runtime_error if the id does not exist

◆ delete_resource_template()

bool reusex::ProjectDB::delete_resource_template ( int64_t id )

◆ delete_sample()

bool reusex::ProjectDB::delete_sample ( int64_t id )

◆ delete_survey_part()

void reusex::ProjectDB::delete_survey_part ( std::string_view code )

Exceptions

std::out_of_range when code is unknown.

◆ delete_survey_type()

void reusex::ProjectDB::delete_survey_type ( int64_t id )

Deletes a survey type; its parts and sample links cascade.

Storage only: tombstones and passports are core::delete_survey_type's job.

Exceptions

std::out_of_range when id is unknown.

◆ dismiss_instance()

void reusex::ProjectDB::dismiss_instance ( std::string_view instance_guid )

Tombstones (schema v26, survey_dismissed_instances): instance guids whose survey part the user deleted, so sync_survey does not re-create it.

Idempotent — dismissing a guid twice keeps the first timestamp.

References instance_guid().

◆ dismissed_instances()

std::vector< std::string > reusex::ProjectDB::dismissed_instances ( ) const

nodiscard

Every dismissed instance guid, ascending. Empty before v26.

◆ ensure_resource_passport()

std::string reusex::ProjectDB::ensure_resource_passport ( std::string_view code )

Resource storage (schema v25).

Call inside a Transaction. Returns the part's passport guid; on first use creates a bare passport (or adopts the instance's linked passport when no other part owns it), sets survey_parts.passport_guid, upserts instance_materials for an instance-backed part, and makes sure the leksikon property_definitions exist.

Exceptions

std::out_of_range when code is unknown.

◆ gaussian_splat_blob()

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

The stored bytes, reassembled from their chunks — byte-for-byte what save_gaussian_splat() was given.

Exceptions

std::runtime_error when there is no splat named name.

◆ gaussian_splat_metadata()

GaussianSplatMetadata reusex::ProjectDB::gaussian_splat_metadata ( std::string_view name ) const

Exceptions

std::runtime_error when there is no splat named name.

◆ get_project_metadata()

ProjectMetadata reusex::ProjectDB::get_project_metadata ( std::string_view projectId ) const

Get project metadata by project ID.

Parameters

projectId Project identifier

Returns: Project metadata

Exceptions

std::runtime_error if project does not exist

◆ glass_confidence_image()

cv::Mat reusex::ProjectDB::glass_confidence_image ( int nodeId ) const

◆ glass_confidence_image_ids()

std::vector< int > reusex::ProjectDB::glass_confidence_image_ids ( ) const

◆ hardened_by_default()

bool reusex::ProjectDB::hardened_by_default ( )

staticnoexcept

◆ has_building_component()

bool reusex::ProjectDB::has_building_component ( std::string_view name ) const

◆ has_gaussian_splat()

bool reusex::ProjectDB::has_gaussian_splat ( std::string_view name ) const

False — not an error — on a project whose schema predates the splat tables, which is what a read-only open of an old project looks like (read-only opens never migrate).

◆ has_glass_confidence_image()

bool reusex::ProjectDB::has_glass_confidence_image ( int nodeId ) const

◆ has_mesh()

bool reusex::ProjectDB::has_mesh ( std::string_view name ) const

◆ has_panorama_segmentation()

bool reusex::ProjectDB::has_panorama_segmentation ( int panoId ) const

◆ has_panoramic_image()

bool reusex::ProjectDB::has_panoramic_image ( std::string_view filename ) const

◆ has_passport_field_values()

bool reusex::ProjectDB::has_passport_field_values ( std::string_view name ) const

nodiscard

True when any passport stores a value under the field name name (a leksikon name_en or a user column's display name) — including values a deleted user column left behind.

◆ has_point_cloud()

bool reusex::ProjectDB::has_point_cloud ( std::string_view name ) const

◆ has_pose_graph()

bool reusex::ProjectDB::has_pose_graph ( ) const

True when the pose graph table exists and has at least one edge.

◆ has_segmentation_image()

bool reusex::ProjectDB::has_segmentation_image ( int nodeId ) const

◆ has_sensor_frame()

bool reusex::ProjectDB::has_sensor_frame ( int nodeId ) const

◆ has_sensor_frame_pose()

bool reusex::ProjectDB::has_sensor_frame_pose ( int nodeId ) const

True when this frame carries a usable stored world pose.

sensor_frame_pose() cannot answer this: it returns identity for a frame with no row, a NULL transform, or a wrong-sized blob, so a poseless frame is indistinguishable from one legitimately at the origin (#330) — and it returns an all-zero or NaN transform verbatim (#336).

Checks: the row exists, the blob is exactly 16 doubles, all finite, the bottom row is [0,0,0,1], and |det(R)| is above epsilon. A genuinely stored identity pose IS valid — a scan may put its first frame at the origin.

◆ has_survey_part_for()

bool reusex::ProjectDB::has_survey_part_for	(	std::string_view	cloud_name,
		std::uint32_t	instance_id ) const

nodiscard

◆ instance_guid()

std::string reusex::ProjectDB::instance_guid	(	const std::string &	cloud_name,
		uint32_t	instance_id ) const

Stable GUID of a single instance.

Exceptions

std::runtime_error if the cloud or instance does not exist.

Referenced by dismiss_instance(), and is_instance_dismissed().

◆ instance_material_guid()

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

Material passport guid linked to an instance, or nullopt if unlinked.

◆ instance_materials()

std::map< int, std::string > reusex::ProjectDB::instance_materials ( std::string_view cloudName ) const

All instance_id → material_guid links for a cloud.

◆ instances()

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

All instance rows for a cloud, ordered by instance_id.

◆ is_instance_dismissed()

bool reusex::ProjectDB::is_instance_dismissed ( std::string_view instance_guid ) const

nodiscard

False on a read-only open of a pre-v26 project (no table).

References instance_guid().

◆ is_open()

bool reusex::ProjectDB::is_open ( ) const

noexcept

References is_open().

Referenced by is_open().

◆ is_passport_linked()

bool reusex::ProjectDB::is_passport_linked ( std::string_view guid ) const

nodiscard

True when a survey part or an instance link still references guid.

◆ is_read_only()

bool reusex::ProjectDB::is_read_only ( ) const

noexcept

◆ label_definitions()

std::map< int, std::string > reusex::ProjectDB::label_definitions ( std::string_view cloudName ) const

◆ latest_schema_version()

int reusex::ProjectDB::latest_schema_version ( )

staticnoexcept

References latest_schema_version().

Referenced by latest_schema_version().

◆ list_building_components() [1/2]

std::vector< std::string > reusex::ProjectDB::list_building_components ( ) const

Referenced by reusex::geometry::list_building_components().

◆ list_building_components() [2/2]

std::vector< std::string > reusex::ProjectDB::list_building_components ( std::string_view type ) const

Names of the components whose stored type discriminator equals type.

◆ list_gaussian_splats()

std::vector< std::string > reusex::ProjectDB::list_gaussian_splats ( ) const

Empty on a pre-v12 schema, for the same reason as has_gaussian_splat().

◆ list_meshes()

std::vector< std::string > reusex::ProjectDB::list_meshes ( ) const

◆ list_panoramic_images()

std::vector< PanoramicImage > reusex::ProjectDB::list_panoramic_images ( ) const

◆ list_passport_guids()

std::vector< std::string > reusex::ProjectDB::list_passport_guids ( ) const

List document GUIDs ordered by created_at.

Returns: Vector of document GUID strings

◆ list_point_clouds()

std::vector< std::string > reusex::ProjectDB::list_point_clouds ( ) const

◆ list_pose_graph_edges()

std::vector< PoseGraphEdge > reusex::ProjectDB::list_pose_graph_edges ( ) const

All stored edges, in insertion order.

Returns an empty vector when the table does not exist (pre-v15 schema opened read-only).

◆ list_project_ids()

std::vector< std::string > reusex::ProjectDB::list_project_ids ( ) const

List all project IDs in the database.

Returns: Vector of project IDs

◆ list_property_definitions()

std::vector< PropertyDefinition > reusex::ProjectDB::list_property_definitions ( ) const

nodiscard

List all user-defined material column definitions.

Returns: Definitions ordered by sort_order then created_at.

◆ list_report_pdfs()

std::vector< ReportPdfRecord > reusex::ProjectDB::list_report_pdfs ( ) const

nodiscard

List all stored report PDFs, newest first.

Does NOT return the blob payload — call report_pdf(id) for that.

◆ list_tables()

std::vector< TableInfo > reusex::ProjectDB::list_tables ( ) const

Every user table, sorted by name, with its row count.

◆ log_pipeline_end() [1/2]

void reusex::ProjectDB::log_pipeline_end	(	int	logId,
		bool	success,
		std::string_view	errorMsg = "" )

Shim for the two-outcome form: success maps to PipelineOutcome:: success, !success to PipelineOutcome::failed.

Prefer the PipelineOutcome overload when a cancel is possible.

◆ log_pipeline_end() [2/2]

void reusex::ProjectDB::log_pipeline_end	(	int	logId,
		PipelineOutcome	outcome,
		std::string_view	errorMsg = "" )

◆ log_pipeline_start()

int reusex::ProjectDB::log_pipeline_start	(	std::string_view	stage,
		std::string_view	paramsJson = "" )

◆ material_annotation()

std::optional< MaterialAnnotation > reusex::ProjectDB::material_annotation ( std::string_view materialGuid ) const

The stored annotation for one material passport, or nullopt when none was saved.

Key/value pairs are returned in key-sorted order (deterministic).

◆ material_passport()

core::MaterialPassport reusex::ProjectDB::material_passport ( std::string_view documentGuid ) const

◆ material_thumbnail()

std::optional< std::pair< std::vector< std::uint8_t >, std::string > > reusex::ProjectDB::material_thumbnail ( const std::string & guid ) const

nodiscard

Fetch a material's thumbnail blob and its MIME type.

Parameters

guid	Material passport document GUID

Returns: {blob, mime_type} when a thumbnail exists, else std::nullopt

◆ max_survey_part_number()

int reusex::ProjectDB::max_survey_part_number ( ) const

nodiscard

◆ mesh()

std::shared_ptr< pcl::PolygonMesh > reusex::ProjectDB::mesh ( std::string_view name ) const

Referenced by save_mesh(), and save_mesh().

◆ mesh_data_blob()

std::vector< uint8_t > reusex::ProjectDB::mesh_data_blob ( std::string_view name ) const

◆ mesh_format()

std::string reusex::ProjectDB::mesh_format ( std::string_view name ) const

◆ mesh_metadata()

MeshMetadata reusex::ProjectDB::mesh_metadata ( std::string_view name ) const

◆ mesh_texture_blobs()

std::vector< MeshTextureInfo > reusex::ProjectDB::mesh_texture_blobs ( std::string_view name ) const

◆ mesh_texture_metadata()

std::vector< MeshTextureMetadata > reusex::ProjectDB::mesh_texture_metadata ( std::string_view name ) const

◆ nearest_sensor_frame_by_timestamp()

int reusex::ProjectDB::nearest_sensor_frame_by_timestamp ( double timestamp ) const

Find the sensor frame with the closest timestamp to the given value.

Returns -1 if no sensor frames have timestamps.

◆ operator=() [1/2]

ProjectDB & reusex::ProjectDB::operator= ( const ProjectDB & )

delete

References ProjectDB().

◆ operator=() [2/2]

ProjectDB & reusex::ProjectDB::operator= ( ProjectDB && )

noexcept

References ProjectDB().

◆ panorama_segmentation()

cv::Mat reusex::ProjectDB::panorama_segmentation ( int panoId ) const

◆ panoramic_image() [1/2]

cv::Mat reusex::ProjectDB::panoramic_image ( int id ) const

◆ panoramic_image() [2/2]

cv::Mat reusex::ProjectDB::panoramic_image ( std::string_view filename ) const

◆ panoramic_image_count()

int reusex::ProjectDB::panoramic_image_count ( ) const

◆ passport_linked_node_id()

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

Return the sensor frame node_id this passport was linked to.

When a passport is imported via "rux import photos" and matched to a sensor frame, material_passports.id is set to the frame's node_id (as decimal text). This helper returns that id parsed as an integer, or std::nullopt when the passport was stored without a link (id falls back to the document_guid).

Parameters

documentGuid Document GUID

Returns: Node id when the row id is a non-negative integer, else std::nullopt

Exceptions

std::runtime_error if passport not found

◆ passport_metadata()

core::MaterialPassportMetadata reusex::ProjectDB::passport_metadata ( std::string_view documentGuid ) const

Get passport metadata without loading all properties.

Parameters

documentGuid Document GUID

Returns: MaterialPassportMetadata struct

Exceptions

std::runtime_error if passport not found

◆ passport_property_value()

std::string reusex::ProjectDB::passport_property_value	(	std::string_view	documentGuid,
		std::string_view	fieldName ) const

Get a single passport property value by field name.

Parameters

documentGuid	Document GUID
fieldName	Property field name (name_en in property_definitions)

Returns: String value of the property

Exceptions

std::runtime_error if passport or property not found

◆ passport_stored_properties()

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

Get stored property field_name→string pairs for a passport.

Only includes properties that actually have rows in passport_property_values. Values are returned as human-readable strings (BLOB decoded via as_string()).

Parameters

documentGuid Document GUID

Returns: Map of name_en → string value

Exceptions

std::runtime_error if passport does not exist

◆ path()

const std::filesystem::path & reusex::ProjectDB::path ( ) const

noexcept

References path().

Referenced by path(), and probe().

◆ pipeline_log()

std::vector< PipelineLogEntry > reusex::ProjectDB::pipeline_log ( int limit = 0 ) const

◆ point_cloud_label()

CloudLPtr reusex::ProjectDB::point_cloud_label ( std::string_view name ) const

◆ point_cloud_normal()

CloudNPtr reusex::ProjectDB::point_cloud_normal ( std::string_view name ) const

◆ point_cloud_page()

CloudPage reusex::ProjectDB::point_cloud_page	(	std::string_view	name,
		uint64_t	offset,
		uint64_t	limit ) const

Read one page of a point cloud without materializing the cloud.

Peak memory is O(page), not O(cloud). The chunk map is built from length(data) (which does not load a blob), and only the chunks the requested byte range [offset*step, (offset+count)*step) overlaps are touched, via SQLite incremental blob I/O. A 100k-point page of a 10M-point PointXYZRGB cloud therefore costs ~1.6 MB, not the ~160 MB the blob occupies (nor the ~320 MB it would occupy once inflated into pcl::PointXYZRGB, which is 32 bytes wide because of SSE padding).

A record may straddle a chunk boundary, so the read works in raw byte ranges rather than whole records per chunk.

Parameters

offset	First point index. Past the end yields count == 0 with total still populated — not an error.
limit	Maximum points to return. 0 yields an empty page.

Exceptions

std::runtime_error when name is not a stored cloud, or when the stored point_step contradicts the stored point_type.

◆ point_cloud_provenance()

std::pair< std::string, std::string > reusex::ProjectDB::point_cloud_provenance ( std::string_view name ) const

The stage and parameters (JSON, may be empty) the cloud was last saved with — so an in-place edit can save it again without erasing how it was produced.

Exceptions

std::runtime_error when name is not a cloud.

◆ point_cloud_storage_order()

std::string reusex::ProjectDB::point_cloud_storage_order ( std::string_view name ) const

Returns the "storage_order" value from the cloud's parameters JSON, or an empty string when the key is absent or the JSON is unparseable.

"morton_10bit" means the cloud was stored in Morton order (10 bits/axis, 30-bit code) so any prefix is a uniform spatial sample — the LOD read path can skip its voxel pass and return a prefix directly (#394).

◆ point_cloud_type()

std::string reusex::ProjectDB::point_cloud_type ( std::string_view name ) const

◆ point_cloud_xyz()

pcl::PointCloud< pcl::PointXYZ >::Ptr reusex::ProjectDB::point_cloud_xyz ( std::string_view name ) const

◆ point_cloud_xyzrgb()

CloudPtr reusex::ProjectDB::point_cloud_xyzrgb ( std::string_view name ) const

◆ probe()

ProbeResult reusex::ProjectDB::probe ( const std::filesystem::path & path )

staticnoexcept

Is path a ReUseX project, and at which schema?

Opens the file read-only, checks the tables validate_schema() requires and reads the recorded version. Never writes, creates, migrates or logs — so a GUI can vet a foreign or empty sqlite file before a read-write open would give it ReUseX tables.

The open is sqlite-immutable (?mode=ro&immutable=1) unless a non-empty -wal sits beside the file: no locks, no -shm / -wal created, and it works in a read-only directory. Trade-off: a writer's in-flight transaction is not seen, which a table check can live with. With a live WAL it is a plain read-only open (the WAL's pages count), which may wait on and report a lock in error (is_project false). Under hardened_by_default() the connection is hardened like any other open; rux leaves that off, so its probe is the plain open described here.

References path().

◆ project_summary()

ProjectSummary reusex::ProjectDB::project_summary ( ) const

◆ rename_passport_field()

void reusex::ProjectDB::rename_passport_field	(	std::string_view	old_name,
		std::string_view	new_name )

Call inside a Transaction.

Moves the values stored under a user column's field name to new_name; a no-op when nothing is stored.

Exceptions

core::NameConflictError when values already exist under new_name (they would merge).

◆ report_pdf()

std::optional< std::vector< std::uint8_t > > reusex::ProjectDB::report_pdf ( int64_t id ) const

nodiscard

Fetch one stored PDF blob by id.

Returns: The raw PDF bytes, or std::nullopt if the id does not exist.

◆ resource_template()

std::optional< ResourceTemplateRecord > reusex::ProjectDB::resource_template ( int64_t id ) const

nodiscard

◆ resource_templates()

std::vector< ResourceTemplateRecord > reusex::ProjectDB::resource_templates ( ) const

nodiscard

By id. Empty on a read-only open of a pre-v25 project.

◆ sample()

std::optional< SampleRecord > reusex::ProjectDB::sample ( int64_t id ) const

nodiscard

◆ samples()

std::vector< SampleRecord > reusex::ProjectDB::samples ( ) const

nodiscard

◆ samples_for_type()

std::vector< SampleRecord > reusex::ProjectDB::samples_for_type ( int64_t type_id ) const

nodiscard

◆ save_component_record()

void reusex::ProjectDB::save_component_record ( const core::ComponentRecord & record )

Insert or replace the component row identified by record.name.

A guid is generated when record.guid is empty; an existing row's guid is never overwritten.

Referenced by reusex::geometry::save_building_component().

◆ save_gaussian_splat()

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

Store an INRIA-format 3DGS .ply under name, replacing any splat already stored under it (chunks of the previous payload are dropped, so a re-save never leaves orphaned rows behind).

The header is parsed for two reasons, not one: it yields the metadata (gaussian_count, sh_degree) without a second source of truth, and it rejects a file that is not a Gaussian splat before several hundred MB are committed to the project.

Exceptions

std::runtime_error if ply is not an INRIA 3DGS PLY.

◆ save_glass_confidence_image()

void reusex::ProjectDB::save_glass_confidence_image	(	int	nodeId,
		const cv::Mat &	confidence )

◆ save_instances()

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

Replace the full set of instance rows for a cloud (transactional).

Existing rows for the cloud are deleted first; each record's GUID must be non-empty and unique across the DB. Throws on empty/duplicate GUID.

◆ save_label_definitions()

void reusex::ProjectDB::save_label_definitions	(	std::string_view	cloudName,
		const std::map< int, std::string > &	labelMap )

◆ save_material_annotation()

void reusex::ProjectDB::save_material_annotation	(	std::string_view	materialGuid,
		const MaterialAnnotation &	annotation )

Upsert the VLM annotation for one material passport (keyed on its document GUID).

Replaces the description/provenance and REPLACES the key/value rows for that GUID atomically, so no stale key survives a re-describe.

Exceptions

std::runtime_error if the material passport does not exist (STANDARDS §5) — run rux create materials first.

◆ save_mesh() [1/2]

void reusex::ProjectDB::save_mesh	(	std::string_view	name,
		const pcl::PolygonMesh &	mesh,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

References mesh().

◆ save_mesh() [2/2]

void reusex::ProjectDB::save_mesh	(	std::string_view	name,
		const pcl::TextureMesh &	mesh,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

References mesh().

◆ save_panorama_pose()

void reusex::ProjectDB::save_panorama_pose	(	int	id,
		const std::array< double, 16 > &	pose,
		int	inliers,
		double	rms )

Store a content-aligned pose (row-major 4x4 world) for a panorama.

◆ save_panorama_segmentation()

void reusex::ProjectDB::save_panorama_segmentation	(	int	panoId,
		const cv::Mat &	labels )

◆ save_panoramic_image()

void reusex::ProjectDB::save_panoramic_image	(	const std::string &	filename,
		const std::vector< uint8_t > &	jpeg_data,
		double	timestamp = -1.0,
		int	nodeId = -1 )

◆ save_point_cloud() [1/4]

void reusex::ProjectDB::save_point_cloud	(	std::string_view	name,
		const Cloud &	cloud,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

◆ save_point_cloud() [2/4]

void reusex::ProjectDB::save_point_cloud	(	std::string_view	name,
		const CloudL &	cloud,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

◆ save_point_cloud() [3/4]

void reusex::ProjectDB::save_point_cloud	(	std::string_view	name,
		const CloudN &	cloud,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

◆ save_point_cloud() [4/4]

void reusex::ProjectDB::save_point_cloud	(	std::string_view	name,
		const pcl::PointCloud< pcl::PointXYZ > &	cloud,
		std::string_view	stage = "",
		std::string_view	paramsJson = "" )

◆ save_pose_graph_edges()

void reusex::ProjectDB::save_pose_graph_edges ( const std::vector< PoseGraphEdge > & edges )

Replace the stored pose graph atomically (delete-then-insert inside one transaction).

Calling with an empty vector clears the table.

◆ save_segmentation_image()

void reusex::ProjectDB::save_segmentation_image	(	int	nodeId,
		const cv::Mat &	labels )

◆ save_segmentation_images()

void reusex::ProjectDB::save_segmentation_images	(	const std::vector< int > &	nodeIds,
		const std::vector< cv::Mat > &	labels )

◆ save_sensor_frame() [1/2]

void reusex::ProjectDB::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,
		int	scan_id = -1 )

◆ save_sensor_frame() [2/2]

void reusex::ProjectDB::save_sensor_frame	(	int	nodeId,
		const cv::Mat &	colorImage )

◆ save_tile_index()

void reusex::ProjectDB::save_tile_index	(	std::string_view	name,
		const std::vector< uint8_t > &	blob )

Save a serialized tile index blob for the named cloud.

◆ scans()

std::vector< ScanRecord > reusex::ProjectDB::scans ( ) const

Returns all scan records ordered by id.

◆ schema_version()

int reusex::ProjectDB::schema_version ( ) const

References schema_version().

Referenced by schema_version().

◆ segmentation_image()

cv::Mat reusex::ProjectDB::segmentation_image ( int nodeId ) const

◆ segmentation_image_ids()

std::vector< int > reusex::ProjectDB::segmentation_image_ids ( ) const

◆ sensor_frame_confidence()

cv::Mat reusex::ProjectDB::sensor_frame_confidence ( int nodeId ) const

◆ sensor_frame_depth()

cv::Mat reusex::ProjectDB::sensor_frame_depth ( int nodeId ) const

◆ sensor_frame_ids()

std::vector< int > reusex::ProjectDB::sensor_frame_ids ( ) const

◆ sensor_frame_ids_with_scan()

std::vector< std::pair< int, int > > reusex::ProjectDB::sensor_frame_ids_with_scan ( ) const

Returns {node_id, scan_id} pairs ordered by node_id.

scan_id is 0 when the frame has no recorded scan (schema < v17).

◆ sensor_frame_image()

cv::Mat reusex::ProjectDB::sensor_frame_image ( int nodeId ) const

◆ sensor_frame_intrinsics()

core::SensorIntrinsics reusex::ProjectDB::sensor_frame_intrinsics ( int nodeId ) const

◆ sensor_frame_pose()

std::array< double, 16 > reusex::ProjectDB::sensor_frame_pose ( int nodeId ) const

The stored world pose, verbatim — row-major 4x4, identity when the row is missing, the transform is NULL, or the blob is the wrong size.

This accessor does NOT validate. A well-sized all-zero or NaN transform is handed back exactly as stored, and the identity fallback is indistinguishable from a frame legitimately placed at the origin.

If a wrong pose would corrupt your output, gate on has_sensor_frame_pose() first — every pipeline stage does (#336). Raw use is for read-out surfaces (rux get, the GUI API, the Python bindings) that exist to show what the project actually contains, including when it is broken.

Deliberately non-throwing (#336): making it reject degenerate transforms would break exactly the diagnostic paths you need on a bad project, and the validity question has a dedicated accessor below.

◆ sensor_frame_timestamp()

double reusex::ProjectDB::sensor_frame_timestamp ( int nodeId ) const

Get the timestamp (epoch seconds) of a sensor frame.

Returns -1.0 if not set.

◆ set_hardened_by_default()

void reusex::ProjectDB::set_hardened_by_default ( bool on )

staticnoexcept

Process-wide default for OpenOptions::hardened, used by the (path, readOnly) constructor — and so by every open in this process that does not pass options, pipeline stages included.

A server sets it once at startup; the local rux CLI leaves it off.

◆ set_instance_material()

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

Link an instance (a row in the instances table) to a material passport by its document guid.

Upserts on (cloud, instance_id).

Validates referential integrity: the instance must exist in the target cloud's instances rows and the passport GUID must exist in material_passports. Throws std::runtime_error otherwise (STANDARDS §5).

◆ set_instance_point_count()

void reusex::ProjectDB::set_instance_point_count	(	const std::string &	cloud_name,
		uint32_t	instance_id,
		int	point_count )

Update one instance row's point_count in place (no delete/re-insert).

Exceptions

std::out_of_range when the cloud has no such instance.

◆ set_material_thumbnail()

void reusex::ProjectDB::set_material_thumbnail	(	const std::string &	guid,
		const std::vector< std::uint8_t > &	blob,
		const std::string &	mime_type )

Insert or replace a material's thumbnail blob.

Parameters

guid	Material passport document GUID
blob	Raw image bytes
mime_type	Image MIME type (e.g. "image/jpeg")

◆ set_passport_metadata_field()

void reusex::ProjectDB::set_passport_metadata_field	(	std::string_view	documentGuid,
		std::string_view	column,
		std::string_view	value )

Set a metadata column on a material passport.

Supported columns: created_at, revised_at, version_number, version_date. document_guid cannot be changed (it is the primary key).

Parameters

documentGuid	Document GUID (must exist)
column	Metadata column name
value	New value

Exceptions

std::runtime_error if passport not found or column not allowed

◆ set_passport_property()

void reusex::ProjectDB::set_passport_property	(	std::string_view	documentGuid,
		std::string_view	fieldName,
		std::string_view	value )

Set a single property value by field name (upsert).

Looks up the property_definitions entry by name_en, then upserts into passport_property_values. Creates property_definitions entry if needed.

Parameters

documentGuid	Document GUID (must exist)
fieldName	Property field name (name_en)
value	String value to store

Exceptions

std::runtime_error if passport does not exist

◆ set_sample_links()

void reusex::ProjectDB::set_sample_links	(	int64_t	id,
		const std::vector< int64_t > &	type_ids )

◆ set_survey_part_quantities()

void reusex::ProjectDB::set_survey_part_quantities ( const std::vector< std::pair< std::string, double > > & code_quantities )

Set several parts' quantities in one transaction — all or nothing.

Storage only; the redistribution rule lives in core/survey_service.

◆ survey_part()

std::optional< SurveyPartRecord > reusex::ProjectDB::survey_part ( std::string_view code ) const

nodiscard

◆ survey_parts()

std::vector< SurveyPartRecord > reusex::ProjectDB::survey_parts ( ) const

nodiscard

◆ survey_type()

std::optional< SurveyTypeRecord > reusex::ProjectDB::survey_type ( int64_t id ) const

nodiscard

◆ survey_types()

std::vector< SurveyTypeRecord > reusex::ProjectDB::survey_types ( ) const

nodiscard

◆ table_columns()

std::vector< TableColumn > reusex::ProjectDB::table_columns ( std::string_view table ) const

The columns of table, in declaration order.

Exceptions

std::invalid_argument when table is not a user table.

◆ table_row_count()

std::int64_t reusex::ProjectDB::table_row_count ( std::string_view table ) const

Rows in table now (COUNT(*)).

Exceptions

std::invalid_argument when table is not a user table.

◆ table_rows()

std::vector< std::vector< TableCell > > reusex::ProjectDB::table_rows	(	std::string_view	table,
		std::int64_t	offset,
		std::int64_t	limit,
		std::size_t	text_limit = 256 ) const

Rows [offset, offset + limit) of table in rowid order (or primary-key order for a WITHOUT ROWID table), one TableCell per column of table_columns().

Blob cells carry at most 16 head bytes in text.

Exceptions

std::invalid_argument when table is not a user table or offset / limit is negative.

◆ texture_mesh()

std::shared_ptr< pcl::TextureMesh > reusex::ProjectDB::texture_mesh ( std::string_view name ) const

◆ tile_index()

std::vector< uint8_t > reusex::ProjectDB::tile_index ( std::string_view name ) const

Load the tile index blob, or empty if not set.

Exceptions

std::runtime_error when name is not a stored cloud.

◆ unlink_instance_material()

bool reusex::ProjectDB::unlink_instance_material	(	std::string_view	cloud_name,
		int	instance_id )

Removes the instance_materials link of (cloud_name, instance_id).

Returns false when there was none (or the cloud is unknown).

◆ update_component_record_by_guid()

void reusex::ProjectDB::update_component_record_by_guid ( const core::ComponentRecord & record )

Update an existing component's mutable fields (name, type, parent_id, confidence, metadata, notes), matched by its immutable guid.

Geometry is left untouched. Throws if no component has the given guid.

Referenced by reusex::geometry::update_building_component_by_guid().

◆ update_project_metadata()

void reusex::ProjectDB::update_project_metadata ( const ProjectMetadata & metadata )

Update project metadata.

Parameters

metadata Project metadata to update Creates project if it doesn't exist

◆ update_property_definition()

void reusex::ProjectDB::update_property_definition	(	const std::string &	id,
		const std::string &	name,
		const std::string &	type,
		const std::vector< std::string > &	options,
		int	sort_order,
		int	width )

Overwrite an existing material column definition.

Exceptions

std::runtime_error if the id does not exist

◆ update_resource_template()

ResourceTemplateRecord reusex::ProjectDB::update_resource_template	(	int64_t	id,
		const ResourceTemplatePatch &	patch )

Exceptions

std::out_of_range,core::NameConflictError

◆ update_sample()

SampleRecord reusex::ProjectDB::update_sample	(	int64_t	id,
		const SamplePatch &	patch )

◆ update_sensor_frame_pose()

void reusex::ProjectDB::update_sensor_frame_pose	(	int	nodeId,
		const std::array< double, 16 > &	worldPose )

Update only the stored world pose (transform) of an existing sensor frame.

Leaves color/depth/confidence/intrinsics blobs untouched. Throws if no sensor frame with the given node_id exists.

Parameters

worldPose Row-major 4x4 SE(3) world pose (16 doubles).

◆ update_survey_part()

SurveyPartRecord reusex::ProjectDB::update_survey_part	(	std::string_view	code,
		const SurveyPartPatch &	patch )

◆ update_survey_type()

SurveyTypeRecord reusex::ProjectDB::update_survey_type	(	int64_t	id,
		const SurveyTypePatch &	patch )

◆ validate_schema()

void reusex::ProjectDB::validate_schema ( ) const

The documentation for this class was generated from the following file:

libs/reusex/include/core/ProjectDB.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ PipelineOutcome

Constructor & Destructor Documentation

◆ ProjectDB() [1/4]

◆ ProjectDB() [2/4]

◆ ~ProjectDB()

◆ ProjectDB() [3/4]

◆ ProjectDB() [4/4]

Member Function Documentation

◆ add_instance()

◆ add_material_passport() [1/2]

◆ add_material_passport() [2/2]

◆ add_pose_graph_edge()

◆ add_property_definition()

◆ add_report_pdf()

◆ add_resource_template()

◆ add_sample()

◆ add_survey_part()

◆ add_survey_type()

◆ all_material_passports()

◆ building_component_count()

◆ check_integrity()

◆ component_record()

◆ create_scan()

◆ delete_building_component()

◆ delete_gaussian_splat()

◆ delete_material_passport()

◆ delete_material_thumbnail()

◆ delete_panoramic_image() [1/2]

◆ delete_panoramic_image() [2/2]

◆ delete_passport_field_values()

◆ delete_passport_property()

◆ delete_point_cloud()

◆ delete_pose_graph_edges()

◆ delete_property_definition()

◆ delete_resource_template()

◆ delete_sample()

◆ delete_survey_part()

◆ delete_survey_type()

◆ dismiss_instance()

◆ dismissed_instances()

◆ ensure_resource_passport()

◆ gaussian_splat_blob()

◆ gaussian_splat_metadata()

◆ get_project_metadata()

◆ glass_confidence_image()

◆ glass_confidence_image_ids()

◆ hardened_by_default()

◆ has_building_component()

◆ has_gaussian_splat()

◆ has_glass_confidence_image()

◆ has_mesh()

◆ has_panorama_segmentation()

◆ has_panoramic_image()

◆ has_passport_field_values()

◆ has_point_cloud()

◆ has_pose_graph()

◆ has_segmentation_image()

◆ has_sensor_frame()

◆ has_sensor_frame_pose()

◆ has_survey_part_for()

◆ instance_guid()

◆ instance_material_guid()

◆ instance_materials()

◆ instances()

◆ is_instance_dismissed()

◆ is_open()

◆ is_passport_linked()

◆ is_read_only()

◆ label_definitions()

◆ latest_schema_version()

◆ list_building_components() [1/2]

◆ list_building_components() [2/2]

◆ list_gaussian_splats()

◆ list_meshes()