GPC: Vona's Java Utils

This is a collection of general purpose Java code I have written and which I use in various projects.

A makefile-based (also see the build system doc) generic recursive build system for mostly-Java projects. It can handle subprojects in other languages that use their own makefiles. And it includes features beyond just compilation, including documentation build, distribution packaging, and pubishing.
CompileServer (also see the build system doc) accelerates Java builds by delegating compilation tasks to an always-running server process, thereby avoiding JVM startup costs for each complier invocation.
Some additional developer scripts (also see the build system doc).
A color sublibrary including a command-line colorspace conversion utility, ICCConvert, and a color scheme generation system based on [Bourges, Jean. (1997). Color Bytes. Forest Hills, New York: Chromatics Press, Inc.].
RMIWrap, a code generator that eases the difficulty of adding RMI capability to an arbitrary Java class.
Utilities for detecting Java version compatibility issues and working around them.
Utilities for dealing with Java3D scene graphs outside Java3D, including a JOGL-only replacement for Java3D's GeometryArray and accessors for Java3D vertex, index, and primitive datastructures.
a JOGL-only immediate mode renderer for Java3D scene graphs, with optimization for JOGLGeometry and Widgets that define collections of geometries, including a number of pre-defined simple shapes like SphereWidget.
ActionMapper, a layered system for dynamic mappings from key and mouse actions to handlers.
Some conveniences for using VT100-compatible terminals in Java, including terminal type detection, cursor placement, and text coloring.
A log implementation that integrates with Java's standard Logger infrastructure but which also generates colored terminal output and behaves reasonably well in applet contexts.
SuperClock, a timebase that can be accelerated or decelerated with respect to wall-clock time.
VonaMath, a collection of (mostly geometric) short math routines I've found useful.
SVD driver infrastructure with JLAPACK and netlib-java backends.
A generic prioritized damped least squares real-time numeric solver for differentiable constraint systems based on [Paolo Baerlocher and Ronan Boulic. An inverse kinematics architecture enforcing an arbitrary number of strict priority levels. The Visual Computer 20, pp 402--417, 2004].
A 3D rigid transform library based on the exponential map parameterization for rotations, as described in [Grassia. Practical parameterization of rotations using the exponential map. Journal of Graphics Tools, 3(3):29-48, 1998], and corresponding interpolation and interaction systems.
A set of DAE utilities for reading and writing a subset of COLLADA 1.5. Uses JAXB.

The best way to learn about using these utilities is to read the javadoc and the source.

Download, Dependencies, and Installation

Vona's Java Utils is released in under the GNU GPL. The distribution jar comes with everything rolled into one: java source, scheme source, html (m4) source, the makefiles and related stuff, plus precompiled versions of everything (java class files, html, and javadoc). Further, it includes the pure java dependencies of the library, which are

the Java Concurrency in Practice Annotations (jcip-annotations.jar)
netlib-java (netlib-java.jar and arpack_combined_all.jar, which may be provided in a netlib-java download as arpack-combo-VER.jar; see below for adding netlib-java native acceleration)
the pure-java parts of Java3D (j3dcore.jar, j3dutils.jar, vecmath.jar), and optionally also the Java3D VRML97 (j3d-vrml97.jar) and Microcrowd 3DS (loader3DS1_2.jar) loaders.

A lighter-weight jar is also available which excludes third-party dependencies.

Native Dependencies

Vona's Java Utils requires a Java 1.6+ JRE and, for JOGLDisplay, JOGL 2.0+. It has been tested under recent Sun JREs on GNU/Linux, Windows XP, and Mac OS 10.6.

JOGL is required for building and for runtime use of JOGLDisplay but, as this includes native code (i.e. it is not "pure java"), it is not included in any of the provided jars. You will need to download and install it separately if you want to rebuild the code or if you want to use JOGLDisplay. I typically set it up as an installed extension, though this may not be officially recommended.

netlib-java JNI Acceleration

The SVD driver can use netlib-java for computation of the SVD (this is the default). While netlib-java will itself default to a pure-java implementation, it is much faster to use its optional JNI-accelerated call to an optimized native SVD implementation.

You do not need to take any special action to run without netlib-java JNI acceleration, since the distribution jar includes a copy of netlib-java.

To use netlib-java JNI acceleration, you'll need to download netlib-java separately, build the native libraries on your system (we provide some precompiled binaries below), and symlink the native libs so your JRE can find them.

Here are the steps on a modern Debian-based GNU/Linux system like Ubuntu (the resulting GNU/Linux x86_64 and x86 *.so binaries are available here for convenience; unpack in /usr/local/lib and skip directly to the last step if you want to try them directly):

sudo apt-get install liblapack-dev libatlas-base-dev gfortran
download netlib-java and unpack into e.g. /usr/local/lib/netlib-java-version
cd /usr/local/lib/netlib-java-version/jni
set the environment variable JAVA_HOME to the base dir of your JDK and ensure $JAVA_HOME/bin (the directory containing the javac executable) is on your PATH

at this point I found a bug in the netlib-java configure script, I had to change the line

echo "JLAPACK_JNI_CP=../netlib-java-0.9.0.jar" >> Makefile.incl

echo "JLAPACK_JNI_CP=../netlib-java-0.9.1.jar" >> Makefile.incl

chmod a+x configure; ./configure
make
cd $JAVA_HOME/jre/lib/arch/; sudo ln -s /usr/local/lib/netlib-java-version/jni/*.so (Notes: substitute your machine architecture, such as i386, for arch; depending on where you've installed your JDK, you may not need or want the sudo; if you've downloaded the precompiled binaries then you can install directly into a JRE at $JAVA_HOME/lib/arch.)

On Macintosh OS X 10.6.2 (x86_64) I had success with these steps (the resulting OS X x86_64 *.jnilib binaries are available here for convenience; unpack in /usr/local/lib and skip directly to the last step if you want to try them directly):

sudo port install gcc45 +gfortran (get some coffee...)

make the following changes to the netlib-java jni configure script:

ARCH=x86_64

CPPFLAGS="$CPPFLAGS -I/Developer/SDKs/MacOSX10.6.sdk/System/Library/Frameworks/JavaVM.framework/Versions/1.6.0/Headers"

FC="/opt/local/bin/gfortran-mp-4.5"

FORTRAN_LIBS="-L/opt/local/lib/gcc45 -lgfortran -Wl,-single_module"

chmod a+x configure; ./configure
make
cd /System/Library/Java/Extensions; sudo ln -s /usr/local/lib/netlib-java-version/jni/*.jnilib .

(Re-)Building the Code

The Vona's Java Utils build has been tested on GNU/Linux. Other platforms may work. You should only need to (re)build the code if you have made a change; it is distributed with pre-built binaries.

The build system is based on the Super-Ninja Makefile. You'll need to have already installed

a 1.6+ JDK with the binaries on your path
(GNU) make and m4
the JOGL library.

You'll probably want to create a directory into which to unpack the jar (jar xvf Vona-newest.jar). The code for Vona's Java Utils proper will be under the unpacked directory vona/; sibling directories contain the bundled pure-Java dependencies. The build system will find these. Alternately, you can unpack Vona-lite-newest.jar, and in that case, the build system will look for jarfiles for the pure java deps in the location specified by its EXT_DIR variable, which you can inspect via make show-settings (and/or see the makefile for how it is derived).

From within the vona/ directory,

make show-settings dumps the build system's config vars
make makefiles generates makefiles in any subpackages
make project-clean removes most precompiled stuff
make project-realclean removes all precompiled stuff
make project (re)builds the binary files for the project
make (re)builds the binary files in the current directory
make project-javadoc (re)builds the project documentation
make jar (re)builds the jar
make jar-lite (re)builds the lite jar

Disclaimer

THIS INFORMATION AND/OR SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS INFORMATION AND/OR SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.