ArtiSynth Installation Guide for Linux

10 Integrating external models

While it is easiest to add a model to ArtiSynth by simply placing its source code under <ARTISYNTH_HOME>/src, as described in Section 8, it is usually best practice to keep model source code separate from ArtiSynth. This is largely to avoid conflicts when ArtiSynth is updated (Section 12) or reinstalled.

When model source code is external to ArtiSynth, one must manage two things:

  1. 1.

    Making the ArtiSynth classes visible to the Java compiler when compiling the code;

  2. 2.

    Making the model classes visible to ArtiSynth when running the model.

This involves managing the class path used by either the Java compiler or by ArtiSynth.

For purposes of this discussion, we will assume that the model is contained under a top-level directory denoted by <MYPROJECT>, and that the root directories for the Java source code and class files are <MYPROJECT>/src and <MYPROJECT>/classes, respectively. This Java file structure is common, and is used by artisynth_core and most other projects currently associated with ArtiSynth.

10.1 Making ArtiSynth visible to the compiler

How this is done depends on your development environment.

10.1.1 Eclipse development

When using Eclipse, the project will also be associated with an Eclipse project name, which we will call myproject. In order for myproject to compile, the ArtiSynth project artisynth_core should be added to the build path of myproject, as described in Section 13.5. This will ensure that the ArtiSynth classes are added to the class path used by the Java compiler.

Some projects, such as artisynth_models, already have their build path preconfigured to contain artisynth_core, and so for them this step is unnecessary.

10.1.2 Command line development

If you are compiling from the command line , then the compile command described earlier will still work, provided that, as assumed above, <MYPROJECT> contains the source and classes directories src/ and classes/. The compile command will supply the Java compiler with a class path containing all the ArtiSynth classes, plus <MYPROJECT>/classes. If additional classes are needed (such as external JAR files or class directories from other projects), they may be added by setting them in the CLASSPATH environment variable (Section 14.2).

Use of the make command will require setting up Makefiles in the directories in which you wish to run make. It will also (usually) require setting the CLASSPATH environment variable to contain the ArtiSynth class path entries,

<ARTISYNTH_HOME>/classes;<ARTISYNTH_HOME>/lib/*

where as usual <ARTISYNTH_HOME> should be expanded to the path for the ArtiSynth installation directory. The character ‘*’ functions as a wildcard to specify all the JAR files in <ARTISYNTH_HOME>/lib.

10.2 Making external models visible to ArtiSynth

10.2.1 Running from Eclipse

When running ArtiSynth under Eclipse, you can make myproject’s models visible by adding myproject to the ArtiSynth launch configuration, as described in Section 13.6.

10.2.2 Using the external classpath

External models can be made visible to ArtiSynth by adding any needed class directories and JAR files to the external class path. The easiest way to do this is to select “Settings > External classpath ...” from the Settings menu, which will open an external classpath editor as shown in Figure 3, allowing the necessary class directories and JAR files to be added. The classpath entries are displayed in a large panel on the left (which will initially be blank after ArtiSynth is first installed).

Figure 3: The external classpath editor.

As an example, assume that the model class files are contained under <MYPROJECT>/classes, and that the JAR file <MYPROJECT>/lib/dicom.jar is also required. If <MYPROJECT> is located at /research/myproject, then the following entries should be added to the external classpath: 

/research/myproject/classes
/research/myproject/lib/dicom.jar

ArtiSynth must be restarted for external classpath changes to come into effect.

More details are given in the section “Setting the external classpath” of the ArtiSynth User Interface Guide. The external classpath is stored in the file EXTCLASSPATH in the user configuration folder and can be edited directly (Section 14.4).

The external classpath can be used when running from Eclipse or any other IDE.

10.2.3 Setting the CLASSPATH environment variable

When running ArtiSynth from the command line, external models can also be made visible by adding class folders and JAR files to the CLASSPATH environment variable, as described in Section 14.2. For the example of Section 10.2.2, we could instead add the following to CLASSPATH:

   /research/myproject/classes;/research/myproject/lib/dicom.jar

Note that in this situation the ArtiSynth class files do not need to be included in CLASSPATH, as they will be added automatically.

10.2.4 Using the -cp option

ArtiSynth also provides the command line option -cp which allows a class path to be specified directly:

   > artisynth -cp "/research/myproject/classes:/research/myproject/lib/dicom.jar"

Class paths specified using -cp will replace any specified through the CLASSPATH variable.