ReadMe for Tektosyne 6.2.0

ProgramTektosyne Library for Java
Version6.2.0 (History)
Released25 March 2018
AuthorChristoph Nahr (Copyright)
Contactwebmaster@kynosarges.org
Websitekynosarges.org/Tektosyne.html

Table of Contents

  1. System Requirements
  2. Package Contents
  3. Demo Application
  4. Source Package
  5. Changes from .NET Version
  6. Known Issues
  7. Copyright Notice

1. System Requirements

Tektosyne is a Java library that should work on any system with a current Java Runtime Environment (JRE) that supports the Java SE 8 Compact 1 profile, or the module java.base on Java SE 9 and later. The included JavaFX demo application and the IntelliJ project in the source package require Oracle Java SE 9.0.4 which can be obtained from the Oracle Technology Network.

Some hyperlink actions in the demo application rely on Java’s multiplatform support for invoking default applications, such as web browsers and mail clients. These should work on all desktop platforms, assuming your applications are properly configured to handle the desired URLs or file types. If some action is entirely unsupported on your platform, the hyperlink’s tool tip will state that fact.

Microsoft Windows — When targeting Java SE 8, please see Oracle Java on Windows for information on how to avoid Oracle’s inferior default Windows JRE. This is generally necessary to obtain the best possible performance with computationally intensive code. No special action is required for Java SE 9 and later whose distribution has dropped this inferior JRE.

2. Package Contents

The directory to which the binary package was unpacked contains the following files:

ReadMe.htmlThis file
WhatsNew.htmlTektosyne version history
project.cssStyle sheet for ReadMe & WhatsNew
Diagrams.xmlProject file for overview diagrams
Tektosyne.jarTektosyne library (requires Java SE 8)
Tektosyne.Demo.jarTektosyne demo application (requires Java SE 9)
javadoc/*Javadoc class reference for the library

These files are all you need to use the library or run the demo application. To inspect the original Java code, you may also wish to download the source package which is available separately.

Available as another download, the Tektosyne User’s Guide (PDF) presents an overview of all public library classes and a set of sample benchmark results. Unusual features such as graph algorithms are covered in greater depth. The project file Diagrams.xml was used to create the UML Diagrams for this guide.

3. Demo Application

Use the command line javaw -jar Tektosyne.Demo.jar to run the JavaFX demo application. Depending on your JVM, you may also be able to omit javaw -jar and directly execute Tektosyne.Demo.jar directly, or to simply double-click on Tektosyne.Demo.jar in your favorite file explorer.

Saving & Printing Grids

Tektosyne.Demo contains a useful feature that helps with the creation of game maps based on real-world terrain. Choose Polygon & Graph: Save & Print Grid to show a dialog that allows you to save or print grids of arbitrary size that are composed of squares or hexagons of any side length and orientation.

You can print a grid on transparent film and overlay it on an atlas page to determine your map layout, or you can save a grid to a PNG file and use your favorite paint program to superimpose it on an image file with your real-world map. I used this feature in Tektosyne for .NET to create some demo scenarios for Hexkit.

Notes on Save & Print Grids

PNG output features black grid lines on a transparent background, so you’ll see nothing if you open it in an image viewer with a black display background!

When running with assertions enabled (-ea), printing may cause a flood of assertion failures (“*** unexpected PG access”). This is a known bug in the JavaFX printing system that will hopefully get fixed eventually. Print output and application stability are not affected by these assertion failures.

4. Source Package

The source package is available as a separate download on the Tektosyne home page. The expected environment is IntelliJ IDEA 2017.3.5 with Oracle JDK 9.0.4. This package contains all of the files in the binary package, except for the precompiled Java archives, plus the following:

Tektosyne.imlIntelliJ project file
.idea/*IntelliJ project metadata
src/*Source code and JAR manifest
test/*Unit tests for JUnit 4
Tektosyne.Demo/*Source code for the demo application

Most files and directories contain files for the library itself, except for Tektosyne.Demo which contains all files for the JavaFX demo application. The binary package was created by building the artifact Tektosyne.Demo.jar which includes all other output files (except for the Javadoc tree).

The source package does not include standard build files (e.g. Ant) but you can simply download the free IntelliJ Community Edition and generate such files from the project.

UML Diagrams

Open the included project file Diagrams.xml with my free Class Diagrammer application to view or change the UML diagrams that appear in the Tektosyne User’s Guide. Note that these diagrams were created with locally installed Adobe Myriad Pro fonts, so you may have to adjust the diagram layouts for wider fonts.

5. Changes from .NET Version

Tektosyne is a partial Java port of my older .NET library. For those who have used the older version, here is a list of significant changes in functionality.

Removed Classes

Tektosyne for Java only contains functionality from the .NET library Tektosyne.Core. The second library in the .NET edition, Tektosyne.Windows, was entirely specific to Windows and WPF.

From Tektosyne.Core, the geometric and graph algorithms with related collections have been ported, along with some fundamental mathematical algorithms. All .NET-specific classes (e.g. Tektosyne.IO), general-purpose classes with existing Java ports (e.g. MersenneTwister), and various helper classes of dubious usefulness have been removed.

Changed Classes

As Java lacks a global flag or keyword for checked arithmetic, many methods were changed to either widen calculations from int to long or throw an ArithmeticException if the target type of a conversion overflows. This has been noted in the corresponding Javadoc entries.

The .NET version used to silently ignore negative comparison epsilons, which however could lead to nonsensical results in certain algorithms. The Java version throws an IllegalArgumentException whenever a negative epsilon is specified, except for methods that always raise epsilon to a fixed minimum value (see Javadoc).

Fortran:

MathUtility:

Collections:

Geometry:

Graph:

Subdivision:

6. Known Issues

Currently none, except as noted for the demo application.

All files – individual files, multi-file packages, and individual files contained in multi-file packages – that constitute the original distribution of Tektosyne are Copyright © 2002–2018 by Christoph Nahr, except where otherwise noted.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.