Installing ArtiSynth from GitHub into Eclipse (Windows)

This document describes how to install ArtiSynth directly from GitHub and import it into the Eclipse IDE (Integrated Development Environment), within a Windows environment. While for demonstration purposes it is faster to install ArtiSynth using a precompiled release, installing from GitHub provides access to the most recent updates, and the Eclipse IDE is a convenient platform for developing and modifying the Java code used to create ArtiSynth models.

There are three parts to the installation process:

1. 1.

   Installing the Java development kit (JDK)

2. 2.

   Installing Eclipse

3. 3.

   Installing ArtiSynth from GitHub

Your host machine should be a 64 bit system that is based on the Intel processor. ArtiSynth may also run on ARM-based systems that provide an Intel compatibility layer. We recommend a minimum of 8 Gbytes of memory, and 16 Gbytes or more is better if you are doing FEM work with larger numbers of elements.

This document is intentionally brief and describes only installation from Git into an Eclipse IDE. More complete instructions, including how to create and add models, integrate external models, and update ArtiSynth, are given in the General Installation Guide. Instructions for visualizing, navigating, editing and simulating models are given in the ArtiSynth User Interface Guide. Instructions on how to build a model using Java are given in the ArtiSynth Modeling Guide.

ArtiSynth requires that you have a full 64-bit Java development kit (JDK) installed, which comes with a Java compiler; a simple run time environment (JRE) will not be sufficient.

Important: on ARM-based machines, you must still install a 64-bit Intel-based JDK which must then execute through an Intel compatibility layer. Invocation of the compatibility layer should generally be invisible to the user. 64-bit Intel-based JDKs contain the string x64 in their download names, whereas ARM-based JDKs contain aarch64 or arm32.

By default, ArtiSynth is compiled to be compliant with Java 8. While ArtiSynth will generally work under later Java versions, use of both the MATLAB and Jython interfaces generally requires Java 8. Therefore we currently recommend using Java 8; this also provides maximum compatibility with MATLAB. 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

www.oracle.com/java/technologies/javase/javase-jdk8-downloads.html

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.

The java and javac commands associated with your Java 8 JDK must be visible from a terminal window. To verify this, open a terminal window, run the command javac -version, and check that the command is found and that the version matches the JDK. If it does not, follow the instructions in Section 6.

Eclipse is an integrated development environment (IDE) that is commonly used for writing and maintaining Java programs. While other IDEs exist for Java, such as NetBeans and IntelliJ, Eclipse is currently the most commonly used amongst ArtiSynth users. It should be noted, however, that an IDE is not required for Java programming; simpler programs, in particular, can often be created by editing the .java source files using a text editor and then compiling them with command line tools, including the compile utility supplied by ArtiSynth.

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 folderwith a file explorer, and you will see the eclipse application:

Click on this to open it. The following dialog will appear, asking you to select a workspace folder:

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 this:

Newer versions of Eclipse come with their own version of Java. However, since we want to use the Java 8 JDK, as discussed above, we need to configure Eclipse to use that instead.

Eclipse can be configured to use your JDK 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 Java home folder where Java 8 was installed. 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 here:

   
5. 5.

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

   
6. 6.

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

You can now install ArtiSynth from GitHub.

1. 1.

   From the panel at the left of the main Eclipse frame, choose “Import projects...”. 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 folderinto which ArtiSynth will be placed locally. Use the default location, or edit it to some other desired location. This will be your ArtiSynth installation folder. 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 next to 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 installation folder (e.g., C:\people\roger\artisynth_core), open the bin folder, and click on the updateArtisynthLibs batch file:

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.

You should now be able to run ArtiSynth. From the main menu, select artisynth_core by clicking on it in the Package Explorer, and then from the main menu select Run > Run, and the ArtiSynth application will start up (perhaps a little slowly the first time). Within ArtiSynth, you can load a demonstration model by selecting Models > Demos from the main menu and choosing a demo model:

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, and resetting it to time 0 is done by clicking reset. The single-step button advances the simulation by one time step.

A model can also be loaded by specifying either its defining class or a .art file containing its textual representation. For details, see the section “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 interface guide also contains information on using the ArtiSynth GUI for model visualization, navigation, editing, and simulation control. Instructions on how to build a model using Java are given in the ArtiSynth Modeling Guide.

The image below shows ArtiSynth with the Spring Net demo loaded:

If the java and javac commands of your Java JDK are not visible from a terminal command window, you can fix this by adding <JDK_HOME>\bin to your system Path variable, where <JDK_HOME> is the installation folder for your JDK. For example, if your JDK is installed in C:\Program Files\Java\jdk1.8.0_281, you want to add C:\Program Files\Java\jdk1.8.0_281\bin to the Path, ahead of other entries.

The Path is a list of directories which the system searches in order to find executables. You can add <JDK_HOME>\bin to it as follows: