ArtiSynth User Interface Guide

2 Loading, Simulating and Saving Models

The first thing an ArtiSynth user is likely to want is to load a demonstration model, and explore and simulate it.

A number of predefined demonstration models come bundled with the ArtiSynth distribution. These are generally simple models that illustrate particular simulation capabilities. More complex anatomical models, including those used in various research projects, are available in the separate project artisynth_models, which must be downloaded separately (see www.artisynth.org/models for instructions).

An ArtiSynth model is defined by a Java class which is a subclass of the ArtiSynth RootModel component. This class builds the model, serves as the root container for all its components, and implements the advance() method which allows the model to be simulated.

There are several ways to load models.

2.1 Loading from the Models menu

Some models can be loaded directly using the Models menu located in the ArtiSynth menu bar. By default, this expands to a number of submenus:

Demos - all models listed in the file .demoModels
All Demos - every model found under the package artisynth.demos, arranged hierarchically

In addition, if artisynth_models has also been installed, or if ArtiSynth otherwise detects the presence of Java packages located under artisynth.models, then the Models menu will also contain:

Models - all models listed in the file .mainModels
All Models - every model found under the packages artisynth.models, arranged hierarchically

The files .demoModels and .mainModels are searched for in the list of directories specified by the ARTISYNTH_PATH environment variable (which if not present defaults to the current directory, the user’s home directory, and the ArtiSynth install directory).

Each submenu expands out to identify a set of models. Selecting one of the models will cause it to be loaded into ArtiSynth and displayed in the viewer. Hovering over one of the entries will display the full classname of the associated RootModel.

It is possible to customize the contents of the Models menu; see Section 14.

2.2 Loading by class path

As mentioned above, models are defined by subclasses of RootModel. A model may therefore be loaded into ArtiSynth by specifying the classname of its RootModel. To do this, go to the File menu and choose Load from class ..., which will bring up a dialog that permits you to enter the classname. The dialog supports expansion using the <TAB> key.

It is also possible to use the -model <classname> command line argument to have a model loaded directly into ArtiSynth when it starts up. For example, when running ArtiSynth using the artisynth command, one may specify

  artisynth -model artisynth.models.mystuff.TestModel

Under Eclipse, the -model argument may be specified in the Arguments section of the run configuration.

2.3 Loading from a file

Finally, it is possible to load a model from a file. Selecting Load model ... from the File menu will bring up a File browser that lets you select and load a model from an ArtiSynth model file. ArtiSynth model files are text-based documents that contain a hierarchical description of all the model’s components, and are typically identified by the extension .art.

When loading a model from a .art file, it is necessary to have all classes associated with that model in the current Java classpath. This can be an issue when loading files generated by other users using application-specific Java code. Two possible solutions to this are: (a) bundling the application-specific code into a .jar file and placing it in the directory <ARTISYNTH_HOME>/lib, or (b) making sure that the file was saved using only artisynth_core components, as described in Section 2.7.

2.4 Reloading a model

After a model has been loaded by any of the methods described above, it can be reloaded by selected Reload model from the File menu.

2.5 Simulating a model

Once a model is loaded, simulation of the model can be started, paused, single-stepped, or reset using the play controls (Figure 1) located at the upper right of the ArtiSynth window frame. Play controls are discussed in more detail in Section 7.2.1.

Play controls are also available in the ArtiSynth timeline (Section 7). Also, hitting the ‘p’, ‘s’ and ‘r’ keys from within the viewer (Section 3.9) can be used to play/pause, single step and reset the simulation.

Figure 1: The ArtiSynth play controls. From left to right: step size control, current simulation time, and the reset, skip-back, play/pause, single-step and skip-forward buttons.

2.6 Other toolbar controls

The ArtiSynth application contains a toolbar that runs along the top of the frame. The right side contains the play controls shown in Figure 1.

When a grid is enabled in the viewer (Section 3.5), a text box appears in the center of the toolbar displaying the current grid units (Section 3.5.1).

The left side of the toolbar contains the following buttons:

NavPanel: Shows or hides the navigation panel (Section 4.2)
Reset state: Resets the simulation state at time 0 to the current state.
Rerender: Rerenders all viewers and displays.
Enable real-time: Toggle which if pressed (the default), forces the simulation to run no faster than real time.

2.7 Saving a model

An ArtiSynth model can be saved to a file to be reloaded and used later. Selecting Save model as ... from the File menu will bring up a dialog that lets you select the name and directory for the model file (Figure 2). If a model file has already been specified, then one can save to it again by selecting the Save model menu item. ArtiSynth model files are text-based and are typically identified by the extension .art.

Figure 2: The save model dialog.

When using the Save model as ... menu item, the user may choose the following options:

Save waypoint data:

Causes the state data for any valid waypoints (Section 7.3) to be saved in addition to the waypoint locations. This is optional because a large number of waypoints may significantly increase the file size for models with a large state sizes.

Core components only:

Saves only those components which are present in the main artisynth_core package. Any non-core components, and any other components which have a hard dependency on them, will not be written, and the user will be advised of this via a message dialog. The root model (Section 4.1) is saved as a pure instance of RootModel, instead of the application-specific class that was used to build it. This means that any properties or class overrides specific to the application root model class will not be present in the saved model. The advantage to storing a model using only core components is that it can be loaded by any other user running that same ArtiSynth version, without needing access to any application-specific classes.

2.8 The ArtiSynth working directory

ArtiSynth maintains the notion of a working directory, which is the default directory (or folder, in Windows parlance) under which the files used to store various types of model information are stored. This includes model files, as described above, along with other files such as those used to store waypoints, probe configurations, or probe data (Section 8).

Chooser dialogs for these files will generally open in the working directory by default.

The working directory is initialized to the local system directory in which the ArtiSynth application is started. Once ArtiSynth is running, it can be set by choosing Set working dir ... from the File menu, or by calling

   ArtisynthPath.setWorkingDir (file)

in code. When a model is saved (Section 2.7), the working directory is saved with it and restored when the model file is subsequently loaded.