reusex::visualize Namespace Reference

Classes
struct	CameraSpec
	An explicit camera: rigid pose plus pinhole intrinsics. 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	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 }
	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...

Functions
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.
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 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.

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); mesh draws a stored mesh and components draws building-component outlines.

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)

Definition at line 42 of file render_view.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 63 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.

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).

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().

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.

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.

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.

to_string() [1/2]

std::string_view reusex::visualize::to_string

(

Layer

layer

)

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

to_string() [2/2]

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.

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.

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

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 118 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 110 of file render_view.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 123 of file render_view.hpp.