Tutorial

Back to Main page.

This page includes some generic usage notes and a brief tutorial on how to use GeomSS.

• A Quick Demo
• Introduction
• Geometry Object Creation
• Sample Geometry Data Files
• Example/Demo Scripts
• Seeing What You Have
  • Drawing Geometry
  • Querying Variables and Geometry

A Quick Demo

Ok. Your impatient, and you want results fast. Let's hop to it.
* Quick Demos

Introduction

First of all, GeomSS is not really meant to be "easy to use". It is meant to be powerful. Secondly, it is aimed at programmers and those comfortable around a command-line environment. It's not going to be useful to you if all you want to do is point-and-click. That said, GeomSS could be used to create "point-and-click" applications that are geared for end-users and solve a narrowly defined problem. But creating this application on top of GeomSS will require considerable programming skill.

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 some 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 itself, 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.getTangencyPoint(p, 0.5, 1e-4);
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.getTangencyPoint". You also needed the standard Java API documentation to understand the Color cosntants that are defined.

It isn't possible for it all to be in BeanShell form and though you can do everything GeomSS does in native Java form, it is most inconvenient at times. You just have to be familiar with both sets of documentation and that makes the learning curve for this program extremely steep.

Geometry Object Creation

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

Instead of the typical Java object creation syntax of:

Point p = new Point(1,3.5,2,FOOT);  // Does not work in GeomSS.

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();

Sample Geometry Data 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).

Example/Demo Scripts

I have created a few demo scripts that show by example 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 some of the example scripts:

crvTest.bsh:
This is a script that tests out many of the NURBS curve related features in GeomSS. This script is not really 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.

cube.bsh:
This script simple creates a 1 meter x 1 meter x 1 meter cube and draws it.

gridSpacingOptions.bsh:
This script creates a set of lines and "grids" the lines with points (a step in the "meshing process") that have various useful distributions.

plotXY_test.bsh:
This script demonstrates several way sto create 2D plots of data in GeomSS. The resulting 2D plots are placed in separate windows and are interactive!

random_orientation.bsh:
This script demonstrates the right and wrong ways to create a uniformly distributed set of points on the surface of a sphere representing random orientations of a vector. You will notice that the "wrong way" has points bunched at the poles.

Finally, the next set of scripts were added as an example of a "real world" use for GeomSS.

buildWing.bsh:
This script uses several "sub-scripts" found in the "scripts_airfoils" and "scripts_wings" directories 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.

Seeing What You Have

Drawing Geometry

When you create geometry with GeomSS, you probably want to see what it looks like. To do that, you draw the geometry into the 3D view using the draw command. For example:

// Create a string of points to draw.
str = newPointString();
str.add(newPoint(0,0,0));
str.add(newPoint(3,0,0,FOOT));
str.add(newPoint(5,0,0,FOOT));
str.add(newPoint(7,1,1,FOOT));
str.add(newPoint(10,2,3,FOOT));

// Draw the string while erasing anything that was previously drawn.
draw(str, true);

// Draw all the points that make up the string without erasing what was there previously.
draw(str.getAll());

After copying the above code and pasting it onto the GeomSS command line, you should see a line drawn in green with the points drawn as red dots. With the "draw" command, you can draw any geometry object including lists of geometry such as PointString, PointArray, GeomList, etc. If you ever want to just erase the scene, use the "erase()" command.

You can use the mouse to rotate the 3D view (click-and-drag with the left mouse button), zoom in and out (use the mouse wheel or click-and-drag with the middle mouse button or option-drag with a single mouse button), and translate it around (click-and-drag with the right mouse button or control-click and drag on a single-button mouse). Near the top of the GeomSS window, you will see a button with a yellow and black "target" icon on it. If you click on that, the geometry is centered on the display and zoomed to fit in the 3D window. Next to that is a menu with some pre-defined view angles in it (top, side, etc). The next button over that is half-gray/half-blue toggles mirroring across the XY plane off and on. This is useful for left-right symmetry geometry where you need only to draw one side or the other, but you would like to see what the whole thing would look like. Finally, the last menu determines how point-geometry objects (arrays, strings and points) are rendered.

You have a little control over how various geometry objects are drawn. You can do things like set the color of lines and points:

color = getPointColor();
setPointColor(BLUE);
draw(str.getAll(),true);
setPointColor(color);

crv = fitPoints(3,str);  // Interpolate a cubic curve through the existing string of points.
color = getLineColor();
setLineColor(YELLOW);
draw(crv);
setLineColor(color);

Likewise, you can get and set the size of the dot representing points: getPointSize() and setPointSize(size).

Querying Variables and Geometry

Besides drawing geometry, you can also query geometry objects and variables from the GeomSS command line. For example, you can print the value of any variable including a description of any geometry object using print():

theta = newParameter(35,DEGREE_ANGLE);
cth = Parameter.cos(theta);
print("theta = " + theta);
print("cth = " + cth);
print("str = " + str);  // Assuming that the "str" variable defined above is still in the workspace.

This outputs the following:

theta = 35.0 °
cth = 0.819152044288992
str = PointString: {
{0.0 m, 0.0 m, 0.0 m},
{3.0 ft, 0.0 ft, 0.0 ft},
{5.0 ft, 0.0 ft, 0.0 ft},
{7.0 ft, 1.0 ft, 1.0 ft},
{10.0 ft, 2.0 ft, 3.0 ft}
}

Note that the "show()" command can be used to toggle on and off an automatic listing of any variable every time it is assigned a value or typed on the command line. This is very helpful for debugging. Saves you from having to type "print()" all the time.

Printing is OK when you know what is in your workspace, but what if you have been doing a lot of stuff and you aren't sure anymore what you called what? Use the "list()" and "listVars()" commands. If you type list();, by itself, you get a listing of all the geometry objects in your workspace. In this case, I got the following:

%list();
VARIABLE        NAME/ID         TYPE            PHYDIM PARDIM
crv             126             BasicNurbsCurve 3      1
str             1               PointString     3      0

As you can see, the list() not only lists out the geometry objects (a point string and a curve), but also some useful information about them: variable name, any name or id# assigned to the object, the class-type of the object, it's physical dimension (1 for 1D, 2 for 2D, 3 for 3D, etc) and it's parametric dimension (0 for points, 1 for curves, 2 for surfaces).

Since many geometry objects are actually collections of other geometry objects (a string is a list of points for example), you can often list the contents of other objects using the "list" command as well. For example: list(str); gives the following output:

%list(str);
VARIABLE        NAME/ID         TYPE            PHYDIM PARDIM
str(0)          2               Point           3      0
str(1)          3               Point           3      0
str(2)          4               Point           3      0
str(3)          5               Point           3      0
str(4)          6               Point           3      0

You can also use "list" to list simple variables as a short cut. So instead of print("theta = " + theta);, you can use list(theta);. The output will be the same.

Finally, you can list all the non-geometry variables in your workspace using: listVars();. The result of this in my current workspace is:

%listVars();
Non-GeomElement variables:
  theta          gApp           $_e            color          
  cth            bsh            gScene

So, you can see that I have "theta", "cth" and "color" defined. In addition, there are some variables that are always present such as "gApp" and "gScene". These give you access to some of the application and scene rendering features (the "draw" command calls through to "gScene.draw()" for instance). The "bsh" variable gives you access to the BeanShell system.

Note: if you want to clear all your variables and geometry from the workspace, effectively erasing all of them (no undo!), use the clear() command.