ArtiSynth Installation Guide for Windows

John Lloyd, Sebastian Kazenbroot-Guppy, and Antonio Sánchez

Last updated: March, 2021

Contents

1 Overview

ArtiSynth is an open-source Java-based platform that supports combined multibody/FEM modeling in an interactive simulation environment. Users may build their own models using Java code, or load preexisting models from either files or Java classes. This document describes how to install and run ArtiSynth on 64-bit Windows machines.

ArtiSynth’s prerequisites are listed in Section 2. A Java JDK must be installed on your system; information on this is given in Section 4.

There are two ways to obtain ArtiSynth:

  1. 1.

    Install a precompiled release - the fastest way to quickly install ArtiSynth to try out some of the demo programs. Instructions for this are given in Section 5.

  2. 2.

    Install from GitHub - recommended for more serious developers who want to keep their codebase current and easily install new features and bug fixes. When installing from GitHub, you also need to download the runtime libraries, and compile ArtiSynth. GitHub installation instructions are given in Section 6.

Once ArtiSynth is installed, it can be run and various demonstration models can be loaded. Some simple details on this are given in Section 7; complete instructions on running and interacting with models are provided in the ArtiSynth User Interface Guide.

Many users will want to create their own models in Java. This is done by creating Java classes to implement these models, as described in the ArtiSynth Modeling Guide, and then integrating them into ArtiSynth, as described in Section 8. When creating models, users may want to use an integrated development environment (IDE) for editing and compiling their Java code. At present, most of the ArtiSynth community uses the Eclipse IDE (Section 12), but other IDEs such as NetBeans and IntelliJ could be used as well.

Users may also want to install and run external models and projects that have been created either by others or by themselves. In particular, the project artisynth_models contains an open source set of models primarily related to head and neck anatomy. Installation of artisynth_models is discussed in Section 10.

2 Prerequisites

To install ArtiSynth on Windows, you will need:

  • A 64 bit version of Windows.

  • Java 8 (see Section 4).

    ArtiSynth will generally work with later versions of Java, but Java 8 currently provides maximum compatibility with MATLAB, which still uses Java 8.

  • A three-button mouse is useful for GUI interaction.

  • A machine with a good graphics card and a decent amount of memory. We recommend 16 Gbytes, or more if you are doing FEM analysis with larger numbers of elements.

3 The ArtiSynth installation folder

You can install ArtiSynth in any location you like. In this document, the location of the ArtiSynth installation folder will be denoted by <ARTISYNTH_HOME>. For example if ArtiSynth is installed in

  C:\people\roger\artisynth_core

then <ARTISYNTH_HOME> denotes this folder and <ARTISYNTH_HOME>\lib denotes the sub-folder

  C:\people\roger\artisynth_core\lib

It recommended that ArtiSynth be installed in a location where none of the folder names contain spaces (e.g., avoid placing it under Program Files). This will help ensure that all ArtiSynth utilities function correctly.

4 Installing Java

ArtiSynth requires that you have a full Java development kit (JDK) installed, which comes with a Java compiler; a simple run time environment (JRE) will not be sufficient. By default, ArtiSynth is compiled to be compliant with Java 8. While ArtiSynth will generally work under later Java versions, there have been occasional reports of compatibility issues involving the Java OpenGL (JOGL) interface. Therefore we currently recommend using Java 8; this also provides maximum compatibility with MATLAB, as indicated above. We specifically recommend the Java SE Development Kit 8uXXX (where XXX is the latest revision number), which can be obtained from Oracle (registration required). At the time of this writing, the download page is located at

and the latest release is 8u281. This page provides downloads for all systems; be sure to choose the download link appropriate to yours. For Windows, this will be jdk-8u281-windows-x64.exe. After the file downloads, open it, and follow the installation wizard, using the default values provided. The installer will probably install both a JRE and a JDK, and place them in the folders

C:\Program Files\Java\jre1.8.0_281
C:\Program Files\Java\jdk1.8.0_281

The second contains the JDK, and is your JDK installation folder.

If the above Oracle link is no longer current, the search terms ``java 8 jdk download'' should get you to the right place.

4.1 Ensuring the JDK is visible to your system

After the JDK has been installed, it is important to ensure that it is visible to your system and that it supersedes any other Java installations. One test for this is to open a CMD window and run the command

 > javac -version

The output should match the version of the installed JDK. If it does not, or if the command javac is not found, then one fix is to add the folder <JDK_HOME>\bin to your system Path, as described in Section 13.1, where <JDK_HOME> is the JDK installation directory. On Windows, your JDK is likely to be installed under Program Files\Java. For example, if your JDK is 1.8.0_281, then <JDK_HOME> will likely be

  C:\Program Files\Java\jdk1.8.0_281

In particular, <JDK_HOME>\bin should be added ahead of any other Java installations that might be specified on the Path. To see the current contents of the Path, open a CMD window and run the command

 > echo %PATH%

5 Installing a Precompiled Release

Installing one of the precompiled releases is the easiest way to obtain ArtiSynth for running demo programs or some existing models. To do this, go to www.artisynth.org/downloads, download the distribution you want, and unzip it in an appropriate location on your computer.

5.1 Running from the file browser

Once ArtiSynth is downloaded and unzipped, it should be possible to run it immediately by using a file browser to locate and then double click on the batch file

  <ARTISYNTH_HOME>\bin\artisynth.bat

You can create a shortcut to this batch file (by right clicking on it and selecting Create Shortcut), and then place the shortcut in either the START menu or on the Desktop. However, the file itself must remain in <ARTISYNTH_HOME>\bin.

5.2 Running from a terminal window

ArtiSynth can also be run from a terminal window.

To do this, open a terminal (CMD) window, set the current folder to <ARTISYNTH_HOME>, and run the command bin\artisynth:

 > cd <ARTISYNTH_HOME>
 > bin\artsiynth

If you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 13.1), then ArtiSynth can be run from a terminal window with the simple command

 > artisynth

regardless of the current folder.

Details on how to load and run demo models are given in Section 7.

A precompiled ArtiSynth distribution can also be imported into an integrated development environment (IDE), such as Eclipse, to facilitate compilation and execution. To import ArtiSynth into Eclipse, follow the instructions in Section 12.2, using <ARTISYNTH_HOME> as the project directory.

6 Installing from GitHub

For most users doing active modeling work, we recommend installing the current ArtiSynth development version from GitHub, which will provide ongoing access to updates and bug fixes. GitHub is a web-based repository service based on the source control management system Git. A very brief summary of Git is given in Section 13.5.

ArtiSynth is available from GitHub at the URL

   https://github.com/artisynth/artisynth_core.git

After installation, users can continually update the ArtiSynth codebase to the latest version using pull operations (Section 11). In some cases, developers we work with closely can also obtain, by mutual arrangement, write access to our GitHub repository, allowing them to also commit changes.

Users who have a GitHub account combined with SSH keys may instead wish to clone using the SSH URL

   git@github.com:artisynth/artisynth_core.git

For users with repository write access, this will allow them to perform subsequent push operations without having to enter a username and password.

6.1 Installation using Eclipse

If you are planning to use the Eclipse IDE (Section 12), you can install from GitHub directly into Eclipse. Directions on installing Eclipse and configuring it for ArtiSynth development are given in Section 12.1. Once Eclipse is installed, ArtiSynth can be installed as follows:

  1. 1.

    From the main menu, select “File > Import ...”. This will cause an Import dialog to appear, as shown below. Open “Git > Projects from Git”, and then click Next.

  2. 2.

    In the next dialog, choose Clone URI, and click Next.

  3. 3.

    A Source Git Repository dialog will appear, as shown below. In the URI field at the top, enter
    https://github.com/artisynth/artisynth_core.git
    This will automatically fill the Host and Repository path fields. Click Next.

  4. 4.

    A Branch Selection dialog will appear; uncheck svn, so that only master is selected. Click Next.

  5. 5.

    A Local Destination dialog will appear as shown below, indicating the folder into which ArtiSynth will be placed locally. Use the default location, or edit it to the desired location. This will be your ArtiSynth home folder, and will be referred to later in this document as <ARTISYNTH_HOME>. Click Next.

  6. 6.

    ArtiSynth will now be downloaded; this may take a few minutes, depending on your network connection speed. Another dialog will appear, asking you to select to project import wizard. Leave the default (“Import existing Eclipse projects”) selected, and click Next.

  7. 7.

    An Import Projects dialog will appear, confirming that you want to import artisynth_core. Leave everything as is, and click Finish.

artisynth_core has now been imported into Eclipse as a project. However, we are not quite done. Eclipse will try to compile artisynth_core, but will fail because some Java and native libraries are missing. (These libraries are not included in the GitHub repository because they are quite large.) The compile failure will be indicated by a red exclamation mark to the left of the artisynth_core project entry in the Package Explorer:

The Java and native libraries must be downloaded separately, outside of Eclipse. Open a file explorer, navigate to the <ARTISYNTH_HOME> folder (described above), open the bin folder, and click on the updateArtisynthLibs batch file (Figure 1). This will load the libraries, temporarily displaying a terminal window while doing so. The process may take a few minutes, depending on network speed.

Figure 1: updateArtisynthLibs batch file in <ARTISYNTH_HOME>\bin.

When the libraries are loaded, return to Eclipse, click on the artisynth_core project to select it, then “refresh”, either by right clicking and selecting Refresh, or by hitting the F5 key. Eclipse should now find the libraries and compile ArtiSynth; a green progress bar will appear at the lower right while compilation is in progress.

After compilation is complete, ArtiSynth can be run by simply choosing Run > Run from the main menu. This works by invoking a predefined launch configuration named ArtiSynth. In some cases, one may wish to adjust this launch configuration to set environment variables, command line arguments, or Java JVM arguments that affect how ArtiSynth behaves. Instructions for doing so are contained in Sections 12.3 and 12.4.

It is also possible to run ArtiSynth from a terminal window, as described in Section 5.2. Detail on how to load and run demo models are given in Section 7.

6.2 Installation using Git for Windows

Git for Windows is an application that provides the user with a terminal window interface that can be used for entering Git commands. Users can choose between GitBash, which provides a Unix-like bash shell, or GitCMD, which provides a Windows CMD shell. GitBash has several advantages, such as allowing users to easily set environment variables in a .bashrc file (Section 13.2.3), and supplying a number of Unix-like commands that can be convenient for tasks other than those involving Git.

At the time of this writing, Git for Windows can be installed from git-scm.com/download/win.

Once installed, ArtiSynth can then be installed and compiled by opening a GitBash window and entering the following commands (where the ‘$’ character indicates the GitBash prompt and should not be entered):

 $ cd /path/to/install
 $ git clone https://github.com/artisynth/artisynth_core
 $ cd artisynth_core
 $ bin/updateArtisynthLibs
 $ make

The first line simply sets the current folder to the one under which you wish to install ArtiSynth, as indicated by /path/to/install. (Note that GitBash follows the Unix convention of using forward slash (’/’) instead of backslash (’\’) to separate files.) The git clone command then downloads ArtiSynth and extracts it to a folder named artisynth_core, so that the ArtiSynth installation directory (or <ARTISYNTH_HOME>) is/path/to/install/artisynth_core. The updateArtisynthLibs command fetches additional libraries that are not included in the GitHub repository for space reasons, and the make command on the last line is a Unix build utility provided by GitBash; in this situation, it compiles all the .java files under artisynth_core.

Once built, ArtiSynth can then be run (from within artisynth_core) using the command

  $ bin/artisynth

For convenience, if you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 13.1), then ArtiSynth can be run independently of the current directory using the simple command

 % artisynth

ArtiSynth can also be installed and compiled using GitCMD, with an analogous command sequence:

 > cd \path\to\install
 > git clone https://github.com/artisynth/artisynth_core
 > cd artisynth_core
 > bin\updateArtisynthLibs
 > bin\compile

The only real difference is using backslash (’\’) instead of forward slash (’/’) as a file separator, and the use of bin\compile instead of make (which is not supported in Git CMD). compile is a command supplied by ArtiSynth that compiles all .java files located under the current folder.

Details on how to load and run demo models are given in Section 7.

Note that once you have installed ArtiSynth, you still have the option to later import it into an IDE such as Eclipse. For Eclipse specifically, this is done by importing it as an external project, as described in Section 12.2.

7 Loading and Running Models

After ArtiSynth starts up, you can load and run demonstration models. Do this by selecting Models > Demos from the main menu and choosing a demo model (Figure 2).

Figure 2: The ArtiSynth model selection menu.

Once a model is loaded, it will appear in the viewer, and simulation can be controlled using the “play” controls located at the upper right of the application window:

From left to right, these are: step size control, which controls the simulation step size (in seconds); current simulation time (in seconds); and the reset, skip-back, play/pause, single-step and skip-forward buttons. Starting and stopping a simulation is done by clicking play/pause, while reset resets the simulation to time 0. The single-step button advances the simulation by one time step.

Detailed information on how to use the ArtiSynth GUI for model visualization, navigation and simulation control is given in the ArtiSynth User Interface Guide.

Figure 3 shows ArtiSynth with the Spring Net demo loaded.

Figure 3: ArtiSynth with the Spring Net demo loaded.

7.1 Command line arguments

If you are running ArtiSynth from a terminal window (Section 5.2) or GitBash (Section 6.2) then you can supply it with command line arguments to control different aspects of its behavior. A full list of these can be seen by running artisynth with the -help option:

 > artisynth -help

Descriptions of these options appear in various places within the ArtiSynth documentation. For example, one commonly used option is -model <modelClassName>, which instructs ArtiSynth to preload a model associated with a given class name:

 > artisynth -model artisynth.demos.mech.SpringMeshDemo

If you are running under Eclipse, command line arguments can be set in the launch configuration, as described in Section 12.4.

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 9.

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 13.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 Models menu

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

By default, the Models 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 Models Menu” of the ArtiSynth User Interface Guide,

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.

10 Installing artisynth_models

artisynth_models is an open source collection of anatomical models, focused primarily on the head and neck region (see www.artisynth.org/models). It can be obtained either as a precompiled release, or from GitHub.

Once installed, the models will appear in the ArtiSynth Models menu under Models > and All models >.

10.1 Installing a precompiled release

If you are running a precompiled release of ArtiSynth, then you will need to use the corresponding precompiled release of artisynth_models, which can be obtained from

  www.artisynth.org/Software/ModelsDownload

Download the distribution you want and unzip it in your desired location; the recommended spot is right next to artisynth_core.

artisynth_models comes preconfigured with Eclipse project files, and so can be immediately imported into Eclipse as an external project, as described in Section 12.2. To make the models visible to ArtiSynth when running from Eclipse, it will be necessary to add artisynth_models to the ArtiSynth launch configuration, as described in Section 12.6.

If you are running ArtiSynth from the command line or the artisynth.bat file, you will need to ensure that the class folder artisynth_models\classes is visible to ArtiSynth, as described in Section 9.4.

10.2 Installing from GitHub

The latest development version of artisynth_models is available from GitHub at the URL

   https://github.com/artisynth/artisynth_models.git

10.2.1 Installation using Eclipse

If you are using Eclipse, you can install artisynth_models in the same way as for artisynth_core (Section 6.1):

  1. 1.

    Select File > Import ..., open “Git > Projects from Git” in the Import dialog, and click Next.

  2. 2.

    In the Select Repository Source dialog, choose Clone URI, and click Next.

  3. 3.

    In the Source Git Repository dialog, enter
    https://github.com/artisynth/artisynth_models.git
    in the URI field at the top, and click Next.

  4. 4.

    In the Branch Selection dialog, uncheck svn and click Next.

  5. 5.

    In the Local Destination dialog, adjust the install location if desired, and click Next.

  6. 6.

    artisynth_models will now be downloaded. A “wizard” dialog will then appear. Leave the default (“Import existing Eclipse projects”) selected, and click Next.

  7. 7.

    In the Import Projects dialog, click Finish.

artisynth_models should now compile automatically; there is no need to download external libraries. However, to make the models visible to ArtiSynth when running from Eclipse, it will be necessary to add artisynth_models to the ArtiSynth launch configuration, as described in Section 12.6.

10.2.2 Installation using Git for Windows

If you have Git for Windows installed (Section 6.2), and you have placed <ARTISYNTH_HOME>\bin in your Path environment variable (Section 13.1), allowing the compile command to be called from any folder, then artisynth_models can be installed from GitBash as follows:

 $ cd /path/to/install
 $ git clone https://github.com/artisynth/artisynth_models
 $ cd artisynth_models
 $ compile

The last line uses the compile command instead of make because the latter will not work unless the CLASSPATH environment variable has been set to include the ArtiSynth class path entries, as described in Section 9.3.

If you run ArtiSynth from the command line, you will need to ensure that artisynth_models\classes is visible to ArtiSynth, as described in Section 9.4.

11 Updating ArtiSynth

One reason to install ArtiSynth from GitHub is to be able to update the codebase to incorporate new features and bug fixes. When a significant update occurs, a posting is made to the ArtiSynth update log, currently located at www.artisynth.org/doc/html/updates/updates.html. Users may also be notified via the artisynth-updates email list.

Eclipse users may update simply by selecting the artisynth_core in the Package Explorer and then right clicking and choosing Team > Pull.

If Git for Windows is installed (Section 6.2), then updating may be done using GitBash:

 $ cd <ARTISYNTH_HOME>
 $ git pull

If local changes have been made to artisynth_core that interfere with the changes made by the update, a Git pull operation may result in a conflict. Conflict resolution is outside the scope of this document, but documentation on this is available online. Conflicts should not occur if local changes have not been made to artisynth_core.

Other Git-based projects, such as artisynth_models, may be updated similarly.

11.1 Library updates

Occasionally, a software update will be accompanied by a change in the libraries located in <ARTISYNTH_HOME>\libs. When this happens, it will be indicated on the ArtiSynth update log and appropriate instructions will be given. In these cases, one should also run the command updateArtisynthLibs located in <ARTISYNTH_HOME>\bin. This can be done from a terminal window:

 > cd <ARTISYNTH_HOME>
 > bin\updateArtisyntnLibs

It can also be done from a file browser, by navigating to <ARTISYNTH_HOME> and clicking on updateArtisynthLibs.bat. (Figure 1).

12 The Eclipse IDE

Eclipse is an integrated development environment (IDE) commonly used for Java code development, and many ArtiSynth developers use it for both developing models in Java and for running the system. This section describes how to install Eclipse and provides some other information relevant to ArtiSynth users. A general introduction to Eclipse is beyond the scope of this document, but there are many Eclipse resources available online.

12.1 Installing Eclipse

This document describes specifically the installation of Eclipse 2020-12; other versions should be similar.

Eclipse can be downloaded from www.eclipse.org/downloads/packages. From this page, choose “Eclipse IDE for Java Developers”, Windows x86_64, which will download the file

  eclipse-java-2020-12-R-win32-x86_64.zip

Unzip this into a convenient folder, such as for example:

  C:\eclipse\eclipse-2020-12

Open this folder with a file explorer, and you will see the eclipse application:

Click on this to open it. A dialog will appear, asking you to select a workspace folder (Figure 4). This is where Eclipse settings and project information will be stored. Unless you have a another Eclipse already installed, the default location should be fine. (Remember also to check the “Use this as the default ...” box so that this query won’t appear every time you open Eclipse.) Next, click Launch. A welcome page will appear; close this. A “donate” panel may also appear; close this too. You should then see an empty Eclipse display, similar to Figure 5.

Figure 4: Eclipse Workspace dialog.

This is where Eclipse settings and project information will be stored. Unless you have a another Eclipse already installed, the default location should be fine. (Remember also to check the “Use this as the default ...” box so that this query won’t appear every time you open Eclipse.) Next, click Launch. A welcome page will appear; close this. A “donate” panel may also appear; close this too. You should then see an Emily Eclipse display, similar to Figure 5.

Figure 5: An empty, newly initialized Eclipse console.

12.1.1 Setting Eclipse to use the correct Java JDK

Newer versions of Eclipse come with their own version of Java. However, since we generally want to use our own Java JDK (such as Java 8, as described in Section 4), we need to configure Eclipse to use that instead. This can be done as follows:

  1. 1.

    From the main menu, select Window > Preferences.

  2. 2.

    A Preferences dialog will open. In the left panel, select “Java > Installed JREs”, which will open an Installed JREs panel. Click the Add... button at the right.

  3. 3.

    A JRE Type dialog will appear. Leave “Standard VM” selected in the dialog and click Next.

  4. 4.

    A JRE Definition dialog will appear. In the “JRE home” field at the top, enter the installation folder for your JDK. On Windows, this is likely to be a location like C:\Program Files\Java\jdk1.8.0_281. Specifying the java home folder will cause some other fields to fill in automatically, as seen in Figure 6.

    Figure 6: Eclipse JRE Definition dialog.
  5. 5.

    Click Finish. Your Java JDK will now show up in the list of installed JREs. Click on the left box to select it, as shown in Figure 7 (ignore any warnings about Java 15 compatibility).

    Figure 7: Eclipse Installed JREs dialog.
  6. 6.

    Finish by clicking the “Apply and Close” button at the bottom of the Preferences dialog.

12.1.2 Preventing excess resource copying

By default, ArtiSynth classes are placed in file tree located beneath <ARTISYNTH_HOME>\classes that is separate from the source tree located beneath <ARTISYNTH_HOME>\src. That means that Eclipse will try to copy all non-Java files and folders from the source tree into the build tree. For ArtiSynth, this is excessive, and results in many files being copied that don’t need to be, since ArtiSynth looks for resources in the source tree anyway.

To prevent this copying:

  1. 1.

    Choose Window > Preferences.

  2. 2.

    Select Java > Compiler > Building.

  3. 3.

    Open Output folder, and in the box entitled Filter resources, enter the single character ‘*’.

12.2 Importing external projects

Let <PROJECT_DIR> denote the top-level folder of the project to be imported. (In the case of artisynth_core, this will also be <ARTISYNTH_HOME>.) Assuming that <PROJECT_DIR> contains an Eclipse .project file, you can import it into Eclipse as follows:

  1. 1.

    From within Eclipse, choose File > Import ....

  2. 2.

    An Import dialog will appear. Select General > Existing Projects into Workspace and click Next.

  3. 3.

    An Import Projects dialog will appear. In the field Select root directory, enter (or browse to) the parent folder of <PROJECT_DIR>. The project itself should now appear in the Projects box (Figure 8). (If other projects are contained in the parent folder, these will appear as well.) Make sure that the desired project is selected and then click Finish.

If Eclipse complains that "No projects are found to import", or does not otherwise show the project as available for import, then most likely the <PROJECT_DIR> folder does not contain a .project file.

Figure 8: Partial view of the Eclipse Import Projects dialog.

12.3 Configuring environment variables

While it is generally not necessary to set environment variables in Eclipse, it may be useful to do this on occasion to control certain aspects of ArtiSynth’s operation. Directions on setting the environment variables are given in Section 12.3.1, and descriptions of the variables themselves may be found in Section 13.2.

Some variables that are commonly set within Eclipse include:

  • ARTISYNTH_HOME: If set, this should be set to <ARTISYNTH_HOME>. Normally ArtiSynth is able to infer its own location internally, so it is generally unnecessary to set this variable explicitly.

  • OMP_NUM_THREADS: Specifies the maximum number of processor cores available for multicore execution.

If any of the above variables have already been set externally in Windows (Sections 13.2.1 and 13.2.2), such that they are visible to Eclipse at start-up, then they do not need to be set in the launch configuration.

12.3.1 Setting environment variables

To set environment variables within Eclipse:

  1. 1.

    Open a java perspective if necessary by choosing Window > Open Perspective > Java.

  2. 2.

    Select the ArtiSynth project in the Package Explorer form.

  3. 3.

    Choose Run > Run Configurations... to open the Run Configurations window.

  4. 4.

    In the left panel, under Java Application, select the launch configuration (the default is named ArtiSynth).

  5. 5.

    In the right panel, select the Environment tab.

  6. 6.

    To create a new environment variable, click the New button and enter the name and value in the dialog box.

  7. 7.

    When finished, make sure that Append environment to native environment is selected, and click Apply.

12.4 Command line and JVM arguments

As described in Section 7.1, the artisynth command accepts command line arguments. To invoke these when running from Eclipse, it is necessary to set the desired arguments in the launch configuration, as described below.

Sometimes it may also be necessary to set JVM arguments, which control the Java virtual machine running ArtiSynth. An example of such an argument is -Xmx, which can be used to increase the maximum amount of memory available to the application. For example, -Xmx6g sets the maximum amount of memory to 6 gigabytes.

12.4.1 Setting command line and JVM arguments

To set command line arguments for your Eclipse application:

  1. 1.

    Open a java perspective if necessary by choosing Window > Open Perspective > Java.

  2. 2.

    Select the ArtiSynth project in the Package Explorer form.

  3. 3.

    Choose Run > Run Configurations... to open the Run Configurations window.

  4. 4.

    In the left panel, under Java Application, select the launch configuration (the default is named ArtiSynth).

  5. 5.

    In the right panel, select the Arguments tab.

  6. 6.

    Program arguments (which are passed directly to ArtiSynth) should be specified in the Program arguments box. JVM arguments should be specified in the VM arguments box. See Figure 9.

  7. 7.

    When finished, click Close.

Figure 9: Editing command line and JVM arguments for a run configuration.

12.5 Adding projects to the build path

A project imported into Eclipse may depend on the packages and libraries found in other projects to compile properly. For example, ArtiSynth applications which are external to artisynth_core will nonetheless depend on artisynth_core. To ensure proper compilation, project dependencies should be added to each dependent project’s build path.

  1. 1.

    Select the dependent project in the Package Explorer form.

  2. 2.

    Right click and choose Build Path > Configure Build Path...

  3. 3.

    In the right panel, select the Projects tab.

  4. 4.

    Click the Add button, select the project dependencies, and click OK

  5. 5.

    Click OK in the Java Build Path panel

12.6 Adding projects to the ArtiSynth launch configuration

The classes of external projects can be made visible to ArtiSynth by adding the projects themselves to the Classpath of the ArtiSynth launch configuration.

  1. 1.

    From the main menu, choose Run > Run Configurations... to open a Run Configurations dialog.

  2. 2.

    In the left panel, under Java Application, select your ArtiSynth launch configuration (the default one is called ArtiSynth). This may already be selected when you open the panel.

  3. 3.

    In the right panel, select the Classpath tab.

  4. 4.

    In the Classpath window, select User Entries, and then click the Add Projects button.

  5. 5.

    In the Project Selection dialog, select the external projects that you wish to add. Generally, the boxes Add exported entries ... and Add required projects ... can be unchecked. Click OK.

  6. 6.

    Close the Run Configurations dialog.

13 Additional Information

13.1 Adding Directories to the System Path

The system “Path” is a list of directories which the system searches in order to find executables. Adding a directory to the path allows executables contained in that directory to be called directly from a command window such as CMD.

13.1.1 Windows 10

  1. 1.

    Open the Start search, enter “env”, and choose “Edit the system environment variables”.

  2. 2.

    Click on Environment Variables.

  3. 3.

    Under User variables (the top window), click on Path and click Edit. If Path does not exist, click New.

  4. 4.

    In the Edit environment variable dialog, click New and enter the full path name for each directory you wish to add.

  5. 5.

    Close each dialog by clicking OK.

13.1.2 Windows 8 and earlier

  1. 1.

    Right-click My Computer, and then click Properties.

  2. 2.

    Click the Advanced tab.

  3. 3.

    Click Environment variables.

  4. 4.

    In the top User variables window, click on Path and then Edit. If Path does not exist, click New.

  5. 5.

    In the edit window, add the full path name for each new directory, separated by semi-colons ‘;’.

  6. 6.

    Close each dialog by clicking OK.

For example, if ArtiSynth is installed at C:\artisynth\artisynth_core and the desired JDK is at C:\Program Files\Java\jdk1.8.0_281, then we can add the bin directories for both by setting the User path to

  C:\artisynth\artisynth_core\bin;C:\Program Files\Java\jdk1.8.0_281\bin

Most most command windows and applications need to be restarted in order to get them to notice changes to Path.

13.2 Environment variables

This is a glossary of all the environment variables that are associated with building or running ArtiSynth. Often, the system can detect and set appropriate values for these automatically. In other cases, as noted in the above documentation, it may be necessary or desirable for the user to set them explicitly.

ARTISYNTH_HOME

The path name of the ArtiSynth installation folder.

CLASSPATH

A list of folders and/or JAR files, separated by semi-colons ‘;’, which Java uses to locate its class files.

Path

A list of folders, separated by semi-colons ‘;’, which the operating system uses to locate executable programs and applications. Placing <ARTISYNTH_HOME>\bin in Path (as described in Section 13.1) will allow you to run artisynth and related commands directly from a command window.

OMP_NUM_THREADS

Specifies the maximum number of processor cores that are available for multicore execution. Setting this variable to the maximum number of cores on your machine can significantly increase performance.

Note that settings for most of the above can be derived from the value of ARTISYNTH_HOME.

13.2.1 Setting environment variables

On Windows, a user can view, set, or change environment variables via the following steps:

Windows 10:

  1. 1.

    Open the Start search, enter “env”, and choose “Edit the system environment variables”.

  2. 2.

    Click on Environment Variables.

  3. 3.

    Choose one of the following options:

    • Click New to add a new variable name and value.

    • Click an existing variable, and then Edit to change its name or value.

    • Click an existing variable, and then Delete to remove it.

  4. 4.

    Close each dialog by clicking OK.

Windows 8 and earlier:

  1. 1.

    Right-click My Computer, and then click Properties.

  2. 2.

    Click the Advanced tab.

  3. 3.

    Click Environment variables.

  4. 4.

    Choose one of the following options:

    • Click New to add a new variable name and value.

    • Click an existing variable, and then Edit to change its name or value.

    • Click an existing variable, and then Delete to remove it.

  5. 5.

    Close each dialog by clicking OK.

Variable settings can reference other environment variables by surrounding them with percent signs, as in %VAR_NAME%. For example, suppose you already have an environment variable HOME that gives the location of your home folder, and your ArtiSynth distribution is located in packages\artisynth_core relative to your home folder. Then the environment variable ARTISYNTH_HOME can be specified as

  %HOME%\packages\artisynth_core

13.2.2 Typical environment settings

Typical settings for the environment variables described above might look like this:

ARTISYNTH_HOME c:\users\joe\artisynth_core
CLASSPATH %ARTISYNTH_HOME%\classes;%ARTISYNTH_HOME%\lib\*
PATH %ARTISYNTH_HOME%\bin;%PATH%
OMP_NUM_THREADS 4

13.2.3 GitBash environment settings

When using GitBash (Section 6.2), it is possible to set environment variables in a .bashrc file located in the user’s home folder. The file entries corresponding to the settings of Section 13.2.2 would look like this:

# set ARTISYNTH_HOME to the appropriate location ...
export ARTISYNTH_HOME=C:/users/joe/artisynth_core
# Windows file notation is needed for CLASSPATH:
AH="C:\users\joe\/artisynth_core"
export CLASSPATH="$AH\classes;$AH\lib\*"
export PATH=$ARTISYNTH_HOME/bin:$PATH
# Set to the number of cores on your machine:
export OMP_NUM_THREADS=4

Note that the CLASSPATH environment variable must be set using a Windows format, with backslash (’\’) to separate files and semicolon (’;’) to separate path entries. This requirement is imposed by the Java compiler.

13.3 ArtiSynth Libraries

ArtiSynth uses a set of libraries located under <ARTISYNTH_HOME>\lib. These include a number of JAR files, plus native libraries located in architecture-specific sub-folders (Windows64 for 64-bit Windows systems).

As described in Section 6, these libraries need to be downloaded automatically if the system is obtained from the GitHub repository. The required libraries are listed in the file <ARTISYNTH_HOME>\lib\LIBRARIES. This file is checked into the repository, so that the system can always determine what libraries are needed for a particular checkout version.

Occasionally the libraries are changed or upgraded (Section 11). If you run ArtiSynth with the -updateLibs command line option, the program will ensure that not only are all the required libraries present, but that they also match the latest versions on the ArtiSynth server.

13.4 The EXTCLASSPATH File

In order to run an external model in ArtiSynth, all class folders and JAR files associated with those external models must be made visible to ArtiSynth. One way to do this is to list these as entries in a text file named EXTCLASSPATH, located in <ARTISYNTH_HOME>.

Using a plain text editor (such as Notepad) open EXTCLASSPATH (or create it if it does not already exist) and add the required class folders and JAR files. Usually these are added one per line, but multiple entries can be made on the same line if separated by semi-colons ‘;’.

The syntax rules for EXTCLASSPATH are:

  1. 1.

    Entries on the same line should be separated semi-colons ‘;’.

  2. 2.

    The ‘#’ character comments out all remaining characters to the end of line.

  3. 3.

    The ‘$’ character can be used to expand environment variables.

  4. 4.

    Any spaces present will be included in the entry name.

An example EXTCLASSPATH might look like this:

C:\research\artisynth_models\classes
C:\research\models\special.jar
$HOME\projects\crazy\classes

13.5 Quick Git Summary

Git is a distributed source control management (SCM) system that is widely used in the software industry. A full discussion of Git is beyond the scope of this document, but a large literature is available online. Generally, when you clone a Git repository, you create a local copy of that repository on your machine, along with a checked out working folder containing the most recent version of the code (which is referred to as the HEAD).

Unlike client/server SCMs, Git is distributed, with users maintaining their own private copies of a repository. This allows a great deal of flexibility in usage, but also adds an extra “layer” to the workflow: when you “checkout” from a repository or “commit” to it, you do so with respect to your own local copy of that repository, not the original (origin) repository from which you performed the original clone. The process of merging in changes from the origin to the local repository is known as “pulling”, while committing changes from the local repository back to the origin is known as “pushing”.

There is also another layer of interaction when you commit changes to the local repository: you first add them to a staging area (also known as the “index”), and then commit them using the commit command.

A very simple workflow for a typical ArtiSynth user is summarized below. The actions are described in command-line form, but the same commands can generally be issued through Eclipse or other interfaces. First, clone the most recent version of the ArtiSynth repository on GitHub:

  git clone https://github.com/artisynth/artisynth_core.git [<dir>]

This will create a local copy of the GitHub repository, along with a checked out “working copy”, in the folder specified by <dir>, or in artisynth_core if <dir> is omitted. The repository itself will be located in a sub-folder called .git.

Other Git repositories can be cloned in a similar manner. If the repository has read access restrictions, then when performing a checkout it may also be necessary to specify a user name for which the repository has granted read access. This is typically done by embedding the user name in the URL, as in (for example):

https://user@host.xz/path/to/repo.git

Later, to fetch the latest updates from the GitHub repository and merge them into your working copy, from within the working copy folder you can do

  git pull

If you make changes to some files in your working copy and wish to commit these to your local repository, you first add (or remove them) from the staging area using commands such as:

  git add <fileName>    # add a new (or modified) file
  git add *             # add all files
  git rm <fileName>     # remove a file

and then commit them to your local repository using

  git commit -m "commit message"

Note that you can also add modified files and commit them using the single command

  git commit -m -a "commit message"

To see the current status of the files in your working copy and the staging area, use the command

  git status

and to see the commit history for particular files or folders, use

  git log [ <filename> ... ]

Finally, to push your changes back to the GitHub repository (assuming you have permission do so), you would do so using the command

  git push origin master

Note that the above commands all have various options not mentioned. There are also numerous topics that haven’t been discussed, including the creation and merging of branches, but there are many useful online resources that describe these in detail. Some current references include

   https://git-scm.com/docs
   http://rogerdudler.github.io/git-guide