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.
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.
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
Under Eclipse, the -model argument may be specified in the Arguments section of the run configuration.
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.
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.
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.
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.
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.|
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.
When using the Save model as ... menu item, the user may choose the following options:
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.
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.
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
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.