GeomSS Files

GeomSS README
Version 0.0.8 - 4/4/2011
Joseph A. Huwaldt, jhuwaldt@users.sourceforge.net


GeomSS (Geometry Scripting System) is a geometry modeling and scripting system written in Java. It uses the BeanShell scripting language to allow the user to write scripts which can create and analyze complex geometries that include NURBS curves and surfaces. This is especially important for geometry modeling tasks that must be repeated over and over with small or parametric variations.

GeomSS is not an interactive CAD program. You can't "draw" things using the mouse, etc. Rather, it is a geometry programming language. It is designed with aerospace applications in mind, but can find uses in many other applications. To use this program well, you need a programming mind-set. There is very little interactivity with the GUI. Most of your interactions with GeomSS are through the scripting interface.

GeomSS is currently in a prototype stage. Many interfaces and features are likely to change significantly until the program has matured. I have been working on this off-and-on (mostly off) for many years, but it has never been used in a "production" environment and I know of MANY critical features that are missing and I know of a few critical bugs. But, hopefully, it will evolve and maybe even improve over time.


Some of the primary features of GeomSS:
* Generally, n-dimensional geometry is supported throughout the program (not just 3D!).  However, geometry can only be displayed up to 3D.  You will have to roll your own projections for higher dimensionality.
* Point objects: points, strings of points (lists of points), array of points (lists of strings of points), lists of arrays of points, etc.
* NURBS curves including interpolating curves through a list of points, creating elliptical arcs, creating circular arcs, extracting curve properties such as tangency, principle normals, bi-normals, torsion, finding closest points on a curve and gridding points onto a curve using various point distributions.
* NURBS surfaces including interpolating surfaces through an array of points, creating a lofted surface from a list of defining section curves, surfaces of revolution, spheres and toruses.  You can extract surface properties such as surface normals, tangent planes, closest points on the surface, mean curvature, Gaussian curvature, twist vector, surface area, enclosed volume, and you can extract a grid of points on a surface.
* Flexible and geometry-aware lists of geometry elements.
* Reading and writing of geometry to a range of file formats including: IGES, APAS CARD file, GGP file, LaWG geometry file, POI points file, and VECC Mk5 input file.  Other readers can be easily added.
* All geometry elements and most calculations are fully unit aware.  For example, you can specify a point in meters, and another in feet and subtract one from the other and get a vector that has length in meters.  All unit calculations are handled automatically behind the scenes.
* Flexible support is provided for geometry transformations (scaling, translating, rotating, and affine transformations) including transformation chaining that maintains the full history of transformations (which can then be edited changing everything "downstream" automatically).
* Support for subrange points and curves on NURBS curves and surfaces.  This means, for example, that you can define a point on a surface by it's parametric (s,t) parameters and that point will remain attached to that surface.  Or, you can define a curve in parametric (s,t) space and use it to define a curve on a NURBS surface that will always be on that mathematical surface.
* Fully interactive GUI or batch mode non-interactive processing.
* Java3D based scene rendering.  However, the geometry library is ''not'' dependent on Java3D and can be made to work with any rendering engine or none at all (such as when in non-interactive batch mode).
* Intuitive mouse gestures for interacting with the 3D view.
* [http://www.beanshell.org/ BeanShell] scripting environment.  This provides powerful scripting/programming capabilities with a Java-like syntax.  You can write pure Java in the command window, or you can write with the "short-hand" BeanShell conventions.  Unlike pure Java, types are dynamic and commands are interpreted as you type them.  However, in addition to the GeomSS libraries, you have the full power of the entire set of standard Java libraries at your finger tips.


The latest information and installation instructions can always be found on the GeomSS web site:  http://geomss.sourceforge.net


Installation Instructions:
The instructions that were current as of the publishing of this release can be found in the Installation_Instructions.pdf file (which is a print of the installation instructions page on the GeomSS wiki).  The latest version of these instructions can always be found on the project web site:  http://geomss.sourceforge.net

GeomSS requires Java version 1.5 (Java 5) or later and Java3D version 1.5 or later.  Everything else that it needs to run is bundled with the program.  These instructions assume you have Java 1.5 or later installed on your computer.  If you don't, please visit:  http://www.java.com/

If you encounter any problems with this installation process, leave a message in the Support Request Forum ( http://sourceforge.net/projects/geomss/support ) I will try to get back to you if I can.


Usage Notes:
You will find a tutorial and documentation on GeomSS on the project web site (http://geomss.sourceforge.net).  However, the following can serve as a hint on how to use GeomSS.


GeomSS is extremely flexible and almost infinitely extensible. Sadly, this makes it almost infinitely complex to understand all it's possible uses! For example, you can write pure Java in the GeomSS command window or you can write a shortened version of Java known as "BeanShell". BeanShell is a scripting language that uses the Java syntax but is abbreviated and has many features similar to Python such as dynamically defining types on the fly. For example:

Pure Java:
Parameter p = Parameter.valueOf(10, FOOT);
Parameter q = Parameter.valueOf(20, METER);
Parameter r = p.plus(q);
System.out.println("r = " + r);
r = 75.6167979002625 ft

BeanShell:
p = newParameter(10, FOOT);
q = newParameter(20, METER);
r = p.plus(q);
print("r = " + r);
r = 75.6167979002625 ft

Both pure Java and BeanShell can make use of the GeomSS API for geometry manipulation. But, besides the GeomSS API iteself, GeomSS also gives you access to the full set of standard Java libraries. So anything you can do with Java, you can do from GeomSS! Yikes. This includes accessing files and URLs, processing XML, creating complex GUI's, etc. Plus, it's relatively easy to make your own Java libraries available in GeomSS.

To use GeomSS to do anything useful, you have to make use of both the BeanShell commands and the pure Java API. That causes a major schism in the project that really shows up in the documentation.

For example:

// Create a 5 ft circle centered on the origin.
o = newPoint(0,0,0);
r = newParameter(5, FOOT);
c = newCircle(o, r);
draw(c);

// Find the point on a circle, near s=0.5 that creates a line through
// point "p" that is tangent to the circle.
p = newPoint(10,5,1,FOOT);
draw(p);
t = c.getTangentPoint(p, 0.5);
draw(t);
s = newPointString();
s.add(p);
s.add(t);
setLineColor(BLUE);
draw(s);

You needed the GeomSS BeanShell documentation to understand "newPoint", "newParameter", "newCircle", "newPointString", "setLineColor" and "draw". But, you needed the standard GeomSS Java Docs to understand "Curve.getTangentPoint". You also needed the standard Java API documentation to understand the Color constants that are defined.

Maybe some day it will all be in the BeanShell form. Maybe not. For now, you have to be familiar with both sets of documentation and that makes the learning curve for this program extremely steep.


Note that the GeomSS geometry library uses some design features (provided by JScience) that prevent the creation of garbage and that speed up run-times. However, the price paid for this is a non-standard object creation pattern. For example:

Instead of the typical Java object creation syntax of:
Point p = new Point(1,3.5,2,FOOT);

In GeomSS you use the following pure Java syntax:
Point p = Point.valueOf(1,3.5,2,FOOT);

Often, I have provided BeanShell short-cuts to simplify this type of object creation that look like this:
p = newPoint(1,3.5,2,FOOT);

Note that you still create objects from other packages, like the standard Java libraries, using the standard syntax:
List myList = new ArrayList();


Example Geometry Files:
There are a couple of sample point geometry files included in the "Sample Geometry" folder in the file distribution. To use these, you can open them by choosing "Open..." from the "File" menu. The sample geometry files are:

SWB.WGS:
This is a NASA Langley Geometry System file with a very simple wing/body geometry in it that was used to test some old aero codes.

shuttle.mk5:
This is a VECC (Viscous Effects on Complex Configurations) input file that has a model of a Space Shuttle Orbiter wind tunnel model in it.

apas_sample.card:
This is an APAS II (Airplane Preliminary Analysis System) CARD file containing some ancient aerospace related configurations (an old shuttle study configuration and an old Apollo capsule configuration).


Demo Scripts:
I have created a few demo scripts that illustrate how to use GeomSS and illustrate some of it's features. These scripts are in the "Sample Geometry" directory included in the file distribution. To use these, you need to change the "working directory" in GeomSS to the "Sample Geometry" directory. Do that by choosing "Change Working Directory…" from the "File" menu and navigating to the "Sample Geometry" folder. You can see what directory is the current working directory by typing pwd(); at the command line. You can also get a listing of the current working directory using dir();. To run a script from the GeomSS command line, you type in the following:
  source("scriptname.bsh");

Where "scriptname.bsh" is the name of the BeanShell script file you want to run. The "source" command will run the specified script as if you typed it in at the command line.

Here is a description of each sample script:

crvTest.bsh:
This is a script that tests out many of the NURBS curve related features in GeomSS. This script is not meant to be run all at once (using "source"), but rather it is meant for pieces of it be copied to the clipboard and pasted into the GeomSS command window a little at a time, starting at the top and moving down. The script starts by illustrating how you can create a NURBS curve from scratch (supplying your own control points and your own knot vectors). Then it shows all the different ways that you can create circular and elliptical arcs; illustrating functionality for nearest and furthest points, plane intersections, tangents and normals, and arc-length calculations along the way. Then it illustrates how to create a subrange curve on a curve (how to create a curve that is defined only between a range of parameters on a parent curve -- this is sometimes known as a 'trim curve"). Finally, it illustrates how to interpolate a curve through a list of points and join two such curves together.

surfaceTest.bsh:
This script is similar to crvTest.bsh in that it tests out many NURBS surface related features. NURBS surfaces are very new to GeomSS and so are not as mature and so there is not as much in here yet.


The next several scripts were added as an example of a "real-world" use for GeomSS.

nacaAirfoil.bsh:
This script will do nothing when "sourced". All it does is create a subroutine definition in BeanShell that calls through to a pure Java library that can create a range of NACA airfoils. The scripted subroutine returns the airfoil as a NURBS curve.

gaAirfoil.bsh:
This script will do nothing when "sourced". All it does is create a subroutine definition in BeanShell that creates a family of airfoil curves as described in: Ribblet, H., "GA Airfoils, A Catalog of Airfoils for General Aviation Use", 1996. The scripted subroutine returns the airfoil as a NURBS curve.

splitAfCrv.bsh:
This script will do nothing when "sourced". All it does is create a subroutine definition in BeanShell that takes the input curve (assumed to be an airfoil curve) and splits it into an upper and lower curve. This is useful for gridding airfoil curves.

buildWing.bsh:
Finally, this script uses the three scripts listed above to create a simple trapezoidal wing surface lofted from two airfoil sections. The wing surface is then gridded with points that could possibly be output to an aerodynamics analysis program such as PANAIR [http://www.pdas.com/panair.htm].


Revision History:
== Alpha 0.0.8 ==
April 4, 2011
This update fixes some user interface issues only.
* Corrected a long-standing error with zooming which caused the geometry to not be displayed in some circumstances.  The zoom method has been changed from moving the camera closer or farther away from the model to leaving the camera fixed and scaling the model up or down in the virtual world with a uniform scaling factor.
* Added the ability to display the geometry with a perspective transformation (default) or parallel (isometric) projection transformation.
* Fixed a bug that prevented opening of files when all windows were closed on MacOS X. 

== Alpha 0.0.7 ==
September 30, 2010
This update primarily improves NURBS curve and surface support and fixes bugs.
* Added the ability to reverse the parametric direction of a curve and to reverse either of the parametric directions of a surface.
* Added the ability to transpose the parametric directions of a surface.
* Added the ability to elevate the degree of a NURBS curve or surface.
* Added the ability to split a curve into two curves at an arbitrary parametric position.
* Added the ability to split a surface into two surfaces at an arbitrary S or T parametric position.
* Added the ability to thin out every other point in a string or every other column or row in an array of points.
* Made the closest point algorithms for curves and surfaces more robust.
* Modified "decomposeToBezier" methods to return actual curve and surface representations of the segments/patches (rather than lists of control points only).
* Fixed a bug that caused some geometry readers/writers to not close their output streams.
* Corrected errors with NurbsSurface.getS0Curve(), getS1Curve(), getT0Curve(), and getT1Curve().

== Alpha 0.0.6 ==
This update primarily adds the ability to read/write Initial Graphics Exchange Specification (IGES) files (to a limited extent), run the program form a command line in batch mode, and numerous bug fixes and small enhancements.
* Added the ability to read the following entities from an IGES file:  100 (circular arc), 104 (conic arc), 106-1 (list of 2D points), 106-2 (list of 3D points), 106-11 (linear string of 2D points), 106-12 (linear string of 3D points), 106-63 (planar segmented curve), 108-0 (unbounded plane), 110 (line), 116 (point), 124 (transformation), 126 (NURBS curve), 128 (NURBS surface), and 402-15 (ordered associativity/group).
* Added the ability to write some GeomSS geometry types to an IGES file including: PointList (106-12), GeomPlane (108-0), GeomPoint (116), NurbsCurve (126) and NurbsSurface (128) and GeomList (402-15).  Transformations are not yet supported explicitly in writing the exchange file, but currently the geometry is transformed before being written out.
* Redesigned the interfaces and methods for reading/writing geometry files to be more general.
* Added new command options for creating points, and the various geometry lists.
* Added a method that will return the length of a PointString where "length" is defined as the sum of the distances between each consecutive point in the string.
* Modified CurveFactory as follows:
** Added a method for creating a degenerate point curve.  This is a curve that is defined only at a single point (it has zero length).
** Added a method for creating an elliptical arc segment.
** Added a method for creating a parabolic arc segment.
** Reversed the parametric direction of all circular/elliptical arcs so that they are counterclockwise when viewed looking down the normal vector (consistent with the right hand rule).  This change will break existing scripts that use circular or elliptical arcs created using CurveFactory.
* Updated to BeanShell2 Revision 39 which fixes a number of bugs.
* Added the ability to run GeomSS from the command line in a "batch" mode that runs the specified script without bringing up the interactive GUI.

== Alpha 0.0.5 ==
8/14/2010
This update primarily fixes bugs and adds a few new methods for working with NURBS curves and surfaces.  Changes include the following:
* Added methods for inserting one or many new knots into the knot vector(s) of existing curves (surfaces).
* Added methods for attempting to remove knots from a curve or surface maintaining the curve or surface shape to within a certain tolerance.
* Added methods for easily extracting the S & T curves that correspond to the columns & rows of the surface's control point network.
* Added methods that decompose a NurbsCurve (or NurbsSurface) into Bézier curve segments (or surface patches).  GeomSS doesn't support dedicated Bézier curve or surface objects, so these methods return lists of lists of control points or control point networks.
* Added variants of the draw() command that will draw control points and any List containing geometry objects (or containing other Lists containing geometry, etc).
* Added a command for creating a 1-degree straight line NurbsCurve between any two points (in any dimension).
* KnotVectors are now immutable.
* Corrected an error in "copyToReal()" that prevented it from working with geometry lists and LoftedSurfaces.
* Corrected an error in GeomVector's calculation of getBoundsMin() and getBoundsMax().
* Fixed a bug with the LoftedSurface, BasicNurbsCurve, and BasicNurbsSurface copy() methods.
* Corrected an error that occurred when a curve is created with points of different units.
* Improved the defensiveness of some objects (copies are made of input objects and copies of internal objects are output).
* Fixed some misc. bugs that cropped up in testing.

== Alpha 0.0.4 ==
7/18/2010
This update primarily improves support for finding closest and farthest points on a curve or surface to/from a target point.
* Added the ability to find the closest and farthest point on a surface to a specified point or array (list of lists) of points.
* Added methods for finding the closest/farthest point on a curve for each point in a list of points.
* Added methods for finding closest and farthest points on a curve or surface that are near the specified parametric position (allowing the user to identify the particular local minima to be returned).
* Corrected errors in the calculation of curve arc length, surface area and surface enclosed volume that greatly increased the accuracy of these methods.
* Improved type safety of the various geometry lists (so that you can't add a PointArray to a PointString for instance).

== Alpha 0.0.3 ==
7/5/2010
This update primarily adds additional support for NURBS surfaces.  Changes include:
* Added a "newLoftedSurface" command.
* Added support for creating NURBS surfaces of revolution, spheres and toruses.
* Added methods to return the boundary curves of a surface in the native format of that surface (such as a NURBS curve from a NURBS surface).
* Added the ability to extract a grid of subrange points from a surface.
* Removed tolerance from calculation of arc-length, surface area and surface enclosed volume.
* Curve & surface derivatives are now returned as GeomVector objects rather than GeomPoint objects.
* Improved getClosestPoint and getFarthestPoint algorithms for curves.
* Added ability to draw ControlPointNet objects with the draw() command.
* Fixed a bug with changing the working directory on the Windows platform.
* Corrected a bug with newUnitVector(x,y) that prevented it from working.
* Fixed a bug with the Point.set() methods that caused unit errors.
* Improved BeanShell script documentation for standard set of GeomSS commands.

== Alpha 0.0.2b ==
This update affects primarily the Windows platform only, so that is all that has been included in this release.
* Fixed a bug that prevented "Change Working Directory…" in the "File" menu from working.

== Alpha 0.0.2 ==
6/27/2010
Added much more support for NURBS surfaces and fixed a few bugs.  Changes include:
* Added support for Lofted Surfaces (surfaces made from a list of defining curves).
* Added calculation of surface normal vector, tangent plane, mean curvature, Gaussian curvature, twist vector, surface area and enclosed volume.
* Greatly improved unit support for parametric objects (curves & surfaces).
* Corrected an error that caused an invalid error message to be displayed when Java3D 1.5+ could not be found.
* Newly drawn objects now honor the previously set mirroring and render type settings.  CenterAndZoom now honors the mirroring setting.
* Fixed a bug with the calculation of derivatives on a SubrangeCurve.
* Corrected an error in ControlPointNet.to() method.

== Alpha 0.0.1 ==
6/20/2010
This is an initial public prototype version of GeomSS.  It is intended for experimenting with the geometry and parameter libraries and for getting some very early feedback on the direction that the project is going.  This release is not intended for "production" use.


This is all I have for now.  Hopefully, there will be much more to come.

Ad astra,

Joseph A. Huwaldt