ArtiSynth Installation Guide for Windows

9 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 11) 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 folder denoted by <MYPROJECT>, and that the root folders 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.

9.1 Making ArtiSynth visible to the compiler

How this is done depends on your development environment.

9.2 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 12.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.

9.3 Command line development

If you are compiling from the command line or GitBash, then the compile command described earlier will still work, provided that, as assumed above, <MYPROJECT> contains the source and classes folders 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 folders from other projects), they may be added by setting them in the CLASSPATH environment variable (Section 13.2).

Use of the make command will require setting up Makefiles in the folders 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.

9.4 Making external models visible to ArtiSynth

9.5 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 12.6.

9.6 Using EXTCLASSPATH

External models can be made visible to ArtiSynth by adding any needed class folders and JAR files to a file called EXTCLASSPATH, located in <ARTISYNTH_HOME>, as described in Section 13.4. 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 C:\research\myproject, then the following lines should be added to EXTCLASSPATH:

C:\research\myproject\classes
C:\research\myproject\lib\dicom.jar

Class path entries in EXTCLASSPATH will be appended to any specified through the CLASSPATH environment variable.

The EXTCLASSPATH file can be used when running from Eclipse or some other IDE.

9.7 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 13.2. For the example of Section 9.6, we could instead add the following to CLASSPATH:

   C:\research\myproject\classes;C:\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.

9.8 Using the -cp option

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

   > artisynth -cp "C:\research\myproject\classes;C:\research\myproject\lib\dicom.jar"

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