The Wes Project is about editing animations used in the jMonkeyEngine (JME) game engine.

It contains 2 subprojects:

1. WesLibrary: the Wes JVM runtime library
2. WesExamples: demos, examples, and non-automated test software

Complete source code (in Java) is provided under a 3-clause BSD license.

Contents of this document

• Important features
• How to add Wes to an existing project
• How to build Wes from source
• Downloads
• Conventions
• An overview of the demo applications
• External links
• History
• Acknowledgments

Important features

• extract a time-range from an animation
• resample an animation track at a new frame rate
• retarget animations from one model/skeleton to another
• interpolate between keyframes using a wide assortment of algorithms
• reverse an animation track
• chain 2 tracks together
• repair certain issues with animation tracks
• convert a traveling animation to an in-place cyclic animation

Most of the features work with both the old and new animation systems.

Jump to the table of contents

How to add Wes to an existing project

Wes comes pre-built as a single library dependent on the Heart Library, which in turn depends on the standard "jme3-core" library from jMonkeyEngine. Adding Wes to an existing jMonkeyEngine project should be a simple matter of adding these libraries to the classpath.

For projects built using Maven or Gradle, it is sufficient to add a dependency on the Wes Library. The build tool should automatically resolve the remaining dependencies.

Gradle-built projects

Add to the project’s "build.gradle" or "build.gradle.kts" file:

repositories {
    mavenCentral()
}
dependencies {
    implementation("com.github.stephengold:Wes:0.8.1")
}

For some older versions of Gradle, it's necessary to replace implementation with compile.

Maven-built projects

Add to the project’s "pom.xml" file:

<repositories>
  <repository>
    <id>mvnrepository</id>
    <url>https://repo1.maven.org/maven2/</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.stephengold</groupId>
  <artifactId>Wes</artifactId>
  <version>0.8.1</version>
</dependency>

Ant-built projects

For projects built using Ant, download the Wes and Heart libraries from GitHub:

• https://github.com/stephengold/Wes/releases/tag/latest
• https://github.com/stephengold/Heart/releases/tag/8.8.0

You'll definitely want both class jars and probably the "-sources" and "-javadoc" jars as well.

Open the project's properties in the IDE (JME SDK or NetBeans):

1. Right-click on the project (not its assets) in the "Projects" window.
2. Select "Properties" to open the "Project Properties" dialog.
3. Under "Categories:" select "Libraries".
4. Click on the "Compile" tab.
5. Add the Heart class jar:

• Click on the "Add JAR/Folder" button.
• Navigate to the download folder.
• Select the "Heart-8.8.0.jar" file.
• Click on the "Open" button.

6. (optional) Add jars for javadoc and sources:

• Click on the "Edit" button.
• Click on the "Browse..." button to the right of "Javadoc:"
• Select the "Heart-8.8.0-javadoc.jar" file.
• Click on the "Open" button.
• Click on the "Browse..." button to the right of "Sources:"
• Select the "Heart-8.8.0-sources.jar" file.
• Click on the "Open" button again.
• Click on the "OK" button to close the "Edit Jar Reference" dialog.

7. Similarly, add the Wes jar(s).
8. Click on the "OK" button to exit the "Project Properties" dialog.

Jump to the table of contents

How to build Wes from source

1. Install a Java Development Kit (JDK), if you don't already have one.
2. Point the JAVA_HOME environment variable to your JDK installation: (In other words, set it to the path of a directory/folder containing a "bin" that contains a Java executable. That path might look something like "C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot" or "/usr/lib/jvm/java-17-openjdk-amd64/" or "/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home" .)

• using Bash or Zsh: export JAVA_HOME=" path to installation "
• using Fish: set -g JAVA_HOME " path to installation "
• using Windows Command Prompt: set JAVA_HOME=" path to installation "
• using PowerShell: $env:JAVA_HOME = ' path to installation '

3. Download and extract the Wes source code from GitHub:

• using Git:
  • git clone https://github.com/stephengold/Wes.git
  • cd Wes
  • git checkout -b latest 0.8.1
• using a web browser:
  • browse to the latest release
  • follow the "Source code (zip)" link
  • save the ZIP file
  • extract the contents of the saved ZIP file
  • cd to the extracted directory/folder

4. Run the Gradle wrapper:

• using Bash or Fish or PowerShell or Zsh: ./gradlew build
• using Windows Command Prompt: .\gradlew build

After a successful build, Maven artifacts will be found in "WesLibrary/build/libs".

You can install the artifacts to your local Maven repository:

• using Bash or Fish or PowerShell or Zsh: ./gradlew install
• using Windows Command Prompt: .\gradlew install

You can restore the project to a pristine state:

• using Bash or Fish or PowerShell or Zsh: ./gradlew clean
• using Windows Command Prompt: .\gradlew clean

Jump to the table of contents

Downloads

Newer releases (since v0.3.9) can be downloaded from GitHub.

Old releases (v0.2.1 through v0.3.8) can be downloaded from the Jme3-utilities Project.

Newer Maven artifacts (since v0.6.2) are available from MavenCentral.

Old Maven artifacts (v0.4.8 thru v0.6.1) are available from JCenter.

Jump to the table of contents

Conventions

Package names begin with jme3utilities. (if Stephen Gold holds the copyright) or com.jme3. (if the jMonkeyEngine Project holds the copyright).

The source code is compatible with JDK 7. The pre-built libraries are compatible with JDK 8.

Jump to the table of contents

An overview of the demo applications

Applications have been created to showcase certain features of Wes. The following demos are found in the WesExamples subproject:

ConvertToInPlace

Demonstrates converting the "hurricane_kick" animation (from Adi Barda's ninja-fighter model) to an in-place cyclic animation. The unmodified animation is shown on a white skeleton, synchronized with the converted animation, which is shown on a yellow skeleton.

FlashMobDemo

Demonstrates retargeting the "Dance" animation clip of the Sinbad model to 4 unrelated models: Jaime, MhGame, Oto, and Puppet.

ReverseAnimation

Demonstrates reversing the "StandUpBack" animation clip of the Sinbad model to generate a "LieDown" clip.

TrimAnimation

Demonstrates trimming and stretching the "SliceHorizontal" animation clip of the Sinbad model to generate a "warn" clip.

Jump to the table of contents

External links

• the Wes Animation Toolkit page in the JmonkeyEngine Library

Jump to the table of contents

History

The evolution of this project is chronicled in its release log.

Much of the Wes code was originally developed for the Maud editor.

The retargeting code is derived from the Bvhretarget Project.

From September 2017 to January 2019, Wes was a subproject of the Jme3-utilities Project.

Since January 2019, Wes has been a separate project, hosted at GitHub.

Jump to the table of contents

Acknowledgments

Like most projects, the Wes Project builds on the work of many who have gone before. I therefore acknowledge the following artists and software developers:

• Rémy Bouquet (aka "nehon") for creating the Jaime model and the Bvhretarget Project (on which BoneMapping and SkeletonMapping are based) and also for many helpful insights
• Adi Barda, for creating the ninja-fighter model
• Zi Ye, for creating the Sinbad model
• Nathan Vegdahl, for creating the Puppet model
• Paul Speed, for helpful insights
• Ali (aka "Ali_RS") for sharing a code snippet that inspired the convertToInPlace() methods
• plus the creators of (and contributors to) the following software:
  • the Checkstyle tool
  • the FindBugs source-code analyzer
  • the Firefox and Google Chrome web browsers
  • the Git revision-control system and GitK commit viewer
  • the GitKraken client
  • the Gradle build tool
  • the IntelliJ IDEA and NetBeans integrated development environments
  • the Java compiler, standard doclet, and runtime environment
  • jMonkeyEngine and the jME3 Software Development Kit
  • the Linux Mint operating system
  • LWJGL, the Lightweight Java Game Library
  • the MakeHuman 3-D character creation tool
  • the Markdown document-conversion tool
  • the Meld visual merge tool
  • Microsoft Windows
  • the PMD source-code analyzer
  • the WinMerge differencing and merging tool

I am grateful to GitHub, Sonatype, JFrog, and Imgur for providing free hosting for this project and many other open-source projects.

I'm also grateful to my dear Holly, for keeping me sane.

If I've misattributed anything or left anyone out, please let me know, so I can correct the situation: [email protected]

Jump to the table of contents