ArtiSynth Installation Guide for Windows

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