trimnurbs (NEW in 3.3 release) for function display (LONG)

[Seth Teller]

hello posters/poseurs:

>> agate!apple!tahoe!wrc.unr.edu!steve
asked about displaying function data on an sgi box.  steve, i tried
to email but the berkeley gateway bounced it back, so here's the post:

steve:

the trimnurbs program does what you want... it's in the 3.3 release.
unfortunately the manpage was accidentally omitted (i'm including
it at the end of this letter).

it's a bit of overkill, but you can get shaded, lit, realtime,
etc., display by defining a bilinear nurbs surface of your data.

you need to write an ascii file with your data in the ascii format 
the program knows how to read.  there's some ancillary data that 
will probably look incomprehensible to you.  here's a description
of the file that will do what you want (tokens and parentheses
are important, whitespace and /* */ aren't):

surface
        majorspec    /* row-major, t-spec */
                order   2	/* linear */	
                nknots  n+2	/* n is # of x points */
                knots
                        0 1 2 .. n-1
                endknots
        endmajorspec
        minorspec    /* col-minor, s-spec */
                order   2
                nknots  m+2	/* m is # of y points */
                knots
                        0 1 2 .. m-1
                endknots
        endminorspec
        nonrational
        transform		/* optional */	
                scale 1 /* isotropic */
                scale  1 1 1 /* anisotropic */
                translate 0 0 0
                matrix
                        1 0 0 0
                        0 1 0 0
                        0 0 1 0
                        0 0 0 1
        endtransform
        points
                (x y z) ... (x y z)		/* m points per column */
		...
		...	
                (x y z) ... (x y z)
		/* n rows of m columns */
        endpoints
endsurface

if this file is called 'data', just run trimnurbs -f data.

yours,

seth teller

ps.  here's the manpage (raw form):

.. \f2 gives underline; \f3 gives bold
.. \fB gives bold; \fI gives underline? \fP gives previous
'\"macro stdmacro
.if n .pH g1.find @(#)trimnurbs	30.7 of 3/21/86
.nr X
.if \nX=0 .ds x} TRIMNURBS 1 "Textured, Trimmed NURB Surfaces" "\&"
.if \nX=1 .ds x} TRIMNURBS 1 "Textured, Trimmed NURB Surfaces"
.if \nX=2 .ds x} TRIMNURBS 1 "" "\&"
.if \nX=3 .ds x} TRIMNURBS "" "" "\&"
.TH \*(x}
.SH NAME
\fBtrimnurbs\fP \- create, display and edit textured, trimmed, non-uniform rational B-Spline surfaces (\fBNURBS\fP)
.SH SYNOPSIS
.B trimnurbs
<options>
.SH DESCRIPTION

\fBtrimnurbs\fP is a multi-focus program which allows interactive manipulation of 
\fBtrimmed NURB surfaces\fP: tensor-product parametric maps of trimmed domains in R2 
onto continuous ranges in R3.   In the VGX and future architectures, these 
surfaces may also be \fBtexture-mapped\fP in a variety of ways, with a user-definable
set of textures.  A complete exposition of these surfaces is beyond the scope of this document.  
The acronym \fBNURBS\fP, however, may be expanded as 
\fBN\fIon-\fBU\fIniform \fBR\fIational \fBB\fI-\fBS\fIpline\f1.
The meaning of each term can be explained briefly as follows.

.B Non-Uniform:
describes the "knot vector," or underlying demarcation of the range space,
for the NURB.  The simplest\^
\fBNURBS\fP have uniform knot vectors, and thus regular
continuity properties (perhaps these should be called \fBURBS\fP).  These continuity 
constraints may be relaxed by making the knot vector for the \fBNURB\fP non-uniform; that
is, comprised of heterogeneous intervals.  

.B Rational:
refers to the "\fBrational weights\fP" of the \fBcontrol points\fP
which are blended to form the nurbs surface.  This component is often referred to as
"\fBW\fP" in the literature, and forms the fourth entry in the coordinate quadruple \fB(X,Y,Z,W)\fP
which specifies each control point in \fBR4\fP.  The surface is actually generated
in \fBR4\fP, then projected onto the \fBW = 1\fP plane which is a copy of \fBR3\fP.
This projection allows exact modeling of a larger set of implicit surfaces
(for instance, quadric surfaces).

.B B-Spline:
or \fBbasis-spline\fP, refers to the method by which the surface is parametrically generated.
The control points
are (usually smoothly) blended through multiplication by a set of (usually) smooth, bi-variate
scalar functions known as "\fBbasis functions\fP."  Changing the \fBknot vectors\fP changes
the smoothness properties and relative heights of the basis functions.  No matter how
the basis functions are manipulated, they are always \fBnon-negative\fP and \fBsum to one\fP at
every point in their
domain, thus guaranteeing the \fBconvex hull\fP property: the generated surface always
lies within the convex hull of its control points.  

B-Spline basis functions afford\^
.B local support \^
to the surface; that is, since they
are \fBexactly zero\fP outside certain restricted subranges of the domain, the control point
which a particular basis function multiplies has \fBno effect\fP on the surface outside the
image of this subdomain.

.SH USAGE

.PP
.B trimnurbs
was originally conceived as a stress test for Silicon Graphics' implementation of the NURBS 
surface primitive.  It has since evolved into an interactive tool which aids in
understanding, and demonstrating the flexibility of, the NURBS surface representation. 

.B trimnurbs
offers \fBfive\fP major areas of interaction to the user.  These areas, or windows, will
be referred to as the \fBnurb\fP, \fBbasis\fP, \fBtrim\fP, \fBmodel\fP, and \fBoptions\fP
windows.

.B standard user-interface

there is a standard user-interface paradigm in all the windows: namely, that \fBpicking
on a graphical object operates on that object\fP, and \fBpicking on the window background
operates on the view\fP.

.nf

as much as possible, the same mouse buttons perform the same 
view operations in every window. the mapping is:

    \fBleft mouse\fP to isotropically \fBscale\fP
    \fBmiddle mouse\fP to \fBrotate\fP (in 3d windows)
       or \fBtranslate\fP (in 2d windows)
    \fBright mouse\fP for pull-down menu

.fi

to edit an \fBobject\fP rather than the view, the user must pick
near the object itself with the appropriate mouse button.
for example, to \fBedit\fP the position of a \fBcontrol point\fP, pick
near it with the \fBleft mouse\fP in the \fBnurb\fP window.  to \fBisotropically scale\fP
the nurbs window, pick on the window \fBbackground\fP (i.e., pick \fBaway\fP from all 
graphical objects in the window).

there are many such examples.  the mouse operations are \fBheavily overloaded\fP, and it
would be awkward to enumerate them here.  the best way to learn them is by experimentation,
and by reading the \fBon-line help\fP files provided in every window as the \fBfirst pick\fP
of the \fBpull-down\fP menus.  These, of course, are elicited by clicking on the \fBright
mouse\fP; remember to use the right-mouse \fBaway\fP from any graphical objects!

.B the cursor

the \fBshape and color\fP of the \fBcursor\fP are important cues to the user.  in normal operation,
the cursor is a \fBred arrow\fP.  when an object, such as a control point or a knot, is
picked, the cursor becomes \fBgreen\fP, and remains green until the editing operation
terminates.  when the user must \fBwait\fP for an operation (for instance, file i/o) to 
complete, the cursor becomes an \fBhourglass\fP.  

.B the preferred object

in all windows, there is the notion of the \fBpreferred\fP, or most recently
picked, object.  If a menu pick is to act on an individual object, it will
always choose the preferred object.  This object is always \fBdisplayed\fP
with a \fBhighlighted\fP color to distinguish it from other objects.

.B aborting edit operations

pressing the \fBescape\fP key will immediately \fBabort\fP any current editing
operation and restore the object to its state at the time of the initial 
selection pick.

.B view operations

several standard \fBview operations\fP are defined in the pull-down menu of every window.
\fBreset view\fP centers, rotates, and scales the view appropriately for the currently displayed
object.

.B centering attention on one window

the \fBfull window\fP and \fBquarter window\fP picks expand the current window to
the full size of the program window, or shrink it back to quarter size,
respectively.

.B using the entire screen

in the \fBoptions\fP window, the full screen / initial screen picks expand
and shrink the \fBprogram\fP window between full-screen size and its size
immediately before the last time the full-screen pick was chosen.

the five windows also offer the following display and editing options:

.B nurb window
.nf

    this is an \fBobject space\fP window, and displays the \fBcontrol
    hull\fP, the \fBcontrol points\fP, the \fBs\fP and \fBt order\fP of the 
    surface, and the \fBnurbs surface\fP itself.

    \fBleft mouse\fP edits the \fBcontrol point\fP x, y, and z
    \fBmiddle mouse\fP edits the control point \fBrational weights\fP w
    \fBleft\fP and \fBright\fP mice edit the \fBs\fP and \fBt order\fP of surface

    \fBleft\fP mouse scales the view
    \fBmiddle\fP mouse rotates the view
    \fBright\fP mouse elicits \fBpull-down\fP menu, for lighting, texturing, etc.

.fi

.B basis window
.nf

    this is a bi-modal window.

    in \fBfocus basis functions\fP mode, it is an \fBs-t parameter
    space\fP window, in which the \fBbasis functions\fP and the 
    \fBs\fP and \fBt knot vectors\fP are displayed.

    in \fBfocus trim knots\fP mode, it is a \fBu-parameter
    space\fP window, in which the \fBknot vector\fP for the
    current \fBtrim curve\fP is displayed.

    \fBleft mouse\fP edits individual \fBknots\fP
    \fBleft mouse\fP edits knot \fBmultiplicities\fP

    \fBleft\fP mouse scales the view
    \fBmiddle\fP mouse rotates the view
    \fBright\fP mouse elicits \fBpull-down\fP menu

.fi

.B trim window
.nf

    this is a \fBparameter space\fP window, in which the \fBtrim curves\fP and
    the \fBs\fP and \fBt knot vectors\fP are displayed.

    \fBleft mouse\fP on a trim curve vertex \fBedits\fP the vertex \fBposition\fP
    \fBleft mouse\fP on a trim curve edge \fBscales\fP the curve

    \fBmiddle mouse\fP on a trim curve vertex \fBedits\fP the vertex \fBweight\fP
    \fBmiddle mouse\fP on a trim curve edge \fBrotates\fP the curve

    \fBright mouse\fP on a trim curve vertex \fBdeletes\fP the vertex
    \fBright mouse\fP on a trim curve edge \fBtranslates\fP the curve

    \fBleft\fP/\fBright\fP mouse, respectively, on the numeric \fBlabel\fP
    attached to each trim curve, \fBdecrements\fP/\fBincrements\fP
    the \fBdegree\fP of the trim curve.

    \fBdouble-clicking\fP the middle mouse in place creates a new
    trim curve, which is then rubber-banded until another
    \fBdouble-click\fP.  in this mode, a \fBsingle-click\fP of the 
    middle mouse lays down a new trim point.  Also in this mode,
    a \fBleft\fP/\fBright\fP mouse click will \fBdecrement\fP/\fBincrement\fP,
    (respectively) the order of the \fBnurbs\fP trim curve being created.

    \fBleft\fP mouse scales the view
    \fBmiddle\fP mouse \fBtranslates\fP the view
    \fBright\fP mouse elicits \fBpull-down\fP menu

.fi

.B model window
.nf

    this is a \fBworld space\fP window, in which all \fBenabled
    nurbs objects\fP are displayed after being subjected to
    \fBmodeling transformations\fP.

    \fBleft mouse\fP scales the selected nurb object.
	    (when the left mouse is down and an object is
	    selected, the cursor is green.  in this mode, 
	    pressing the \fBmiddle\fP mouse selects the object
	    into the \fBnurb window\fP; pressing the \fBright\fP
	    mouse disables the object's display in the \fBmodel
	    window\fP.)

    \fBmiddle mouse\fP rotates the selected nurb object.

    \fBright mouse\fP translates the selected nurb object.
	    (when the right mouse is down and an object is
	    selected, the cursor is green.  in this mode, 
	    pressing the \fBleft\fP mouse scales the object 
	    \fBanistropically\fP along an axis \fBnormal\fP
	    to the translation plane.  pressing the \fBmiddle\fP
	    mouse \fBcycles\fP translation planes among the
	    \fBXY\fP, \fBXZ\fP, and \fBYZ\fP planes.)

    \fBleft\fP mouse scales the view
    \fBmiddle\fP mouse rotates the view
    \fBright\fP mouse elicits \fBpull-down\fP menu

.fi
.SH OPTIONS

.nf
(this information may also be had by invoking trimnurbs \fB-h\fP.)

    -\fBe\fP(nable trimmed surfaces)
    -\fBf\fP(ile load from) <nurbfilename>
    -\fBi\fP(sotropic scale by) <factor> (only model, nurb windows)
    -\fBp\fP(layback) <playbackfile>
        [-\fBd\fP(isable) auto-append mode after playback]
        [-\fBA\fP(nimate; i.e., scrsave each frame)]
        [-\fBD\fP(elay between frames during playback)]
    -\fBq\fP(uiet) : suppress auto-scripting
    -\fBs <0/1> \fP(set s domain cyclicity; default 1)
    -\fBt <0/1> \fP(set t domain cyclicity; default 1)
    -\fBv\fP(erbose) : force status updates
    -\fBw\fP\fBx,y,w,h\fP : window position and size in pixels
    -\fBx<angle>\fP (rotation angle, in degrees (model, nurb windows))
    -\fBy<angle>\fP (rotation angle, in degrees (model, nurb windows))
    -\fBz<angle>\fP (rotation angle, in degrees (model, nurb windows))

    -\fBC<ncols>\fP (set default columns; must be >= 2)
    -\fBR<nrows>\fP (set default rows; must be >= 2)

    -\fBP\fP(ath) \fB<dir>\fP: add 'dir' to directory 
        list searched for nurbs at startup

    -\fBS<sorder>\fP <%d..%d>", MINGLORDER, DYNAMIC_MAXGLORDER);
    -\fBT<torder>\fP <%d..%d>", MINGLORDER, DYNAMIC_MAXGLORDER);

    -\fBWn\fP -\fBWb\fP -\fBWt\fP -\fBWm\fP 
        make nurbs, basis, trim, or model window full size at startup

(the following options are valid only \fBin-house\fP)

    -\fBE\fP(mulate) : emulate all GL ucode in software where possible
    -\fBF\fP(rontbuffer) : enable front buffer
    -\fBG\fP edge mode : canonical window size for edge debugging
    -\fBM\fP(alloc sanity mode)
    -\fBX\fP disable exception handling
    -\fBZ <debug_level>\fP (currently 0,1 are supported)

    -\fBh\fP(elp) : print this help message
.fi

.SH "THE .trimnurbsrc FILES"
to ease some of the pain involved in so many command-line options,
a facility for run-time commands is provided.  \fBin order\fP, the
files \fB~/.trimnurbsrc\fP (in the home directory) and \fB.trimnurbsrc\fP
(in the current directory), are read if they exist.  in effect, 
their contents are \fBprepended\fP to the command line.  thus, arguments 
in \fB.trimnurbsrc\fP override conflicting arguments in \fB~/.trimnurbsrc\fP; 
and arguments on the \fBcommand line\fP override conflicting arguments 
in either file.

there is a \fBspecial case\fP to consider: how to handle command line
arguments when replaying an event script.  it is unreasonable to
expect the user to issue the same command line options when they
replay the script as when they made it.  it is just as unreasonable,
however, to expect \fBtrimnurbs\fP to make sense of runtime-command
arguments that conflict with objects created in the script.  

thus the special case:  if the first argument to \fBtrimnurbs\fP is
\fB-p\fP (for \fBplayback mode\fP), all .trimnurbsrc files are \fBignored\fP.
(command line arguments are still processed; users should use these
with care.)

lastly, it should be noted that \fBall command flags are written to
the script\fP at startup time for every invocation of trimnurbs.  thus
some program state persists across script generation and playback.

.SH EXAMPLES
.PP
to list all legal command line and .trimnurbsrc options:

    trimnurbs \fB-h\fP(elp)

to read in a pre-created surface in human readable format from 'surface.nurb':

    trimnurbs \fB-f surface.nurb\fP

to create a toroidal surface (\fBclosed \fPin\fB s \fPand\fB t\fP) of 5x6 control points:

    trimnurbs \fB-s1\fP \fB-t1\fP \fB-R5\fP \fB-C6\fP

to \fBreplay\fP the \fBscript\fP file 'demo.script':

    trimnurbs \fB-p\fP \fBdemo.script\fP

.nf
    (\fBn.b.\fP: trimnurbs writes scripts to \fB/usr/tmp/nscript.xxxx\fP, 
    where \fBxxxx\fP is the process id of its current invocation.
    it is the \fBuser's responsibility\fP to copy this file to a safe
    place after exiting; trimnurbs \fBdeletes\fP all such files which 
    are \fBmore than one day old\fP on startup.)
.fi

.SH "THE NURBS HUMAN-READABLE FORMAT"

this format is an \fBascii\fP format with a simple nesting structure
(surfaces within files, trim curves within surfaces, textures within
surfaces), and c-style comments using \fB/*\fP and \fB*/\fP.  
trim curves may also be read and written as autonomous objects
(with a \fB.trim\fP extension), as may texture descriptors (\fB.text\fP).
Note that texture descriptors are like UNIX symbolic links; they
point to texture sources (i.e., images) that may or may not exist.

\fBtrimnurbs\fP expects nurbs objects as files ending in \fB.nurb\fP,
and trim-curve objects as files ending in \fB.trim\fP.  trimnurbs
reads and writes this format, and will accept multiple nurbs objects
and/or multiple trim curves in a single ascii file.  texture descriptors
may be similarly read or written.

for \fBexamples\fP of valid nurbs object files, see the \fBobjects\fP
subdirectory of the directory trimnurbs is executed from.

.nf

surface
	majorspec
		order	<order>
		nknots	<nknots>
		knots
		    /* <knot 0.. knot nknots - 1 > */
		endknots
	endmajorspec
	minorspec
		order	<order>
		nknots	<nknots>
		knots
		    /* <knot 0.. knot nknots - 1 > */
		endknots
	endminorspec
	[rational]
	[tolerance <tolerance>]
	transform
		scale <isotropic>
		scale <x-anistropic> <y-anistropic> <z-anistropic>
		translate <x-trans> <y-trans> <z-trans>
		matrix
			M00 M01 M02 M03
			M10 M11 M12 M13
			M20 M21 M22 M23
			M30 M31 M32 M33
	endtransform
	points
		/* (majorknots - majororder) groups of 
		    (minorknots - minororder) control points */
		(x y z w)
	endpoints

	trim	    /* optional */
		nurbscurve
			spec
				order	<order>
				nknots <nknots>
				knots
		    		    /* knot 0.. knot nknots - 1 */
				endknots
				[cyclic]
				[rational]
			endspec
			points
				/* (nknots - order) points (s t w) */
			endpoints
		endnurbscurve
	endtrim

	texture	    /* optional */
	    source /usr/demos/data/textures/coke.rgb
	    [function [modulate | decal]]
	    [channels [ 1 | 2 | 3 | 4 ]]
	    [minfilter [point | bilinear | mipmappoint | mipmaplinear | mipmapbilinear]]
	    [magfilter [point | bilinear]]
	    [disabled]
	endtexture

	trim
		pwlcurve
			spec
				npoints <npoints>
				[cyclic]
				[rational]
			endspec
			points
				/* npoints, of form (s t w) */
			endpoints
		endpwlcurve
	endtrim
endsurface

.fi

.SH FILES
 \fB~\fP/.trimnurbsrc	    \fBdefault\fP command line args
 \./.trimnurbsrc         args to \fBoverride\fP ~/.trimnurbsrc
 \./help/nurbs.help	    \fBnurb window\fP on-line help file
 \./help/model.help	    \fBmodel window\fP on-line help file
 \./help/basis.help	    \fBbasis window\fP on-line help file
 \./help/trim.help	    \fBtrim window\fP on-line help file
 \./help/options.help    \fBoptions window\fP on-line help file
 \./help/author.help
 \./objects/*.nurb	    \fBhuman-readable\fP nurb objects
 \./objects/*.trim	    \fBhuman-readable\fP trim objects
 \./textures/*.rgb	    \fBtexture\fP sources (image files)
 /usr/tmp/nscript.*	    \fBscripts\fP created by trimnurbs	    

.SH ENVIRONMENT VARIABLES
The environment variable \fBTRIMNURBS_PATH\fP is examined at startup
for ascii nurb files with extension \fB.nurb\fP and \fB.trim\fP, as
well as for image files with extension \fB.rgb\fP.  If it is not
found, the default path is equivalent to the result of the csh command
\fBsetenv TRIMNURBS_PATH .:./objects:./textures:/usr/demos/data/textures\fP.

.SH "SEE ALSO"
nurbssurface(1), nurbscurve(1), pwlcurve(1), 
setnurbsproperty(1), getnurbsproperty(1).

The \f2Programmer's Reference Manual\f1.

The gl document \f2Silicon Graphics Nurbs Interface\f1.

.SH AUTHOR
seth teller.

seth at miro.berkeley.edu, seth at sgi.com

.SH BUGS
.nf
surfaces take much longer to draw in pick mode.

auto-scaling of subsidiary objects sometimes produces
nonsense results.

degenerate surfaces render, but are not handled 
gracefully by trimnurbs or the gl.

there are too many option flags.

it is possible to force nonsensical results by
replaying a script and issuing command line arguments
which confuse trimnurbs.

sliders are needed for manipulating analog quantities.

although the ascii nurbs file format allows trim curves for
a surface to be specified before the surface data, \fBtrimnurbs\fP
does not.

a better material editor is needed.

the window can not be resized while replaying a script.
(it can be pushed, popped, and moved, however.)

there are too many menu picks.  the more notable should
be described in this document.

.fi

.\"	@(#)trimnurbs.1	2.15 of 8/20/89
.Ee