ArtiSynth Installation Guide for Windows

8 Creating and Adding Models

Most users will want to develop their own ArtiSynth models using Java code. This is done by creating a special Java model class, which is a subclass of RootModel and which contains a build() method that assembles the model from the various Java components that ArtiSynth provides. For example, suppose your model class is called MyModel. This will be implemented inside a Java source file called MyModel.java, a skeleton implementation of which might look like this:

⬇
package artisynth.models.mymodels;
// import statements to access classes:
import maspack.matrix.*;                  // vectors and matrices
import artisynth.core.mechmodels.*;       // mechanical models and components
import artisynth.core.workspace.RootModel;
// model class definition:
public class MyModel extends RootModel {
   public void build (String[] args) {
      // ... model is assembled here ...
   }
}

Full details on how to create a model in Java and the components that are available to do so are given in the ArtiSynth Modeling Guide. For this discussion, we will consider only how to add a model to ArtiSynth once it has been created. The easiest way to do this is to add its source code to the ArtiSynth source code, as described below. However, as a general practice, it is recommended that the model source code be kept separate from ArtiSynth, as described in Section 10.

8.1 Model packages

A model should be implemented inside a Java package, which will contain the model class, and perhaps other supporting classes used to implement it. The package is defined by the package statement at the beginning of each .java file. For the MyModel example above, the package is artisynth.models.mymodels.

Java enforces certain rules for how its source code is organized. In particular, all the .java files associated with a specific package must be placed in the same folder, which in turn must be located in a folder tree that reflects the package hierarchy. For example, source code for the package pack.foo.bar must be placed in a folder whose path (relative to the top of the source tree) is pack\foo\bar. For the MyModel example, MyModel.java must be placed in a folder artisynth\models\mymodels relative to the top of the source tree.

The source code tree for ArtiSynth is rooted at <ARTISYNTH_HOME>\src. It already contains a large number of model classes located in packages such as artisynth.demo.mech, whose source code is therefore located at

<ARTISYNTH_HOME>\src\artisynth\demos\mech

The easiest way to add your own model to ArtiSynth is to simply add the source code for its package to the appropriate location under <ARTISYNTH_HOME>\src. For MyModel, the source code would therefore be placed in

<ARTISYNTH_HOME>\src\artisynth\models\mymodels

Since the ArtiSynth source tree already contains the (empty) folder artisynth\models, in this case it would only be necessary to add the mymodels folder below it.

Multiple models may be placed in any given package. For example, artisynth.demos.tutorial contains a large number of models used as examples for the Modeling Guide.

8.2 Compiling models

When source code is added or modified within the ArtiSynth source tree, it needs to be compiled. How this is done depends on your development environment.

If you are using Eclipse and automatic building is enabled for a project (such as artisynth_core), compilation will occur automatically whenever that project’s .java files are modified. To see if automatic building is enabled, select the project in the Package Explorer, open the Project menu and check Build Automatically. If automatic building is not enabled, the project can be built by selecting Build Project.

If you add or edit source files from outside Eclipse, for example by using an external text editor, then you need to refresh the project in order for Eclipse to notice the changes. To refresh, select the project in the Package Explorer, and then either right-click and choose Refresh, or simply hit the F5 key.

If you are compiling from the command line or GitBash, using either the make or compile commands described earlier, then running these in any given source folder will compile all the .java files contained below it. This will typically be faster than compiling the entire source tree by running make or compile from <ARTISYNTH_HOME>.

To be able to run compile from any folder, place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.1).

If you add a new package folder and want to run make from that folder, you will need to add a Makefile to it. The easiest way to do this is to simply copy an existing Makefile from another package and adjust the PACKAGE_NAME and ROOT_DIR entries; the number of ‘..’ entries in ROOT_DIR should equal the number of “up” steps needed to reach <ARTISYNTH_HOME>.

8.3 Finding models in the model menu

Once a model has been added to ArtiSynth, it is useful to be able to run it directly from the model menu, located under Models in the main menu bar.

By default, the model menu locates all models in the packages (and subpackages) of artisynth.demos andartisynth.model, and makes then available under the entries All demos > and All models >, respectively. Therefore, if your model is located in one of these packages, it will automatically appear in the Models menu. If your model is located in a different package, you can load it either by directly specifying its class path, or by customizing the Models menu. These options are described in the sections “Loading by class path” and “Customizing the Model Menu” of the ArtiSynth User Interface Guide,