7 The Timeline

The play controls are in turn comprised of the following buttons:

The timeline proper is divided into a number of tracks. At the top is the waypoint track, which is used to arrange waypoints and breakpoints. Below that are a variable number of input and output tracks, which are used respectively for arranging the input and output probes.

Waypoints are arranged along the waypoint track at the top of the timeline and are indicated by a small rectangular blue box (Figure 30). A solid box indicates a waypoint that contains a valid state and thus can be advanced to using the fast forward/backward buttons.

To add a waypoint, right-click on the waypoint track. A popup menu will show a number of options, including Add waypoint here, which adds a waypoint at the current location of the time cursor, and Add waypoint(s), which will bring up a dialog prompting for a specific time to add a Waypoint. The "Add Waypoint" dialog also contains a repeat field, which will cause additional waypoints to be added with a spacing indicated by the time value, and an option to create breakpoints instead of waypoints.

Once created, waypoints can be moved by dragging them. They can also be deleted by right-clicking on them and selecting the Delete waypoint option.

To delete all the waypoints, select Delete waypoints, either from the main File menu, or after right-clicking on the waypoint track.

Breakpoints are waypoints that also cause the simulation to stop. They are displayed in red instead of blue.

Breakpoints can be added in the same way as waypoints, i.e., by right clicking on the waypoint track and selecting Add breakpoint here or Add waypoint(s).

Waypoints can be converted into breakpoints (and vice versa) through the context menu.

It is possible to save and load waypoints to and from an external file. The following menu options may be selected to do this, either from the main File menu, or after right-clicking on the waypoint track:

Save waypoints as ...

Brings up a file chooser that allows the user to specify a file for saving all waypoints and their state data. Clicking Save As completes the operation.

Save waypoints

If a waypoint file has already been specified using either “Save waypoints as ...” or “Load waypoints ...”, then all waypoints and their state data are saved to that file.

Load waypoints ...

Brings up a file chooser that allows the user to specify a file from which waypoints and their state data will be loaded. Clicking Load completes the operation. The new waypoints are added to any existing ones, but previously waypoints are not deleted. Checks are made to help ensure that the waypoint data is consistent with the model’s current state.

Reload waypoints

Identical to “Load waypoints ...”, except that it uses a file that has already been specified using either “Save waypoints as ...” or “Load waypoints ...”.

Delete waypoints

Deletes all waypoints except the one at time zero.

Waypoint files are currently stored as binary files. The reason for this is that the required storage is about 1/2 of that required for text files, while the writing and parsing times are as much as faster.

New tracks may be added by right-clicking in the waypoint track and selecting Add input track or Add output track.

The vertical location of a track can be moved by left clicking on it in the left panel and dragging it up or down to a new location.

A track can be deleted by right-clicking on the track in the track panel and selecting Delete track.

A track can be muted or unmuted by clicking on its gray mute button in the track panel (Figure 31). All probes on a muted track are ignored during simulation.

All tracks can be muted, thus disabling all probes, by clicking on the mute all button in the gray panel above the tracks.

A track can be expanded or collapsed by clicking on its green expand button in the track panel (Figure 31). Expanding a track creates an additional area in which the data associated with the track’s probes may be displayed (see Figure 32). The way in which this data is displayed is probe-specific. Probes containing numeric data usually show their data graphically, as described in Section 7.5.

Multiple contiguous tracks can be selected by clicking on them while holding the control key. Furthermore, they can be grouped together or ungrouped by selecting the appropriate option from the context menu. Grouped tracks can be collapsed, moved simultaneously and muted together.

The range and other properties of the display can be set by right clicking in the display and selecting “Edit range and properties ...”, which creates a dialog that allows these to be adjusted. If the autoRanging property is set to true, then the display range automatically expands as needed to accommodate new data. Display ranges can also be adjusted to fit the current data by right-clicking in the display and selecting Fit ranges to data.

Large data displays (Section 7.5.2) contain additional GUI-based features to adjust the display range.

A large display for a numeric probe can be created by right-clicking on the probe icon and selecting Large Display. This will create a large numeric display in a separate panel, allowing more precise inspection of data (Figure 33).

In addition to the functionality of the smaller displays, large displays have additional buttons, located across the top, for controlling the display range and other items. The first four of these are mode buttons:

There are also several additional buttons:

Large data displays can be cloned by right-clicking in the display and selecting Clone display. This creates a duplicate display (Figure 34) containing a copy of all the data currently in the probe. However, the duplicate display is not attached to the probe, and so the data does not change when the probe is reset or additional data is added to the probe. This is useful for comparing outputs between different simulations.

In addition, it is possible to export a large display’s plot to an image file. Right-click in the display, choose “Export image as ...”, and enter the desired file name and file type in the chooser. The file’s type is indicated by its extension. A range of image file types are supported, including JPEG (.jpg, .jpeg), PNG (.png), scalable vector graphics (.svg), and encapsulated PostScript (.eps).

As mentioned above, each entry in a numeric probe’s data vector is rendered in a different color (up to a limit, currently 30, after which colors are reused). If the vector size is large (say more than three or four), or if there is much overlapping of values, then the result can be difficult to visualize.

To manage this problem, numeric displays provide a legend dialog that allows the user to control the color, drawing order, and visibility for each vector entry (Figure 35).

To open the legend dialog, right-click in the display panel and select Show legend. Each row in the legend dialog is associated with a specific trace, consisting of a descriptive label followed by the trace color and a toggle controlling its visibility. For traces associated with component properties, the label consists of a partial path identifying the property, and for vector-valued properties this is followed by the name or number of the corresponding vector element. Traces are rendered in bottom-to-top order, so those at the top will be most visible.

• •

  To change a trace’s color, click the Set button, which will bring up a color menu.

• •

  To make an trace visible or invisible, use the visible toggle box.

• •

  To make all traces visible or invisible, use the All visible toggle box at the bottom of the dialog.

• •

  To change the order in which a trace is drawn, click and drag its dialog entry vertically.

Traces can also be reordered using the Trace ordering selector at the dialog bottom. At the time of this writing, the available orderings include:

ORDINAL

Traces are ordered by their natural place in the probe data. This is the default.

RMS

Traces are ordered in descending order by the RMS (root mean square) of their values over time.

RANGE

Traces are ordered in decreasing order by the difference between their maximum and minimum values over time.

Reordering traces, and then restricting visibility to a few at the top, can allow visualization of the most prominent data in an otherwise crowded display. For example, Figure 36 shows the 16 muscle excitations produced by inverse simulation of a muscular hydrostat model, with the legend dialog shown in Figure 37 (left). To view only the five excitations with the largest RMS values, one can use the Trace ordering selector to sort them in decreasing RMS order, and then make all traces invisible except the top five. The resulting display is shown in Figure 38, with the corresponding legend dialog shown in Figure 37 (middle).

When traces are reordered, their colors are not changed. To reassign the default colors to the traces based on their current ordering, one may use the Reset Colors button at the bottom of the legend dialog. Figure 39 shows the result of doing this for the display of Figure 38, with the corresponding legend dialog shown in Figure 37 (right).

As mentioned in Section 7.1, numeric probe data is described by a temporal sequence of knots, between which data is interpolated as described in Section 7.5.7.

Knot points can be made visible or invisible by setting the display’s knotsVisible property. This can also be done by right-clicking in the display and selecting Show knot points or Hide knot points. The rendered size of the knot, in pixels, is controlled by the knotSize property.

Since output probes typically have a very high knot density, their knots are set to be invisible by default.

For input probes, knot points (when visible) can be edited by moving, adding, or deleting them:

• •

  To move a knot point, left click on the knot and drag it.

• •

  To add a knot point, place the mouse at the desired location and double left-click.

• •

  To delete a knot point, right-click on the knot and select Delete knot point.

• •

  To edit a knot point data value, right-click on the knot and select Edit knot point.

The data for all numeric probes (input or output) can be scaled by right-clicking in the display and selecting “Scale data ...”. This allows the user to enter a scaling factor that is applied uniformly to all the knot points.

Numeric probe data can also be smoothed, which is convenient for removing noise from either input or output data. To apply data smoothing, right click in the display and select “Smooth data ...”; this will open a smoothing dialog as shown in Figure 40.

Different smoothing methods are available and can be selected using the dialog’s method field. At the time of this writing, the following methods are available:

MOVING_AVERAGE

Applies a mean average filter across the knots, using a moving window whose size is specified by the window size field. The window is centered on each knot, and is reduced in size near the end knots to ensure a symmetric fit. The end knot values are not changed. The window size must be odd and the window size field enforces this.

SAVITZKY_GOLAY

Applies Savitzky-Golay smoothing across the knots, using a moving window of size . Savitzky-Golay smoothing works by fitting the data values in the window to a polynomial of a specified degree , and using this to recompute the value in the middle of the window. The polynomial is also used to interpolate the first and last values, since it is not possible to center the window on these.

The window size and the polynomial degree are specified by the window size and polynomial degree fields. must be odd, and must also be larger than , and the fields enforce these constraints.

Note that smoothing makes no adjustment to account for uneven knot spacing, which may sometimes occur for input data.

The data between knot points in a numeric probe is interpolated, using one of the interpolation orders described below, with the default interpolation order being Linear. Linear interpolation is almost always sufficient for output probes, which typically have a close spacing between knots that equals the simulation step size. Input probes, on the other hand, often have a much sparser knot spacing and so different interpolation orders can be useful. The interpolation order of input probes can be set by right-clicking in the display and selecting the Interpolation menu item. This is illustrated in Figure 41, which shows two input probes, one using Cubic interpolation and the other using Linear interpolation.

The interpolation options for a numeric probe include:

Step

Values are set to the values of the closest previous knots points.

Linear

Values are set by linear interpolation of the closest surrounding knot points.

Cubic

Values are set by cubic Catmull interpolation between the surrounding knot points.

CubicStep

Values are set by cubic Hermite interpolation between the surrounding knot points, with the slopes at knot points set to zero.

SphericalLinear

When interpolating quaternions or rigid transformation matrices, 3D rotation values are set by piecewise spherical linear interpolation (i.e., "slerp", as described by Shoemake’s 1985 SIGGRAPH paper). Otherwise, interpolation is linear. Quaternions are assumed if the vector size of the numeric probe is 4, and rigid transformation matrices are assumed if the vector size is 16.

SphericalCubic

When interpolating quaternions or rigid transformation matrices, 3D rotation values are set by spherical cubic interpolation (i.e., "slerp", as described by Shoemake’s 1985 SIGGRAPH paper). Otherwise, interpolation is cubic. Quaternions are assumed if the vector size of the numeric probe is 4, and rigid transformation matrices are assumed if the vector size is 16.

All of the above interpolation orders are instances of the enumeration type Interpolation.Order.