Visualization

The simulate UI of an Env and loop pacing. More...

Classes
struct	mj_kdl::Viewer

Functions
Status	mj_kdl::open_viewer (Env *env, const char *title="MuJoCo")
void	mj_kdl::clear_trace (Viewer *v)
void	mj_kdl::add_trace_segment (Viewer *v, const KDL::Vector &a, const KDL::Vector &b, const float rgba[4]=nullptr)
void	mj_kdl::add_overlay_arrow (Viewer *v, const KDL::Vector &from, const KDL::Vector &dir, double length, const float rgba[4]=nullptr)
void	mj_kdl::pace_realtime (Env *env)
bool	mj_kdl::is_running (const Viewer *v)
bool	mj_kdl::key_pressed (const Viewer *v, int glfw_key)
void	mj_kdl::capture_key (Viewer *v, int glfw_key, bool capture=true)
bool	mj_kdl::use_camera (Viewer *v, const mjModel *model, const char *name)
void	mj_kdl::set_free_camera (Viewer *v, double distance, double azimuth, double elevation, const std::array< double, 3 > &lookat)

Detailed Description

The simulate UI of an Env and loop pacing.

Use open_viewer() + step() for the simulate UI with physics panels.

The simulate UI owns a user scene merged into every frame; draw your own overlay geometry (e.g. a live end-effector trajectory trace) into it with clear_trace() and add_trace_segment(). Both are no-ops in headless mode.

Function Documentation

add_overlay_arrow()

void mj_kdl::add_overlay_arrow	(	Viewer *	v,
		const KDL::Vector &	from,
		const KDL::Vector &	dir,
		double	length,
		const float	rgba[4] = nullptr )

Append a world-space arrow to the viewer's user scene. Thread-safe. Shares the user scene with add_trace_segment(), so clear_trace() clears both and one call per frame is enough for either. dir need not be normalised; a zero-length dir draws nothing. Silently drops the arrow once the user-scene geom buffer is full. No-op while the viewer is closed (e.g. headless).

Parameters

[in,out]	v	An Env's viewer.
[in]	from	Arrow tail (world frame) [m].
[in]	dir	Direction the arrow points; normalised internally.
[in]	length	Arrow length [m].
[in]	rgba	Optional [r, g, b, a] colour; nullptr -> warm orange.

add_trace_segment()

void mj_kdl::add_trace_segment	(	Viewer *	v,
		const KDL::Vector &	a,
		const KDL::Vector &	b,
		const float	rgba[4] = nullptr )

Append a single line segment to the viewer's user scene. Thread-safe. The render thread merges the user scene into each frame automatically. Silently drops the segment once the user-scene geom buffer is full. No-op while the viewer is closed (e.g. headless).

Parameters

[in,out]	v	An Env's viewer.
[in]	a	Segment start point (world frame) [m].
[in]	b	Segment end point (world frame) [m].
[in]	rgba	Optional [r, g, b, a] colour; nullptr -> warm orange.

capture_key()

void mj_kdl::capture_key	(	Viewer *	v,
		int	glfw_key,
		bool	capture = true )

Claim a key for the caller, so the simulate UI never acts on it.

The UI binds keys of its own: the left and right arrows scrub the history, escape restores the free camera, space pauses. A caller that drives a robot with those keys would otherwise fight the UI for them. A captured key is still reported by key_pressed(); it is only withheld from the UI's own handler.

Parameters

[in,out]	v	An Env's viewer, or nullptr.
[in]	glfw_key	A GLFW key code, e.g. GLFW_KEY_LEFT.
[in]	capture	true to claim the key, false to give it back.

clear_trace()

void mj_kdl::clear_trace

(

Viewer *

v

)

Reset the viewer's user-scene geom count to 0. Call once per frame before appending trace segments with add_trace_segment(). No-op while the viewer is closed (e.g. headless).

Parameters

[in,out]

v

An Env's viewer.

is_running()

bool mj_kdl::is_running

(

const Viewer *

v

)

Returns true while the viewer window is open.

Parameters

[in]

v

An Env's viewer.

Referenced by TEST_F().

key_pressed()

bool mj_kdl::key_pressed	(	const Viewer *	v,
		int	glfw_key )

Whether a key is currently held down in the viewer's window.

The simulate UI opened by open_viewer() owns its GLFW window on the render thread, so a caller driving physics on its own thread must not call glfwGetKey() itself. This reads the key state that the UI's own key callback records, which is safe from any thread.

Keys the UI consumes for itself (',' and '.' for the speed control) are reported like any other.

Parameters

[in]	v	Viewer, or nullptr.
[in]	glfw_key	A GLFW key code, e.g. GLFW_KEY_UP.

Returns

true while the key is held; false for a nullptr or headless viewer, or an out-of-range key code.

open_viewer()

Status mj_kdl::open_viewer	(	Env *	env,
		const char *	title = "MuJoCo" )

Open the simulate UI (panels, physics controls) on env, rendered on a background thread; step() then drives physics, pause, perturbation and recording. Linux (X11 / Wayland) only.

Returns

an error when there is no display or the window cannot be created.

Referenced by main(), main(), TEST_F(), and TEST_F().

pace_realtime()

void mj_kdl::pace_realtime

(

Env *

env

)

Sleep out this step's share of wall time at the viewer's real-time factor. step() never sleeps; a loop that paces itself reads Viewer::realtime_factor instead. No-op headless.

Referenced by main(), and main().

set_free_camera()

void mj_kdl::set_free_camera	(	Viewer *	v,
		double	distance,
		double	azimuth,
		double	elevation,
		const std::array< double, 3 > &	lookat )

Configure the viewer's free orbit camera.

use_camera()

bool mj_kdl::use_camera	(	Viewer *	v,
		const mjModel *	model,
		const char *	name )

Switch the viewer to a named fixed camera defined in the model. Pass nullptr or an empty string to return to the free camera.

Returns

true if the camera name was found; false if not found (viewer unchanged).