Skip to content

Tinfour Builds and Dependencies

gwlucastrig edited this page Jun 16, 2019 · 3 revisions

Introduction

One of the goals of the Tinfour software project is to keep its structure and organization as simple as possible. Its design strives to avoids complicated software build processes and external dependencies. By doing so, we hope to ensure that both the source code and compiled API will remain accessible to developers and researchers who wish to use it in their own implementations.

The overall code base is organized into four separate modules: core, gis, analysis, and demo. Although Tinfour may seem a rather small software project to be divided into so many separate modules, this approach has an advantage. It allows developers to select only the modules that they need for their own applications. Each module includes a distinct set of functions that are separated by general purpose and external dependencies. And each module is associated with its own compiled Jar file. If you wish, you can obtain these Jar files directly from Sonatype's Maven Central Repository website, or the Maven Central Repository, ot or you can build them yourself.

The table below gives a description of the Tinfour modules, and their dependencies. If you are building your own software, this information will help you integrate the modules with your project. Starting with Tinfour Release 2.1 (June, 2019), the release also includes a "fat jar" which bundles all the dependencies into a single jar file. If you would just like to run the Tinfour Viewer demonstration program you may do so by accessing the Java jar file TinfourDemo-2.1-jar-with-dependencies.jar (you may substitute the latest version as appropriate).

Module Description Dependencies
core Core classes and interfaces for Tinfour project. None
gis Utilities for reading data from Geographic Information System products including Shapefiles and Lidar. TinfourCore
laszip4j*
analysis Utilities for performing geospatial and statistical analysis over Tinfour structures (such as the Delaunay Triangulation). TinfourCore
Apache Commons Math 3*
demo Demostration utilities including the TinfourViewer user application, performance tests, and example code. TinfourCore
TinfourGis
TinfourAnalysis
laszip4j*
Apache Commons Math 3*
*Apache Commons Math 3 and laszip4j are external projects.
Their compiled Jar files may be obtained via the Maven Central Repository.

As indicated above, the Tinfour package has two external dependencies. The first dependency is the laszip4j package. Laszip4j allows the test and demonstration applications to read Lidar products in the highly specialized LAZ data compression format ("LAS" is the standard format for terrestrial Lidar data, the "Zip" is a call out to traditional compression methods). This dependency is not part of the core functions, but is necessary for access to these data products.

The second dependency is the Apache Commons Math Library. This dependency is required by the linear algebra and statistics functions needed by the Geographically Weighted Regression classes which are part of the non-core functionality. If you have an alternate linear algebra library in your own software, it would be possible to refactor the Tinfour code to perform the core regression functions using the alternative. You would, however, have to remove those functions that specifically require statistics elements (such as the T-Distribution) or provide your own alternative

Tinfour and the Maven Build Process

Starting with Release 2.0, Tinfour uses the Maven build process. Maven has many useful features, but if you don't have Maven installed on your own system (or if you simply prefer not to use Maven), you can still build the Tinfour code without it. Some hints on doing so are given below.

One of the nice things that Maven does do is to automatically download the Jar files or other external resources that are specified in its build configuration. Again, if you don't use Maven, it's easy enough to download these elements by hand. But, for those of you who do use Maven, you may automatically download the Tinfour Jar files by including the following lines in your own pom.xml files. Please feel free to remove any dependencies that you do not need by following the guidelines in the table above. And please check for the latest versions, since the Tinfour code may change more quickly than this wiki page is updated.

<dependencies>
	<dependency>
		<groupId>org.tinfour</groupId>
		<artifactId>TinfourCore</artifactId>
		<version>2.0</version>
	</dependency>                
	<dependency>
		<groupId>org.tinfour</groupId>
		<artifactId>TinfourGis</artifactId>
		<version>2.0</version>
	</dependency>			  
	<dependency>
		<groupId>org.tinfour</groupId>
		<artifactId>TinfourAnalysis</artifactId>
		<version>2.0</version>
	</dependency>
	<dependency>
		<groupId>org.tinfour</groupId>
		<artifactId>TinfourDemo</artifactId>
		<version>2.0</version>
	</dependency>

	<!-- laszip4j is required by TinfourGIS -------------------->
	<dependency>
		<groupId>com.github.mreutegg</groupId>
		<artifactId>laszip4j</artifactId>
		<version>0.5</version>
	</dependency>
	<!-- Apache Commons Math 3 is required by TinfourAnalysis -->
	<dependency>
		<groupId>org.apache.commons</groupId>
		<artifactId>commons-math3</artifactId>
		<version>3.6.1</version>
	</dependency>
</dependencies>

Hints on Building Tinfour without Maven

If you want to build your project without using Maven, simply copy out the code from the Tinfour tree. The four module directories -- core, gis, analysis, and demo -- are located in the main project directory. Under each, you'll find sub-directories named src/main/java. The code for that module is located in each of the "java" directories.

If you elect to work outside of Maven, the TinfourViewer has a special consideration in that it uses resources files to provide icons, palettes, and help-text. Maven keeps resources of this type in a parallel directory structure from the source code. The TinfourViewer will expect to find them bundled with the object code in a sub-directory called "resources". But without Maven to put them there, the TinfourViewer will not be able to find them. If you are working with an alternate build tool, such as ant or gradle, you can configure them to bundle the resources properly. Alternately, if you are one of those hardy souls who builds your Java code by from the command line (or using scripts), you can simply move the content of the resources directory in the path

demo/src/main/resources/org/tinfour/demo/viewer/resources

Into a sub-directory of the source code

demo/src/main/java/org/tinfour/demo/viewer/resources

Tinfour, Maven, and Integrated Development Environments (IDEs)

The major Java IDEs (Netbeans, Eclipse, and IntelliJ) all support direct access to Maven projects. If you have one of these IDE's you can simply load the Tinfour project and run with it. All work fine.

Netbeans does have some quirks. While its handling of Maven is absolutely correct from a technical point-of-view, a Maven project in Netbeans doesn't quite allow you to do all the nice things you can do with an ordinary Netbeans project. For example, one of my favorite things to do with Netbeans is configure one Netbeans project to depend on another. Consider the following scenario. I am developing a module that depends on Tinfour. I want to keep the Tinfour source code accessible for debugging purposes. I might even discover that I need to make modifications to it... But I don't want my new work to be stored under the Tinfour project umbrella. If I were working with non-Maven projects, I'd just have the new project depend on the old. But at least in version 8.2, Netbeans will steadfastly decline to do so.

Fortunately, it's easy to trick Netbeans into treating a Maven project as ordinary code. Simply remove or rename the pom.xml files from the code hierarchy. The pom.xml file is the key configuration file used by Maven and, if it isn't in the code tree, Netbeans doesn't consider the code to be a Maven project. Note, though, that Tinfour includes five pom.xml files. So you'll have to take care of them all. You'll also have to configure the project properties to find the both the sources folders (the one's named src/main/java) and the resources folder that was described above.

You can’t perform that action at this time.