ReadMe for Tektosyne 6.0.1

ProgramTektosyne Library for Java
Version6.0.1 (History)
Released08 April 2017
AuthorChristoph Nahr (Copyright)
Contactwebmaster@kynosarges.org
Websitekynosarges.org/Tektosyne.html

Table of Contents

  1. System Requirements
  2. Package Contents
  3. Demo Application
  4. Building Tektosyne
  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. The included JavaFX demo application requires Oracle Java SE 8 Update 66 with JavaFX 8 or later. Older JREs that only support Swing will not work.

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 — 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.

2. Package Contents

The directory to which the code package was unpacked contains two subdirectories, Tektosyne for the library itself and Tektosyne.Demo for the JavaFX demo application. Tektosyne contains the following files:

ReadMe.htmlThis file
WhatsNew.htmlTektosyne version history
project.cssStyle sheet for ReadMe & WhatsNew
build.xmlCustomized build steps
Diagrams.xmlProject file for Class Diagrammer
dist/Tektosyne.jarTektosyne library
dist/javadoc/*Javadoc class reference
nbproject/*NetBeans project configuration
src/*Complete source code
test/*Unit tests for JUnit 4

Available as a separate 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

Tektosyne.Demo is organized similarly and contains the JavaFX demo application under dist/Tektosyne.Demo.jar. 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.

The folder Tektosyne.Demo/dist contains identical copies of the ReadMe and WhatsNew files, so as to make them accessible from the About dialog.

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.

Note: 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!

Known JavaFX Issues

There are currently two known JavaFX issues that might affect your system. First, its hardware accelerated graphics may cause some display drivers to crash; and second, its automatic DPI scaling is disabled by default on Windows at 120 DPI (125%) which might cause layout errors. Should you experience these issues you can avoid them using Java startup switches, as described here.

4. Building Tektosyne

The expected environment is NetBeans 8.2 with Oracle JDK 8u121. NetBeans injects custom dependencies into its Ant build scripts, so you’ll need an actual NetBeans installation to rebuild the project.

The NetBeans project for the demo application always disables JavaFX hardware acceleration (see Known JavaFX Issues). Remove the corresponding switch from “Project Properties: Run” if you wish to use hardware acceleration.

UML Diagrams

Simply 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

JavaFX Demo Application

Resizable windows do not have sensible minimum sizes because JavaFX does not currently scale minimum (or maximum) sizes with screen DPI. This bug will hopefully get fixed in a future Java release.

If you manually edit the value of an input field, you must press Enter to ensure the new value is committed. Simply leaving the input field with Tab will show the new value to the user, but retain the old value internally. This is a JavaFX bug regarding input controls losing focus.

Save & Print Grid — 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 may or may not get fixed in Java SE 9. Print output and application stability are not affected by these assertion failures.

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–2017 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.