ArtiSynth Installation Guide for Windows

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 14.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 21, then <JDK_HOME> will likely be

  C:\Program Files\Java\jdk-21

JDK 8 is named a little differently, and is likely to be located in

  C:\Program Files\Java\jdk-1.8

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

 > echo %PATH%

If you are using an integrated development environment (IDE), such as Eclipse (Section 13), for compiling and running ArtiSynth programs, you should also ensure that this IDE is configured to use the installed JDK. Instructions on how to do this for Eclipse are given in Section 13.1.1.

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.

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 14.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 13.2, using <ARTISYNTH_HOME> as the project directory.

If you are planning to use the Eclipse IDE (Section 13), you can install from GitHub directly into Eclipse. Directions on installing Eclipse and configuring it for ArtiSynth development are given in Section 13.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.

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.

Regardless of the JDK version, ArtiSynth is compiled to be compliant with Java 8, to ensure compatibility with MATLAB. The Eclipse settings supplied in artisynth_core\.settings will ensure Java 8 compliance.

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 13.3 and 13.4.

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

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 14.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):

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 bin/compile command on the last line is an ArtiSynth-supplied utility that compiles all .java files located under the current folder.

If you have GNU make installed on your system, then you can use that instead of the compile command, replacing

with

Regardless of the JDK version, ArtiSynth is compiled to be compliant with Java 8, to ensure compatibility with MATLAB. The make or compile commands described above are configured to ensure Java 8 compliance.

The compile (or make) command automatically determines the Java classpath needed to compile ArtiSynth. However, if you have explicitly set the CLASSPATH environment variable, then that will be used to define the classpath instead, in which case it must contain both the ArtiSynth classes folder and .jar files in the lib folder. See Sections 10.1.2 and 14.2.

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

For convenience, if you place <ARTISYNTH_HOME>\bin in your Path environment variable (Section 14.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:

The only real difference is using backslash (’\’) instead of forward slash (’/’) as a file separator.

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

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

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, skip-forward and stop-all 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. The stop-all button will also stop the simulation, as well as any Jython commands or scripts that are running.

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.

It is possible to load models in several ways:

• •

  Using a model menu entry, as described above;

• •

  Specifying the Java class describing the model (“Load from class ...” from the Models menu);

• •

  Specifying a .art file containing a text representation of the model (“Load model ...” from the File menu);

• •

  Reloading a recently loaded model (“Load recent” from the Models menu).

It is also possible to configure ArtiSynth to load a specific model when it starts up; see “Loading, Simulating and Saving Models” in the ArtiSynth User Interface Guide. The model menu can also be customized, as described in “Customizing the Model Menu”.

The ArtiSynth user interface provides a variety of tools for exploring and interacting with models, as described in depth in the ArtiSynth User Interface Guide, including:

• •

  3D viewers with grids and clipping planes;

• •

  Component selection using either a viewer or a tree-based navigation panel;

• •

  Property inspection and editing for selected components;

• •

  3D fixtures for translating, rotating and applying forces to models and their components;

• •

  A timeline for viewing and organizing input/output data streams known as probes;

• •

  Some simple model editing, including the ability to interactively delete components and add marker points;

• •

  Making movies from simulations.

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

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.

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

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,

How this is done depends on your development environment.

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 13.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 13.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 10.2.

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

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

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 update the ArtiSynth libraries.

The easiest way to do this is from within ArtiSynth, by selecting “Update Libraries” at the bottom of the File menu.

Libraries can also be updated using 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).

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 5). 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 6.

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

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

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 13.3.1, and descriptions of the variables themselves may be found in Section 14.2.

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

As described in Section 7.4, 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.

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

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.

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.

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 14.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. If not set, the system uses the maximum number of cores available. Users can also set this number from within ArtiSynth by setting the configuration property numSolverThreads, either for the current session by choosing “Settings > Interaction ...” from the main menu, or for all sessions by choosing “Settings > Preferences ... > Interaction”.

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

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

The EXTCLASSPATH file is stored in the user configuration folder (Section 9) and contains the entries for the external class path (Section 10.2.2). It is usually edited within ArtiSynth by selecting “External classpath ...” from the Settings menu but can also be edited directly. Each file entry describes a class folder or JAR file needed to run models external to the core ArtiSynth package. Entries are usually placed 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

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