Classes
struct	Blob
	A non-JSON response body (image, mesh blob). More...
struct	Endpoint
	One row of the route table. More...
class	HttpError
	Thrown by a handler to produce a non-200 JSON error response. More...
struct	ImageResponse
	An encoded image plus the provenance of any rendering applied to it. More...
struct	JobSubmission
	A validated POST /jobs body. More...
struct	LodSelection
	The outcome of a voxel selection over one whole cloud. More...
struct	PageRequest
	A validated, clamped offset/limit window over a collection. More...
struct	PageWindow
	The half-open [first, last) index range a page covers, plus the size of the collection it was taken from. More...
class	Params
	Already-decoded query parameters, so handlers never touch crow::request. More...
struct	PointsResponse
	One points-endpoint response. More...
class	Server
	Crow-backed implementation of the GUI API contract. More...
struct	ServerOptions
	Everything rux gui needs to stand a server up. More...
struct	ValueRange
	Range of the valid stored values a normalize=true rendering mapped. More...

Enumerations
enum class	RuxpType : uint8_t { f32 = 1 , u8 = 2 , u32 = 3 }
	Field value types, as written into a descriptor's type byte. More...

Functions
const std::vector< Endpoint > &	endpoint_table ()
	Every endpoint this server serves, in documentation order.
PageRequest	parse_page_request (const Params &params, long long default_limit, long long max_limit)
	Parse and clamp offset/limit for a paged collection.
PageWindow	page_window (const PageRequest &page, size_t total)
	Clamp `page` onto a collection of `total` items.
void	add_page_envelope (nlohmann::json &object, const PageWindow &window)
	Add the shared offset/count/total envelope to a collection response.
nlohmann::json	error_json (int status, std::string_view message)
nlohmann::json	health_json (const reusex::ProjectDB *db, const std::filesystem::path &project)
nlohmann::json	endpoints_json ()
nlohmann::json	project_summary_json (const reusex::ProjectDB &db)
	The dashboard payload.
nlohmann::json	projects_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	clouds_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	cloud_json (const reusex::ProjectDB &db, const std::string &name)
nlohmann::json	cloud_labels_json (const reusex::ProjectDB &db, const std::string &name)
	Label id → name for one cloud, as {"labels": {...}}.
nlohmann::json	cloud_points_json (const reusex::ProjectDB &db, const std::string &name, const Params &params)
	One page of point data as JSON, ignoring format.
PointsResponse	cloud_points (const reusex::ProjectDB &db, const std::string &name, const Params &params)
	Serve one page of point data in the requested wire format.
nlohmann::json	meshes_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	mesh_json (const reusex::ProjectDB &db, const std::string &name)
nlohmann::json	mesh_textures_json (const reusex::ProjectDB &db, const std::string &name)
Blob	mesh_data_blob (const reusex::ProjectDB &db, const std::string &name)
Blob	mesh_texture_blob (const reusex::ProjectDB &db, const std::string &name, const std::string &texture)
nlohmann::json	frames_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	frame_json (const reusex::ProjectDB &db, int id)
ImageResponse	frame_image (const reusex::ProjectDB &db, int id, const Params &params)
	One of a frame's images, encoded as PNG.
nlohmann::json	panoramas_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	panorama_json (const reusex::ProjectDB &db, int id)
Blob	panorama_image_blob (const reusex::ProjectDB &db, int id, const Params &params)
	The equirectangular image, JPEG-encoded.
nlohmann::json	components_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	component_json (const reusex::ProjectDB &db, const std::string &name)
nlohmann::json	materials_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	material_json (const reusex::ProjectDB &db, const std::string &guid)
nlohmann::json	instances_json (const reusex::ProjectDB &db, const std::string &cloud, const Params &params)
nlohmann::json	stages_json (const reusex::ProjectDB &db)
nlohmann::json	stage_validation_json (const reusex::ProjectDB &db, const std::string &stage)
	Input-contract validation for a single stage.
nlohmann::json	pipeline_log_json (const reusex::ProjectDB &db, const Params &params)
nlohmann::json	job_json (const reusex::pipeline::JobRecord &record, std::string_view project)
nlohmann::json	jobs_json (const std::vector< reusex::pipeline::JobRecord > &jobs, std::string_view project)
	Every supplied job, unpaged, as {"jobs": [...]}.
nlohmann::json	jobs_page_json (const std::vector< reusex::pipeline::JobRecord > &jobs, std::string_view project, const Params &params)
	GET /jobs: one page of the job store, with the shared envelope.
nlohmann::json	job_event_json (const reusex::pipeline::JobEvent &event, std::string_view project)
nlohmann::json	hello_json (const std::vector< reusex::pipeline::JobRecord > &jobs, const std::filesystem::path &project)
JobSubmission	parse_job_request (std::string_view body)
	Parse and validate a job submission body.
void	check_job_project (const JobSubmission &submission, std::string_view open_project)
	Reject a submission aimed at a different project.
std::optional< nlohmann::json >	handle_ws_message (std::string_view body, const std::function< void(std::optional< std::string >)> &subscribe)
	Handle one client message on the WebSocket channel.
bool	event_matches_subscription (const reusex::pipeline::JobEvent &event, const std::optional< std::string > &subscription)
	True when `event` should be delivered to a connection filtered to `subscription` (nullopt = unfiltered, receives everything).
std::filesystem::path	resolve_asset_dir (const std::filesystem::path &override_dir)
	Locate the frontend asset directory, in precedence order:
std::filesystem::path	executable_dir ()
	Directory of the running executable, or an empty path if it cannot be determined.
std::string	percent_decode (std::string_view text)
	Percent-decode a URL path component ("%2e%2e" -> "..").
std::filesystem::path	resolve_asset (const std::filesystem::path &root, std::string_view url_path)
	Map a request path onto a file inside `root`.
bool	looks_like_spa_route (std::string_view url_path)
	True when a path looks like a client-side route rather than a missing file.
std::string	mime_type_for (const std::filesystem::path &path)
	Content type for a file, by extension.
std::string	placeholder_page (std::string_view project_name)
	The built-in landing page served when no asset bundle is installed.
std::vector< uint8_t >	encode_ruxp (const reusex::ProjectDB::CloudPage &page, uint32_t flags=0)
	Encode one stored page as a RUXP v1 buffer.
bool	ruxp_supports (std::string_view point_type)
	True when `type` is one encode_ruxp() knows how to lay out.
nlohmann::json	patch_cloud_labels (reusex::ProjectDB &db, const std::string &name, const std::string &body)
	Rename label classes of one Label cloud.
nlohmann::json	patch_material (reusex::ProjectDB &db, const std::string &guid, const std::string &body)
	Add, change or clear properties of one material passport.
nlohmann::json	gsplats_json (const reusex::ProjectDB &db, const Params &params)
	GET /api/v1/gsplats — every splat stored in the project, paged.
nlohmann::json	gsplat_json (const reusex::ProjectDB &db, std::string_view name)
	GET /api/v1/gsplats/{name} — one splat's metadata.
Blob	gsplat_blob (const reusex::ProjectDB &db, std::string_view name)
	GET /api/v1/gsplats/{name}/data — the INRIA .ply bytes, verbatim.
bool	lod_supports (std::string_view point_type)
	True when `point_type` carries the xyz positions the grid bins.
LodSelection	voxel_lod (const reusex::ProjectDB &db, std::string_view name, uint64_t max_points)
	Select a spatially representative subset of a whole cloud.
reusex::ProjectDB::CloudPage	gather_points (const reusex::ProjectDB &db, std::string_view name, const std::vector< uint64_t > &indices)
	Read the records of `name` at `indices`, as one page.

Variables
constexpr std::string_view	kApiVersion = "1.0.0"
	Contract version served under kApiPrefix.
constexpr std::string_view	kApiPrefix = "/api/v1"
constexpr std::string_view	kImplementation = "rux-gui"
	Identifies which implementation of the contract is answering.
constexpr size_t	kMaxPointsPerPage = 1000000
	Upper bound on limit for the paged points endpoint, so a stray query cannot ask the server to materialize an unbounded response.
constexpr size_t	kDefaultPointsPerPage = 100000
constexpr int	kMaxLogEntries = 1000
	Upper bound on limit for the pipeline-log endpoint.
constexpr int	kDefaultLogEntries = 100
constexpr int	kMaxCollectionItems = 1000
	Upper bound on limit for the ordinary object collections (clouds, meshes, panoramas, components, materials, instances, jobs, project records).
constexpr int	kMaxFrameIds = 10000
	Upper bound on limit for the sensor-frame id list.
constexpr int	kMaxImageSize = 4096
	Upper bound on the max_size image parameter.
constexpr int	kWriteLockTimeoutMs = 250
	How long a mutating request waits for the project's writer lock before answering 503.
constexpr uint16_t	kRuxpVersion = 1
	Format version written into every page.
constexpr size_t	kRuxpHeaderBase = 40
	Fixed part of the header, before the field descriptors.
constexpr size_t	kRuxpFieldSize = 16
	Bytes per field descriptor.
constexpr uint32_t	kRuxpFlagLod = 0x1U
	flags bit 0 — this page is a level-of-detail view of the whole cloud rather than a contiguous window of it (#320).
constexpr uint32_t	kRuxpKnownFlags = kRuxpFlagLod
	Every flag bit this encoder will emit.
constexpr uint64_t	kMaxGsplatBytes = 1024ull * 1024ull * 1024ull
	Upper bound on a splat blob this server will serve in one response.
constexpr uint64_t	kLodStreamChunk = 262144
	Points read from storage per streaming step while selecting.

Enumeration Type Documentation

◆ RuxpType

enum class rux::gui::RuxpType : uint8_t

strong

Field value types, as written into a descriptor's type byte.

Enumerator
f32
u8
u32

Definition at line 55 of file binary_points.hpp.

Function Documentation

◆ add_page_envelope()

void rux::gui::add_page_envelope	(	nlohmann::json &	object,
		const PageWindow &	window )

Add the shared offset/count/total envelope to a collection response.

Every paged collection carries these three fields under exactly these names, so a client writes its "is there more?" logic once (docs/gui/openapi.yaml, schema Page).

◆ check_job_project()

void rux::gui::check_job_project	(	const JobSubmission &	submission,
		std::string_view	open_project )

Reject a submission aimed at a different project.

Exceptions

HttpError(409) when submission names a project that is not open_project.

◆ cloud_json()

nlohmann::json rux::gui::cloud_json	(	const reusex::ProjectDB &	db,
		const std::string &	name )

◆ cloud_labels_json()

nlohmann::json rux::gui::cloud_labels_json	(	const reusex::ProjectDB &	db,
		const std::string &	name )

Label id → name for one cloud, as {"labels": {...}}.

Id 0 is never included: it means unlabeled (STANDARDS §3).

◆ cloud_points()

PointsResponse rux::gui::cloud_points	(	const reusex::ProjectDB &	db,
		const std::string &	name,
		const Params &	params )

Serve one page of point data in the requested wire format.

Exceptions

HttpError(404) for an unknown cloud, HttpError(400) for a format other than json|binary or a malformed offset/limit.

◆ cloud_points_json()

nlohmann::json rux::gui::cloud_points_json	(	const reusex::ProjectDB &	db,
		const std::string &	name,
		const Params &	params )

One page of point data as JSON, ignoring format.

Backed by ProjectDB::point_cloud_page(), so it reads only the bytes the page occupies. Use cloud_points() to serve the endpoint — this is the format=json half of it.

With max_points (#320) the answer is instead a voxel-subsampled view of the whole cloud, and the body carries lod (and voxel_size when it is true). max_points is mutually exclusive with offset/limit; see docs/gui/binary-points.md § "Level of detail".

Exceptions

HttpError(404) when name is not a stored cloud, HttpError(400) on a malformed offset/limit/max_points, on max_points combined with offset/limit, or on a max_points request against a cloud with no positions and no usable lod_source.

◆ clouds_json()

nlohmann::json rux::gui::clouds_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ component_json()

nlohmann::json rux::gui::component_json	(	const reusex::ProjectDB &	db,
		const std::string &	name )

◆ components_json()

nlohmann::json rux::gui::components_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ encode_ruxp()

std::vector< uint8_t > rux::gui::encode_ruxp	(	const reusex::ProjectDB::CloudPage &	page,
		uint32_t	flags = 0 )

Encode one stored page as a RUXP v1 buffer.

Produces the 40-byte header, 16 * field_count bytes of descriptors, and then one tightly packed little-endian section per field, in descriptor order. Header integers are written byte-by-byte so the output is byte-identical regardless of host endianness (the payload is not — see the Endianness section of docs/gui/binary-points.md, which makes little-endian a deliberate constraint of the format).

A page with count == 0 still yields a complete, valid header.

Parameters

flags Bits to write into the header's flags word — today only kRuxpFlagLod. A client rejects a page carrying a bit it does not know, so a bit must never be set speculatively.

Exceptions

std::runtime_error when the page's point_type has no RUXP field mapping, when its data is shorter than count * point_step, or when flags contains a bit outside kRuxpKnownFlags.

◆ endpoint_table()

const std::vector< Endpoint > & rux::gui::endpoint_table ( )

Every endpoint this server serves, in documentation order.

◆ endpoints_json()

nlohmann::json rux::gui::endpoints_json ( )

◆ error_json()

nlohmann::json rux::gui::error_json	(	int	status,
		std::string_view	message )

◆ event_matches_subscription()

bool rux::gui::event_matches_subscription	(	const reusex::pipeline::JobEvent &	event,
		const std::optional< std::string > &	subscription )

True when event should be delivered to a connection filtered to subscription (nullopt = unfiltered, receives everything).

◆ executable_dir()

std::filesystem::path rux::gui::executable_dir ( )

Directory of the running executable, or an empty path if it cannot be determined.

◆ frame_image()

ImageResponse rux::gui::frame_image	(	const reusex::ProjectDB &	db,
		int	id,
		const Params &	params )

One of a frame's images, encoded as PNG.

Parameters

params kind (color|depth|confidence|segmentation), max_size (longest edge, downscale only) and normalize (render for display rather than for measurement).

◆ frame_json()

nlohmann::json rux::gui::frame_json	(	const reusex::ProjectDB &	db,
		int	id )

◆ frames_json()

nlohmann::json rux::gui::frames_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

Parameters

params segmented filters the id list; see docs/gui/openapi.yaml.

◆ gather_points()

reusex::ProjectDB::CloudPage rux::gui::gather_points	(	const reusex::ProjectDB &	db,
		std::string_view	name,
		const std::vector< uint64_t > &	indices )

Read the records of name at indices, as one page.

The sibling half of a LOD: indices comes from voxel_lod() over a geometry cloud, and this pulls the same point positions out of an index-aligned cloud (docs/CONTRACTS.md, STANDARDS §3.2) so the two pages can still be zipped positionally.

Streams the cloud in kLodStreamChunk windows and picks the wanted records out as they go by, so this is one sequential pass and O(indices) memory — not one blob open per index.

Parameters

indices Ascending, unique, all < total of name.

Exceptions

std::runtime_error when name is not a stored cloud, or when an index is out of range (which means the two clouds are not index-aligned and the caller asked for something meaningless).

◆ gsplat_blob()

Blob rux::gui::gsplat_blob	(	const reusex::ProjectDB &	db,
		std::string_view	name )

GET /api/v1/gsplats/{name}/data — the INRIA .ply bytes, verbatim.

Exceptions

HttpError(404)	when no splat is stored under `name`.
HttpError(413)	when it exceeds kMaxGsplatBytes.

◆ gsplat_json()

nlohmann::json rux::gui::gsplat_json	(	const reusex::ProjectDB &	db,
		std::string_view	name )

GET /api/v1/gsplats/{name} — one splat's metadata.

Exceptions

HttpError(404) when no splat is stored under name.

◆ gsplats_json()

nlohmann::json rux::gui::gsplats_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

GET /api/v1/gsplats — every splat stored in the project, paged.

Metadata only. The byte_size in each row is what makes the client's decision informed: unlike a cloud, which streams in pages, a splat is one response of hundreds of megabytes, so the viewport does not fetch it until the user switches the layer on.

◆ handle_ws_message()

std::optional< nlohmann::json > rux::gui::handle_ws_message	(	std::string_view	body,
		const std::function< void(std::optional< std::string >)> &	subscribe )

Handle one client message on the WebSocket channel.

Parameters

body	the raw text frame
subscribe	called with the requested filter when the message is a subscribe (nullopt clears the filter)

Returns: the reply to send back, or nullopt when no reply is due.

◆ health_json()

nlohmann::json rux::gui::health_json	(	const reusex::ProjectDB *	db,
		const std::filesystem::path &	project )

Parameters

db	nullptr when the project could not be opened; the response then reports project.open == false instead of failing outright, so a browser pointed at a broken project still gets a usable page.

◆ hello_json()

nlohmann::json rux::gui::hello_json	(	const std::vector< reusex::pipeline::JobRecord > &	jobs,
		const std::filesystem::path &	project )

◆ instances_json()

nlohmann::json rux::gui::instances_json	(	const reusex::ProjectDB &	db,
		const std::string &	cloud,
		const Params &	params )

◆ job_event_json()

nlohmann::json rux::gui::job_event_json	(	const reusex::pipeline::JobEvent &	event,
		std::string_view	project )

◆ job_json()

nlohmann::json rux::gui::job_json	(	const reusex::pipeline::JobRecord &	record,
		std::string_view	project )

Parameters

project Name of the project the job belongs to. Present on every job and event so a client that later talks to a multi- project ruxd (Phase 6) does not need a new message shape.

◆ jobs_json()

nlohmann::json rux::gui::jobs_json	(	const std::vector< reusex::pipeline::JobRecord > &	jobs,
		std::string_view	project )

Every supplied job, unpaged, as {"jobs": [...]}.

The WebSocket hello frame uses this: it is a snapshot of the whole store (which is itself bounded — see JobRunner), not a page of a collection, and giving it a page envelope would invite a client to try to walk it.

◆ jobs_page_json()

nlohmann::json rux::gui::jobs_page_json	(	const std::vector< reusex::pipeline::JobRecord > &	jobs,
		std::string_view	project,
		const Params &	params )

GET /jobs: one page of the job store, with the shared envelope.

◆ lod_supports()

bool rux::gui::lod_supports ( std::string_view point_type )

True when point_type carries the xyz positions the grid bins.

Normal and Label clouds do not: a LOD of them is only meaningful relative to the geometry cloud they are index-aligned with.

◆ looks_like_spa_route()

bool rux::gui::looks_like_spa_route ( std::string_view url_path )

True when a path looks like a client-side route rather than a missing file.

Used to decide whether the SPA index.html fallback applies. A path whose last segment carries an extension (/assets/app.js) is a file request and must 404; an extensionless one (/projects/42) is the router's business.

◆ material_json()

nlohmann::json rux::gui::material_json	(	const reusex::ProjectDB &	db,
		const std::string &	guid )

◆ materials_json()

nlohmann::json rux::gui::materials_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ mesh_data_blob()

Blob rux::gui::mesh_data_blob	(	const reusex::ProjectDB &	db,
		const std::string &	name )

◆ mesh_json()

nlohmann::json rux::gui::mesh_json	(	const reusex::ProjectDB &	db,
		const std::string &	name )

◆ mesh_texture_blob()

Blob rux::gui::mesh_texture_blob	(	const reusex::ProjectDB &	db,
		const std::string &	name,
		const std::string &	texture )

◆ mesh_textures_json()

nlohmann::json rux::gui::mesh_textures_json	(	const reusex::ProjectDB &	db,
		const std::string &	name )

◆ meshes_json()

nlohmann::json rux::gui::meshes_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ mime_type_for()

std::string rux::gui::mime_type_for ( const std::filesystem::path & path )

Content type for a file, by extension.

Falls back to "application/octet-stream".

◆ page_window()

PageWindow rux::gui::page_window	(	const PageRequest &	page,
		size_t	total )

Clamp page onto a collection of total items.

◆ panorama_image_blob()

Blob rux::gui::panorama_image_blob	(	const reusex::ProjectDB &	db,
		int	id,
		const Params &	params )

The equirectangular image, JPEG-encoded.

Parameters

params max_size (longest edge, downscale only), for the thumbnail strip of a panorama picker — a stored equirect is routinely 8192x4096 and several megabytes.

◆ panorama_json()

nlohmann::json rux::gui::panorama_json	(	const reusex::ProjectDB &	db,
		int	id )

◆ panoramas_json()

nlohmann::json rux::gui::panoramas_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ parse_job_request()

JobSubmission rux::gui::parse_job_request ( std::string_view body )

Parse and validate a job submission body.

Exceptions

HttpError(400) on malformed JSON, a missing/unknown stage, or a parameters value that is not an object.

◆ parse_page_request()

PageRequest rux::gui::parse_page_request	(	const Params &	params,
		long long	default_limit,
		long long	max_limit )

Parse and clamp offset/limit for a paged collection.

Parameters

default_limit	limit when the parameter is absent.
max_limit	The server maximum. A limit of 0 requests exactly this; a larger one is clamped down to it rather than rejected, so a client may always ask for more than it expects to receive.

Exceptions

HttpError(400) on a negative offset/limit, or a non-integer.

◆ patch_cloud_labels()

nlohmann::json rux::gui::patch_cloud_labels	(	reusex::ProjectDB &	db,
		const std::string &	name,
		const std::string &	body )

Rename label classes of one Label cloud.

Parameters

body	{"labels": {"<id>": "<name>", ...}} — a sparse patch. Ids absent from it keep the names they had.

Returns: The full legend after the rename, as cloud_labels_json() returns it.

Exceptions

HttpError(404)	when `name` is not a cloud in this project.
HttpError(400)	on a malformed body, an empty name, or an id that is not already in the legend — this renames classes, it does not create them.
HttpError(409)	for the instances cloud, whose names encode the semantic class and instance id in a form the v10 migration and io/export_scene.cpp parse back out.

◆ patch_material()

nlohmann::json rux::gui::patch_material	(	reusex::ProjectDB &	db,
		const std::string &	guid,
		const std::string &	body )

Add, change or clear properties of one material passport.

Parameters

body	{"properties": {"<name>": "<value>"\|null, ...}} — a sparse patch; null deletes. Properties absent from it are untouched.

Returns: The passport after the edit, as material_json() returns it.

Exceptions

HttpError(404)	when no passport carries `guid`.
HttpError(400)	on a malformed body, an empty property name, or a value that is neither a string nor null.

◆ percent_decode()

std::string rux::gui::percent_decode ( std::string_view text )

Percent-decode a URL path component ("%2e%2e" -> "..").

Applied before the traversal check, because a check that runs on the raw text is trivially defeated by encoding the dots. Invalid escapes are left verbatim rather than dropped, so nothing silently changes meaning.

◆ pipeline_log_json()

nlohmann::json rux::gui::pipeline_log_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ placeholder_page()

std::string rux::gui::placeholder_page ( std::string_view project_name )

The built-in landing page served when no asset bundle is installed.

It is a real, functioning page — it calls the API it documents — so that rux gui is verifiable end to end before any frontend exists.

◆ project_summary_json()

nlohmann::json rux::gui::project_summary_json ( const reusex::ProjectDB & db )

The dashboard payload.

Deliberately NOT paged: it is one object describing a project, not a collection, and a client that had to page it would be making several requests to answer the one question it exists to answer.

◆ projects_json()

nlohmann::json rux::gui::projects_json	(	const reusex::ProjectDB &	db,
		const Params &	params )

◆ resolve_asset()

std::filesystem::path rux::gui::resolve_asset	(	const std::filesystem::path &	root,
		std::string_view	url_path )

Map a request path onto a file inside root.

Returns an empty path when the resolved location escapes root (via .., percent-encoded .., a symlink, or an absolute component) or does not name an existing regular file. A request for "/" resolves to index.html.

◆ resolve_asset_dir()

std::filesystem::path rux::gui::resolve_asset_dir ( const std::filesystem::path & override_dir )

Locate the frontend asset directory, in precedence order:

override_dir, when non-empty (from --assets)
$RUX_GUI_ASSETS
<dir of the running executable>/../share/reusex/gui Returns an empty path when none of them exists, in which case the server serves placeholder_page() instead.

Exceptions

std::runtime_error when override_dir is given but is not a directory — an explicit flag that silently does nothing would be a silent failure (STANDARDS §5).

◆ ruxp_supports()

bool rux::gui::ruxp_supports ( std::string_view point_type )

True when type is one encode_ruxp() knows how to lay out.

◆ stage_validation_json()

nlohmann::json rux::gui::stage_validation_json	(	const reusex::ProjectDB &	db,
		const std::string &	stage )

Input-contract validation for a single stage.

Same record shape as one element of stages_json(), so a client refreshing one card after a run does not have to reconcile two schemas.

Exceptions

HttpError(404) when stage is not in the catalogue.

◆ stages_json()

nlohmann::json rux::gui::stages_json ( const reusex::ProjectDB & db )

◆ voxel_lod()

LodSelection rux::gui::voxel_lod	(	const reusex::ProjectDB &	db,
		std::string_view	name,
		uint64_t	max_points )

Select a spatially representative subset of a whole cloud.

One streaming pass over the cloud's stored records, keeping the lowest-indexed point of each occupied voxel. When the kept set would exceed max_points the grid is coarsened — the voxel edge doubles, which maps every key onto its parent by an arithmetic shift, so the already-kept set is merged in place rather than re-read. The scan therefore never rewinds, and peak memory is O(max_points), not O(cloud).

Guarantees. page.count <= max_points always. The result is deterministic: the representative of a voxel is its lowest storage index, the output is sorted by that index, and nothing depends on hash order (STANDARDS §6).

Not guaranteed. The count is not close to max_points from below. The grid is dyadic, so one coarsening step drops the count of a surface-like cloud by roughly 4×; a result may legitimately land anywhere in (max_points/4, max_points]. Hitting a budget exactly is what a precomputed progressive ordering would buy — see the design note in docs/gui/binary-points.md.

Parameters

max_points Budget, >= 1. The caller clamps it to the server maximum.

Exceptions

std::runtime_error when name is not a stored cloud, when its type has no positions (lod_supports), or when max_points is 0.

Variable Documentation

◆ kApiPrefix

std::string_view rux::gui::kApiPrefix = "/api/v1"

inlineconstexpr

Definition at line 43 of file api.hpp.

◆ kApiVersion

std::string_view rux::gui::kApiVersion = "1.0.0"

inlineconstexpr

Contract version served under kApiPrefix.

Bump only for breaking changes, and take a new prefix when you do.

Definition at line 42 of file api.hpp.

◆ kDefaultLogEntries

int rux::gui::kDefaultLogEntries = 100

inlineconstexpr

Definition at line 64 of file api.hpp.

◆ kDefaultPointsPerPage

size_t rux::gui::kDefaultPointsPerPage = 100000

inlineconstexpr

Definition at line 58 of file api.hpp.

◆ kImplementation

std::string_view rux::gui::kImplementation = "rux-gui"

inlineconstexpr

Identifies which implementation of the contract is answering.

Definition at line 45 of file api.hpp.

◆ kLodStreamChunk

uint64_t rux::gui::kLodStreamChunk = 262144

inlineconstexpr

Points read from storage per streaming step while selecting.

The cloud is walked in windows of this size rather than read whole, so the scan costs a fixed ~4 MB of buffer (at the 16-byte PointXYZRGB stride) regardless of how large the cloud is.

Definition at line 34 of file point_lod.hpp.

◆ kMaxCollectionItems

int rux::gui::kMaxCollectionItems = 1000

inlineconstexpr

Upper bound on limit for the ordinary object collections (clouds, meshes, panoramas, components, materials, instances, jobs, project records).

These are counted in the hundreds at worst, so the cap is about bounding the response rather than about forcing anyone to page.

Definition at line 70 of file api.hpp.

◆ kMaxFrameIds

int rux::gui::kMaxFrameIds = 10000

inlineconstexpr

Upper bound on limit for the sensor-frame id list.

Deliberately larger than kMaxCollectionItems: an id is four bytes on the wire, and making a scan of ordinary size page through its own frame list would be ceremony.

Definition at line 75 of file api.hpp.

◆ kMaxGsplatBytes

uint64_t rux::gui::kMaxGsplatBytes = 1024ull * 1024ull * 1024ull

inlineconstexpr

Upper bound on a splat blob this server will serve in one response.

The body is materialized in memory (as the mesh-blob route already is), so this is a real ceiling rather than a formality: 1 GiB is roughly four million Gaussians at spherical-harmonic degree 3. Past it the honest answer is 413 rather than an out-of-memory server.

Definition at line 34 of file gsplat.hpp.

◆ kMaxImageSize

int rux::gui::kMaxImageSize = 4096

inlineconstexpr

Upper bound on the max_size image parameter.

Downscaling only ever makes an image cheaper, so the cap is about rejecting nonsense (and negative values) rather than about cost.

Definition at line 80 of file api.hpp.

◆ kMaxLogEntries

int rux::gui::kMaxLogEntries = 1000

inlineconstexpr

Upper bound on limit for the pipeline-log endpoint.

limit=0 means "as many as the server will give", which is this — not "unbounded", which would let one query serialize an entire project's history into memory.

Definition at line 63 of file api.hpp.

◆ kMaxPointsPerPage

size_t rux::gui::kMaxPointsPerPage = 1000000

inlineconstexpr

Upper bound on limit for the paged points endpoint, so a stray query cannot ask the server to materialize an unbounded response.

Definition at line 57 of file api.hpp.

◆ kRuxpFieldSize

size_t rux::gui::kRuxpFieldSize = 16

inlineconstexpr

Bytes per field descriptor.

Definition at line 37 of file binary_points.hpp.

◆ kRuxpFlagLod

uint32_t rux::gui::kRuxpFlagLod = 0x1U

inlineconstexpr

flags bit 0 — this page is a level-of-detail view of the whole cloud rather than a contiguous window of it (#320).

When set, count points were drawn from all total of them, offset is 0 and carries no meaning, and the page must not be zipped positionally against a page that does not come from the same selection. The layout is unchanged, which is why this is a flag and not a version: a reader that predates it refuses the page (v1's rule for an unknown flag), and it only ever reaches a reader that asked for it with max_points.

Definition at line 48 of file binary_points.hpp.

◆ kRuxpHeaderBase

size_t rux::gui::kRuxpHeaderBase = 40

inlineconstexpr

Fixed part of the header, before the field descriptors.

Definition at line 35 of file binary_points.hpp.

◆ kRuxpKnownFlags

uint32_t rux::gui::kRuxpKnownFlags = kRuxpFlagLod

inlineconstexpr

Every flag bit this encoder will emit.

Anything else is a programming error, not a wire condition.

Definition at line 52 of file binary_points.hpp.

◆ kRuxpVersion

uint16_t rux::gui::kRuxpVersion = 1

inlineconstexpr

Format version written into every page.

Bump only when the layout changes; a client that sees a version it does not know must refuse the page.

Definition at line 32 of file binary_points.hpp.

◆ kWriteLockTimeoutMs

int rux::gui::kWriteLockTimeoutMs = 250

inlineconstexpr

How long a mutating request waits for the project's writer lock before answering 503.

A running stage holds that lock for minutes, so waiting is pointless: the honest answer is "busy, retry", not a stalled request.

Definition at line 85 of file api.hpp.

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ RuxpType

Function Documentation

◆ add_page_envelope()

◆ check_job_project()

◆ cloud_json()

◆ cloud_labels_json()

◆ cloud_points()

◆ cloud_points_json()

◆ clouds_json()

◆ component_json()

◆ components_json()

◆ encode_ruxp()

◆ endpoint_table()

◆ endpoints_json()

◆ error_json()

◆ event_matches_subscription()

◆ executable_dir()

◆ frame_image()

◆ frame_json()

◆ frames_json()

◆ gather_points()

◆ gsplat_blob()

◆ gsplat_json()

◆ gsplats_json()

◆ handle_ws_message()

◆ health_json()

◆ hello_json()

◆ instances_json()

◆ job_event_json()

◆ job_json()

◆ jobs_json()

◆ jobs_page_json()

◆ lod_supports()

◆ looks_like_spa_route()

◆ material_json()

◆ materials_json()

◆ mesh_data_blob()

◆ mesh_json()

◆ mesh_texture_blob()

◆ mesh_textures_json()

◆ meshes_json()

◆ mime_type_for()

◆ page_window()

◆ panorama_image_blob()

◆ panorama_json()

◆ panoramas_json()

◆ parse_job_request()

◆ parse_page_request()

◆ patch_cloud_labels()

◆ patch_material()

◆ percent_decode()

◆ pipeline_log_json()

◆ placeholder_page()

◆ project_summary_json()

◆ projects_json()

◆ resolve_asset()

◆ resolve_asset_dir()

◆ ruxp_supports()

◆ stage_validation_json()

◆ stages_json()

◆ voxel_lod()

Variable Documentation

◆ kApiPrefix

◆ kApiVersion

◆ kDefaultLogEntries

◆ kDefaultPointsPerPage

◆ kImplementation

◆ kLodStreamChunk

◆ kMaxCollectionItems

◆ kMaxFrameIds

◆ kMaxGsplatBytes

◆ kMaxImageSize

◆ kMaxLogEntries

◆ kMaxPointsPerPage

◆ kRuxpFieldSize