Introduction

In its current release, the Tinfour Project is attempting to broaden its focus and make its software more accessible to our users. Originally, the project was intended to provide a software library that could used by developers and computer programmers to incorporate into their own applications. While that remains our primary goal, the Tinfour Project is also working to create small-scale applications that do not require programming skills to operate. These applications can be run by users to perform their own data viewing and analysis tasks.

Of course, that effort is just getting started. Currently, Tinfour includes two applications of general interest – the Tinfour Viewer, and the Simple Volumetric Model (SVM) – as well as a number of more specialized demo and test applications. Right now, though, those applications need to be run from a command-line interface using either a command or terminal window (alternate ways of invoking some applications are discussed below).

This wiki page describes how to run the various Tinfour applications from the command line or from a script or .bat file. If you are using an Integrated Development Environment (IDE) such as Eclipse or Netbeans, they will take care of a number of the details for you. But if you need to invoke any of the Tinfour applications directly, these notes should help.

Note: The text below describes the use of a command-window. Users working under Windows may find it convenient to setup a shortcut to make this process a little easier. Instructions for doing so are given in the wiki page Tinfour Execution Shortcut for Windows

A Brief Introduction to Command Windows

All the major operating systems provide some kind of terminal or command window interface. Under Windows 7, the "Command Prompt" could be found in the Start menu under the "Accessories" folder. Under Windows 10, there are a lot of different ways to open a command window, but the easiest is probably by using the "Search" function. First, move your mouse pointer over the "Windows" icon at the lower-left corner of your desktop display and press a RIGHT click. This action will raise a context menu that includes an option to "Search". Click on the search menu item and then enter CMD in the search window. Then press the result for "Command Window".

Under Linux, command prompts are basically the way things work, so no further explanation is needed here (lacking access to a Mac OS platform, I cannot comment on that operating system here, but would welcome information form experienced users).

In the command window, programs are invoked by typing their name (or path) in the command line and pressing the Enter key. For example, the Java runtime executable (see below) is invoked by typing the name java at the command line. However, the command window can invoke a program only if it knows where to find it. Both Windows and Linux use a concept called the "PATH environment variable". The PATH variable provides a list of places where the command line interface should look for programs. Under windows, you can see the specifications in your PATH variable by typing the command SET PATH. Despite its name, this command will not change the settings in the PATH variable, but will print them out to the command window. Under many Linux shells, you can inspect your PATH environment variable by typing the command printenv.

As discussed below, Tinfour applications are all written in Java and must be run using the Java runtime executable. When you attempt to run the Java runtime by typing the simple command java, the command window will find it only if the PATH variable includes a specification for the location of the version of Java installed on your system. This is true for all programs. Depending which installer was used to put Java on your system, the installer may have modified the PATH as part of its procedures. If not, you can modify the PATH, or you can run Java by typing the full path. To do so under Windows, you might enter a command such as follows (adjusting for the version of Java installed on your system):

"C:\Program Files\Java\jdk1.8.0_91\bin\java" -version

There are a number of ways to modify the PATH variable. Some change it as a permanent system setting. Others change it only within a session. I recommend using Google to find the method that is best suited to your needs.

Redirecting Text Output to a File

Although command-line interfaces are rather old-fashioned, there are a lot of special techniques they allow you to do. One of the most useful is the ability to redirect the text output from a program to be stored in a data file. Under both Windows and Linux, this action is accomplished using the > symbol. For example,

"C:\Program Files\Java\jdk1.8.0_91\bin\java" -version > MyFile.txt

will redirect the output from the version command introduced above to a standard text file. Many of the Tinfour demonstration applications write their output to the command window's "standard output". Using the redirection operator allows you to capture that output for future review.

A Brief Introduction to Java

Java-based applications are not true programs. A Java application is a set of instructions that are interpreted by a program called the Java Virtual Machine (JVM). To run a Java application, the Java executable must be installed on your system. So, before you can run any of the Tinfour demonstration applications, you must first have Java installed on your system.

The good news is that downloading and installing a Java virtual machine is fairly straightforward. Furthermore, Java applications are so common that there is a fair chance that the Java executable is already installed on your computer.

There are plenty of resources on the web describing how to download and install Java. And since many of which do a better job explaining the issues than I ever could, I will not go into too much detail here. You may find Java installation packages at the Oracle web site and other locations. For Windows systems, there is a good discussion of how to set up a command window and configure environment variables at How to Run a Java Program from the Command Line

There are two types of Java installations: the Java Development Kit (JDK) and the Java Runtime Environment (JRE) . The JDK is for people who want to write and build Java applications. The JRE is just for people who want to run the Java applications that other people write. You can install either the JDK or JRE. The JDK is, of course, larger than the JRE, but not so large that it should be a problem on a modern file system.

Jar Files

Java application code is stored in files called "Jar" files (short for Java Archive). In Java development, it is traditional to separate different modules from an application into separate Jar files. This approach is a good way to manage the complexity of an full-sized application, but is not always convenient for the Java neophyte (or, for that matter, experienced Java developers). So, in the Tinfour software distribution, some of the Jars are separated into separate modules and some of them are bundled into large Jars with "all dependencies included". You can recognize the fat jars because they all have the phrase "jar-with-dependencies" in their names.

The Tinfour Viewer Jar

The TinfourViewer demonstration application is the one that was used to produce a lot of the pictures of geophysical data on the Tinfour site. Depending on which version of Java you install, you may be able to launch the viewer from your file system browser (Windows File Explorer, etc.) by simply double-clicking on the jar file TinfourDemo-2.1.1-jar-with-dependencies.jar (substituting the version number for the later release, as necessary, details below). The other demo's need to be launched from a command prompt.

Tinfour Organization

The Tinfour source-code project is organized into modules: demo, analysis, gis, and core. Each of these modules is associated with a unique Java jar file. The demo module includes a number of Java "main" classes which can be run from an IDE or from the command line. Most of these applications are simple demonstrations or test utilities, but the Tinfour Viewer (class: TinfourViewerMain) provides a user interface that allows users to explore and view data. In fact, the pictures on the main Tinfour project page were produced using the Tinfour Viewer. The notes below provide information about running the viewer from the command line.

For more information about the organization and content of the Tinfour modules and Jar files, see the Tinfour Wiki page at Tinfour Builds and Dependencies

Obtaining the Compiled Jar files

Starting with Release 2.0, the Tinfour software project moved to a Maven build environment. Having access to Maven simplifies a number of software build issues, but having access to Maven is not required for running the Tinfour Viewer. Some of the alternative approaches will be discussed below.

The one prerequisite to running the Tinfour Viewer is to obtain the six Java Jar files required by the application. Four of these Jar files originate with the Tinfour project and two others are taken from other open-source software projects. All of them can be downloaded from public Internet services including Sonatype's Maven Central Repository, and the Maven Central website. You may download these files "by hand" using your web browser, or, if you prefer, you can build the Tinfour Jar files using Maven. The Maven build process automatically downloads the external resources required by an application.

An Alternate: Running Tinfour Demonstration Applications with the Tinfour "Fat Jar"

Starting with Tinfour Release 2.1 (June, 2019), the release also includes a pre-built "fat jar" which bundles all the dependencies into a single jar file. This approach is convenient if you just want to run one of the Tinfour demo applications and do not want to take the trouble of dealing with builds, dependencies, and libraries. Naturally, when downloading Tinfour code or binaries, you should take the most recent version.

The Tinfour "fat jar" is available at the Maven Central Repository as a file called TinfourDemo-2.1.1-jar-with-dependencies.jar (you may substitute the latest version as appropriate). It still requires that you have Java installed on your system before you run it, but depending on which version of Java you've installed, you may be able to run the main TinfourViewer demonstration by simply double-clicking on the file from your file system explorer. Alternately, you can run it from the command-line using the following command (if your system is unable to find the java executable, please see the information about PATH variables below):

java -jar TinfourDemo-2.1.1-jar-with-dependencies.jar

General Options for Downloading and Running Tinfour

Option 1: Downloading Jar Files from the Maven Central Repository

To download the Tinfour and supporting Jar files, browse to the web site Sonatype . Sonatype provides a search option that lets you find and download the latest versions of Tinfour. Download the following Jar files and store them on a single folder:

1. TinfourAnalysis (TinfourAnalysis-2.1.1.jar, or later)
2. TinfourCore (TinfourCore-2.1.1.jar, or later)
3. TinfourGis (TinfourGis-2.1.1.jar, or later)
4. TinfourDemo (TinfourDemo-2.1.1.jar or later).
5. laszip (laszip4j-0.5.jar)
6. Apache Commons Math3 (commons-math3-3.6.1.jar)

Note that the versions of each Jar are subject to change. You may even prefer to use more recent versions of Tinfour, if they are available. But you should be able to obtain the above listed Jar files for the forseeable future.

Option 2: Building under Maven

If you are set up to use Maven and have downloaded the Tinfour software release, you can build the Tinfour Jar files and automatically download the external resources using a standard "mvn install" operation. The results will be stored in your local Maven repository. For your preliminary investigation, you may find it more convenient to copy these all to a single folder. To locate the Jar files, start by looking in the main repository, which is usually located in the main user folder or directory under the name .m2/repository Beneath that, you should be able to locate the following (again, the version numbers are subject to change).

1. org\tinfour\TinfourAnalysis\2.1.1\TinfourAnalysis-2.1.1.jar
2. org\tinfour\TinfourCore\2.1.1\TinfourCore-2.1.1.jar
3. org\tinfour\TinfourGis\2.1.1\TinfourGis-2.1.1.jar
4. org\tinfour\TinfourDemo\2.1.1\TinfourDemo-2.1.1.jar
5. org\apache\commons\commons-math3\3.6.1\commons-math3-3.6.1.jar
6. com\github\mreutegg\laszip4j\0.5\laszip4j-0.5.jar

Optionally, you can also download the "fat jars"

7. org\tinfour\TinfourDemo\2.1.1\TinfourDemo-2.1.1-jar-with-dependencies.jar
8. org\tinfour\TinfourSvm\2.1.1\TinfourSvm-2.1.1-jar-with-dependencies.jar

Running the Tinfour Viewer

To run the Tinfour Viewer application, you will need to have the Java Runtime Environment (JRE) or Java Devlopment Kit (JDK) installed on your computer. Ideally, you would also have the path to the Java "java" executable established in your system PATH environment variable. If you do, you should be able to run the Tinfour Viewer application by opening up a command window and typing

     java -Xmx2000m -jar TinfourDemo-2.1.1.jar

If you do not have the the java executable in your PATH environment variable, you may be able to locate the executable and type in the full path. For example, under Windows, you may be able to enter the following command (with the appropriate adjustment for Java version number)

     "C:\Program Files\Java\jdk1.8.0_201\bin\java" -Xmx2000m -jar TinfourDemo-2.1.1.jar

The treatment of PATH under Linux is similar (though the exact location of Java will be different).

The -jar option versus the -classpath option

When the java executable runs, it uses a concept known as the "classpath" to find the Jar files that contain the compiled class files needed by the application. The classpath is often specified using the command-line option -classpath. The example above used a slightly different approach. When the TinfourDemo jar is packaged, the Tinfour build specification (the "pom.xml" file) for that module includes instructions telling the Java executable how to run the TinfourViewer. If you were to inspect the content of the TinfourDemo-2.1.1.jar file, you would find a MANIFEST.MF file which includes text specifying the main class for the Viewer (org.tinfour.demo.viewer.TinfourViewerMain) and a classpath setting specifying the names of the five other Jar files that were indicated in the discussion above. The -jar command line option tells the java executable to use the specifications in the MANIFEST.MF file.

You could also run the application from the command line using the classpath option. With the classpath option, you specify the entire list of Jars needed to run the application (including the main TinfourDemo jar). You would also have to specify the full name of the TinfourViewerMain class. Under Windows, the command would look something like the following

    java -Xmx2000m -classpath TinfourDemo-2.1.1.jar;TinfourGis-2.1.1.jar;TinfourAnalysis-2.1.1.jar;TinfourCore-2.1.1.jar;laszip4j-0.5.jar;commons-math3-3.6.1.jar org.tinfour.demo.viewer.TinfourViewerMain

Basically, the classpath features a list of the Jar files all concatenated together with semicolons. Under Linux, the command would be similar, except that it would use colons instead of semicolons.

The command above is basically unreadable. Because all the jar files for this discussion are in the same folder, you can take advantage of Java's wildcard option. Under Windows, the command would be

    java -Xmx2000m -classpath * org.tinfour.demo.viewer.TinfourViewerMain

Note that the example above uses a simple * for the wildcard, and not *.jar. That unusual specification often confuses developers. It is not the intuitive choice, but it is the design choice the authors of Java made. So it is the way you have to invoke java with a wildcard.

Note that under Linux, the command is slightly different. If you were to invoke java using the wildcard as shown above, the shell would expand the * specification into a list of files from the current folder and the classpath would not work. For Linux, you need to enclose the wildcard in quotes.

    java -Xmx2000m -classpath "*" org.tinfour.demo.viewer.TinfourViewerMain

The discussion above had you put all the Jar files into a single folder or directory. That configuration was used for its simplicity, but is not mandatory. In fact, the classpath can point to anywhere on your computer's file system and the various Jar files used by an application do not even have to be in the same directory.

Invoking other applications from the demo module

The Tinfour Demo module contains a number of other Java "main" classes that perform various tests and demonstrations. If you would like to invoke them from the command line, you may do so by substituting the appropriate target. For example, I often run the performance tests outside of my IDE so that I can ensure that I am measuring the system run times without overhead or other noise-factors that might be introduced by the IDE. Suppose I wished to run the RepeatedBuildTest (which measures the time required to construct a Delaunay Triangulation) using an input file named "sample.csv". I could do so with the following command:

 java -Xmx2000m -classpath * org.tinfour.demo.performance.RepeatedBuildTest -in sample.csv

This command vector tells java that it is to use RepeatedBuildTest as its main class. The command-line arguments -in and sample.csv are passed into the Java main as elements of the "String []args" array.

A description of many of the example, performance, and test applications in the Demo module is given in the document Tinfour Algorithms and Data Elements.

The -Xmx2000m option

Depending on how large your input files are, it may become necessary to increase the amount of memory that the Java runtime allocates. This parameter is controlled by the -Xmx option on the command line. The example command above used the setting -Xmx2000M to increase the memory to 2000 megabytes. The default value for how much memory Java allocates depends on the particular version of the Java runtime that you are operating. In older versions, the setting was quite small. In more recent versions, it may be large enough that you can omit the -Xmx option.