Classes
struct	CameraFraming
	How a preset camera frames the scene. More...
struct	CameraSpec
	An explicit camera: rigid pose plus pinhole intrinsics. More...
struct	CutPlane
	A resolved horizontal cut: where the plane sits and how that was decided. More...
struct	InstanceHighlight
	One instance to call out in a render (Kortlægning evidence, #265 Phase 2 Task 8). More...
struct	LabelPalette
	The categorical colour scale label layers are drawn with. More...
struct	OffscreenGlProbe
	The outcome of one probe, with enough detail to put in an error message. More...
class	OffscreenGlUnavailable
	This machine cannot create an offscreen OpenGL context (#313). More...
struct	RenderOptions
	Everything render_view() can be told to do. More...
struct	SceneBounds
	Axis-aligned bounds of the geometry a scene draws. More...
struct	SceneInfo
	What populate_scene() added. More...
struct	SceneLayer
	The actors one layer added, so an interactive viewer can toggle it. More...
struct	SceneOptions
	What populate_scene() draws, and how. More...
struct	ViewportBounds
	Normalized bounds of a single viewport within a render window. More...

Enumerations
enum class	OffscreenGlStatus { usable , unusable , unknown }
	What the probe could establish about offscreen OpenGL on this machine. More...
enum class	Layer { cloud , labels , planes , rooms , instances , mesh , components , frustums , panoramas }
	One drawable body of content in a rendered view. More...
enum class	ViewPreset { top , plan , front , orbit , explicit_camera }
	How the camera is placed. More...
enum class	LodMethod { all , morton_prefix , stride }
	How a large cloud was thinned for drawing. More...

Functions
std::size_t	apply_instance_highlight (std::vector< unsigned char > &rgb, const std::vector< std::uint32_t > &labels, std::uint32_t instance_id)
	Paint points whose label == instance_id in kHighlightRgb and dim every other point to kHighlightDimFactor of its colour.
OffscreenGlProbe	probe_offscreen_gl () noexcept
	Ask EGL whether an offscreen context is possible here.
bool	display_configured () noexcept
	True when a window-system display is configured (DISPLAY or WAYLAND_DISPLAY).
std::optional< Layer >	layer_from_string (std::string_view name)
	Parse a layer name as accepted by rux render --layers.
std::string_view	to_string (Layer layer)
	The canonical name of `layer` (the inverse of layer_from_string).
const std::vector< Layer > &	all_layers ()
	Every layer, in draw order — the vocabulary --layers accepts.
std::string_view	to_string (ViewPreset view)
	The canonical name of `view`, as accepted by rux render --view.
std::optional< ViewPreset >	view_preset_from_string (std::string_view name)
	Parse a bare view-preset name.
cv::Mat	render_view (const ProjectDB &db, const RenderOptions &opts)
	Render one view of `db` to an image.
CameraSpec	camera_from_sensor_frame (const ProjectDB &db, int node_id, int width, int height)
	Build the camera that reproduces a stored sensor frame's viewpoint.
const LabelPalette &	default_label_palette ()
	The tokens' scale (see LabelPalette).
int	label_palette_slot (std::uint32_t label, std::size_t size)
	Palette slot of a point label: (label - 1) % size; kUnlabeledSlot for label 0 or an empty palette; kInvalidSlot for an out-of-contract label (a wrapped -1), which must not borrow a class's colour.
std::array< std::uint8_t, 3 >	label_palette_color (const LabelPalette &palette, std::uint32_t label)
	The colour of `label` in `palette`.
std::string_view	to_string (LodMethod method)
std::vector< std::uint32_t >	lod_indices (std::size_t total, std::size_t budget, std::string_view storage_order, LodMethod *method=nullptr)
	Which of `total` stored points to draw within a budget of `budget`.
SceneInfo	populate_scene (vtkRenderer *renderer, const ProjectDB &db, const SceneOptions &opts)
	Load `opts'` layers from `db` and add them to `renderer`.
CutPlane	resolve_cut_plane (const ProjectDB &db, const SceneBounds &bounds, std::optional< double > height)
	Decide where to cut `bounds:` `height` (or the default) above the floor detected by rux create planes, or above the bounding box's lower face.
void	apply_cut_plane (vtkRenderer *renderer, double z)
	Clip every actor of `renderer` to the half-space below z = `z`.
void	clear_cut_planes (vtkRenderer *renderer)
	Remove every clipping plane from `renderer's` actors.
void	place_preset_camera (vtkRenderer *renderer, const CameraFraming &framing, const SceneBounds &bounds)
	Place `renderer's` active camera for a preset view of `bounds`.
void	place_explicit_camera (vtkRenderer *renderer, const CameraSpec &spec, int width, int height, const SceneBounds &bounds)
	Place `renderer's` active camera at an explicit pose + pinhole camera, for an image of `width` x `height` pixels.
void	install_vtk_log_bridge ()
	Route VTK's diagnostics into ReUseX logging, once per process (see render_view()).
ViewportBounds	viewport_bounds (std::size_t index, std::size_t total, float left=0.0f, float top=0.0f, float right=1.0f, float bottom=1.0f, bool split_horizontal=true)
	Compute the normalized bounds for one viewport in an N-way split layout.

Variables
constexpr std::array< unsigned char, 3 >	kHighlightRgb {255, 176, 64}
	Accent colour painted onto the highlighted instance's points.
constexpr double	kHighlightDimFactor = 0.3
	Brightness multiplier applied to every non-highlighted point's colour.
constexpr double	kDefaultCutHeightM = 1.2
	Default height of the plan cut above the detected floor, in metres.
constexpr double	kDefaultCutBboxFraction = 0.45
	Fallback cut height when no floor plane is available, as a fraction of the scene's vertical extent.
constexpr double	kHorizontalNormalZ = 0.95
	\|n_z\| above which a segmented plane counts as horizontal when looking for the floor.
constexpr int	kUnlabeledSlot = -1
	Sentinel slots of label_palette_slot().
constexpr int	kInvalidSlot = -2

Enumeration Type Documentation

◆ Layer

enum class reusex::visualize::Layer

strong

One drawable body of content in a rendered view.

cloud draws the geometry cloud with its stored RGB colour; the four label layers draw the same geometry recoloured by the corresponding index-aligned Label cloud (CONTRACTS.md) on the design tokens' categorical --label-* scale (visualize/scene.hpp); mesh draws a stored mesh, components building-component outlines, frustums the camera frustum of each posed sensor frame and panoramas a marker where each 360 panorama was taken.

Enumerator
cloud	cloud (PointXYZRGB), stored per-point colour
labels	labels (Label) — semantic classes
planes	planes (Label) — planar segments
rooms	rooms (Label) — room partition
instances	instances (Label) — spatial instances
mesh	a stored mesh from the meshes table
components	building-component outlines (windows / doors / walls)
frustums	camera frustums of the posed sensor frames (subsampled)
panoramas	a marker at each placed 360 panorama

Definition at line 46 of file render_view.hpp.

◆ LodMethod

enum class reusex::visualize::LodMethod

strong

How a large cloud was thinned for drawing.

Enumerator
all	every point is drawn
morton_prefix	a prefix of a bit-reversed Morton cloud (stratified)
stride	every k-th point, evenly over the storage order

Definition at line 84 of file scene.hpp.

◆ OffscreenGlStatus

enum class reusex::visualize::OffscreenGlStatus

strong

What the probe could establish about offscreen OpenGL on this machine.

Enumerator

usable

EGL enumerated a device and initialised a display on it.

Rendering can proceed.

unusable

EGL is present and was asked, and reports nothing it can render on.

This is the condition that used to crash.

unknown

The probe could not reach a verdict — libEGL is absent, its entry points are missing, or the probe was switched off.

Never a reason to refuse to render: a VTK built against OSMesa, or one that will use GLX on an X display, is perfectly capable and simply does not go through EGL.

Definition at line 35 of file offscreen_gl.hpp.

◆ ViewPreset

enum class reusex::visualize::ViewPreset

strong

How the camera is placed.

Enumerator
top	Orthographic view looking straight down (-Z), north up. Shows whatever is topmost — in a closed interior, the ceiling. For a floor plan use ViewPreset::plan.
plan	A true floor plan: ViewPreset::top plus a horizontal cut (#306). The ceiling and everything else above RenderOptions::cut_height is clipped away, leaving the floor and the walls in section.
front	Orthographic elevation looking along +Y.
orbit	Perspective view on a ring around the scene; see RenderOptions::orbit_index / orbit_count / orbit_elevation_deg.
explicit_camera	Use RenderOptions::camera verbatim.

Definition at line 69 of file render_view.hpp.

Function Documentation

◆ all_layers()

const std::vector< Layer > & reusex::visualize::all_layers ( )

Every layer, in draw order — the vocabulary --layers accepts.

References all_layers().

Referenced by all_layers().

◆ apply_cut_plane()

void reusex::visualize::apply_cut_plane	(	vtkRenderer *	renderer,
		double	z )

Clip every actor of renderer to the half-space below z = z.

References apply_cut_plane().

Referenced by apply_cut_plane().

◆ apply_instance_highlight()

std::size_t reusex::visualize::apply_instance_highlight	(	std::vector< unsigned char > &	rgb,
		const std::vector< std::uint32_t > &	labels,
		std::uint32_t	instance_id )

Paint points whose label == instance_id in kHighlightRgb and dim every other point to kHighlightDimFactor of its colour.

rgb is 3 bytes per point.

Returns: number of highlighted points.

Exceptions

std::invalid_argument on size mismatch.

References apply_instance_highlight().

Referenced by apply_instance_highlight().

◆ camera_from_sensor_frame()

CameraSpec reusex::visualize::camera_from_sensor_frame	(	const ProjectDB &	db,
		int	node_id,
		int	width,
		int	height )

Build the camera that reproduces a stored sensor frame's viewpoint.

Composes the frame's world pose with its camera-to-base local transform and rescales the pinhole intrinsics from the captured frame size to width x height. Lives here rather than in the CLI so that "camera-to-world = pose * local_transform" has exactly one definition outside the back-projection that owns it (STANDARDS §1/§4).

Exceptions

std::runtime_error if the frame has no usable intrinsics, or no usable stored pose (ProjectDB::has_sensor_frame_pose()) — a render from the identity fallback would silently be a view from the world origin (#336).

References camera_from_sensor_frame().

Referenced by camera_from_sensor_frame().

◆ clear_cut_planes()

void reusex::visualize::clear_cut_planes ( vtkRenderer * renderer )

Remove every clipping plane from renderer's actors.

References clear_cut_planes().

Referenced by clear_cut_planes().

◆ default_label_palette()

const LabelPalette & reusex::visualize::default_label_palette ( )

The tokens' scale (see LabelPalette).

References default_label_palette().

Referenced by default_label_palette().

◆ display_configured()

bool reusex::visualize::display_configured ( )

noexcept

True when a window-system display is configured (DISPLAY or WAYLAND_DISPLAY).

VTK prefers a windowed GL path when one of these is set, and only falls back to EGL if it cannot be reached — so on such a machine an unusable EGL says nothing about whether rendering will work, and must not be treated as fatal.

References display_configured().

Referenced by display_configured().

◆ install_vtk_log_bridge()

void reusex::visualize::install_vtk_log_bridge ( )

Route VTK's diagnostics into ReUseX logging, once per process (see render_view()).

References install_vtk_log_bridge().

Referenced by install_vtk_log_bridge().

◆ label_palette_color()

std::array< std::uint8_t, 3 > reusex::visualize::label_palette_color	(	const LabelPalette &	palette,
		std::uint32_t	label )

The colour of label in palette.

References label_palette_color().

Referenced by label_palette_color().

◆ label_palette_slot()

int reusex::visualize::label_palette_slot	(	std::uint32_t	label,
		std::size_t	size )

Palette slot of a point label: (label - 1) % size; kUnlabeledSlot for label 0 or an empty palette; kInvalidSlot for an out-of-contract label (a wrapped -1), which must not borrow a class's colour.

The same rule as the web viewport's labelColorIndex() — indexing with label itself would shift every class by one against the legend.

References label_palette_slot().

Referenced by label_palette_slot().

◆ layer_from_string()

std::optional< Layer > reusex::visualize::layer_from_string ( std::string_view name )

Parse a layer name as accepted by rux render --layers.

Returns: std::nullopt if name is not a layer.

References layer_from_string().

Referenced by layer_from_string().

◆ lod_indices()

std::vector< std::uint32_t > reusex::visualize::lod_indices	(	std::size_t	total,
		std::size_t	budget,
		std::string_view	storage_order,
		LodMethod *	method = nullptr )

Which of total stored points to draw within a budget of budget.

A cloud stored in bit-reversed Morton order (rux create clouds, storage_order "morton_10bit_bitrev", #394/#396) is spatially stratified, so any prefix is a uniform sample: the first budget points. Every other order is thinned by an even stride — a plain Morton or insertion-order prefix would cover one corner of the scene, not all of it.

Returns: the storage indices, ascending; empty when every point fits (method == LodMethod::all).

References lod_indices().

Referenced by lod_indices().

◆ place_explicit_camera()

void reusex::visualize::place_explicit_camera	(	vtkRenderer *	renderer,
		const CameraSpec &	spec,
		int	width,
		int	height,
		const SceneBounds &	bounds )

Place renderer's active camera at an explicit pose + pinhole camera, for an image of width x height pixels.

Exceptions

std::runtime_error on non-positive focal lengths.

References place_explicit_camera().

Referenced by place_explicit_camera().

◆ place_preset_camera()

void reusex::visualize::place_preset_camera	(	vtkRenderer *	renderer,
		const CameraFraming &	framing,
		const SceneBounds &	bounds )

Place renderer's active camera for a preset view of bounds.

Deterministic: a pure function of the bounds (STANDARDS §6).

References place_preset_camera().

Referenced by place_preset_camera().

◆ populate_scene()

SceneInfo reusex::visualize::populate_scene	(	vtkRenderer *	renderer,
		const ProjectDB &	db,
		const SceneOptions &	opts )

Load opts' layers from db and add them to renderer.

Does not touch the camera, the background or any render window.

Exceptions

std::runtime_error when a requested layer's data is missing or out of sync (the message names the stage to run), or when the layers produced no drawable geometry.

References populate_scene().

Referenced by populate_scene().

◆ probe_offscreen_gl()

OffscreenGlProbe reusex::visualize::probe_offscreen_gl ( )

noexcept

Ask EGL whether an offscreen context is possible here.

Loads libEGL at runtime (dlopen), enumerates devices via eglQueryDevicesEXT and tries eglInitialize on each, falling back to EGL_DEFAULT_DISPLAY. A display it initialises is left initialised rather than terminated: an EGL display is a process-global singleton that VTK's own eglInitialize then simply shares, whereas eglTerminate tears down everything on that display and is the less well-behaved half of the pair across drivers. The probe must not be able to break the render it is clearing the way for.

Runtime loading rather than a link-time dependency is deliberate: whether EGL exists at all is exactly what is being asked, the answer is a property of the machine and not of the build, and it keeps a build with no EGL development package from losing the diagnosis it needs most.

Costs one dlopen and a few EGL calls (single-digit milliseconds). Callers that render in a loop should cache the result; it cannot change within a process.

Setting the environment variable REUSEX_SKIP_EGL_PROBE to a non-empty value makes this return OffscreenGlStatus::unknown without touching EGL — an escape hatch for a configuration the probe judges wrongly, which lets the old (crash-prone) behaviour be reached deliberately rather than by accident.

Never throws: a probe that fails is a verdict, not an error.

References probe_offscreen_gl().

Referenced by probe_offscreen_gl().

◆ render_view()

cv::Mat reusex::visualize::render_view	(	const ProjectDB &	db,
		const RenderOptions &	opts )

Render one view of db to an image.

Deterministic: every preset camera is derived from the bounding box of the geometry actually drawn, so two runs over the same project frame the same shot (STANDARDS §6).

Side effect, once per process: VTK's own diagnostics are rerouted into ReUseX logging (core/logging.hpp) and its stderr sink is switched off, so library code does not write to stderr behind the caller's back. This is global to VTK and is not undone — a process that also opens the interactive viewer will see its VTK messages through the ReUseX log too.

Parameters

db	An open project. Only read.
opts	What and how to draw.

Returns: An 8-bit 3-channel BGR image of size opts.width x opts.height, ready for cv::imwrite.

Exceptions

OffscreenGlUnavailable	if the machine has no usable offscreen OpenGL implementation — probed before any rendering happens, so this is reported rather than crashed on (#313).
std::runtime_error	if the project is not open, the options are invalid, a requested layer's data is missing (the message names the stage to run first), or the framebuffer comes back at the wrong size.

References render_view().

Referenced by render_view().

◆ resolve_cut_plane()

CutPlane reusex::visualize::resolve_cut_plane	(	const ProjectDB &	db,
		const SceneBounds &	bounds,
		std::optional< double >	height )

Decide where to cut bounds: height (or the default) above the floor detected by rux create planes, or above the bounding box's lower face.

Warns when the cut is above or below everything drawn (STANDARDS §5).

References resolve_cut_plane().

Referenced by resolve_cut_plane().

◆ to_string() [1/3]

std::string_view reusex::visualize::to_string ( Layer layer )

The canonical name of layer (the inverse of layer_from_string).

References to_string().

Referenced by to_string(), to_string(), and to_string().

◆ to_string() [2/3]

std::string_view reusex::visualize::to_string ( LodMethod method )

References to_string().

◆ to_string() [3/3]

std::string_view reusex::visualize::to_string ( ViewPreset view )

The canonical name of view, as accepted by rux render --view.

orbit and explicit_camera name the mode; the CLI spells them orbit:N and frame:<node_id> because both need a parameter.

References to_string().

◆ view_preset_from_string()

std::optional< ViewPreset > reusex::visualize::view_preset_from_string ( std::string_view name )

Parse a bare view-preset name.

Returns: std::nullopt if name is not one.

References view_preset_from_string().

Referenced by view_preset_from_string().

◆ viewport_bounds()

ViewportBounds reusex::visualize::viewport_bounds	(	std::size_t	index,
		std::size_t	total,
		float	left = 0.0f,
		float	top = 0.0f,
		float	right = 1.0f,
		float	bottom = 1.0f,
		bool	split_horizontal = true )

Compute the normalized bounds for one viewport in an N-way split layout.

Uses recursive binary space partitioning to tile the unit square into total non-overlapping viewports. Even counts are split evenly in half (alternating horizontal / vertical), while odd counts give the first viewport a larger (60%) region and recursively split the remainder.

This is pure geometry (no rendering dependencies) so it can be unit tested independently of any visualization backend.

Parameters

index	Index of the viewport (0-based, must be < total)
total	Total number of viewports (must be >= 1)
left	Left bound of the current area (default 0.0)
top	Top bound of the current area (default 0.0)
right	Right bound of the current area (default 1.0)
bottom	Bottom bound of the current area (default 1.0)
split_horizontal	Whether to split horizontally first (default true)

Returns: ViewportBounds for the requested viewport

References viewport_bounds().

Referenced by viewport_bounds().

Variable Documentation

◆ kDefaultCutBboxFraction

double reusex::visualize::kDefaultCutBboxFraction = 0.45

inlineconstexpr

Fallback cut height when no floor plane is available, as a fraction of the scene's vertical extent.

A height in metres would be meaningless there — with no segmentation to locate the floor the reference is the bounding box's lower face, which a single stray point can put well below the real floor.

Definition at line 124 of file render_view.hpp.

◆ kDefaultCutHeightM

double reusex::visualize::kDefaultCutHeightM = 1.2

inlineconstexpr

Default height of the plan cut above the detected floor, in metres.

Waist height: above every sill and below every soffit, so a plan shows door and window openings in section the way a drawn plan does.

Definition at line 116 of file render_view.hpp.

◆ kHighlightDimFactor

double reusex::visualize::kHighlightDimFactor = 0.3

inlineconstexpr

Brightness multiplier applied to every non-highlighted point's colour.

Definition at line 23 of file highlight.hpp.

◆ kHighlightRgb

std::array<unsigned char, 3> reusex::visualize::kHighlightRgb {255, 176, 64}

inlineconstexpr

Accent colour painted onto the highlighted instance's points.

Definition at line 20 of file highlight.hpp.

◆ kHorizontalNormalZ

double reusex::visualize::kHorizontalNormalZ = 0.95

inlineconstexpr

|n_z| above which a segmented plane counts as horizontal when looking for the floor.

Same split the real-scan fixture test asserts on the office corridor, so "horizontal" means the same thing in both places.

Definition at line 129 of file render_view.hpp.

◆ kInvalidSlot

int reusex::visualize::kInvalidSlot = -2

inlineconstexpr

Definition at line 70 of file scene.hpp.

◆ kUnlabeledSlot

int reusex::visualize::kUnlabeledSlot = -1

inlineconstexpr

Sentinel slots of label_palette_slot().

Definition at line 69 of file scene.hpp.

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ Layer

◆ LodMethod

◆ OffscreenGlStatus

◆ ViewPreset

Function Documentation

◆ all_layers()

◆ apply_cut_plane()

◆ apply_instance_highlight()

◆ camera_from_sensor_frame()

◆ clear_cut_planes()

◆ default_label_palette()

◆ display_configured()

◆ install_vtk_log_bridge()

◆ label_palette_color()

◆ label_palette_slot()

◆ layer_from_string()

◆ lod_indices()

◆ place_explicit_camera()

◆ place_preset_camera()

◆ populate_scene()

◆ probe_offscreen_gl()

◆ render_view()

◆ resolve_cut_plane()

◆ to_string() [1/3]

◆ to_string() [2/3]

◆ to_string() [3/3]

◆ view_preset_from_string()

◆ viewport_bounds()

Variable Documentation

◆ kDefaultCutBboxFraction

◆ kDefaultCutHeightM

◆ kHighlightDimFactor

◆ kHighlightRgb

◆ kHorizontalNormalZ

◆ kInvalidSlot

◆ kUnlabeledSlot