Provide simple visualization of and interaction with a Simbody simulation, with real time control of the frame rate. There are several operating modes available, including real time operation permitting responsive user interaction with the simulation. More...

Classes
class	BodyFollower
	Causes the camera to point at and follow a point fixed on a body (a station). More...

class	FrameController
	This abstract class represents an object that will be invoked by the Visualizer just prior to rendering each frame. More...

class	InputListener
	This abstract class defines methods to be called when the Visualizer reports user activity back to the simulation process. Derive a concrete event listener whose methods take appropriate actions when event of interest occur. More...

class	InputSilo
	This pre-built InputListener is extremely useful for processing user input that is intended to affect a running simulation. More...

class	Reporter
	This is an EventReporter that makes it easy to generate on-screen movies of any simulation. More...

Public Types
enum	Mode { PassThrough = 1, Sampling = 2, RealTime = 3 }
	These are the operating modes for the Visualizer, with PassThrough the default mode. More...

enum	BackgroundType { GroundAndSky = 1, SolidColor = 2 }
	These are the types of backgrounds the visualizer currently supports. More...

enum	PredefinedMenuIds { ViewMenuId = -1 }
	The visualizer may predefine some menus; if you need to refer to one of those use its menu Id as defined here. More...

Public Member Functions
	Visualizer (const MultibodySystem &system)
	Construct a new Visualizer for the indicated System, and launch the visualizer display executable from a default or specified location. More...

	Visualizer (const MultibodySystem &system, const Array_< String > &searchPath)
	Construct a new Visualizer for a given system, with a specified search path for locating the SimbodyVisualizer executable. More...

	Visualizer (const Visualizer &src)
	Copy constructor has reference counted, shallow copy semantics; that is, the Visualizer copy is just another reference to the same Visualizer object. More...

Visualizer &	operator= (const Visualizer &src)
	Copy assignment has reference counted, shallow copy semantics; that is, the Visualizer copy is just another reference to the same Visualizer object. More...

	~Visualizer ()
	InputListener, FrameController, and DecorationGenerator objects are destroyed here when the last reference is deleted. More...

void	shutdown ()
	Ask the visualizer to shut itself down immediately. More...

Visualizer &	setShutdownWhenDestructed (bool shouldShutdown)
	Set the flag that determines whether we will automatically send a Shutdown message to the visualizer when this Visualizer object is destructed. More...

bool	getShutdownWhenDestructed () const
	Return the current setting of the "shutdown when destructed" flag. More...

visualizer display options
These methods provide programmatic control over some of the visualizer's display options. Typically these can be overridden by the user directly in the GUI, but these are useful for setting sensible defaults. In particular, the Ground and Sky background, which is the GUI default, is not appropriate for some systems (molecules for example).
Visualizer &	setBackgroundType (BackgroundType background)
	Change the background mode currently in effect in the GUI. By default we take the desired background type from the System, which will usually be at its default value which is to show a ground plane and sky. More...

const Visualizer &	setBackgroundColor (const Vec3 &color) const
	Set the background color. This will be used when the solid background mode is in effect but has no effect otherwise. More...

const Visualizer &	setShowShadows (bool showShadows) const
	Control whether shadows are generated when the GroundAndSky background type is in effect. This has no effect if the ground plane is not being displayed. More...

const Visualizer &	setShowFrameRate (bool showFrameRate) const
	Control whether frame rate is shown in the Visualizer. This is a const method so you can call it from within a FrameController. More...

const Visualizer &	setShowSimTime (bool showSimTime) const
	Control whether simulation time is shown in the Visualizer. This is a const method so you can call it from within a FrameController. More...

const Visualizer &	setShowFrameNumber (bool showFrameNumber) const
	Control whether frame number is shown in the Visualizer. This is a const method so you can call it from within a FrameController. More...

const Visualizer &	setWindowTitle (const String &title) const
	Change the title on the main visualizer window. The default title is Simbody version : exename, where version is the current Simbody version number in major.minor.patch format and exename is the name of the executing simulation application's executable file (without suffix if any). More...

Visualizer options
These methods are used for setting a variety of options for the Visualizer's behavior, normally prior to sending it the first frame.
Visualizer &	setSystemUpDirection (const CoordinateDirection &upDirection)
	Set the coordinate direction that should be considered the System's "up" direction. When the ground and sky background is in use, this is the direction that serves as the ground plane normal, and is used as the initial orientation for the camera's up direction (which is subsequently under user or program control and can point anywhere). More...

CoordinateDirection	getSystemUpDirection () const
	Get the value the Visualizer is using as the System "up" direction ( not to be confused with the camera "up" direction). More...

Visualizer &	setGroundHeight (Real height)
	Set the height at which the ground plane should be displayed when the GroundAndSky background type is in effect. This is interpreted along the system "up" direction that was specified in the Visualizer's System or was overridden with the setSystemUpDirection() method. More...

Real	getGroundHeight () const
	Get the value the Visualizer considers to be the height of the ground plane for this System. The value must be interpreted along the System's "up" direction. More...

Visualizer &	setMode (Mode mode)
	Set the operating mode for the Visualizer. More...

Mode	getMode () const
	Get the current mode being used by the Visualizer. More...

Visualizer &	setDesiredFrameRate (Real framesPerSec)
	Set the frame rate in frames/sec (of real time) that you want the Visualizer to attempt to achieve. More...

Real	getDesiredFrameRate () const
	Get the current value of the frame rate the Visualizer has been asked to attempt; this is not necessarily the rate actually achieved. More...

Visualizer &	setRealTimeScale (Real simTimePerRealSecond)
	In RealTime mode we normally assume that one unit of simulated time should map to one second of real time; however, in some cases the time units are not seconds, and in others you may want to run at some multiple or fraction of real time. More...

Real	getRealTimeScale () const
	Return the current time scale, which will be 1 by default. More...

Visualizer &	setDesiredBufferLengthInSec (Real bufferLengthInSec)
	When running an interactive realtime simulation, you can smooth out changes in simulation run rate by buffering frames before sending them on for rendering. More...

Real	getDesiredBufferLengthInSec () const
	Get the current value of the desired buffer time length the Visualizer has been asked to use for smoothing the frame rate, or the default value if none has been requested. More...

Real	getActualBufferLengthInSec () const
	Get the actual length of the real time frame buffer in seconds, which may differ from the requested time because the buffer contains an integer number of frames. More...

int	getActualBufferLengthInFrames () const
	Get the actual length of the real time frame buffer in number of frames. More...

int	addInputListener (InputListener *listener)
	Add a new input listener to this Visualizer, methods of which will be called when the GUI detects user-driven events like key presses, menu picks, and slider or mouse moves. More...

int	getNumInputListeners () const
	Return the count of input listeners added with addInputListener(). More...

const InputListener &	getInputListener (int i) const
	Return a const reference to the i'th input listener. More...

InputListener &	updInputListener (int i)
	Return a writable reference to the i'th input listener. More...

int	addFrameController (FrameController *controller)
	Add a new frame controller to this Visualizer, methods of which will be called just prior to rendering a frame for the purpose of simulation-controlled camera positioning and other frame-specific effects. More...

int	getNumFrameControllers () const
	Return the count of frame controllers added with addFrameController(). More...

const FrameController &	getFrameController (int i) const
	Return a const reference to the i'th frame controller. More...

FrameController &	updFrameController (int i)
	Return a writable reference to the i'th frame controller. More...

Frame drawing methods
These are used to report simulation frames to the Visualizer. Typically the report() method will be called from a Reporter invoked by a TimeStepper, but it can also be useful to invoke directly to show preliminary steps in a simulation, to replay saved States later, and to display frames when using an Integrator directly rather than through a TimeStepper. How frames are handled after they have been reported depends on the specific method called, and on the Visualizer's current Mode.
void	report (const State &state) const
	Report that a new simulation frame is available for rendering. More...

void	flushFrames () const
	In RealTime mode there will typically be frames still in the buffer at the end of a simulation. This allows you to wait while the buffer empties. More...

void	drawFrameNow (const State &state) const
	This method draws a frame unconditionally without queuing or checking the frame rate. More...

Scene-building methods
These methods are used to add permanent elements to the scene being displayed by the Visualizer. Once added, these elements will contribute to every frame. Calling one of these methods requires writable (non-const) access to the Visualizer object; you can't call them from within a FrameController object. Note that adding DecorationGenerators does allow different geometry to be produced for each frame; however, once added a DecorationGenerator will be called for every frame generated.
Visualizer &	addMenu (const String &title, int id, const Array_< std::pair< String, int > > &items)
	Add a new pull-down menu to the visualizer's display. More...

Visualizer &	addSlider (const String &title, int id, Real min, Real max, Real value)
	Add a new slider to the visualizer's display. More...

int	addDecoration (MobilizedBodyIndex mobodIx, const Transform &X_BD, const DecorativeGeometry &geometry)
	Add an always-present, body-fixed piece of geometry like the one passed in, but attached to the indicated body. More...

int	getNumDecorations () const
	Return the count of decorations added with addDecoration(). More...

const DecorativeGeometry &	getDecoration (int i) const
	Return a const reference to the i'th decoration. More...

DecorativeGeometry &	updDecoration (int i) const
	Return a writable reference to the i'th decoration. More...

int	addRubberBandLine (MobilizedBodyIndex b1, const Vec3 &station1, MobilizedBodyIndex b2, const Vec3 &station2, const DecorativeLine &line)
	Add an always-present rubber band line, modeled after the DecorativeLine supplied here. More...

int	getNumRubberBandLines () const
	Return the count of rubber band lines added with addRubberBandLine(). More...

const DecorativeLine &	getRubberBandLine (int i) const
	Return a const reference to the i'th rubber band line. More...

DecorativeLine &	updRubberBandLine (int i) const
	Return a writable reference to the i'th rubber band line. More...

int	addDecorationGenerator (DecorationGenerator *generator)
	Add a DecorationGenerator that will be invoked to add dynamically generated geometry to each frame of the the scene. More...

int	getNumDecorationGenerators () const
	Return the count of decoration generators added with addDecorationGenerator(). More...

const DecorationGenerator &	getDecorationGenerator (int i) const
	Return a const reference to the i'th decoration generator. More...

DecorationGenerator &	updDecorationGenerator (int i)
	Return a writable reference to the i'th decoration generator. More...

Frame control methods
These methods can be called prior to rendering a frame to control how the camera is positioned for that frame. These can be invoked from within a FrameController object for runtime camera control and other effects. See the Visualizer::BodyFollower class for an example of a FrameController that causes the camera to follow a body.
const Visualizer &	setCameraTransform (const Transform &X_GC) const
	Set the transform defining the position and orientation of the camera. More...

const Visualizer &	zoomCameraToShowAllGeometry () const
	Move the camera forward or backward so that all geometry in the scene is visible. More...

const Visualizer &	pointCameraAt (const Vec3 &point, const Vec3 &upDirection) const
	Rotate the camera so that it looks at a specified point. More...

const Visualizer &	setCameraFieldOfView (Real fov) const
	Set the camera's vertical field of view, measured in radians. More...

const Visualizer &	setCameraClippingPlanes (Real nearPlane, Real farPlane) const
	Set the distance from the camera to the near and far clipping planes. More...

const Visualizer &	setSliderValue (int slider, Real value) const
	Change the value currently shown on one of the sliders. More...

const Visualizer &	setSliderRange (int slider, Real newMin, Real newMax) const
	Change the allowed range for one of the sliders. More...

Methods for debugging and statistics
void	dumpStats (std::ostream &o) const
	Dump statistics to the given ostream (for example, std::cout). More...

void	clearStats ()
	Reset all statistics to zero. More...

Internal use only
const Array_< InputListener * > &	getInputListeners () const

const Array_< FrameController * > &	getFrameControllers () const

const MultibodySystem &	getSystem () const

int	getRefCount () const

Friends
class	Impl

Detailed Description

Provide simple visualization of and interaction with a Simbody simulation, with real time control of the frame rate. There are several operating modes available, including real time operation permitting responsive user interaction with the simulation.

Frames are sent to the renderer at a regular interval that is selectable, with a default rate of 30 frames/second. The various operating modes provide different methods of controlling which simulation frames are selected and how they are synchronized for display.

Visualization modes

There are three operating modes for the Visualizer's display of simulation results, selectable via setMode():

PassThrough. This is the default mode. It sends through to the renderer every frame that is received from the simulation, slowing down the simulation if necessary so that the frames are presented at a selected frame rate. But note that the simulation time will not be synchronized to real time; because Simbody simulations generally proceed at a variable rate, the regularly-spaced output frames will represent different amounts of simulated time. If you want real time and simulation time synchronized, use the RealTime mode.
Sampling. This mode is useful for monitoring a simulation that is allowed to run at full speed. We send frames for display at a maximum rate given by the frame rate setting. After a frame is sent, all subsequent frames received from the simulation are ignored until the frame interval has passed; then the next received frame is displayed. This allows the simulation to proceed at the fastest rate possible but time will be irregular and not all frames generated by the simulation will be shown.
RealTime. Synchronize frame times with the simulated time, slowing down the simulation if it is running ahead of real time, as modifed by the time scale; see setRealTimeScale(). Frames are sent to the renderer at the selected frame rate. Smoothness is maintained by buffering up frames before sending them; interactivity is maintained by keeping the buffer length below human perception time (150-200ms). The presence and size of the buffer is selectable; see setDesiredBufferLengthInSec().

User interaction

The Simbody visualizer provides some user interaction of its own, for example allowing the user to control the viewpoint and display options. User inputs that it does not interpret locally are passed on to the simulation, and can be intercepted by registering InputListeners with the Visualizer. The Visualizer provides a class Visualizer::InputSilo which is an InputListener that simply captures and queues all user input, with the intent that a running simulation will occasionally stop to poll the InputSilo to process any input that has been collected.

Implementation notes

RealTime mode is worth some discussion. There is a simulation thread that produces frames at a variable rate, and a draw thread that consumes frames at a variable rate (by sending them to the renderer). We want to engineer things so that frames are sent to the renderer at a steady rate that is synchronized with simulation time (possibly after scaling). When a thread is running too fast, that is easily handled by blocking the speeding thread for a while. The "too slow" case takes careful handling.

In normal operation, we expect the simulation to take varying amounts of real time to generate fixed amounts of simulation time, because we prefer to use variable time-step integrators that control errors by taking smaller steps in more difficult circumstances, and large steps through the easy parts of the simulation. For real time operation, the simulation must of course average real time performance; we use a frame buffer to smooth out variable delivery times. That is, frames go into the buffer at an irregular rate but are pulled off at a regular rate. A longer buffer can mask wider deviations in frame time, at the expense of interactive response. In most circumstances people cannot perceive delays below about 200ms, so for good response the total delay should be kept around that level.

Despite the buffering, there will be occasions when the simulation can't keep up with real time. A common cause of that is that a user has paused either the simulation or the renderer, such as by hitting a breakpoint while debugging. In that case we deem the proper behavior to be that when we resume we should immediately resume real time behavior at a new start time, not attempt to catch up to the previous real time by running at high speed. As much as possible, we would like the simulation to behave just as it would have without the interruption, but with a long pause where interrupted. We deal with this situation by introducing a notion of "adjusted real time" (AdjRT). That is a clock that tracks the real time interval counter, but uses a variable base offset that is used to match it to the expected simulation time. When the simulation is long delayed, we modify the AdjRT base when we resume so that AdjRT once again matches the simulation time t. Adjustments to the AdjRT base occur at the time we deliver frames to the renderer; at that moment we compare the AdjRT reading to the frame's simulation time t and correct AdjRT for future frames.

You can also run in RealTime mode without buffering. In that case frames are sent directly from the simulation thread to the renderer, but the above logic still applies. Simulation frames that arrive earlier than the corresponding AdjRT are delayed; frames that arrive later are drawn immediately but cause AdjRT to be readjusted to resynchronize. Overall performance can be better in unbuffered RealTime mode because the States provided by the simulation do not have to be copied before being drawn. However, intermittent slower-than- realtime frame times cannot be smoothed over; they will cause rendering delays.

PassThrough and Sampling modes are much simpler because no synchronization is done to the simulation times. There is only a single thread and draw time scheduling works in real time without adjustment.

With the above explanation, you may be able to figure out most of what comes out of the dumpStats() method which can be used to help diagnose performance problems.

Member Enumeration Documentation

◆ Mode

enum SimTK::Visualizer::Mode

These are the operating modes for the Visualizer, with PassThrough the default mode.

See the documentation for the Visualizer class for more information about the modes.

Enumerator
PassThrough	Send through to the renderer every frame that is received from the simulator (default mode).
Sampling	Sample the results from the simulation at fixed real time intervals given by the frame rate.
RealTime	Synchronize real frame display times with the simulated time.

◆ BackgroundType

enum SimTK::Visualizer::BackgroundType

These are the types of backgrounds the visualizer currently supports.

You can choose what type to use programmatically, and users can override that choice in the GUI. Each of these types may use additional data (such as the background color) when the type is selected.

Enumerator
GroundAndSky	Show a ground plane on which shadows may be cast, as well as a sky in the far background.
SolidColor	Display a solid background color that has been provided elsewhere.

◆ PredefinedMenuIds

enum SimTK::Visualizer::PredefinedMenuIds

The visualizer may predefine some menus; if you need to refer to one of those use its menu Id as defined here.

Note that the id numbers here are negative numbers, which are not allowed for user-defined menu ids.

Enumerator
ViewMenuId	The id of the predefined View pull-down.

Constructor & Destructor Documentation

◆ Visualizer() [1/3]

SimTK::Visualizer::Visualizer ( const MultibodySystem & system )

explicit

Construct a new Visualizer for the indicated System, and launch the visualizer display executable from a default or specified location.

The camera's "up" direction will initially be set to match the "up" direction hint that is stored with the supplied system; the default is that "up" is in the direction of the positive Y axis. The background will normally include a ground plane and sky, but if the system has been set to request a uniform background we'll use a plain white background instead. You can override the chosen defaults using Visualizer methods setSystemUpDirection() and setBackgroundType().

Simbody is shipped with a separate executable program simbody-visualizer (simbody-visualizer_d if building as Debug) that provides the graphics display and collects user input. Normally that executable is installed in the "bin" subdirectory of the Simbody installation directory. However, first we look in the same directory as the currently-running executable and, if found, we will use that visualizer. If no visualizer is found with the executable, we check if environment variables SIMBODY_HOME or SimTK_INSTALL_DIR exist, and look in their "bin" (or "libexec/simbody" on UNIX) subdirectories if so. Next, we attempt to use the relative path from the SimTKsimbody library to the simbody-visualizer (this helps if Simbody is relocated, but does not work on Windows, or if using static Simbody libraries). Then, we check the installed location of the visualizer, as specified when Simbody is compiled. If the visualizer is not there, we'll look in platform-specific default locations. The other constructor allows specification of a search path that will be checked before attempting to find the installation directory.

If you want to override the name of the visualizer executable for which Simbody searches, set the environment variable SIMBODY_VISUALIZER_NAME to the desired executable name. For example, if you want to use the debug visualizer with release libraries, set SIMBODY_VISUALIZER_NAME to simbody-visualizer_d.

The SimTK::Pathname class is used to process the supplied search path, which can consist of absolute, working directory-relative, or executable directory-relative path names.

See also: SimTK::Pathname

◆ Visualizer() [2/3]

SimTK::Visualizer::Visualizer	(	const MultibodySystem &	system,
		const Array_< String > &	searchPath
	)

Construct a new Visualizer for a given system, with a specified search path for locating the SimbodyVisualizer executable.

The search path is checked after looking in the current executable directory, and before trying to locate the Simbody or SimTK installation directory. See the other constructor's documentation for more information.

◆ Visualizer() [3/3]

SimTK::Visualizer::Visualizer ( const Visualizer & src )

Copy constructor has reference counted, shallow copy semantics; that is, the Visualizer copy is just another reference to the same Visualizer object.

◆ ~Visualizer()

SimTK::Visualizer::~Visualizer ( )

InputListener, FrameController, and DecorationGenerator objects are destroyed here when the last reference is deleted.

Member Function Documentation

◆ operator=()

Visualizer& SimTK::Visualizer::operator= ( const Visualizer & src )

Copy assignment has reference counted, shallow copy semantics; that is, the Visualizer copy is just another reference to the same Visualizer object.

◆ shutdown()

void SimTK::Visualizer::shutdown ( )

Ask the visualizer to shut itself down immediately.

This will cause the display window to close and the associated process to die. This method returns immediately but it may be some time later when the visualizer acts on the instruction; there is no way to wait for it to die. Normally the visualizer will persist even after the death of the simulator connection unless you have called setShutdownWhenDestructed() to make shutdown() get called automatically.

See also: setShutdownWhenDestructed()

◆ setShutdownWhenDestructed()

Visualizer& SimTK::Visualizer::setShutdownWhenDestructed ( bool shouldShutdown )

Set the flag that determines whether we will automatically send a Shutdown message to the visualizer when this Visualizer object is destructed.

Normally we allow the GUI to persist even after death of the simulator connection, unless an explicit call to shutdown() is made.

See also: getShutdownWhenDestructed(), shutdown()

◆ getShutdownWhenDestructed()

bool SimTK::Visualizer::getShutdownWhenDestructed ( ) const

Return the current setting of the "shutdown when destructed" flag.

By default this is false.

See also: setShutdownWhenDestructed(), shutdown()

◆ setBackgroundType()

Visualizer& SimTK::Visualizer::setBackgroundType ( BackgroundType background )

Change the background mode currently in effect in the GUI. By default we take the desired background type from the System, which will usually be at its default value which is to show a ground plane and sky.

You can override that default choice with this method.

Parameters

background The background type to use.

Returns: A reference to this Visualizer so that you can chain "set" calls.

Note: Molmodel's CompoundSystem requests a solid background by default, since ground and sky is not the best way to display a molecule!

◆ setBackgroundColor()

const Visualizer& SimTK::Visualizer::setBackgroundColor ( const Vec3 & color ) const

Set the background color. This will be used when the solid background mode is in effect but has no effect otherwise.

This is a const method so you can call it from within a FrameController, for example if you want to flash the background color.

Parameters

color The background color in r,g,b format with [0,1] range.

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

◆ setShowShadows()

const Visualizer& SimTK::Visualizer::setShowShadows ( bool showShadows ) const

Control whether shadows are generated when the GroundAndSky background type is in effect. This has no effect if the ground plane is not being displayed.

The default if for shadows to be displayed. This is a const method so you can call it from within a FrameController.

Parameters

showShadows Set true to have shadows generated; false for none.

See also: setBackgroundType()

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

◆ setShowFrameRate()

const Visualizer& SimTK::Visualizer::setShowFrameRate ( bool showFrameRate ) const

Control whether frame rate is shown in the Visualizer. This is a const method so you can call it from within a FrameController.

Parameters

showFrameRate Set true to show the frame rate; false for none.

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

◆ setShowSimTime()

const Visualizer& SimTK::Visualizer::setShowSimTime ( bool showSimTime ) const

Control whether simulation time is shown in the Visualizer. This is a const method so you can call it from within a FrameController.

Parameters

showSimTime Set true to show the simulation time; false for none.

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

◆ setShowFrameNumber()

const Visualizer& SimTK::Visualizer::setShowFrameNumber ( bool showFrameNumber ) const

Control whether frame number is shown in the Visualizer. This is a const method so you can call it from within a FrameController.

Parameters

showFrameNumber Set true to show the frame number; false for none.

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

◆ setWindowTitle()

const Visualizer& SimTK::Visualizer::setWindowTitle ( const String & title ) const

Change the title on the main visualizer window. The default title is Simbody version : exename, where version is the current Simbody version number in major.minor.patch format and exename is the name of the executing simulation application's executable file (without suffix if any).

Parameters

[in] title The new window title. The amount of room for the title varies; keep it short.

Returns: A const reference to this Visualizer so that you can chain "set" calls, provided subsequent ones are also const.

See also: SimTK_version_simbody(), Pathname::getThisExecutablePath(), Pathname::desconstructPathname()

◆ setSystemUpDirection()

Visualizer& SimTK::Visualizer::setSystemUpDirection ( const CoordinateDirection & upDirection )

Set the coordinate direction that should be considered the System's "up" direction. When the ground and sky background is in use, this is the direction that serves as the ground plane normal, and is used as the initial orientation for the camera's up direction (which is subsequently under user or program control and can point anywhere).

If you don't set this explicitly here, the Visualizer takes the default up direction from the System, which provides a method allowing the System's creator to specify it, with the +Y axis being the default.

Parameters

[in] upDirection This must be one of the CoordinateAxis constants XAxis, YAxis, or ZAxis, or one of the opposite directions -XAxis, -YAxis, or -ZAxis.

Returns: A writable reference to this Visualizer so that you can chain "set" calls in the manner of chained assignments.

◆ getSystemUpDirection()

CoordinateDirection SimTK::Visualizer::getSystemUpDirection ( ) const

Get the value the Visualizer is using as the System "up" direction ( not to be confused with the camera "up" direction).

◆ setGroundHeight()

Visualizer& SimTK::Visualizer::setGroundHeight ( Real height )

Set the height at which the ground plane should be displayed when the GroundAndSky background type is in effect. This is interpreted along the system "up" direction that was specified in the Visualizer's System or was overridden with the setSystemUpDirection() method.

The default value is zero, meaning that the ground plane passes through the ground origin.

Parameters

height The position of the ground plane along the system "up" direction that serves as the ground plane normal. Note that height is along the up direction, meaning that if up is one of the negative coordinate axis directions a positive height will move the ground plane to a more negative position.

Returns: A reference to this Visualizer so that you can chain "set" calls.

See also: setSystemUpDirection(), setBackgroundType()

◆ getGroundHeight()

Real SimTK::Visualizer::getGroundHeight ( ) const

Get the value the Visualizer considers to be the height of the ground plane for this System. The value must be interpreted along the System's "up" direction.

See also: setSystemUpDirection()

◆ setMode()

Visualizer& SimTK::Visualizer::setMode ( Mode mode )

Set the operating mode for the Visualizer.

See Visualizer::Mode for choices, and the discussion for the Visualizer class for meanings.

Parameters

[in] mode The new Mode to use.

Returns: A reference to this Visualizer so that you can chain "set" calls.

◆ getMode()

Mode SimTK::Visualizer::getMode ( ) const

Get the current mode being used by the Visualizer.

See Visualizer::Mode for the choices, and the discussion for the Visualizer class for meanings.

◆ setDesiredFrameRate()

Visualizer& SimTK::Visualizer::setDesiredFrameRate ( Real framesPerSec )

Set the frame rate in frames/sec (of real time) that you want the Visualizer to attempt to achieve.

This affects all modes. The default is 30 frames per second. Set the frame rate to zero to return to the default behavior.

Parameters

[in] framesPerSec The desired frame rate; specify as zero to get the default.

Returns: A reference to this Visualizer so that you can chain "set" calls.

◆ getDesiredFrameRate()

Real SimTK::Visualizer::getDesiredFrameRate ( ) const

Get the current value of the frame rate the Visualizer has been asked to attempt; this is not necessarily the rate actually achieved.

A return value of zero means the Visualizer is using its default frame rate, which may be dependent on the current operating mode.

See also: setDesiredFrameRate() for more information.

◆ setRealTimeScale()

Visualizer& SimTK::Visualizer::setRealTimeScale ( Real simTimePerRealSecond )

In RealTime mode we normally assume that one unit of simulated time should map to one second of real time; however, in some cases the time units are not seconds, and in others you may want to run at some multiple or fraction of real time.

Here you can say how much simulated time should equal one second of real time. For example, if your simulation runs in seconds, but you want to run twice as fast as real time, then call setRealTimeScale(2.0), meaning that two simulated seconds will pass for every one real second. This call will have no immediate effect if you are not in RealTime mode, but the value will be remembered.

Parameters

[in] simTimePerRealSecond The number of units of simulation time that should be displayed in one second of real time. Zero or negative value will be interpeted as the default ratio of 1:1.

Returns: A reference to this Visualizer so that you can chain "set" calls.

◆ getRealTimeScale()

Real SimTK::Visualizer::getRealTimeScale ( ) const

Return the current time scale, which will be 1 by default.

See also: setRealTimeScale() for more information.

◆ setDesiredBufferLengthInSec()

Visualizer& SimTK::Visualizer::setDesiredBufferLengthInSec ( Real bufferLengthInSec )

When running an interactive realtime simulation, you can smooth out changes in simulation run rate by buffering frames before sending them on for rendering.

The length of the buffer introduces an intentional response time lag from when a user reacts to when he can see a response from the simulator. Under most circumstances a lag of 150-200ms is undetectable. The default buffer length is the time represented by the number of whole frames that comes closest to 150ms; 9 frames at 60fps, 5 at 30fps, 4 at 24fps, etc. To avoid frequent block/unblocking of the simulation thread, the buffer is not kept completely full; you can use dumpStats() if you want to see how the buffer was used during a simulation. Shorten the buffer to improve responsiveness at the possible expense of smoothness. Note that the total lag time includes not only the buffer length here, but also lag induced by the time stepper taking steps that are larger than the frame times. For maximum responsiveness you should keep the integrator step sizes limited to about 100ms, or reduce the buffer length so that worst-case lag doesn't go much over 200ms.

Parameters

[in] bufferLengthInSec This is the target time length for the buffer. The actual length is the nearest integer number of frames whose frame times add up closest to the request. If you ask for a non-zero value, you will always get at least one frame in the buffer. If you ask for zero, you'll get no buffering at all. To restore the buffer length to its default value, pass in a negative number.

Returns: A reference to this Visualizer so that you can chain "set" calls.

◆ getDesiredBufferLengthInSec()

Real SimTK::Visualizer::getDesiredBufferLengthInSec ( ) const

Get the current value of the desired buffer time length the Visualizer has been asked to use for smoothing the frame rate, or the default value if none has been requested.

The actual value will differ from this number because the buffer must contain an integer number of frames.

See also: getActualBufferTime() to see the frame-rounded buffer length

◆ getActualBufferLengthInSec()

Real SimTK::Visualizer::getActualBufferLengthInSec ( ) const

Get the actual length of the real time frame buffer in seconds, which may differ from the requested time because the buffer contains an integer number of frames.

◆ getActualBufferLengthInFrames()

int SimTK::Visualizer::getActualBufferLengthInFrames ( ) const

Get the actual length of the real time frame buffer in number of frames.

◆ addInputListener()

int SimTK::Visualizer::addInputListener ( InputListener * listener )

Add a new input listener to this Visualizer, methods of which will be called when the GUI detects user-driven events like key presses, menu picks, and slider or mouse moves.

See Visualizer::InputListener for more information. The Visualizer takes over ownership of the supplied listener object and deletes it upon destruction of the Visualizer; don't delete it yourself.

Returns: An integer index you can use to find this input listener again.

◆ getNumInputListeners()

int SimTK::Visualizer::getNumInputListeners ( ) const

Return the count of input listeners added with addInputListener().

◆ getInputListener()

const InputListener& SimTK::Visualizer::getInputListener ( int i ) const

Return a const reference to the i'th input listener.

◆ updInputListener()

InputListener& SimTK::Visualizer::updInputListener ( int i )

Return a writable reference to the i'th input listener.

◆ addFrameController()

int SimTK::Visualizer::addFrameController ( FrameController * controller )

Add a new frame controller to this Visualizer, methods of which will be called just prior to rendering a frame for the purpose of simulation-controlled camera positioning and other frame-specific effects.

See Visualizer::FrameController for more information. The Visualizer takes over ownership of the supplied controller object and deletes it upon destruction of the Visualizer; don't delete it yourself.

Returns: An integer index you can use to find this frame controller again.

◆ getNumFrameControllers()

int SimTK::Visualizer::getNumFrameControllers ( ) const

Return the count of frame controllers added with addFrameController().

◆ getFrameController()

const FrameController& SimTK::Visualizer::getFrameController ( int i ) const

Return a const reference to the i'th frame controller.

◆ updFrameController()

FrameController& SimTK::Visualizer::updFrameController ( int i )

Return a writable reference to the i'th frame controller.

◆ report()

void SimTK::Visualizer::report ( const State & state ) const

Report that a new simulation frame is available for rendering.

Depending on the current Visualizer::Mode, handling of the frame will vary:

PassThrough: All frames will be rendered, but the calling thread (that is, the simulation) may be blocked if the next frame time has not yet been reached or if the renderer is unable to keep up with the rate at which frames are being supplied by the simulation.

Sampling: The frame will be rendered immediately if the next sample time has been reached or passed, otherwise the frame will be ignored and report() will return immediately.

RealTime: Frames are queued to smooth out the time stepper's variable time steps. The calling thread may be blocked if the buffer is full, or if the simulation time is too far ahead of real time. Frames will be dropped if they come too frequently; only the ones whose simulated times are at or near a frame time will be rendered. Frames that come too late will be queued for rendering as soon as possible, and also reset the expected times for subsequent frames so that real time operation is restored.

◆ flushFrames()

void SimTK::Visualizer::flushFrames ( ) const

In RealTime mode there will typically be frames still in the buffer at the end of a simulation. This allows you to wait while the buffer empties.

When this returns, all frames that had been supplied via report() will have been sent to the renderer and the buffer will be empty. Returns immediately if not in RealTime mode, if there is no buffer, or if the buffer is already empty.

◆ drawFrameNow()

void SimTK::Visualizer::drawFrameNow ( const State & state ) const

This method draws a frame unconditionally without queuing or checking the frame rate.

Typically you should use the report() method instead, and let the the internal queuing and timing system decide when to call drawFrameNow().

◆ addMenu()

Visualizer& SimTK::Visualizer::addMenu	(	const String &	title,
		int	id,
		const Array_< std::pair< String, int > > &	items
	)

Add a new pull-down menu to the visualizer's display.

A label for the pull-down button is provided along with an integer identifying the particular menu. A list of (string,int) pairs defines the menu and submenu item labels and associated item numbers. The item numbers must be unique across the entire menu and all its submenus. The strings have a pathname-like syntax, like "submenu/item1", "submenu/item2", "submenu/lowermenu/item1", etc. that is used to define the pulldown menu layout.

Parameters

title	the title to display on the menu's pulldown button
id	an integer value >= 0 that uniquely identifies this menu
items	item names, possibly with submenus as specified above, with associated item numbers When a user picks an item on a menu displayed in the visualizer, that selection is delievered to the simulation application via an InputListener associated with this Visualizer. The selection will be identified by (id, itemNumber) pair.

Returns: A reference to this Visualizer so that you can chain "add" and "set" calls.

◆ addSlider()

Visualizer& SimTK::Visualizer::addSlider	(	const String &	title,
		int	id,
		Real	min,
		Real	max,
		Real	value
	)

Add a new slider to the visualizer's display.

Parameters

title	the title to display next to the slider
id	an integer value that uniquely identifies this slider
min	the minimum value the slider can have
max	the maximum value the slider can have
value	the initial value of the slider, which must be between min and max When a user moves a slider displayed in the visualizer, the new value is delievered to the simulation application via an InputListener associated with this Visualizer. The slider will be identified by the id supplied here.

Returns: A reference to this Visualizer so that you can chain "add" and "set" calls.

◆ addDecoration()

int SimTK::Visualizer::addDecoration	(	MobilizedBodyIndex	mobodIx,
		const Transform &	X_BD,
		const DecorativeGeometry &	geometry
	)

Add an always-present, body-fixed piece of geometry like the one passed in, but attached to the indicated body.

The supplied transform is applied on top of whatever transform is already contained in the supplied geometry, and any body index stored with the geometry is ignored.

Returns: An integer index you can use to find this decoration again.

◆ getNumDecorations()

int SimTK::Visualizer::getNumDecorations ( ) const

Return the count of decorations added with addDecoration().

◆ getDecoration()

const DecorativeGeometry& SimTK::Visualizer::getDecoration ( int i ) const

Return a const reference to the i'th decoration.

◆ updDecoration()

DecorativeGeometry& SimTK::Visualizer::updDecoration ( int i ) const

Return a writable reference to the i'th decoration.

This is allowed for a const Visualizer since it is just a decoration.

◆ addRubberBandLine()

int SimTK::Visualizer::addRubberBandLine	(	MobilizedBodyIndex	b1,
		const Vec3 &	station1,
		MobilizedBodyIndex	b2,
		const Vec3 &	station2,
		const DecorativeLine &	line
	)

Add an always-present rubber band line, modeled after the DecorativeLine supplied here.

The end points of the supplied line are ignored, however: at run time the spatial locations of the two supplied stations are calculated and used as end points.

Returns: An integer index you can use to find this rubber band line again.

◆ getNumRubberBandLines()

int SimTK::Visualizer::getNumRubberBandLines ( ) const

Return the count of rubber band lines added with addRubberBandLine().

◆ getRubberBandLine()

const DecorativeLine& SimTK::Visualizer::getRubberBandLine ( int i ) const

Return a const reference to the i'th rubber band line.

◆ updRubberBandLine()

DecorativeLine& SimTK::Visualizer::updRubberBandLine ( int i ) const

Return a writable reference to the i'th rubber band line.

This is allowed for a const Visualizer since it is just a decoration.

◆ addDecorationGenerator()

int SimTK::Visualizer::addDecorationGenerator ( DecorationGenerator * generator )

Add a DecorationGenerator that will be invoked to add dynamically generated geometry to each frame of the the scene.

The Visualizer assumes ownership of the object passed to this method, and will delete it when the Visualizer is deleted.

Returns: An integer index you can use to find this decoration generator again.

◆ getNumDecorationGenerators()

int SimTK::Visualizer::getNumDecorationGenerators ( ) const

Return the count of decoration generators added with addDecorationGenerator().

◆ getDecorationGenerator()

const DecorationGenerator& SimTK::Visualizer::getDecorationGenerator ( int i ) const

Return a const reference to the i'th decoration generator.

◆ updDecorationGenerator()

DecorationGenerator& SimTK::Visualizer::updDecorationGenerator ( int i )

Return a writable reference to the i'th decoration generator.

◆ setCameraTransform()

const Visualizer& SimTK::Visualizer::setCameraTransform ( const Transform & X_GC ) const

Set the transform defining the position and orientation of the camera.

Parameters

[in] X_GC This is the transform giving the pose of the camera's frame C in the ground frame G; see below for a precise description.

Our camera uses a right-handed frame with origin at the image location, with axes oriented as follows: the x axis is to the right, the y axis is the "up" direction, and the z axis is the "back" direction; that is, the camera is looking in the -z direction. If your simulation coordinate system is different, such as the common "virtual world" system where ground is the x-y plane (x right and y "in") and z is up, be careful to account for that when positioning the camera.

For example, in the virtual world coordinate system, setting X_GC to identity would put the camera at the ground origin with the x axis as expected, but the camera would be looking down (your -z) with the camera's "up" direction aligned with your y. In this case to make the camera look in the y direction with up in z, you would need to rotate it +90 degrees about the x axis:

Visualizer viz;
// ...
// Point camera along Ground's y axis with z up, by rotating the camera
// frame's z axis to align with Ground's -y.
viz.setCameraTransform(Rotation(Pi/2, XAxis));

◆ zoomCameraToShowAllGeometry()

const Visualizer& SimTK::Visualizer::zoomCameraToShowAllGeometry ( ) const

Move the camera forward or backward so that all geometry in the scene is visible.

◆ pointCameraAt()

const Visualizer& SimTK::Visualizer::pointCameraAt	(	const Vec3 &	point,
		const Vec3 &	upDirection
	)		const

Rotate the camera so that it looks at a specified point.

Parameters

point	the point to look at
upDirection	a direction which should point upward as seen by the camera

◆ setCameraFieldOfView()

const Visualizer& SimTK::Visualizer::setCameraFieldOfView ( Real fov ) const

Set the camera's vertical field of view, measured in radians.

◆ setCameraClippingPlanes()

const Visualizer& SimTK::Visualizer::setCameraClippingPlanes	(	Real	nearPlane,
		Real	farPlane
	)		const

Set the distance from the camera to the near and far clipping planes.

◆ setSliderValue()

const Visualizer& SimTK::Visualizer::setSliderValue	(	int	slider,
		Real	value
	)		const

Change the value currently shown on one of the sliders.

Parameters

slider	the id given to the slider when created
value	a new value for the slider; if out of range it will be at one of the extremes

◆ setSliderRange()

const Visualizer& SimTK::Visualizer::setSliderRange	(	int	slider,
		Real	newMin,
		Real	newMax
	)		const

Change the allowed range for one of the sliders.

Parameters

slider	the id given to the slider when created
newMin	the new lower limit on the slider range, <= newMax
newMax	the new upper limit on the slider range, >= newMin The slider's current value remains unchanged if it still fits in the new range, otherwise it is moved to the nearest limit.

◆ dumpStats()

void SimTK::Visualizer::dumpStats ( std::ostream & o ) const

Dump statistics to the given ostream (for example, std::cout).

◆ clearStats()

void SimTK::Visualizer::clearStats ( )

Reset all statistics to zero.

◆ getInputListeners()

const Array_<InputListener*>& SimTK::Visualizer::getInputListeners ( ) const

◆ getFrameControllers()

const Array_<FrameController*>& SimTK::Visualizer::getFrameControllers ( ) const

◆ getSystem()

const MultibodySystem& SimTK::Visualizer::getSystem ( ) const

◆ getRefCount()

int SimTK::Visualizer::getRefCount ( ) const

Friends And Related Function Documentation

◆ Impl

friend class Impl

friend

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

Visualizer.h

Classes

Public Types

Public Member Functions

Friends

Detailed Description

Visualization modes

User interaction

Implementation notes

Member Enumeration Documentation

◆ Mode

◆ BackgroundType

◆ PredefinedMenuIds

Constructor & Destructor Documentation

◆ Visualizer() [1/3]

◆ Visualizer() [2/3]

◆ Visualizer() [3/3]

◆ ~Visualizer()

Member Function Documentation

◆ operator=()

◆ shutdown()

◆ setShutdownWhenDestructed()

◆ getShutdownWhenDestructed()

◆ setBackgroundType()

◆ setBackgroundColor()

◆ setShowShadows()

◆ setShowFrameRate()

◆ setShowSimTime()

◆ setShowFrameNumber()

◆ setWindowTitle()

◆ setSystemUpDirection()

◆ getSystemUpDirection()

◆ setGroundHeight()

◆ getGroundHeight()

◆ setMode()

◆ getMode()

◆ setDesiredFrameRate()

◆ getDesiredFrameRate()

◆ setRealTimeScale()

◆ getRealTimeScale()

◆ setDesiredBufferLengthInSec()

◆ getDesiredBufferLengthInSec()

◆ getActualBufferLengthInSec()

◆ getActualBufferLengthInFrames()

◆ addInputListener()

◆ getNumInputListeners()

◆ getInputListener()

◆ updInputListener()

◆ addFrameController()

◆ getNumFrameControllers()

◆ getFrameController()

◆ updFrameController()

◆ report()

◆ flushFrames()

◆ drawFrameNow()

◆ addMenu()

◆ addSlider()

◆ addDecoration()

◆ getNumDecorations()

◆ getDecoration()

◆ updDecoration()

◆ addRubberBandLine()

◆ getNumRubberBandLines()

◆ getRubberBandLine()

◆ updRubberBandLine()

◆ addDecorationGenerator()

◆ getNumDecorationGenerators()

◆ getDecorationGenerator()

◆ updDecorationGenerator()

◆ setCameraTransform()

◆ zoomCameraToShowAllGeometry()

◆ pointCameraAt()

◆ setCameraFieldOfView()

◆ setCameraClippingPlanes()

◆ setSliderValue()

◆ setSliderRange()

◆ dumpStats()

◆ clearStats()

◆ getInputListeners()

◆ getFrameControllers()

◆ getSystem()