ArtiSynth Installation Guide for Windows

To obtain one of the packaged distributions, go to www.artisynth.org/downloads and select the distribution you want. Download it, and unzip it in an appropriate location on your computer.

Important:
On Windows, it is highly recommended that ArtiSynth is not installed in a location for which any of the folder names contain spaces (i.e., Program Files). This can be important for some ArtiSynth programs to run correctly.

Once ArtiSynth is downloaded and unpacked, it should be possible to run it immediately by executing the artisynth.bat file located in <ARTISYNTH_HOME>\bin (see Section 6.1).

Because the jar files and native libraries used by ArtiSynth are large, they are not stored in the Github repository. Instead, they must be downloaded separately. This can be done using the command updateArtisynthLibs.bat, located in <ARTISYNTH_HOME>\bin. You can execute it by double-clicking on it in a file-browser, or by opening a command console (CMD), navigating to <ARTISYNTH_HOME>, and entering the command

 % bin\updateArtisynthLibs

If you have Cygwin (Section 10.3) installed, the same command is available as updateArtisynthLibs, also located in <ARTISYNTH_HOME>\bin.

If your Github clone has been done externally to Eclipse (i.e., not according to Section 4.0.3), then you need to first import ArtiSynth into Eclipse. Follow the instructions in Section 9.2.1.

Once ArtiSynth has been imported, you should be able to build it. If necessary, first open a Java perspective by choosing Window > Open Perspective > Java. The project artisynth_core (or whatever you might have named it) should appear in the Package Explorer window. To build the system, select the project in the Package Explorer window, and then choose Project > Build Project. Note that it may be necessary to deselect Build Automatically in order to enable Build Project.

If you have Cygwin (Section 10.3) installed, ArtiSynth can also be built from a Cygwin terminal by running a make command in the top level folder. Before doing this, you need to first set the environment variables ARTISYNTH_HOME and CLASSPATH as described in Sections 10.4 and 10.4.4. ArtiSynth can then be built by executing

 > cd <ARTISYNTH_HOME>
 > make

The most direct way to start ArtiSynth is to run the batch file artisynth.bat, located in <ARTISYNTH_HOME>\bin. This can be done by double-clicking on it in a file browser.

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

Alternatively, you can open a command console (CMD), navigate to <ARTISYNTH_HOME>, and enter the command

 % bin\artisynth

It is recommended to place <ARTISYNTH_HOME>\bin in your PATH environment variable (Section 10.4), so that the console command simplifies to

 % artisynth

regardless of the current directory.

Note:
If Java is installed in a non-conventional location, the system may not be able to find it and this will cause artisynth.bat to fail. To fix this, locate the folder in which java.exe resides, and let the location of this folder be called JAVA_DIR. You should then add JAVA_DIR to your system’s PATH environment variable (see Section 10.4.2).

If you have Cygwin (Section 10.3) installed, then you can run ArtiSynth directly with the artisynth command located in <ARTISYNTH_HOME>/bin:

 > cd <ARTISYNTH_HOME>
 > bin/artisynth

If <ARTISYNTH_HOME>/bin has been placed in your PATH variable (Section 10.4), then it is sufficient to do

 > artisynth

artisynth can be called with a number of options; to see these, run

 > artisynth -help

The artisynth command accepts command line arguments, a full list of which 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

Once ArtiSynth has been imported into Eclipse (and built if necessary), it should contain a launch configuration called ArtiSynth that will allow ArtiSynth to be run by choosing Run > Run.

In some cases, one may wish to adjust environment variables, command line arguments, or Java JVM arguments to affect how ArtiSynth behaves. Instructions for doing so are contained in Sections 9.3 and 9.4.

Once ArtiSynth starts up, you can use it to load and run models. General instructions on how to load and run models are given in the section ``Loading and Simulating Models'' of the ArtiSynth User Interface Guide.

By default, ArtiSynth comes with a number of demonstration models, which can be loaded and run as follows:

From the menu bar, Select Models > Demos. This will display a submenu of demonstration models. Choosing one will cause that model to be loaded and displayed in the viewer. Simulation of the model can then be started, paused, single-stepped, or reset using the play controls (Figure 1) located at the upper right of the ArtiSynth window frame.

Comprehensive information on exploring and interacting with models is given in the ArtiSynth User Interface Guide.

Some model and package collections, such as artisynth_models mentioned above, may be available either as prepackaged distributions, or through Git or Subversion repositories. Prepackaged distributions should be downloaded and unpacked into a desired location, while Git or Subversion checkouts may may be obtained as described in Sections 10.7 or 10.8.

Some collections maintained by ArtiSynth may contain Eclipse project settings (in an eclipseSettings.zip file in their root folder), allowing them to be imported into Eclipse, either directly from Git (Section 9.2.2) or Subversion ( Section 9.2.3), or after being obtained separately (Section 9.2.1).

Collections that are obtained from Git or Subversion will need to be built (compiled).

External models are executed by running ArtiSynth itself (Section 6). However, in order to execute these models, ArtiSynth must be able to locate their associated classes. This can be arranged in three different ways:

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. Sometimes, it will be necessary to explicitly update the libraries after doing the main update. This can be done by executing updateArtisynthLibs as described in Section 4.1.

Eclipse can be obtained from www.eclipse.org/downloads. A good version to obtain (at the time of this writing) is Eclipse IDE for Java Developers.

The Eclipse instructions described below are based on the ``Neon'' distribution, but should be largely similar for later versions.

ArtiSynth projects include the core distribution (artisynth_core), the open source models collection artisynth_models (which contains human anatomy models), as well as other model and code collections maintained by the ArtiSynth team and other users.

There are several ways to import ArtiSynth projects into Eclipse. If the project has already been downloaded or checked out from a repository, then it can be imported as an external project (Section 9.2.1). Otherwise, Eclipse itself can be used to check out a project from either Git (Section 9.2.2) or Subversion (Section 9.2.3).

When running ArtiSynth from Eclipse, it may be useful to set certain environment variables that affect its operation. Directions on setting the environment variables are given in Section 9.3.1, and descriptions of the variables themselves may be found in Section 10.4.

Some variables that are commonly set within Eclipse include:

• •

  ARTISYNTH_HOME: This should be set to <ARTISYNTH_HOME>. The ArtiSynth launch configuration in artisynth_core achieves this by settingARTISYNTH_HOME to the built-in Eclipse variable ${project_loc}. However, for launch configurations defined outside of artisynth_core, it may be necessary to set this variable explicitly.

• •

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

• •

  ARTISYNTH_PATH: A list of folders, separated by semi-colons ";", which ArtiSynth uses to search for configuration files. See Section 10.4.

If any of the above variables have already been set externally in Windows (Sections 10.4.1 and 10.4.3), 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 6.3, 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 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.

In order to work with Subversion from within Eclipse, either to check out ArtiSynth from the repository, or to update or commit changes, it is necessary to use a Subversion plug-in. First, check to see if your version of Eclipse contains an Subversion plug-in:

Open an import panel using File > Import..., and then look for SVN in the set of available import sources. If you don’t see SVN listed, it will be necessary to install a plug-in.

We recommend the Eclipse-supported Subversive plug-in, but if this proves difficult for any reason, there are other options, such as Subclipse, currently obtainable from subclipse.tigris.org.

Instructions for installing Subversive can be obtained at www.eclipse.org/subversive/installation-instructions.php.

One way to install Subversive is through the Eclipse Marketplace. If you have an older version of Eclipse that doesn’t have Marketplace, you may be able to obtain it from www.eclipse.org/mpc. To access the Marketplace, click Help > Eclipse Marketplace. Once the available applications have been displayed, type Subversive into the Find box in the top-left corner of the Marketplace window. Navigate to the package labeled Subversive - SVN Team Provider and click Install. On the Confirm Selected Features screen, ensure all boxes are checked and click the button labeled Confirm >. Restart Eclipse when prompted.

One more step is now necessary. Re-open Eclipse, and you should be prompted to choose an SVN connector in the start menu. SVN connectors interface Subversive to the SVN server, and are OS and server-specific. A recommended SVN Connector will be pre-selected for downloading; this is most likely the one you need.

If Eclipse did not prompt you to choose a connector when it restarted, you can install SVN connectors separately (thanks to bmaupin at Stackoverflow for this information):

1. 1.

   Go to www.polarion.com/products/svn/subversive/download.php

2. 2.

   Under the latest Release, copy the Subversive SVN Connectors URL. The current URL for Eclipse 4.3 Kepler is http://community.polarion.com/projects/subversive/download/eclipse/3.0/kepler-site.

3. 3.

   In Eclipse, go to Help > Install New Software... and click Add...

4. 4.

   Copy the URL for the Subversive SVN Connectors into the Location box and click OK

5. 5.

   Check Subversive SVN Connectors, click Next, and then follow the instructions to complete installation.

If in doubt about the connector you need, you can install multiple ones, and then adjust the one Subversive actually uses by going to Windows > Preferences, opening Team > SVN, and then opening the SVN Connector tab.

By default, ArtiSynth classes are built in a directory tree (<PROJECT_DIR>\classes) that is separate from the source tree (<PROJECT_DIR>\src), where <PROJECT_DIR> denotes the project root folder and is <ARTISYNTH_HOME> for ArtiSynth itself. 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.

It is possible to inhibit most of this copying:

1. 1.

   Choose Window > Preferences (or Eclipse > Preferences).

2. 2.

   Select Java > Compiler > Building.

3. 3.

   Open Output folder, and in the box entitled Filter resources, enter the string:

   ⬇

       Makefile,*.a*,*.b*,*.c,*.cc,*.cxx,*.e*,*.g*,*.h*,*.i*,*.m*,*.n*,*.o*,*.r*,*.s*,*.t*

That should filter out the copying of most non-java files.

Or, to prevent copying any resource, simply enter:

A version of Git for Windows can be installed from git-scm.com/download.

It installs a version of Git Bash for that can be used for entering Git commands. While going through the install steps, there is an option to select between:

1. 1.

   Use Git from Git Bash only

2. 2.

   Use Git from the Windows Command Prompt

3. 3.

   Use Git and optional Unix tools from the Windows Command Prompt

Option 2 (Git from CMD) is often fine for most users, and allows them to run all git commands directly from a command console CMD. There are other options for setting the default editor, the default console to open when starting Git Bash, etc., but the defaults should work well in most cases.

As mentioned above, some ArtiSynth models may be distributed via Subversion (SVN), and access to these will require an SVN client program. A popular SVN client for Windows is TortoiseSVN, which can be acquired from tortoisesvn.net. On that website, navigate to Downloads and then select the package appropriate for your operating system (which presumably will be 64-bits).

Once downloaded, run the MSI installer and follow the instructions in the installer. When the download completes, right-clicking in any file browser in Windows should now present you with SVN version control options, analogous to the command line instructions discussed in other parts of the documentation. We will briefly discuss here the three most common operations:

Checking out a repository

To check out an SVN repository with TortoiseSVN, right-click in any file exploration window and select SVN Checkout... from the context menu. The current directory will be the default directory for the Checkout directory field, and the Subversion_URL can be selected in the URL of repository field. It is recommended that other fields remain as their default values.

Updating a working copy

While inside a working copy of a repository in a file browser window, updating that repository is as simple as right-clicking and selecting SVN Update.

Committing changes

Users which have write-access to a Subversion repository may commit changes that they have made. Right-click in a file browser window inside a working copy of a repository and select Commit.... Write a commit message and the select OK.

Cygwin provides Windows users with a Linux-like, shell-based command environment. Its provides useful tools and enables ArtiSynth users to employ all the script-based commands in <ARTISYNTH_HOME>\bin, as well as various Makefile commands.

Cygwin can be downloaded from www.cygwin.com. Run the executable that was just downloaded (setup.exe) to begin installation. After selecting a download source, an install directory, a package directory, an internet connection, and a download site, the installer will display a list of packages which the user can select for download. Normally, a default set of packages is already selected for installation. It is advisable to install these packages to ensure that Cygwin retains its basic capabilities. It is also recommended that you select the following additional packages:

• •

  archive

• •

  git, svn, make (located under devel)

• •

  python (located under interpreters).

• •

  openssh (located under net)

If you are planning to compile C/C++ code, you may also want to install the various gcc and gdb packages (located under devel).

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.

ARTISYNTH_PATH

A list of folders, separated by semi-colons ";", which ArtiSynth uses to search for configuration files such as .artisyntInit or .demoModels. A typical setting for ARTISYNTH_PATH consists of the current folder (indicated by "."), the user’s home folder, and the ArtiSynth installation folder. If ARTISYNTH_PATH is not defined explicitly in the user’s environment, ArtiSynth assumes an implicit path consisting of the folder sequence just described.

CLASSPATH

A list of folders and/or jar files, separated by semi-colons ";", which Java uses to locate its class files. This variable should be set to include <ARTISYNTH_HOME>\classes and <ARTISYNTH_HOME>\lib\* (the latter uses the wildcard * to specify all the jar files in <ARTISYNTH_HOME>\lib).

PATH

A list of folders, separated by semi-colons ";", which the operating system uses to locate executable programs and applications. This should be set to include <ARTISYNTH_HOME>\bin and <ARTISYNTH_HOME>\lib\Windows64. This variable is described in detail in Section 10.4.2.

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.

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

In order to run an external model or package in ArtiSynth, all class paths (i.e., class folders or jar files) associated with those external classes must be made visible to ArtiSynth. One way to do this is to list these class paths as entries in the text file EXTCLASSPATH, located in <ARTISYNTH_HOME>.

To add class paths to EXTCLASSPATH, open it using a standard text editor (such as Notepad) and add each required path. For clarity, each path is typically added on a separate line. However, multiple paths can be added on the same line if they are separated by the path separator character used for that OS.

The syntax rules for EXTCLASSPATH are:

1. 1.

   Class path entries on the same line should be separated by a path separator character (a semi-colon ’;’ for Windows and a colon ’:’ for MacOS and Linux).

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 path 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, then from within the working copy directory 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

Subversion is a client/server source control management (SCM) system that is widely used in the software industry. A full discussion of Subversion is beyond the scope of this document, but a large literature is available online.

Subversion allows you to check out a codebase from a (often remote) repository into a local working copy, update recent changes from the repository into the working copy, and (if one has the appropriate permissions) commit local changes back into to repository.

A Subversion client application is used to access both Subversion repositories and local working copies. The remainder of this discussion will assume use of the command-line client svn, although other clients are available, including TortoiseSVN for Windows (Section 10.2) and the Subversion plug-ins for Eclipse (Section 9.7).

Some ArtiSynth models collections and code extensions are distributed through Subversion, including the artisynth_projects package used by some collaborators. A very simple workflow involving one of these is summarized below.

First, check out the most recent version from the repository, using the repository’s URL. For example, the URL for artisynth_projects is https://svn.artisynth.org/svn/artisynth_projects, and the associated checkout command is

  svn checkout https://svn.artisynth.org/svn/artisynth_projects/trunk [<dir>]

This will create a local working copy of the ``trunk'' branch of artisynth_projects in the folder specified by <dir>, or in artisynth_projects if <dir> is omitted. Local repository information is stored in a sub-folder called .svn.

If the SVN repository has read access restrictions (which artisynth_projects actually does), then when performing a checkout it may also be necessary to specify a user name or email address for which the repository has granted read access. This may be done with the --username option. The user will also typically be prompted for an access password.

Note:
If you omit the trailing /trunk from the Subversion URL, then the checkout will contain the entire Subversion directory structure, including the subdirectories trunk, branches, and tags, which is generally not needed by most users.

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

  svn update

If you make changes to some files in your working copy and wish to commit these back to the repository (assuming you have the necessary permissions), then you can issue the command

  svn commit -m "commit message"

To add or remove files from the repository, one may use the commands

  svn add <fileName> ...     # add files
  svn delete <fileName> ...  # delete files

prior to performing the commit.

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

  svn status

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

  svn log [ <filename> ... ]

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. The most comprehensive is probably the Subversion ``Redbook''.