Simbody
3.7
|
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 |
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.
There are three operating modes for the Visualizer's display of simulation results, selectable via setMode():
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.
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.
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.
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. |
|
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.
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.
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.
SimTK::Visualizer::~Visualizer | ( | ) |
InputListener, FrameController, and DecorationGenerator objects are destroyed here when the last reference is deleted.
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.
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.
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.
bool SimTK::Visualizer::getShutdownWhenDestructed | ( | ) | const |
Return the current setting of the "shutdown when destructed" flag.
By default this is false.
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.
background | The background type to use. |
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.
color | The background color in r,g,b format with [0,1] range. |
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.
showShadows | Set true to have shadows generated; false for none. |
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.
showFrameRate | Set true to show the frame rate; false for none. |
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.
showSimTime | Set true to show the simulation time; false for none. |
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.
showFrameNumber | Set true to show the frame number; false for none. |
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).
[in] | title | The new window title. The amount of room for the title varies; keep it short. |
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.
[in] | upDirection | This must be one of the CoordinateAxis constants XAxis, YAxis, or ZAxis, or one of the opposite directions -XAxis, -YAxis, or -ZAxis. |
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).
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.
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. |
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.
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.
[in] | mode | The new Mode to use. |
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.
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.
[in] | framesPerSec | The desired frame rate; specify as zero to get the default. |
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.
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.
[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. |
Real SimTK::Visualizer::getRealTimeScale | ( | ) | const |
Return the current time scale, which will be 1 by default.
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.
[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. |
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.
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.
int SimTK::Visualizer::getActualBufferLengthInFrames | ( | ) | const |
Get the actual length of the real time frame buffer in number of frames.
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.
int SimTK::Visualizer::getNumInputListeners | ( | ) | const |
Return the count of input listeners added with addInputListener().
const InputListener& SimTK::Visualizer::getInputListener | ( | int | i | ) | const |
Return a const reference to the i'th input listener.
InputListener& SimTK::Visualizer::updInputListener | ( | int | i | ) |
Return a writable reference to the i'th input listener.
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.
int SimTK::Visualizer::getNumFrameControllers | ( | ) | const |
Return the count of frame controllers added with addFrameController().
const FrameController& SimTK::Visualizer::getFrameController | ( | int | i | ) | const |
Return a const reference to the i'th frame controller.
FrameController& SimTK::Visualizer::updFrameController | ( | int | i | ) |
Return a writable reference to the i'th frame controller.
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:
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.
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().
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.
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. |
Visualizer& SimTK::Visualizer::addSlider | ( | const String & | title, |
int | id, | ||
Real | min, | ||
Real | max, | ||
Real | value | ||
) |
Add a new slider to the visualizer's display.
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. |
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.
int SimTK::Visualizer::getNumDecorations | ( | ) | const |
Return the count of decorations added with addDecoration().
const DecorativeGeometry& SimTK::Visualizer::getDecoration | ( | int | i | ) | const |
Return a const reference to the i'th decoration.
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.
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.
int SimTK::Visualizer::getNumRubberBandLines | ( | ) | const |
Return the count of rubber band lines added with addRubberBandLine().
const DecorativeLine& SimTK::Visualizer::getRubberBandLine | ( | int | i | ) | const |
Return a const reference to the i'th rubber band line.
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.
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.
int SimTK::Visualizer::getNumDecorationGenerators | ( | ) | const |
Return the count of decoration generators added with addDecorationGenerator().
const DecorationGenerator& SimTK::Visualizer::getDecorationGenerator | ( | int | i | ) | const |
Return a const reference to the i'th decoration generator.
DecorationGenerator& SimTK::Visualizer::updDecorationGenerator | ( | int | i | ) |
Return a writable reference to the i'th decoration generator.
const Visualizer& SimTK::Visualizer::setCameraTransform | ( | const Transform & | X_GC | ) | const |
Set the transform defining the position and orientation of the camera.
[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:
const Visualizer& SimTK::Visualizer::zoomCameraToShowAllGeometry | ( | ) | const |
Move the camera forward or backward so that all geometry in the scene is visible.
const Visualizer& SimTK::Visualizer::pointCameraAt | ( | const Vec3 & | point, |
const Vec3 & | upDirection | ||
) | const |
Rotate the camera so that it looks at a specified point.
point | the point to look at |
upDirection | a direction which should point upward as seen by the camera |
const Visualizer& SimTK::Visualizer::setCameraFieldOfView | ( | Real | fov | ) | const |
Set the camera's vertical field of view, measured in radians.
const Visualizer& SimTK::Visualizer::setCameraClippingPlanes | ( | Real | nearPlane, |
Real | farPlane | ||
) | const |
Set the distance from the camera to the near and far clipping planes.
const Visualizer& SimTK::Visualizer::setSliderValue | ( | int | slider, |
Real | value | ||
) | const |
Change the value currently shown on one of the sliders.
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 |
const Visualizer& SimTK::Visualizer::setSliderRange | ( | int | slider, |
Real | newMin, | ||
Real | newMax | ||
) | const |
Change the allowed range for one of the sliders.
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. |
void SimTK::Visualizer::dumpStats | ( | std::ostream & | o | ) | const |
Dump statistics to the given ostream (for example, std::cout).
void SimTK::Visualizer::clearStats | ( | ) |
Reset all statistics to zero.
const Array_<InputListener*>& SimTK::Visualizer::getInputListeners | ( | ) | const |
const Array_<FrameController*>& SimTK::Visualizer::getFrameControllers | ( | ) | const |
const MultibodySystem& SimTK::Visualizer::getSystem | ( | ) | const |
int SimTK::Visualizer::getRefCount | ( | ) | const |
|
friend |