ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/GRAPHICS/PLOT/IRITSM3S.ZIP/DOCS/IRIT.SRC

Text File | 1992-03-10 | 131.0 KB | 4,102 lines

;This is the source file to create documentation for the IRIT solid modeler.
;First character in line specifies the action to take for this line/next block
;as follows:
; ';' - a comment that is always ignored.
; '#' - all lines following this line until next '#' are indented as an array.
;       Four integers follows specifying indentations, # of elements per
;       line, whether or not to put an internal vertical seperators, and
;       if entries are row ordered (1) or col ordered (2).
; '@' - latex only manual. Latex commands can appear within this line.
; '!' - plain text and irit docs only manual - keywords/headers.
; '&' - plain text only manual - headers.
; '$' - terminator for current block.
;
; latex commands can appear in regular text limited to a single line as
; {\command *}. For plain text the {\command } will be filtered out.
; Escaped characters via '\' (i.e. \#) will be left escaped (\#) in the
; latex output but unescaped (#) in the plain output.
;
;                       IRIT solid modeler (C) Gershon Elber 1991.
;

@%
@% Irit Solid modeler latex manual.
@%
@% Authors:     Gershon Elber
@%
@% Date:        Tri Nov 29, 1991
@%
@% Copyright (c) 1991 Gershon Elber
@%
@
@\documentstyle[11pt]{article}
@\oddsidemargin  -.195in
@\evensidemargin -.195in
@\textwidth 6.50in
@\topmargin -.5in
@\textheight 9.5in
@
@\begin{document}
@
@\pagestyle{empty}
@   \rule{0in}{3in}
@   \begin{center}
@       {\huge\bf IRIT}\\
@       \vspace{3cm}
@       {\Large A Solid modeling Program}\\
@       \vspace{2cm}
@       {\large Copyright (C) 1989, 1990, 1991 Gershon Elber}\\
@       \vspace{1cm}
@       {\large EMail: [e-mail] }\\
@
@       \vfill
@       {\small This manual is for IRIT version 3.0.}
@   \end{center}
@\newpage
@
@\tableofcontents
@\newpage
@
@\setcounter{page}{1}
@\markright{{\em {\bf Irit Solid modeler}}\hfil G. Elber}
@\pagestyle{myheadings}
@\newpage
@
@
@%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@
@\section{Introduction}
!INTRODUCTION

   {\em IRIT} is a small solid modeler developed for educational purposes. Although
 small, it is now powerful enough to create quite complex scenes. I wrote
 it mainly so I can learn all the little small and not so small problems
 in developing such a system.

   {\em IRIT} started as a polygonal solid modeler and was originally developed
 (and mostly still is) on an IBM PC under MSDOS. Version 2.0 was also ported
 to X11 and version 3.0 to SGI 4D systems. Version 3.0 also includes
 quite a few free form curves and surfaces tools. See the UPDATE.NEW
 file for more detailed update information.
$

@\section{Copyrights}
!COPYRIGHTS

   BECAUSE {\em IRIT} AND ITS SUPPORTING TOOLS AS DOCUMENTED IN THIS DOCUMENT
 ARE LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT
 PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I
 GERSHON ELBER PROVIDE {\em IRIT} PROGRAM AND ITS SUPPORTING TOOLS "AS IS" WITHOUT
 WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 PURPOSE.
 THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THESE PROGRAMS IS WITH
 YOU. SHOULD THE {\em IRIT} PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
 NECESSARY SERVICING, REPAIR OR CORRECTION.

   IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
 BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
 OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
 USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
 FAILURE OF THE PROGRAMS TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
 ELBER) THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
 SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.

@\smallskip

   {\em IRIT} is a freeware solid modeler. It is not public domain since I
 hold copyrights on it. However unless you are to sell or attempt to make
 money from any part of this code and/or any model you made with this solid
 modeler, you are free to make anything you want with it.

   You are not obligated to me or to anyone else in any way by using {\em IRIT}.
   You are encourage to share any model you made with it, but the models
 you made with it are {\em yours}, and you have no obligation to share them.
   You can use this program and/or any model created with it for any non
 commerical and non profit purposes only. An acknowledgement on the way the
 models were created would be nice but is {\em not} required.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Command Line Options and Set Up}
!SETUP

   The {\em IRIT} program reads a file called {\bf IRIT.CFG} each time it is executed.
   This file configures the system. It is a regular text file with comments, so
 you can edit it and properly modify it for your environment.
   This file is being searched for in all directories as specified by the
 PATH environment variable on MSDOS BC++ port or in the IRIT\_PATH environment
 variable under UNIX hosts or MSDOS DJGPP port.
   For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
   Note IRIT\_PATH must terminate with '/'. If the variables is not set only
 the current directory is being searched for {\bf IRIT.CFG} under UNIX systems.
   Since there exists a configuration file for MSDOS BC++ called IRIT-DOS.CFG,
 for MSDOS DJGPP called IRIT\_DJG.CFG, and for UNIX called IRIT-UNX.CFG, make
 sure you copy the right one for your system, into {\bf IRIT.CFG}.

   In addition, if exists, a file by the name of {\bf IRITINIT.IRT} will be
 automatically executed before any other '.irt' file. This file may contain
 any {\em IRIT} command. It is the proper place to put your ALIASs if you have
 some. This file will be searched much the same way {\bf IRIT.CFG} is. The
 name of this initialization file may be changed by setting the StartFile
 entry in the configuration file.

   Under MSDOS the solid modeler can be executed in text mode (see the .cfg
 and the -t flag below) on virtually any MSDOS compatible system. The BC++ port
 uses Borlands BGI interface which makes it possible to use almost any device
 that has a BGI interface from Hercules to a Super VGA. See the configuration
 file for the supported device. The DJGPP port can be used on any system that
 has graphic driver for it in this compiler.
 Under BC++ the coprocessor will be used if detected but floating pointing
 emulation will take place otherwise. Under DJGPP the provided emulator
 (emu387) must be used if no 387 exists. If a mouse or a joystick exists
 they can be use by enabling their respective flags in the configuration
 file. The mouse sensitivity can be controlled via the configuration file
 MouseSensitivity flag. In addition whether a mouse or a joystick exists or
 not, the numeric keypad can be used to move the cursor as well. Shifted keys
 will move the cursors 10 pixels at a time instead of one.
   Since MSDOS does not support windowing system, an interface library called
 intr\_lib is used and which provides the windowing and interfacing
 capabilities expected from a windowing system. Four windows are created
 under BC++, three under DJGPP:
# 19 2 0 1
 View
  The window where geometry is displayed.
 Transformation
  The window holding the transformation interaction.

  This window pops up with INTERACT command, by default.
 Input
  The window input is keyed in/sourced from a file.
 Status
  Status window, mainly for core left display (only BC++).
#
   These windows can be placed everywhere in the screen by specifing their
 position and size in the configuration file. Border width and color of
 the window can be specified in the configuration file as well as other
 window attributes such as smooth scrolling and window headers.
   Furthermore, these windows can be moved, resized, poped, or pushed during
 a session via a pop up window triggered by the left mouse button (EXECUTE -
 see INTERACT) or F1 keystroke. Note however that while the mouse cursor is
 on the Input window scroll bar or in the Trans window, EXECUTE has a
 different meaning and the pop up menu will not be displayed. The following
 entries can be found in the pop up menu, and their meaning.
# 12 2 0 1
 Redraw all
  Redraw all windows. No window configuration is modified.
 Move
  Move a window. Window to move is picked by left mouse button.
 Resize
  Resize a window. Window to resize is picked as above.
 Pop
  Pop up a window. Window to pop up is picked as above.
 Push
  Push up a window. Window to push down is picked as above.
 Zoom
  Zoom a window to full screen. Window is picked as above.

  Zoom on a zoomed window restore the window original size.
 Reset
  Reset all windows to their default position and size.
 Headers
  Toggle the display of windows header - names.
#

  Under UNIX using X11 add the following options to your .Xdefaults. Most
 are self explanatory. The Trans attributes control the transformation
 window, while View control the view window. SubWin attributes control
 the subwindows within the Transformation window.
# 33 2 0 1
 irit*Trans*BackGround:
  NavyBlue
 irit*Trans*BorderColor:
  Red
 irit*Trans*BorderWidth:
  3
 irit*Trans*TextColor:
  Yellow
 irit*Trans*SubWin*BackGround:
  DarkGreen
 irit*Trans*SubWin*BorderColor:
  Magenta
 irit*Trans*Geometry:
  =150x500+500+0
 irit*Trans*CursorColor:
  Green
 irit*View*BackGround:
  NavyBlue
 irit*View*BorderColor:
  Red
 irit*View*BorderWidth:
  3
 irit*View*Geometry:
  =500x500+0+0
 irit*View*CursorColor:
  Red
#

   If poly3d is used under SGI gl library, you can set the prefered windows
 location in the poly3d.cfg. No color control is provided at this time.

   A session can be logged into a file as set via LogFile in the configuration
 file. See also the LOGFILE command.

   When developing new model under MSDOS, it is extremely convenient to switch
 between the solid modeler and an editor of your choice to edit the '.irt' file.
 The solid modeler provides a way to fork to an editor of your choice to edit
 the current '.irt' program you develop. Set EditPrgm (in irit.cfg) to the
 editor of your choice, which should be small for fast access. Specify the
 full path to that editor. Use the edit command in {\em IRIT} to call it. Only one
 argument is given to the editor once forking to it - the '.irt' file name as
 given to the edit command (see EDIT command). You can alias the command to
 make it even faster as it is done in the current iritinit.irt - {\em IRIT}
 initialization file.
   Under UNIX one can use the gnu emacs irit.el {\em IRIT} mode provided in this
 package to run {\em IRIT}.

   The following command line options are available:

@\begin{verbatim}
   IRIT [-t] [-z] [file.irt]
@\end{verbatim}

# 10 2 1 1
 -t
   Puts {\em IRIT} into text mode. No graphics will be displayed and

   the INTERACT and VIEW commands will be ignored. Useful when

   one needs to execute an irt file to create data on a tty device...
 -z
   Prints usage message and current configuration/version

   information.
 file.irt
   A file to directly invoke instead of waiting to input from

   stdin.
#
$

@\section{First Usage}
!FIRSTUSAGE

   Once executed, the program opens four windows under MSDOS BC++ (three
 under MSDOS DJGPP - no status window): view, status, trans and input windows,
 and opens a view window under UNIX.

   Commands are entered through the input window, which is in the same window
 as the shell executed {\em IRIT} under UNIX. Objects are viewed in the view
 window, and the status window is used as an auxiliary window (MSDOS only).

   Some important commands to begin with are

   1. include("file.irt"); - will execute the commands in file.irt. Note
      include can be recursive up to 10 levels. To execute the demo
      (demo.irt) simply type 'include("demo.irt");'. Another way to run
      the demo is by typing DEMO (must be capitalized as this is an alias
      loaded via the iritinit.irt initialization file - see the ALIAS
      command for more).

   2. help(""); - will print all available commands and how to get help on
      them. A file by the name irit.hlp will be searched as irit.cfg is
      being searched (see above), to provide the help.

   3. exit(); - close everything and exit {\em IRIT}.

   Be careful. Most operators are overloaded. This means that you can multiply
 two scalars (numbers) or two vectors or even two matrices with the same
 multiplication symbol ($*$). To get its on line type 'help("$*$");'

   The best way to learn this program (like any other program...) is by
 playing with it. Print the manual and study each of the commands available.
   Study the demo programs ($*$.irt) provided as well.

   Under MSDOS, input from keyboard has full line editing capability:

   1. Up/Down arrow : retrieve old command for 10 last commands.

   2. Left/Right arrows : to move left and right along the line.

   3. Home/End : to move to beginning/end of line.

   4. Delete : to delete the character the cursor is on.

   5. Back space : to delete one char backward.

   6. Insert : toggles insert/overwrite mode. Note cursor shape is modified.

   7. Esc : clear the entire line.

   8. CR : to accept line and quit.
$

@\section{Data Types}
!DATATYPES
  These are the Data Types recognized the system. They are also used to
 define the calling sequences of the different functions below:
# 18 2 1 1
 {\bf ConstantType}
  Scalar real type that cannot be modified.
 {\bf NumericType}
  Scalar real type.
 {\bf VectorType}
  3D real type vector (points/vectors).
 {\bf CtlPtType}
  Curve or Surface Control Point.
 {\bf MatrixType}
  4 by 4 matrix (homogeneous transformation matrix).
 {\bf PolygonType}
  Object consists of Polygons.
 {\bf PolylineType}
  Object consists of Polylines.
 {\bf CurveType}
  Object consists of Curves.
 {\bf SurfaceType}
  Object consists of Surfaces.
 {\bf GeometriceType}
  One of Polygon/lineType, CurveType, SurfaceType.
 {\bf GeometricTreeType}
  A list of GeometricTypes or GeometricTreeTypes.
 {\bf StringType}
  Sequence of chars within double quotes - "A string".

  Current implementation is limited to 80 chars.
 {\bf AnyType}
  Any of the above.
 {\bf ListType}
  List of (any of the above type) objects. Implementation

  is currently limited to 250 (50 MSDOS) objects in a list.
#
$

@\section{Commands summary}
!COMMANDS

 These are all the commands and operators supported by the {\em IRIT} solid modeler:

# 11 6 1 0
 $+$
 $-$
 $*$
 $/$
 \verb+^+
 ABS
 ACOS
 ALIAS
 ARC
 AREA
 ASIN
 ATAN
 ATAN2
 ATTRIB
 BEEP
 BOOLSUM
 BOX
 CBEZIER
 CBSPLINE
 CDIVIDE
 CEDITPT
 CEVAL
 CHDIR
 CIRCLE
 CIRCPOLY
 CLOSED
 CMESH
 COLOR
 COMMENT
 CON2
 CONE
 CONVEX
 COS
 CPOLY
 CRAISE
 CREFINE
 CREGION
 CROSSEC
 CSURFACE
 CTANGENT
 CTLPT
 CYLIN
 DIR
 EDIT
 EXIT
 EXP
 EXTRUDE
 FOR
 FREE
 GBOX
 GPOLYGON
 GPOLYLINE
 HELP
 IF
 INCLUDE
 INTERACT
 LIST
 LN
 LOAD
 LOG
 LOGFILE
 MERGEPOLY
 NORMAL
 NTH
 OFFSET
 PAUSE
 POLY
 ROTX
 ROTY
 ROTZ
 RULEDSRF
 SAVE
 SBEZIER
 SBSPLINE
 SCALE
 SDIVIDE
 SEDITPT
 SEVAL
 SFROMCRVS
 SIN
 SNOC
 SNORMAL
 SPHERE
 SQRT
 SRAISE
 SREFINE
 SREGION
 STANGENT
 SURFREV
 SWEEPSRF
 SYSTEM
 TAN
 TIME
 TORUS
 TRANS
 VARLIST
 VECTOR
 VIEW
 VOLUME
#
$

@\section{Functions and Variables}
!FUNCTIONS
@ This sections lists all the functions supported by the {\em IRIT} system
@ according to their classes - the object type they return.
@

 These are the functions returning a {\bf NumericType}:
# 11 5 1 0
 ABS
 ACOS
 AREA
 ASIN
 ATAN
 ATAN2
 COS
 CPOLY
 EXP
 LN
 LOG
 SIN
 SQRT
 TAN
 VOLUME
#

 These are the functions returning a {\bf GeometricType}:
# 11 6 1 0
 ARC
 BOOLSUM
 BOX
 CBEZIER
 CBSPLINE
 CDIVIDE
 CEDITPT
 CEVAL
 CIRCLE
 CIRCPOLY
 CMESH
 CON2
 CONE
 CONVEX
 CPOLY
 CRAISE
 CREFINE
 CREGION
 CROSSEC
 CSURFACE
 CTANGENT
 CTLPT
 CYLIN
 EXTRUDE
 GBOX
 GPOLYGON
 GPOLYLINE
 MERGEPOLY
 OFFSET
 POLY
 RULEDSRF
 SBEZIER
 SBSPLINE
 SDIVIDE
 SEDITPT
 SEVAL
 SFROMCRVS
 SNORMAL
 SPHERE
 SRAISE
 SREFINE
 SREGION
 STANGENT
 SURFREV
 SWEEPSRF
 TORUS
#

 These are the functions to linearly transform an object:
# 11 5 1 0
 ROTX
 ROTY
 ROTZ
 SCALE
 TRANS
#

 These are the miscellaneous functions:
# 11 6 1 0
 ALIAS
 ATTRIB
 BEEP
 CHDIR
 CLOSED
 COLOR
 COMMENT
 DIR
 EDIT
 EXIT
 FOR
 FREE
 HELP
 IF
 INCLUDE
 INTERACT
 LIST
 LOAD
 LOGFILE
 NORMAL
 NTH
 PAUSE
 SAVE
 SNOC
 SYSTEM
 TIME
 VARLIST
 VECTOR
 VIEW
#

 These are the variables predefined in the system:
# 11 5 1 0
 AXES
 DRAWCTLPT
 DUMPLVL
 ECHOSRC
 FLAT4PLY
 INTERCRV
 INTERNAL
 MACHINE
 RESOLUTION
 VIEW\_MAT
#

 These are the constants predefined in the system:
# 11 6 1 0
 APOLLO
 BLACK
 BLUE
 COL
 CYAN
 E2
 E3
 FALSE
 GREEN
 HP
 KV\_FLOAT
 KV\_OPEN
 MAGENTA
 MSDOS
 OFF
 ON
 P2
 P3
 PI
 RED
 ROW
 SGI
 SUN
 TRUE
 UNIX
 WHITE
 YELLOW
#
$

@\section{Language description}
!LANGUAGE
    The front end of the {\em IRIT} solid modeler is an infix parser that mimics
 some of the C language behavior. The infix operators that are supported
 are plus (+), minus (-), multiply (*), divide (/), and power (\verb+^+) for
 numeric operators and with the same precedence as in C.

    However, unlike the C language, these operators are overloaded,
@\footnote{In fact the C language do support overloaded operators to some
@extent: '1 + 2' and '1.0 + 2.0' implies invocation of two different
@actions.}
 or different action is taken based upon the different operands.
   This means that one can write '1 + 2' in which the plus sign is a regular
 numetic addition, or one can write 'PolyObj1 + PolyObj2' in which the plus
 sign is now the Boolean operation of union between two geometric objects.
   The exact way each operator is overloaded is defined below.

   In this environment the representation of reals, integers, and even
 Boolean data is identical. Data is automatically promoted as necessary.
 The constants TRUE and FALSE are defined as 1.0 and 0.0 respectively,
 for example.

   Each expression is terminated by a semicolon. An expression can be as
 simple as 'a;' which prints the value of variable a, or as complex as:

@\begin{verbatim}
    for ( (t = 1.1), 0.1, 1.9,
            (
               ( cb1 = csurface( sb, COL, t ) ):
               color( cb1, green ):
               snoc( cb1, cb_all )
            )
        );
@\end{verbatim}

   Once a complete expression is read in and parsed correctly (i.e. no syntax
 errors were found), it is executed. Before each operator or a function
 are executed, parameter type matching tests are being made to make sure
 the operator can be applied to these operand(s), or the function gets the
 correct set of arguments.

   The parser is almost totally case insensitive (with one exception - see
 the ALIAS command) so Obj, obj and OBJ will refer to the same object while
 MergePoly, MERGEPOLY, and margePoly will refer to the same function.

   Objects (Variables if you prefer) need not be declared. Simply use them
 when you need them. Object names may be any alpha-numeric (and underscore)
 string of at most 10 characters. By assigning to an old object, the old
 object will be automatically deleted and if necessary its type will be
 changing on the fly. For example:

@\begin{verbatim}
    V = sin( 45 * pi / 180.0 );
    V = V * vector( 1, 2, 3 );
    V = V * rotx( 90 );
    V = V * V;
@\end{verbatim}

 will assign to V a NumericType of sine of 45 degrees, the VectorType
 ( 1, 2, 3 ) scaled by the sine of 45, rotate that vector around the X axis
 by 90 degrees, and finally a NumericType which is its dot product.

   The parser will read from stdin unless a file was specified on the command
 line or an INCLUDE command was executed. In both cases, when done reading
 from the file, the parser will again wait for input from stdin. In order
 to execute a file and quit when the file is done, put an EXIT command as
 the last command in the file.
$

@\section{Operator overloading}
@
@ This section lists the way the basic operators $+$, $-$, $*$, $/$, and
@ \verb+^+ are overloaded. In other words, what action is taken by each
@ of these operators depending upon its arguments.
@
@\subsection{Overloading $+$}
!+
 The $+$ operator is overloaded above the following domains:

@\begin{verbatim}
  NumericType + NumericType -> NumericType
  VectorType  + VectorType  -> VectorType
  MatrixType  + MatrixType  -> MatrixType
  PolygonType + PolygonType -> PolygonType  (Boolean UNION operation)
  CurveType   + CurveType   -> CurveType    (Curve curve chaining)
  CurveType   + CtlPtType   -> CurveType    (Curve control point chaining)
  CtlPtType   + CtlPtType   -> CurveType    (Control points chaining)
  ListType    + ListType    -> ListType     (Append lists operator)
@\end{verbatim}

 Note: Boolean UNION of two disjoint objects (no common volume) will result
 with the two objects combined. It is the USER responsibility to make sure that
 the non intersecting object are also disjoint - this system only tests for
 no intersection.
$

@\subsection{Overloading $-$}
!-
 The $-$ operator is overloaded above the following domains:

 As a Diadic operator:

@\begin{verbatim}
  NumericType - NumericType -> NumericType
  VectorType  - VectorType  -> VectorType
  MatrixType  - MatrixType  -> MatrixType
  PolygonType - PolygonType -> PolygonType (Boolean SUBTRACT operation)
@\end{verbatim}

 As a Monadic operator:

@\begin{verbatim}
  - NumericType -> NumericType
  - VectorType  -> VectorType    (Scaling all vector by -1)
  - MatrixType  -> MatrixType    (Scaling all matrix by -1)
  - PolygonType -> PolygonType   (Boolean NEGATION operation)
  - CurveType   -> CurveType     (Curve parameterization is reversed)
  - SurfaceType -> SurfaceType   (Surface parameterization is reversed)
@\end{verbatim}

 Note: Boolean SUBTRACT of two disjoint objects (no common volume) will result
 with an empty object. For both a curve and a surface parameterization reverse
 opeartion (Monadic minus) causes the object normal to be flipped as a side
 effect.
$

@\subsection{Overloading $*$}
!*
 The $*$ operator is overloaded above the following domains:

@\begin{verbatim}
  NumericType * NumericType   -> NumericType
  VectorType  * NumericType   -> VectorType     (Vector scaling)
  VectorType  * VectorType    -> NumericType    (Inner product)
  MatrixType  * NumericType   -> MatrixType     (Matrix Scaling)
  MatrixType  * VectorType    -> VectorType     (Vector transform)
  MatrixType  * MatrixType    -> MatrixType     (Matrix multiplication)
  MatrixType  * GeometricType -> GeometricType  (Object transform)
  MatrixType  * ListType      -> ListType       (Object hierarchy transform)
  PolygonType * PolygonType   -> PolygonType    (Boolean INTERSECTION operation)
@\end{verbatim}

 Note: Boolean INTERSECTION of two disjoint objects (no common volume) will
 result with an empty object. Object hierarchy transform transforms any
 transformable object (GeometricType) found in the list recursively.
$

@\subsection{Overloading $/$}
!/
 The $/$ operator is overloaded above the following domains:

@\begin{verbatim}
  NumericType / NumericType -> NumericType
  PolygonType / PolygonType -> PolygonType   (Boolean CUT operation)
@\end{verbatim}
$

 Note: Boolean CUT of two disjoint objects (no common volume) will result
 with an empty object.
$

@\subsection{Overloading \^{\ }}
!^
 The \verb+^+ operator is overloaded above the following domains:

@\begin{verbatim}
  NumericType ^ NumericType -> NumericType
  MatrixType  ^ NumericType -> MatrixType   (Matrix to the power)
  PolygonType ^ PolygonType -> PolygonType  (Boolean MERGE operation)
@\end{verbatim}

 Note: Boolean MERGE simply merges the two sets of polygons without any
 intersection tests. Matrix powers must be positive integers or -1 in which
 the matrix inverse (if exists) is computed.
$

@\subsection{Assignments}
!=
   Assignments are allowed as side effects, any place in any expressions:
 If Expr is an expression, then (var = Expr) is the exact same expression
 with the side effect of setting Var to that value. There is no guarantee
 on the order of evaluation, so using Vars that are set within same
 expression are a bad practice.

   Any assignment which is not at top level, MUST be within parenthesis.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Function's Description}
&Function's Description

@ The function description below defines their calling sequence in ANSI C
@ notation. Listed are all the functions the system knows about in alphabetic
@ order, according to their classes.
@
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{NumericType returning functions}
&NumericType returning functions

@\subsubsection{ABS}
!ABS

@\begin{verbatim}
 NumericType ABS( NumericType Operand )
@\end{verbatim}

   Returns the absolute value of the given {\bf Operand}.
$

@\subsubsection{ACOS}
!ACOS

@\begin{verbatim}
 NumericType ACOS( NumericType Operand )
@\end{verbatim}

   Returns the arc cosine value (in radians) of the given {\bf Operand}.
$

@\subsubsection{AREA}
!AREA

@\begin{verbatim}
 NumericType AREA( PolygonType Object )
@\end{verbatim}

   Return the area of the given {\bf Object} (in object units). Returned is
 the real area of the polygonal object - not the primitive it might approximate.

   That means that the area of a polygonal approximation to a sphere will be
 returned, not the sphere area.
$

@\subsubsection{ASIN}
!ASIN

@\begin{verbatim}
 NumericType ASIN( NumericType Operand )
@\end{verbatim}

   Returns the arc sine value (in radians) of the given {\bf Operand}.
$

@\subsubsection{ATAN}
!ATAN

@\begin{verbatim}
 NumericType ATAN( NumericType Operand )
@\end{verbatim}

   Returns the arc tangent value (in radians) of the given {\bf Operand}.
$

@\subsubsection{ATAN2}
!ATAN2

@\begin{verbatim}
 NumericType ATAN2( NumericType Operand1, NumericType Operand2 )
@\end{verbatim}

   Returns the arc tangent value (in radians) of the given ratio:
 {\bf Operand1} / {\bf Operand2}, over the whole angle circle.
$

@\subsubsection{COS}
!COS

@\begin{verbatim}
 NumericType COS( NumericType Operand )
@\end{verbatim}

   Returns the cosine value of the given {\bf Operand} (in radians).
$

@\subsubsection{CPOLY}
!CPOLY

@\begin{verbatim}
 NumericType CPOLY( PolygonType Object )
@\end{verbatim}

   Returns the number of polygons in the given polygonal {\bf Object}.
$

@\subsubsection{EXP}
!EXP

@\begin{verbatim}
 NumericType EXP( NumericType Operand )
@\end{verbatim}

   Returns the natural exponent value of the given {\bf Operand}.
$

@\subsubsection{LN}
!LN

@\begin{verbatim}
 NumericType LN( NumericType Operand )
@\end{verbatim}

   Returns the natural logarithm value of the given {\bf Operand}.
$

@\subsubsection{LOG}
!LOG

@\begin{verbatim}
 NumericType LOG( NumericType Operand )
@\end{verbatim}

   Returns the base 10 logarithm value of the given {\bf Operand}.
$

@\subsubsection{SIN}
!SIN

@\begin{verbatim}
 NumericType SIN( NumericType Operand )
@\end{verbatim}

   Returns the sine value of the given {\bf Operand} (in radians).
$

@\subsubsection{SQRT}
!SQRT

@\begin{verbatim}
 NumericType SQRT( NumericType Operand )
@\end{verbatim}

   Returns the square root value of the given {\bf Operand}.
$

@\subsubsection{TAN}
!TAN

@\begin{verbatim}
 NumericType TAN( NumericType Operand )
@\end{verbatim}

   Returns the tangent value of the given {\bf Operand} (in radians).
$

@\subsubsection{VOLUME}
!VOLUME

@\begin{verbatim}
 NumericType VOLUME( PolygonType Object )
@\end{verbatim}

   Return the volume of the given {\bf Object} (in object units). Returned is
 the real volume of the polygonal object - not the object it might approximate.

   This routine decompose all non convex polygons to convex ones as side
 effect (see CONVEX).
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{GeometricType returning functions}

&GeometricType returning functions

@\subsubsection{ARC}
!ARC

@\begin{verbatim}
 CurveType ARC( VectorType StartPos, VectorType Center, VectorType EndPos )
@\end{verbatim}

 An arc constructor between two end points {\bf StartPos} and {\bf EndPos}
 centered at {\bf Center}. Arc will always be less than 180 degrees so the
 shortest arc path from {\bf StartPos} to {\bf EndPos} is selected. The
 case where {\bf StartPos}, {\bf Center}, and {\bf EndPos} are colinear is
 illegal, since it attempts to define a 180 degrees arc. Arc is constructed
 as a single rational quadratic Bezier curve. Example:

@\begin{verbatim}
    Arc1 = ARC( vector( 1.0, 0.0, 0.0 ),
                vector( 1.0, 1.0, 0.0 ),
                vector( 0.0, 1.0, 0.0 ) );
@\end{verbatim}

 constructs a 90 degrees arc tangent to both X and Y axes at coordinate 1.
$

@\subsubsection{BOOLSUM}
!BOOLSUM

@\begin{verbatim}
 SurfaceType BOOLSUM( CurveType Crv1, CurveType Crv2,
                      CurveType Crv3, CurveType Crv4 )
@\end{verbatim}

 Construct a surface using the provided four curves as its four boundary
 curves. Curves do not have to have the same order or type and will be
 promoted to their least common denominator. The four curves end points
 should match as follows:
# 30 2 0 1
 {\bf Crv1} start point,
  to {\bf Crv3} start point.
 {\bf Crv1} end point,
  to {\bf Crv4} start point.
 {\bf Crv2} start point,
  to {\bf Crv3} end point.
 {\bf Crv2} end point,
  to {\bf Crv4} end point.
#
 where {\bf Crv1} and {\bf Crv2} are the two boundaries in one parameteric
 direction and {\bf Crv3} and {\bf Crv4} are the two in the other.

 Example:

@\begin{verbatim}
    Cbzr1 = cbezier( list( ctlpt( E3, 0.1, 0.1, 0.1 ),
                           ctlpt( E3, 0.0, 0.5, 1.0 ),
                           ctlpt( E3, 0.4, 1.0, 0.4 ) ) );
    Cbzr2 = cbezier( list( ctlpt( E3, 1.0, 0.2, 0.2 ),
                           ctlpt( E3, 1.0, 0.5, -1.0 ),
                           ctlpt( E3, 1.0, 1.0, 0.3 ) ) );
    Cbsp3 = cbspline( 4,
                      list( ctlpt( E3, 0.1,  0.1, 0.1 ),
                            ctlpt( E3, 0.25, 0.0, -1.0 ),
                            ctlpt( E3, 0.5,  0.0, 2.0 ),
                            ctlpt( E3, 0.75, 0.0, -1.0 ),
                            ctlpt( E3, 1.0,  0.2, 0.2 ) ),
                      list( KV_OPEN ) );
    Cbsp4 = cbspline( 4,
                      list( ctlpt( E3, 0.4,  1.0, 0.4 ),
                            ctlpt( E3, 0.25, 1.0, 1.0 ),
                            ctlpt( E3, 0.5,  1.0, -2.0 ),
                            ctlpt( E3, 0.75, 1.0, 1.0 ),
                            ctlpt( E3, 1.0,  1.0, 0.3 ) ),
                      list( KV_OPEN ) );
    Srf = BOOLSUM( Cbzr1, Cbzr2, Cbsp3, Cbsp4 );
@\end{verbatim}
$

@\subsubsection{BOX}
!BOX

@\begin{verbatim}
 PolygonType BOX( VectorType Point,
                  NumericType Dx, NumericType Dy, NumericType Dz )
@\end{verbatim}

   Creates a main planes parallel BOX polygonal object, defined by {\bf Point} as
 base position, and {\bf Dx, Dy, Dz} as BOX dimensions. Note negative dimensions
 are allowed. Example:

@\begin{verbatim}
    B = BOX( vector( 0, 0, 0 ), 1, 1, 1);
@\end{verbatim}

 creates a unit cube from 0 to 1 in all axes.
$

@\subsubsection{CBEZIER}
!CBEZIER

@\begin{verbatim}
 CurveType CBEZIER( ListType CtlPtList )
@\end{verbatim}

   Creates a Bezier curve out of the provided control point list. {\bf CtlPtList}
 is a list of control points, all of the same type (E2, E3, P2, or P3).
 Example:

@\begin{verbatim}
    s45 = sin(pi / 4);
    Arc90 = CBEZIER( list( ctlpt( P2, 1.0, 0.0, 1.0 ),
                           ctlpt( P2, s45, s45, s45 ),
                           ctlpt( P2, 1.0, 1.0, 0.0 ) ) );
@\end{verbatim}

 constructs an arc of 90 degrees as a rational quadratic Bezier curve.
$

@\subsubsection{CBSPLINE}
!CBSPLINE

@\begin{verbatim}
 CurveType CBSPLINE( NumericType Order, ListType CtlPtList,
                                                        ListType KnotVector )
@\end{verbatim}

   Creates a Bspline curve out of the provided control point list and the
 knot vector, with the specified order. {\bf CtlPtList} is a list of control points,
 all of the same type (E2, E3, P2, or P3) defining the curve control polygon.
 The length of the {\bf KnotVector} must be equal to the number of control
 points in {\bf CtlPtList} plus {\bf Order}.
 Example:

@\begin{verbatim}
    s45 = sin(pi / 4);
    HalfCirc = CBSPLINE( 3,
                      list( ctlpt( P3, 1.0,  0.0, 0.0,  1.0 ),
                            ctlpt( P3, s45, -s45, 0.0,  s45 ),
                            ctlpt( P3, 1.0, -1.0, 0.0,  0.0 ),
                            ctlpt( P3, s45, -s45, 0.0, -s45 ),
                            ctlpt( P3, 1.0,  0.0, 0.0, -1.0 ) ),
                      list( 0, 0, 0, 1, 1, 2, 2, 2 ) );
@\end{verbatim}

 constructs an arc of 180 degrees in the XZ plane as a rational quadratic
 Bspline curve.

   The knot vector list may be specified as {\bf list( KV\_OPEN )} or as
 {\bf list( KV\_FLOAT )} in which a uniform open or floating knot vector
 with the appropriate length is automatically constructed.
$

@\subsubsection{CDIVIDE}
!CDIVIDE

@\begin{verbatim}
 ListType CDIVIDE( CurveType Curve, NumericType Param )
@\end{verbatim}

   Subdivides a curve into two at the specified parameter value. {\bf Curve}
 can be either a Bspline curve in which {\bf Param} must be within Curve
 parametric domain or a Bezier curve in which {\bf Param} must be in the
 0 to 1 range.

   Returned is a list of the two sub-curves. The individual curves may be
 extracted from the list using the NTH command. For example:

@\begin{verbatim}
 CrvLst = CDIVIDE( Crv, 0.5 );
 Crv1 = nth( CrvLst, 1 );
 Crv2 = nth( CrvLst, 2 );
@\end{verbatim}

 subdivides the curve {\bf Crv} at the parameter value 0.5.
$

@\subsubsection{CEDITPT}
!CEDITPT

@\begin{verbatim}
 CurveType CEDITPT( CurveType Curve, CtlPtType CtlPt, NumericType Index )
@\end{verbatim}

   Provides a simple mechanism to manually modify a single control point number
 {\bf Index} (base count is 0) in {\bf Curve}, by substituting {\bf CtlPt}
 instead. {\bf CtlPt} must have the same point type as {\bf Curve} points.
 Original curve {\bf Curve} is not modified. Example:

@\begin{verbatim}
    CPt = ctlpt( E3, 1, 2, 3 );
    NewCrv = CEDITPT( Curve, CPt, 1 );
@\end{verbatim}

 constructs a {\bf NewCrv} with the second control point of {\bf Curve} being
 {\bf CPt}.
$

@\subsubsection{CEVAL}
!CEVAL

@\begin{verbatim}
 CtlPtType CEVAL( CurveType Curve, NumericType Param )
@\end{verbatim}

   Evaluates the provided {\bf Curve} at the given {\bf Param } value.
 {\bf Param} should be with the curve domain if {\bf Curve} is a Bspline
 curve, or between 0 and 1 if {\bf Curve} is a Bezier curve. Returned
 control point has the same type as the {\bf Curve} control points. Example:

@\begin{verbatim}
    CPt = CEVAL( Crv, 0.25 );
@\end{verbatim}

 evaluates {\bf Crv} at the parameter value of 0.25.
$

@\subsubsection{CIRCLE}
!CIRCLE

@\begin{verbatim}
 CurveType CIRCLE( VectorType Center, NumericType Radius )
@\end{verbatim}

   Construct a circle at the specified {\bf Center} with the specified
 {\bf Radius}. Returned circle is a Bspline curve of four piecewise Bezier
 90 degree arcs. Circle is always parallel to the XY plane. Use the linear
 transformation routines to place the circle in the appropriate location.
$

@\subsubsection{CIRCPOLY}
!CIRCPOLY

@\begin{verbatim}
 PolygonType CIRCPOLY( VectorType Normal, VectorType Trans, NumericType Radius )
@\end{verbatim}

   As in this solid modeler, open objects are allowed (although any two
 objects intersection should form a closed loop), a plane (open!) object
 also exists. The function defines a circular polygon with the given
 {\bf Normal}, and includes the {\bf Trans} point. It is implemented as a FINITE
 circle with resolution (see RESOLUTION) edges, radius {\bf Radius} and center
 {\bf Trans} on that plane. It is the user responsibility to make sure that any
 Boolean operation on it (or any other open object) will create closed loops as
 intersecting curves and/or open loops terminated on its boundary (no
 termination in the middle of it is allowed).

   Alternative to the function are manual construction of the required plane
 as a single polygon using POLY, or construction of a flat ruled surface using
 RULEDSRF.
$

@\subsubsection{CMESH}
!CMESH

@\begin{verbatim}
 CurveType CMESH( SurfaceType Srf, ConstantType Direction, NumericType Index )
@\end{verbatim}

   Returns a single ROW or COLumn as specified by the {\bf Direction} and
 {\bf Index} (base count is 0) of the surface {\bf Srf} control mesh.

   Returned curve will have the same knot vector as {\bf Srf} in the
 appropriate direction. See also CSURFACE.

   Note this curve is {\em not} necessarily in the surface {\bf Srf}. Example:

@\begin{verbatim}
    Crv = CMESH( Srf, COL, 0 );
@\end{verbatim}

 extracts the first column of surface {\bf Srf} as a curve.
$

@\subsubsection{CON2}
!CON2

@\begin{verbatim}
 PolygonType CON2( VectorType Center, VectorType Direction,
                   NumericType Radius1, NumericType Radius2 )
@\end{verbatim}

   Create a truncated CONE geometric object, defined by {\bf Center} as CONE main
 base center, CONE axes {\bf Direction}, and CONE base radii {\bf Radius1/2}.

   Note {\bf Direction} magnitude also sets the CONE height. {\bf Direction} can be any
 3D vector.

   Unlike the regular cone (CONE) constructor which has discontinuities in
 its apex generated normals, CON2 may be used to form a truncated cone but
 with continuous normals.
   See RESOLUTION for accuracy of CON2 approximation as polygonal model.
   Example:

@\begin{verbatim}
    Crv = CON2( vector( 0, 0, -1 ), vector( 0, 0, 4 ), 2, 1 );
@\end{verbatim}

 constructs a truncated cone based at the XY parallel plane Z = -1, top at
 plane Z = 3, and with radii of 2 and 1 respectively.
$

@\subsubsection{CONE}
!CONE

@\begin{verbatim}
 PolygonType CONE( VectorType Center, VectorType Direction,
                   NumericType Radius )
@\end{verbatim}

   Create a CONE geometric object, defined by {\bf Center} as CONE base center,
 CONE axes {\bf Direction}, and CONE base radius {\bf Radius}. Note {\bf Direction} magnitude
 also sets the CONE height. {\bf Direction} can be any 3D vector.

   See RESOLUTION for accuracy of CONE approximation as polygonal model.
   Example:

@\begin{verbatim}
    Crv = CONE( vector( 0, 0, 0 ), vector( 1, 1, 1 ), 1 );
@\end{verbatim}

 constructs a cone based in the XY parallel plane, centered at the origin
 with radius 1 and with tilted apex at ( 1, 1, 1 ).

   See also CON2.
$

@\subsubsection{CONVEX}
!CONVEX

@\begin{verbatim}
 PolygonType CONVEX( PolygonType Object )
@\end{verbatim}

   Coerce non convex polygons in {\bf Object}, into convex one. New vertices
 are introduced into the polygonal data during this process. The Boolean
 operations require the input to have convex polygons only (although it may
 return non convex polygons...) and automatically coerced non convex input
 polygons to convex ones, using this same routine.

   However some external tools (like irit2ray, poly3d-r and poly3d-h) requires
 convex polygons. This function may be used on the objects to provide that,
 just before they are being saved into data files. Example:

@\begin{verbatim}
    CnvxObj = CONVEX( Obj );
    save("data", CnvxObj);
@\end{verbatim}

 decompose non convex polygons into convex ones so that data file could be
 used by external tools requiring convex polygons.
$

@\subsubsection{CPOLY}
!CPOLY

@\begin{verbatim}
 NumericType CPOLY( PolygonType Polys )
@\end{verbatim}

   Returns number of polygons in provided object. Example:

@\begin{verbatim}
    DumpLvl = 1
    NumPolys = CPOLY( Obj );
    NumPolys;
@\end{verbatim}

 prints the number of polygons in object {\bf Obj}.
$

@\subsubsection{CRAISE}
!CRAISE

@\begin{verbatim}
 CurveType CRAISE( CurveType Curve, NumericType NewOrder )
@\end{verbatim}

   Raise {\bf Curve} to the {\bf NewOrder} Order specified. Currently
 implemented for Bezier curves of any order and linear Bspline curve only.
 Example:

@\begin{verbatim}
    Crv = ctlpt( E3, 0.0, 0.0, 0.0 ) +
          ctlpt( E3, 0.0, 0.0, 1.0 ) +
          ctlpt( E3, 1.0, 0.0, 1.0 );
    Crv2 = CRAISE( Crv, 4 );
@\end{verbatim}

 raises the 90 degrees corner linear Bspline curve {\bf Crv} to be a cubic.
$

@\subsubsection{CREFINE}
!CREFINE

@\begin{verbatim}
 CurveType CREFINE( CurveType Curve, NumericType Replace, ListType KnotList )
@\end{verbatim}

   Provides the ability to {\bf Replace} a knot vector of {\bf Curve} or refine
 it. {\bf KnotList} is a list of knots to refine {\bf Curve} at and all
 should be within {\bf Curve} parametric domain. If knot vector is to be
 replaced, the length of {\bf KnotList} should be identical to the length
 of {\bf Curve} knot vector. If {\bf Curve} is a Bezier curve, it is
 automatically promoted to be a Bspline curve. Example:

@\begin{verbatim}
    Crv2 = CREFINE( Crv, FALSE, list( 0.25, 0.5, 0.75 ) );
@\end{verbatim}

 refines {\bf Crv} at the three knots 0.25, 0.5, and 0.75.
$

@\subsubsection{CREGION}
!CREGION

@\begin{verbatim}
 CurveType CREGION( CurveType Curve, NumericType MinParam,
                                                       NumericType MaxParam )
@\end{verbatim}

   Extracts a subdomain of {\bf Curve} between {\bf MinParam} and {\bf MaxParam}.
 Both {\bf MinParam} and {\bf MaxParam} should be within {\bf Curve}
 parametric domain. Example:

@\begin{verbatim}
    SubCrv = CREGION( Crv, 0.3, 0.6 );
@\end{verbatim}

 extracts the subdomain of {\bf Crv} from the parameter value 0.3 to the
 parameter value 0.6.
$

@\subsubsection{CROSSEC}
!CROSSEC

@\begin{verbatim}
 PolygonType CROSSEC( PolygonType Object )
@\end{verbatim}

;   Invoke interactive mode to edit/create a polygon in the plane Z = 0. The
; polygon must be in the domain [0..1] in X,Y. The first polygon of the given
; Object is copied to begin with. If the given {\bf Operand} is NOT a geometric
; object, but false (numeric 0.0), a new polygon is created. Returns an (open)
; object with this one polygon only and inside side of +Z. Note that if the
; given polygon (first polygon of Object) is not on XY plane it is transformed
; to it before editing, and transformed back after.
   Unfortunately, this feature is NOT implemented...
$

@\subsubsection{CSURFACE}
!CSURFACE

@\begin{verbatim}
 CurveType CSURFACE( SurfaceType Srf, ConstantType Direction,
                                                          NumericType Param )
@\end{verbatim}

   Extract an iso parametric curve out of {\bf Srf} in the specified
 {\bf Direction} (ROW or COL) at the specified parameter value {\bf Param}.
 {\bf Param} must be in {\bf Srf} parameter range in {\bf Direction} direction.
 The returned curve is {\em in} {\bf Srf}. See also CMESH. Example:

@\begin{verbatim}
    Crv = CSURFACE( Srf, COL, 0.15 );
@\end{verbatim}

 extract an iso parametric curve in the COLumn direction at parameter value
 0.15 from surface {\bf Srf}.
$

@\subsubsection{CTANGENT}
!CTANGENT

@\begin{verbatim}
 VectorType CTANGENT( CurveType Curve, NumericType Param )
@\end{verbatim}

   Computes the tangent vector to {\bf Curve} at the parameter value {\bf Param}.
 Example:

@\begin{verbatim}
    Tang = CTANGENT( Crv, 0.5 );
@\end{verbatim}

 computes the tangent to {\bf Crv} at the parameter value 0.5.
$

@\subsubsection{CTLPT}
!CTLPT

@\begin{verbatim}
 CPt = CTLPT( ConstantType E2, NumericType X, NumericType Y )

 or

 CPt = CTLPT( ConstantType E3, NumericType X, NumericType Y, NumericType Z )

 or

 CPt = CTLPT( ConstantType P2, NumericType W, NumericType X, NumericType Y )

 or

 CPt = CTLPT( ConstantType P3, NumericType W,
                               NumericType X, NumericType Y, NumericType Z )
@\end{verbatim}

   Construct a single control point to be used in curves and surfaces
 construction. Four types of points may be constructed as follows:
# 10 2 1 1
 E2
  A two dimensional point with X and Y.
 E3
  A three dimensional point with X, Y, and Z.
 P2
  A two dimensional rational point at X/W, and Y/W.
 P3
  A three dimensional rational point at X/W, Y/W, and Z/W.
#
 Example:

@\begin{verbatim}
    CPt = CTLPT( E3, 0.0, 0.0, 0.0 );
@\end{verbatim}

 constructs an {\bf E3} points at the origin.
$

@\subsubsection{CYLIN}
!CYLIN

@\begin{verbatim}
 PolylineType CYLIN( VectorType Center, VectorType Direction,
                     NumericType Radius )
@\end{verbatim}

   Create a CYLINder geometric object, defined by {\bf Center} as CYLIN base center,
 CYLIN axes {\bf Direction}, and CYLIN base radius {\bf Radius}. Note Direction magnitude
 also sets the CYLIN height. {\bf Direction} can be any 3D vector.
   See RESOLUTION for accuracy of CYLIN approximation as polygonal model.
   Example:

@\begin{verbatim}
    Crv = CYLIN( vector( 0, 0, 0 ), vector( 1, 0, 0 ), 10 );
@\end{verbatim}

 constructs a cylinder along the X axis from the origin to X = 10.
$

@\subsubsection{EXTRUDE}
!EXTRUDE

@\begin{verbatim}
 PolygonType EXTRUDE( PolygonType Object, VectorType Dir )

 or

 SurfaceType EXTRUDE( CurveType Object, VectorType Dir )
@\end{verbatim}

   Creates an extrusion of the given {\bf Object}. If {\bf Object} is a
 PolygonObject, its first polygon is used as the base for the extrusion in
 {\bf Dir} direction, and a closed PolygonObject is constrcted. If {\bf Object}
 is a CurveType, an extrusion surface is constructed instead which is {\em not}
 a closed object (the two bases of the extrusion are excluded and the curve may
 be open by itself).

   No limitation exists on the polygon (can be non-convex), but {\bf Dir}
 cannot be coplanar with the polygon plane. The curve need not be planar.
   Example:

@\begin{verbatim}
    Cross = cbspline( 3,
                      list( ctlpt( E2, -0.018, 0.001 ),
                            ctlpt( E2,  0.018, 0.001 ),
                            ctlpt( E2,  0.019, 0.002 ),
                            ctlpt( E2,  0.018, 0.004 ),
                            ctlpt( E2, -0.018, 0.004 ),
                            ctlpt( E2, -0.019, 0.001 ) ),
                      list( KV_OPEN ) );
    Cross = Cross + -Cross * scale( vector( 1, -1, 1 ) );
    Napkin = EXTRUDE( Cross * scale( vector( 1.6, 1.6, 1.6 ) ),
                      vector( 0.02, 0.03, 0.2 ) );
@\end{verbatim}

 constructs a closed cross section {\bf Cross} by duplicating a half of
 it in reverse and merging the two sub-curves. {\bf Cross} is then used as
 the cross section for the extrusion operation.
$

@\subsubsection{GBOX}
!GBOX

@\begin{verbatim}
 PolygonType GBOX( VectorType Point,
                   VectorType Dx, VectorType Dy, VectorType Dz )
@\end{verbatim}

   Create a parallelpiped - Generalized BOX polygonal object, defined by
 {\bf Point} as base position, and {\bf Dx, Dy, Dz} as 3 3D vectors to define
 the 6 faces of this generalized BOX. The regular BOX object is special case
 of GBOX where {\bf Dx} = vector(Dx, 0, 0),   {\bf Dy} = vector(0, Dy, 0),
 {\bf Dz} = vector(0, 0, Dz).

   Note {\bf Dx}, {\bf Dy}, {\bf Dz} must be non-coplanar in order to create a feasible object.
   Example:

@\begin{verbatim}
    GB = GBOX(vector(0.0, -0.35, 0.63), vector(0.5, 0.0, 0.5),
                                        vector(-0.5, 0.0, 0.5),
                                        vector(0.0, 0.7, 0.0));
@\end{verbatim}
$

@\subsubsection{GPOLYGON}
!GPOLYGON

@\begin{verbatim}
 PolygonType GPOLYGON( GeometryTreeType Object )
@\end{verbatim}

   Approximate all Surface(s) in {\bf Object} as polygons using the RESOLUTION
 and FLAY4PLY variables. The larger RESOLUTION is the more polygons and
 finer the result approximation will be. Each Bezier patch will have roughly
 $RESOLUTION^2$ polygons.

   FLAT4PLY is a Boolean flag controlling the conversion of an (almost) flat
 patch into four (TRUE) or two (FALSE) polygons. Normals are computed to
 polygons vertices using surface normal, so Guaroud or Phong rendering can be
 performed. Returned is a single polygon object, no matter how complex
 {\bf Object} Hierarchy is. Example:

@\begin{verbatim}
    Polys = GPOLYGON( list( Srf1, Srf2, Srf3 ) );
@\end{verbatim}

 Converts to polygons the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}.
$

@\subsubsection{GPOLYLINE}
!GPOLYLINE

@\begin{verbatim}
 PolylineType GPOLYLINE( GeometryTreeType Object )
@\end{verbatim}

   Converts all Surface(s) and Curves(s) in {\bf Object} into polylines using
 the RESOLUTION variable. The larger RESOLUTION is the finer the result
 approximation will be. Returned is a single polyline object, no matter
 how complex {\bf Object} Hierarchy is. Example:

@\begin{verbatim}
    Polys = GPOLYLINE( list( Srf1, Srf2, Srf3, list( Crv1, Crv2, Crv3 ) ) );
@\end{verbatim}

 converts to polyline the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}
 and the three curves {\bf Crv1}, {\bf Crv2}, and {\bf Crv3}.
$

@\subsubsection{MERGPOLY}
!MERGEPOLY

@\begin{verbatim}
 PolygonType MERGEPOLY( ListType PolyList )
@\end{verbatim}

 Merge a set of polygonal objects in {\bf PolyList} list to a single polygonal
 object. All elements in {\bf ObjectList} must be of PolygonType type. No test
 is made on the validity of the data. This function performs the same
 operation as the {\bf \verb+^+} operator would, but may be more convenient
 to use under some conditions. Example:

@\begin{verbatim}
    Vrtx1 = vector( -3, -2, -1 );
    Vrtx2 = vector( 3, -2, -1 );
    Vrtx3 = vector( 3, 2, -1 );
    Vrtx4 = vector( -3, 2, -1 );
    Poly1 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );

    Vrtx1 = vector( -3, 2, 1 );
    Vrtx2 = vector( 3, 2, 1 );
    Vrtx3 = vector( 3, -2, 1 );
    Vrtx4 = vector( -3, -2, 1 );
    Poly2 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );

    Vrtx1 = vector( -3, -2, 1 );
    Vrtx2 = vector( 3, -2, 1 );
    Vrtx3 = vector( 3, -2, -1 );
    Vrtx4 = vector( -3, -2, -1 );
    Poly3 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );

    PolyObj = MERGEPOLY( list( Poly1, Poly2, Poly3 ) );
@\end{verbatim}
$

@\subsubsection{OFFSET}
!OFFSET

@\begin{verbatim}
 CurveType OFFSET( CurveType Crv, NumericType OffsetDistance )

 or

 SurfaceType OFFSET( SurfaceType Srf, NumericType OffsetDistance )
@\end{verbatim}

 Offsets {\bf Crv} or {\bf Srf}, by translating all control points in the
 curve or surface normal, by the {\bf OffsetDistance} amount. Returned curve
 or surface only approximates the real offset. One may improve the offset
 accuracy using refinement. Negative {\bf OffsetDistance} denotes offset in
 the reversed direction of the normal.

 Example:

@\begin{verbatim}
    OffCrv = OFFSET(Crv, -0.1);
@\end{verbatim}

 offsets {\bf Crv} by the amount of $-0.1$ in the reversed normal direction.
$

@\subsubsection{POLY}
!POLY

@\begin{verbatim}
 PolygonType POLY( ListType ObjectList )
@\end{verbatim}

   Create a single polygon (and therefore open) object, defined by the
 vertices which respectively defined by the objects in {\bf ObjectList} (see LIST).
 All elements in {\bf ObjectList} must be of VertorType type. No validity test is
 made and it is the user responsibility. see CIRCPOLY for conditions applied to
 open objects. Example:

@\begin{verbatim}
    V1  = vector( 0.0, 0.0, 0.0 );
    V2  = vector( 0.3, 0.0, 0.0 );
    V3  = vector( 0.3, 0.0, 0.1 );
    V4  = vector( 0.2, 0.0, 0.1 );
    V5  = vector( 0.2, 0.0, 0.5 );
    V6  = vector( 0.3, 0.0, 0.5 );
    V7  = vector( 0.3, 0.0, 0.6 );
    V8  = vector( 0.0, 0.0, 0.6 );
    V9  = vector( 0.0, 0.0, 0.5 );
    V10 = vector( 0.1, 0.0, 0.5 );
    V11 = vector( 0.1, 0.0, 0.1 );
    V12 = vector( 0.0, 0.0, 0.1 );
    I = poly( list( V1, V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12 ) );
@\end{verbatim}

 constructs an object with a single polygon in the shape of the I letter.
$

@\subsubsection{RULEDSRF}
!RULEDSRF

@\begin{verbatim}
 SurfaceType RULEDSRF( CurveType Crv1, CurveType Crv2 )
@\end{verbatim}

   Constructs a ruled surface between the two curves {\bf Crv1} and {\bf Crv2}.
   Curves do not have to have the same order or type and will be promoted to
 their least common denominator.

 Example:

@\begin{verbatim}
    Circ = circle( vector( 0.0, 0.0, 0.0 ), 0.25 );
    Cyl = RULEDSRF( circ, circ * trans( vector( 0.0, 0.0, 1.0 ) ) );
@\end{verbatim}

 Constructs a cylinder of radius 0.25 along the Z axis from 0 to 1.
$

@\subsubsection{SBEZIER}
!SBEZIER

@\begin{verbatim}
 SurfaceType SBEZIER( ListType CtlMesh )
@\end{verbatim}

   Creates a Bezier surface out of the provided control mesh. {\bf CtlMesh} is a
 list of control points rows, each is a list of control points. All control
 points must be of the same type (E2, E3, P2, or P3).

 Example:

@\begin{verbatim}
   Srf = SBEZIER( list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
                               ctlpt( E3, 0.0, 1.0, 0.0 ),
                               ctlpt( E3, 0.0, 2.0, 1.0 ) ),
                         list( ctlpt( E3, 1.0, 0.0, 0.0 ),
                               ctlpt( E3, 1.0, 1.0, 2.0 ),
                               ctlpt( E3, 1.0, 2.0, 0.0 ) ),
                         list( ctlpt( E3, 2.0, 0.0, 2.0 ),
                               ctlpt( E3, 2.0, 1.0, 0.0 ),
                               ctlpt( E3, 2.0, 2.0, 2.0 ) ),
                         list( ctlpt( E3, 3.0, 0.0, 0.0 ),
                               ctlpt( E3, 3.0, 1.0, 2.0 ),
                               ctlpt( E3, 3.0, 2.0, 0.0 ) ),
                         list( ctlpt( E3, 4.0, 0.0, 1.0 ),
                               ctlpt( E3, 4.0, 1.0, 0.0 ),
                               ctlpt( E3, 4.0, 2.0, 1.0 ) ) ) );
@\end{verbatim}
$

@\subsubsection{SBSPLINE}
!SBSPLINE

@\begin{verbatim}
 SurfaceType SBSPLINE( NumericType UOrder, NumericType VOrder,
                       ListType CtlMesh, ListType KnotVectors )
@\end{verbatim}

   Creates a Bspline surface out of the provided {\bf UOrder} and {\bf VOrder}
 orders, the control mesh {\bf CtlMesh} and the two knot vectors {\bf KnotVectors}.
 {\bf CtlMesh} is a list of control points rows, each is a list of control
 points. All control points must be of the same type (E2, E3, P2, or P3).
 {\bf KnotVectors} is a list of two knot vectors,
 each is a list of NumericType knots or a list of a single constant KV\_OPEN or
 KV\_FLOAT in which a uniform knot vector with open or floating end condition
 will automatically be constructed. Example:

@\begin{verbatim}
    Mesh = list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
                        ctlpt( E3, 0.0, 1.0, 0.0 ),
                        ctlpt( E3, 0.0, 2.0, 1.0 ) ),
                  list( ctlpt( E3, 1.0, 0.0, 0.0 ),
                        ctlpt( E3, 1.0, 1.0, 2.0 ),
                        ctlpt( E3, 1.0, 2.0, 0.0 ) ),
                  list( ctlpt( E3, 2.0, 0.0, 2.0 ),
                        ctlpt( E3, 2.0, 1.0, 0.0 ),
                        ctlpt( E3, 2.0, 2.0, 2.0 ) ),
                  list( ctlpt( E3, 3.0, 0.0, 0.0 ),
                        ctlpt( E3, 3.0, 1.0, 2.0 ),
                        ctlpt( E3, 3.0, 2.0, 0.0 ) ),
                  list( ctlpt( E3, 4.0, 0.0, 1.0 ),
                        ctlpt( E3, 4.0, 1.0, 0.0 ),
                        ctlpt( E3, 4.0, 2.0, 1.0 ) ) );
    Srf = SBSPLINE( 3, 3, Mesh, list( list( KV_OPEN ),
                                      list( 3, 3, 3, 4, 5, 6, 6, 6 ) ) );
@\end{verbatim}

 constructs a Bspline surface with its first knot vector being uniform with
 open end condition.
$

@\subsubsection{SDIVIDE}
!SDIVIDE

@\begin{verbatim}
 SurfaceType SDIVIDE( SurfaceType Srf, ConstantType Direction,
                                                          NumericType Param )
@\end{verbatim}

   Subdivides a surface into two at the specified parameter value {\bf Param}
 in the specified {\bf Direction} (ROW or COL). {\bf Srf} can be either a Bspline
 curve in which {\bf Param} must be within surface parametric domain or a Bezier
 curve in which {\bf Param} must be in the 0 to 1 range.

   Returned is a list of the two sub-surfaces. The individual surfaces may be
 extracted from the list using the {\bf NTH} command. Example:

@\begin{verbatim}
    SrfLst = SDIVIDE( Srf, ROW, 0.5 );
    Srf1 = nth( SrfLst, 1 );
    Srf2 = nth( SrfLst, 2 );
@\end{verbatim}

 subdivides {\bf Srf} at the parameter value of 0.5 in the ROW direction.
$

@\subsubsection{SEDITPT}
!SEDITPT

@\begin{verbatim}
 SurfaceType SEDITPT( SurfaceType Srf, CtlPtType CPt, NumericType UIndex,
                                                      NumericType VIndex )
@\end{verbatim}

   Provides a simple mechanism to manually modify a single control point number
 {\bf UIndex} and {\bf VIndex} (base count is 0) in {\bf Srf} control mesh
 by substituting {\bf CtlPt} instead. CtlPt must have the same point type as
 {\bf Srf} points. Original surface {\bf Srf} is not modified. Example:

@\begin{verbatim}
    CPt = ctlpt( E3, 1, 2, 3 );
    NewSrf = SEDITPT( Srf, CPt, 0, 0 );
@\end{verbatim}

 constructs a {NewSrf} with the first control point of {\bf Srf} being
 {\bf CPt}.
$

@\subsubsection{SEVAL}
!SEVAL

@\begin{verbatim}
 CtlPtType SEVAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
@\end{verbatim}

   Evaluates the provided surface {\bf Srf} at the given {\bf UParam} and
 {\bf VParam} values. Both {\bf UParam} and {\bf VParam} should be within
 the surface parametric domain if {\bf Srf} is a Bspline surface, or between 0
 and 1 if {\bf Srf} is a Bezier surface.  Returned control point has the same
 type as {\bf Srf} control points. Example:

@\begin{verbatim}
    CPt = SEVAL( Srf, 0.25, 0.22 );
@\end{verbatim}

 evaluates {\bf Srf} at the parameter values of (0.25, 0.22).
$

@\subsubsection{SFROMCRVS}
!SFROMCRVS

@\begin{verbatim}
 SurfaceType SFROMCRVS( ListType CrvList )
@\end{verbatim}

   Construct a surface by substituting the curves in {\bf CrvList} as rows
 in a surface control mesh. Curves in {\bf CrvList} are made compatible
 by promoting Bezier curves to Bsplines if necessary and raising degree
 and refining as required before substituting their control polygons as
 rows in the mesh.

   The other direction order is the same as the first direction order or
 if not enough curves are provided equal to the number of curves in {\bf CrvList}.

   The surface will interpolate the first and last curves only. Example:

@\begin{verbatim}
    Crv1 = cbspline( 3,
                     list( ctlpt( E3, 0.0, 0.0, 0.0 ),
                           ctlpt( E3, 1.0, 0.0, 0.0 ),
                           ctlpt( E3, 1.0, 1.0, 0.0 ) ),
                     list( KV_OPEN ) );
    Crv2 = Crv1 * trans( vector( 0.0, 0.0, 1.0 ) );
    Crv3 = Crv2 * scale( vector( 0.0, 0.0, 2.0 ) )
                * trans( vector( 0.1, 0.1, 0.1 ) );
    Srf = SFROMCRVS( list( Crv1, Crv2, Crv3 ) );
@\end{verbatim}
$

@\subsubsection{SNORMAL}
!SNORMAL

@\begin{verbatim}
 VectorType SNORMAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
@\end{verbatim}

   Computes the normal vector to {\bf Srf} at the parameter values {\bf UParam}
 and {\bf VParam}. Example:

@\begin{verbatim}
    Tang = SNORMAL( Crv, 0.5, 0.5 );
@\end{verbatim}

 computes the normal to {\bf Srf} at the parameter values (0.5, 0.5).
$

@\subsubsection{SPHERE}
!SPHERE

@\begin{verbatim}
 PolygonType SPHERE( VectorType Center, NumericType Radius )
@\end{verbatim}

   Creates a SPHERE geometric object, defined by {\bf Center} as SPHERE center,
 and with radius {\bf Radius}.
   See RESOLUTION for accuracy of SPHERE approximation as polygonal model.
$

@\subsubsection{SRAISE}
!SRAISE

@\begin{verbatim}
 SurfaceType SRAISE( SurfaceType Srf, ConstantType Direction,
                                                      NumericType NewOrder )
@\end{verbatim}

   Raise {\bf Srf} to the specified {\bf NewOrder} Order in the specified
 direction {\bf Direction}. Currently implemented for Bezier surfaces of
 any order and linear Bspline surfaces only. Example:

@\begin{verbatim}
    Srf = ruledSrf( cbezier( list( ctlpt( E3, -0.5, -0.5, 0.0 ),
                                   ctlpt( E3,  0.5, -0.5, 0.0 ) ) ),
                    cbezier( list( ctlpt( E3, -0.5,  0.5, 0.0 ),
                                   ctlpt( E3,  0.5,  0.5, 0.0 ) ) ) );
    Srf = SRAISE( SRAISE( Srf, ROW, 3 ), COL, 3 );
@\end{verbatim}

 construct a bilinear flat ruled surface and raise its both directions to be
 quadratic.
$

@\subsubsection{SREFINE}
!SREFINE

@\begin{verbatim}
 SurfaceType SREFINE( SurfaceType Srf, ConstantType Direction,
                      NumericType Replace, ListType KnotList )
@\end{verbatim}

   Provides the ability to {\bf Replace} a knot vector of {\bf Srf} or refine
 it in the specified direction {\bf Direction} (ROW or COL).
   {\bf KnotList} is a list of knots to refine {\bf Srf} at. All knots should be
 within {\bf Srf} parametric domain in {\bf Direction} direction. If knot vector
 is to be replaced, the length of {\bf KnotList} should be identical to the length
 of {\bf Srf} knot vector in direction {\bf Direction}. If {\bf Srf} is a
 Bezier surface, it is automatically promoted to be a Bspline surface.
 Example:

@\begin{verbatim}
    Srf = SREFINE( SREFINE( Srf,
                            ROW, FALSE, list( 0.333, 0.667 ) ),
                   COL, FALSE, list( 0.333, 0.667 ) );
@\end{verbatim}

 refines {\bf Srf} in both directions by adding two more knots at 0.333 and
 0.667
$

@\subsubsection{SREGION}
!SREGION

@\begin{verbatim}
 SurfaceType SREGION( SurfaceType Srf, ConstantType Direction,
                                                        NumericType NewOrder )
@\end{verbatim}

   Extracts a subdomain of {\bf Srf} between {\bf MinParam} and {\bf MaxParam}
 in the specified {\bf Direction}. Both {\bf MinParam} and {\bf MaxParam}
 should be within {\bf Srf} parametric domain in {\bf Direction}.
 Example:

@\begin{verbatim}
    SubSrf = SREGION( Srf, COL, 0.3, 0.6 );
@\end{verbatim}

 extracts the subdomain of {\bf Srf} from the parameter value 0.3 to the
 parameter value 0.6 along the COLumn direction. the ROW direction is
 extracted as a whole.
$

@\subsubsection{STANGENT}
!STANGENT

@\begin{verbatim}
 VectorType STANGENT( SurfaceType Srf, ConstantType Direction,
                      NumericType UParam, NumericType VParam )
@\end{verbatim}

   Computes the tangent vector to {\bf Srf} at the parameter values {\bf UParam}
 and {\bf VParam} in the direction {\bf Direction}. Example:

@\begin{verbatim}
    Tang = STANGENT( Srf, ROW, 0.5, 0.6 );
@\end{verbatim}

 computes the tangent to {\bf Srf} in the ROW direction at the parameter
 values (0.5, 0.6).
$

@\subsubsection{SURFREV}
!SURFREV

@\begin{verbatim}
 PolygonType SURFREV( PolygonType Object )

 or

 SurfaceType SURFREV( CurveType Object )
@\end{verbatim}

   Create a surface of revolution by rotating the first polygon/curve of the
 given {\bf Object}, around the Z axes. No limitation exists on the polygon
 (can be non-convex), aside from the requirement for it to be non coplanar
 with a plane of the form Z = Const. No limitation exists for the curve. Use
 the linear transformation function to position a surface of revolution in a
 different orientation. Example:

@\begin{verbatim}
    VTailAntn = SURFREV( ctlpt( E3, 0.001, 0.0, 1.0 ) +
                         ctlpt( E3, 0.01,  0.0, 1.0 ) +
                         ctlpt( E3, 0.01,  0.0, 0.8 ) +
                         ctlpt( E3, 0.03,  0.0, 0.7 ) +
                         ctlpt( E3, 0.03,  0.0, 0.3 ) +
                         ctlpt( E3, 0.001, 0.0, 0.0 ) );
@\end{verbatim}

 constructs a piecewise linear Bspline curve in the XZ plane and use it to
 construct a surface of revolution by rotating it around the Z axis.
$

@\subsubsection{SWEEPSRF}
!SWEEPSRF

@\begin{verbatim}
 SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
                                                         NumericType Scale )

 or

 SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
                                                         CurveType ScaleCrv )
@\end{verbatim}

   Construct a generalized cylinder surface. This function sweeps a specified
 cross section {\bf CrossSection} along the provided {\bf Axis}.
 The cross section may be constantly scaled (first form above), or scaled
 along the Axis parametric domain (second form).

   No refinement is performed on any of the curves so scaling and axis
 following result is only approximated. Refinement at the proper location
 should improve the output accuracy. {\bf ScaleCrv} parametric domain do not
 have to match the {\bf Axis} parametric domain and their domains are made
 compatible by this function.
 Example:

@\begin{verbatim}
    Cross = arc( vector( 0.2, 0.0, 0.0 ),
                 vector( 0.2, 0.2, 0.0 ),
                 vector( 0.0, 0.2, 0.0 ) ) +
            arc( vector( 0.0, 0.4, 0.0 ),
                 vector( 0.1, 0.4, 0.0 ),
                 vector( 0.1, 0.5, 0.0 ) ) +
            arc( vector( 0.8, 0.5, 0.0 ),
                 vector( 0.8, 0.3, 0.0 ),
                 vector( 1.0, 0.3, 0.0 ) ) +
            arc( vector( 1.0, 0.1, 0.0 ),
                 vector( 0.9, 0.1, 0.0 ),
                 vector( 0.9, 0.0, 0.0 ) ) +
            ctlpt( E2, 0.2, 0.0 );
    Axis = arc( vector( -1.0, 0.0, 0.0 ),
                vector(  0.0, 0.0, 0.1 ),
                vector(  1.0, 0.0, 0.0 ) );
    Axis = crefine( Arc1, FALSE, list( 0.25, 0.5, 0.75 ) );
    ScaleCrv = cbezier( list( ctlpt( E2, 0.0, 0.01 ),
                              ctlpt( E2, 1.0, 0.5 ),
                              ctlpt( E2, 2.0, 0.01 ) ) );
    Srf = SWEEPSRF( Cross, Axis, ScaleCrv );
@\end{verbatim}

 constructs a rounded rectangle cross section and sweep it along an arc while
 scaling it so its end points shrink. Note the axis curve {\bf Axis} is
 manually refined to better approximate the scaling required.
$

@\subsubsection{TORUS}
!TORUS

@\begin{verbatim}
 PolygonType TORUS( VectorType Center, VectorType Normal,
                    NumericType MRadius, NumericType mRadius )
@\end{verbatim}

   Create a TORUS polygonal object, defined by {\bf Center} as TORUS center,
 {\bf Normal} as main TORUS plane normal, {\bf MRadius} as major radius, and
 {\bf mRadius} as minor.

   See RESOLUTION for accuracy of TORUS approximation as polygonal model.
   Example:

@\begin{verbatim}
    T = TORUS( vector( 0.0, 0.0, 0.0), vector( 0.0, 0.0, 1.0), 0.5, 0.2 );
@\end{verbatim}

 constructs a torus with major plane as the XY plane, major radius of 0.5,
 and minor radius of 0.2.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\subsection{Object transformation functions}
&Object transformation functions

 All the routines in this section constructs a 4 by 4 homogeneouos matrix
 representing the required transform. These matrices may be concatenated to
 achieve a more complex transforms using the matrix multiplication operator
 $*$. For example the expression
@\begin{verbatim}
    m = trans( vector( -1, 0, 0 ) ) * rotx( 45 ) * trans( vector( 1, 0, 0 ) );
@\end{verbatim}

 constructs a transform to rotate an object around the X = 1 line, 45 degrees.
 A matrix representing the inverse transform can be computed as:
@\begin{verbatim}
    InvM = m ^ -1
@\end{verbatim}
 See also overloading the - operator.

@\subsubsection{ROTX}
!ROTX

@\begin{verbatim}
 MatrixType ROTX( NumericType Angle )
@\end{verbatim}

   Creates a rotation transformation matrix (around X) with {\bf Angle} degrees.
$

@\subsubsection{ROTY}
!ROTY

@\begin{verbatim}
 MatrixType ROTY( NumericType Angle )
@\end{verbatim}

   Creates a rotation transformation matrix (around Y) with {\bf Angle} degrees.
$

@\subsubsection{ROTZ}
!ROTZ

@\begin{verbatim}
 MatrixType ROTZ( NumericType Angle )
@\end{verbatim}

   Creates a rotation transformation matrix (around Z) with {\bf Angle} degrees.
$

@\subsubsection{SCALE}
!SCALE

@\begin{verbatim}
 MatrixType SCALE( VectorType ScaleFactors )
@\end{verbatim}

   Creates a scaling transformation matrix of {\bf ScaleFactors} scaling factors.
$

@\subsubsection{TRANS}
!TRANS

@\begin{verbatim}
 MatrixType TRANS( VectorType TransFactors )
@\end{verbatim}

   Creates a translation transformation matrix of {\bf TransFactors} translating
 amounts.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{General purpose functions}
&General purpose functions

@\subsubsection{ALIAS}
!ALIAS

@\begin{verbatim}
 ALIAS( StringType Name, StringType Value )
@\end{verbatim}

   Defines a text substitution: each occurrence of {\bf Name} will be replaced by
 the given {\bf Value}. Unlike the rest of the system, this is CASE SENSITIVE.
 It is a good practice, therefore, to defines the aliases names to be upper
 case, and rest of program including alias values in lower case. For example:

@\begin{verbatim}
    ALIAS("ED", "edit(\"file.irt\");");
@\end{verbatim}

 defines the alias "ED" to be 'edit("file.irt");'. Note the way the double
 quotes are being escaped.

   Using "ed" instead of "ED" above will cause infinite loop since "ed"
 will be expanded for ever... The aliases will be expanded until line is
 too long or 100 expansions occurred in line.

   If {\bf Name} is empty string, a list of all defined aliases is printed.

   If {\bf Name} is not empty, but {\bf Value} is, that alias is deleted. This is
 the only case you need to specify the alias {\bf Name} in LOWER case (otherwise it
 will be expanded...) - the alias {\bf Name} comparison is case insensitive.
$

@\subsubsection{ATTRIB}
!ATTRIB

@\begin{verbatim}
 ATTRIB( GeometricType Object, StringType Name, StringType Value )
@\end{verbatim}

   Provides a mechanism to add a string attribute to a geometric {\bf Object},
 with name {\bf Name} and value {\bf Value}.

   These attributes may be used to pass information to other programs about
 this object and are saved with the objects in data files. For example

@\begin{verbatim}
    ATTRIB(Glass, "rgb", "255,0,0");
@\end{verbatim}

 sets the rendered color of the {\bf Glass} object. This specific attribute
 provides a finer control on color setting than provided by the color
 command, for external programs.
$

@\subsubsection{BEEP}
!BEEP

@\begin{verbatim}
 BEEP( NumericType Frequency, NumericType Time )
@\end{verbatim}

   Generates a tone with the given {\bf Frequency} (in Hz), for the given period
 of {\bf Time} (in milliseconds). This command is system dependent and may work
 differently or not work at all on some systems.
$

@\subsubsection{CHDIR}
!CHDIR

@\begin{verbatim}
 CHDIR( StringType NewPath )
@\end{verbatim}

   Change current working directory to NewPath (if exists).
   The entry directory is recovered on exit from program.
$

@\subsubsection{CLOSED}
!CLOSED

@\begin{verbatim}
 CLOSED( NumericType Set )
@\end{verbatim}

   If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then every polygonal
 object drawn is assumed to be closed. If a polygonal model is closed every
 edge is basically drawn twice - once for each adjacent polygon. If the object
 is assumed closed, every such edge will be drawn once only. By default
 this option is TRUE.
$

@\subsubsection{COLOR}
!COLOR

@\begin{verbatim}
 COLOR( GeometricType Object, NumericType Color )
@\end{verbatim}

   Set the color of the object to one of the specified below. Note that an
 object has a default color (see IRIT.CFG file) according to his origin -
 loaded with LOAD command, PRIMITIV, or BOOLEAN operation result.
   The system internally supports colors (although you may have B\&W system)
 and the colors recognized are:
 {\bf BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, and WHITE}.

   See attrib command for more fine control on colors.
$

@\subsubsection{COMMENT}
!COMMENT

@\begin{verbatim}
 COMMENT
@\end{verbatim}

 Two types of comments are allowed:

 1. One lines comment: starts anywhere is a line at the '\#' char up to the
    end of the line.

 2. Block comment: starts by the COMMENT keyword follows by a unique
    character (anything but white space), up to the second occurrence of that
    character. This is a fast way to comment out large blocks. For example:

@\begin{verbatim}
    COMMENT $
      This is a comment
    $
@\end{verbatim}
$

@\subsubsection{DIR}
!DIR

@\begin{verbatim}
 DIR( StringType MatchPattern )
@\end{verbatim}

   Print the files match the MatchPattern in the current working directory.
   MatchPattern may have wild characters as in regular dos DIR - '*', '?'.

   This command is only supported under the MSDOS implementation. Example:

@\begin{verbatim}
    DIR( "*.irt" );
@\end{verbatim}

 lists all the '.irt' files in the current directory.
$

@\subsubsection{EDIT}
!EDIT

@\begin{verbatim}
 EDIT( StringType FileName )
@\end{verbatim}

   Invoke the editor (defined in the IRIT.CFG configuration file) as a child
 process if the solid modeler. Only one parameter is passed to the editor
 which is the FileName to edit. As the solid modeler is still resident, the
 child process (the editor) will get only the remained memory - as seen by
 the core left.

   This command is only supported under the MSDOS implementation.
$

@\subsubsection{EXIT}
!EXIT

@\begin{verbatim}
 EXIT();
@\end{verbatim}

   Exits from the solid modeler. NO warning is given!
$

@\subsubsection{FOR}
!FOR

@\begin{verbatim}
 FOR( NumericType Start, NumericType Increment, NumericType End, AnyType Body )
@\end{verbatim}

   Execute the {\bf Body} (see below), while the FOR loop conditions hold.
   {\bf Start, Increment, End} are evaluated first and the loop will be executed
 while {\bf $<=$ End} if {\bf Increment $>$ 0} or while {\bf $>=$ End} if {\bf Increment $<$ 0}.
   If {\bf Start} is of the form "(Variable = Expression)" then that variable is
 updated on each iteration, and can be used within the body.
   The body may consist of any number of regular commands, separated by
 COLONs, including nesting FOR loops to arbitrary level.
   No new variables should be introduced in loops - Use only old
 variables and/or the iteration variable defined in {\bf Start} (that makes it
 a feature now...). Example:

@\begin{verbatim}
    FOR ( (b = 100), 100, 300,
        FOR ( (a = 100), 100, 2000,
                (
                  beep(a, b)
                )
            )
        );
@\end{verbatim}

 exercises the BEEP function in different durations and different frequencies.
 This will best work under MSDOS systems.
$

@\subsubsection{FREE}
!FREE

@\begin{verbatim}
 FREE( GeometricType Object )
@\end{verbatim}

   Because of the usually huge size of geometric objects, this procedure
 may be used to free them. Note however that reassigning a value (even
 of different type) will automatically release old allocated space as well.
$

@\subsubsection{HELP}
!HELP

@\begin{verbatim}
 HELP( StringType Subject )
@\end{verbatim}

   Provides help on the specified Subject. Example:

@\begin{verbatim}
    HELP("");
@\end{verbatim}

 will list all {\em IRIT} commands.
$

@\subsubsection{IF}
!IF

@\begin{verbatim}
 IF( NumericType Left, StringType Cond, NumericType Right, AnyType Body )
@\end{verbatim}

   Executes {\bf Body} (group of regular commands, separated by COLONs - see FOR)
 if the condition holds: {\bf Left} and {\bf Right} are evaluated and tested against
 the specified condition {\bf Cond} which may be: "$=$", "$>$", "$<$", "$<>$", "$>=$", "$<=$".
   Example:

@\begin{verbatim}
    resolution = 10;
    IF ( machine, "=", msdos, ( resolution = 5 ) );
@\end{verbatim}

 sets the resolution to be 10 unless running on an MSDOS system in which the
 resolution variable will be set to 5.
$

@\subsubsection{INCLUDE}
!INCLUDE

@\begin{verbatim}
 INCLUDE( StringType FileName )
@\end{verbatim}

   Executes the script file {\bf FileName}. Nesting of include file is allowed up
 to 10 levels deep. If error occurs, all open files in all nested files
 are closed and data is expected at the top level (standard input).

   A script file can contain any command the solid modeler supports. Example:

@\begin{verbatim}
    INCLUDE( "general.irt" );
@\end{verbatim}

 includes the file "general.irt".
$

@\subsubsection{INTERACT}
!INTERACT

@\begin{verbatim}
 INTERACT( GeometryTreeType Object, NumericType UpdateViewMat )
@\end{verbatim}

   Invoke interactive mode to manipulate (transform) the given (geometric)
 {\bf Object}. {\bf Object} may be any GeometricType or a list of other
 GeometryTypes nested to an arbitrary level. {\bf Object} is displayed as
 a wire frame. ON SGI 4D systems a rendered display is also available.

   If {\bf UpdateViewMat} is non zero (see TRUE/FALSE and ON/OFF) then the
 global viewing matrix VIEW\_MAT is updated to the last view from INTERACT.

   INTERACT open an interactive menu to rotate/translate/scale an object(s).
 Each transformation has zero influence in middle of its box, and maximum
 (and opposite) on the box left and right ends.

   Screen transformation transforms according to the screen - X is horizontal,
 Y vertical, Z into screen. Object transformation transform in object own
 coordinate system - you probably want to display AXES object with it (see
 AXES).

   Left mouse button (return) is used to EXECUTE transformation. Right mouse
 button (space bar) is used to ABORT long display in the middle.

   On MSDOS, use the numeric keyboard pad (with/without shift) to move if no
 mouse available.

   If {\bf Object} is a GeometricType, that object is being displayed. If
 however it is an ListType the list is recursively traversed and all
 geometric objects within the list are displayed. Non geometric object in
 the list are ignored.

@\begin{verbatim}
 INTERACT( list( Axes, Obj ), FALSE );
@\end{verbatim}

 displays and interact with the object {\bf Obj} and the predefined object
 {\bf Axes}. VIEW\_MAT will not be updated once INTERACT is done.
$

@\subsubsection{LIST}
!LIST

@\begin{verbatim}
 ListType LIST( AnyType Elem1, AnyType Elem2, ... )
@\end{verbatim}

   Constructs an object as a list of several other objects. Only a reference
 is made to the Elements, so modifying Elem1 after being included in list,
 will affect Elem1 in that list, next time list is used!

   Each inclusion of an object in a list increases its internal {\bf used}
 reference. The object is freed iff in {\bf used} reference is zero.
   As a result, attempt to delete a variable (using FREE) which is referenced
 in a list will remove the variable, but the object itself will be freed only
 when that list will be freed.
$

@\subsubsection{LOAD}
!LOAD

@\begin{verbatim}
 AnyType LOAD( StringType FileName )
@\end{verbatim}

   Load the object from the given {\bf FileName}. The object may be any object
 defined in the system, including lists, in which the structure is
 loaded recursively and reconstructed as well (internal objects are
 inserted into the global system object list if have names defined).
   If no file type is provided, ".dat" is assumed.
$

@\subsubsection{LOGFILE}
!LOGFILE

@\begin{verbatim}
 LOGFILE( NumericType Set )
@\end{verbatim}

   If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then everything printed in
 the input window, will go to the log file specified in IRIT.CFG configuration
 file. This file will be created the first time logfile is turned ON.
$

@\subsubsection{NORMAL}
!NORMAL

@\begin{verbatim}
 NORMAL( NumericType Set, NumericType Size, NumericType Color )
@\end{verbatim}

   If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then the normals to the
 objects are also displayed. Normals should always point INTO the object.

   {\bf Size} sets the length of the normals, and {\bf Color} their color.
 See COLOR command for legal colors.
$

@\subsubsection{NTH}
!NTH

@\begin{verbatim}
 AnyType NTH( ListType ListObject, NumericType Index )
@\end{verbatim}

 Returns the {\bf Index} (base count 1) element of the list {\bf ListObject}.
 Example:

@\begin{verbatim}
    Lst = list( a, list( b, c ), d );
    Lst2 = NTH( Lst, 2 );
@\end{verbatim}

 and now {\bf Lst2} is equal to 'list( b, c )'.
$

@\subsubsection{PAUSE}
!PAUSE

@\begin{verbatim}
 PAUSE( NumericType Flush )
@\end{verbatim}

   Waits for a keystroke. Nice to have if temporary stopping in middle of
 included file (see INCLUDE) is needed. If {\bf Flush} is TRUE then the input
 is first flushed to guarantee we will wait.

   The implementation of this function is machine dependent and is geared
 mainly for MSDOS.
$

@\subsubsection{SAVE}
!SAVE

@\begin{verbatim}
 SAVE( StringType FileName, AnyType Object )
@\end{verbatim}

   Saves the provided {\bf Object} into specified file {\bf FileName}. No extension type
 is needed (ignored if specified), and ".dat" is always used. {\bf Object} can
 be any object type including list, in which structure is saved recursively.
 See also LOAD.
$

@\subsubsection{SNOC}
!SNOC

@\begin{verbatim}
 SNOC( AnyType Object, ListType ListObject )
@\end{verbatim}

   Similar to the lisp cons operator but puts the new {\bf Object} in the {\em end}
 of the list {\bf ListObject} instead of the beginning, in place. Example:

@\begin{verbatim}
    Lst = list( axes );
    SNOC( Srf, Lst );
@\end{verbatim}

 and now {\bf Lst} is equal to the list 'list( axes, Srf )'.
$

@\subsubsection{SYSTEM}
!SYSTEM

@\begin{verbatim}
 SYSTEM()
@\end{verbatim}

   Invoke the current command processor (usually COMMAND.COM) as defined by
 the COMSPEC environment variable. As the solid modeler is still resident,
 the child process (the command processor) will get only the remained memory
 - as seen by the core left.

   This command is only supported under the MSDOS implementation.
$

@\subsubsection{TIME}
!TIME

@\begin{verbatim}
 TIME( NumericType Reset )
@\end{verbatim}

   Returns the real time (in seconds) from the last time TIME was called with
 {\bf Reset} TRUE. Note this is real time and not cpu time so running in a multi
 tasked system will return values, which not necessarily reflects this program
 execution time. As mentioned above if {\bf Reset} is non zero the time count is
 reset. The time is automatically reset to beginning of execution of this
 program, when the program is first invoked.

   Since this is real type, it may be unusable for multitasked systems.
 Example:

@\begin{verbatim}
    Time1 = TIME( TRUE );
      .
      .
      .
    Time1 = TIME( FALSE );
    DumpLvl = 1;
    Time1;
@\end{verbatim}

 prints the time in seconds between the above two time function calls.
$

@\subsubsection{VARLIST}
!VARLIST

@\begin{verbatim}
 VARLIST()
@\end{verbatim}

   List all the currently defined objects in the system.
$

@\subsubsection{VECTOR}
!VECTOR

@\begin{verbatim}
 VectorType VECTOR( NumericType Operand1, NumericType Operand2,
                                                       NumericType Operand3 )
@\end{verbatim}

   Creates a vector type object, out of 3 NumericType scalars.
$

@\subsubsection{VIEW}
!VIEW

@\begin{verbatim}
 VIEW( GeometricTreeType Object, NumericType ClearWindow )
@\end{verbatim}

   Display the (geometric) object(s) as given in {\bf Object}. See INTERACT
 for more on {\bf Object}.

   If {\bf ClearWindow} is non zero (see TRUE/FALSE and ON/OFF) the window is
 first cleared (before drawing the objects).

   The global viewing matrix VIEW\_MAT is used as the transformation matrix.
   Example:

@\begin{verbatim}
    VIEW( Axes, FALSE );
@\end{verbatim}

 displays the predefined object {\bf Axes} in the viewing window on top of
 what was drawn there.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{System variables}
&System variables

 System variables are predefined objects in the system. Any time {\em IRIT} is
 executed, these variable will exist and be set to values which are sometimes
 machine dependent. These are {\em regular} objects in any other sense
 including the ability to delete or overwrite them. One can modify, delete
 or introduce other objects by the use of the IRITINIT.IRT file.

@\subsubsection{AXES}
!AXES
   Predefined polyline object (PolylineType) that holds XYZ axes system. May be
 viewed.
$

@\subsubsection{DRAWCTLPT}
!DRAWCTLPT
   Predefined Boolean variable (NumericType) controlling whether curves control
 polygons and surfaces control meshes will be drawn (TRUE) or not (FALSE).
$

@\subsubsection{DUMPLVL}
!DUMPLVL
   Content of objects assigned to variables may be displayed by executing the
 command 'objname;' where objname is the name of the object. This variable
 (NumericType) control the way the data is dumped as follows:

# 20 2 1 1
 DumpLvl $>=$ 0
  Only object names/types are printed.
 DumpLvl $>=$ 1
  Non geometric object values are dumped.
 DumpLvl $>=$ 2
  Curves and Surfaces are dumped.
 DumpLvl $>=$ 3
  Polygons/lines are dumped.
 DumpLvl $>=$ 4
  List objects are traversed recursively.
#
$

@\subsubsection{ECHOSRC}
!ECHOSRC
   Predefined Boolean variable (NumericType) controlling echoing of
 interpreted commands to screen (TRUE) or not (FALSE).
$

@\subsubsection{FLAT4PLY}
!FLAT4PLY
   Predefined Boolean object (NumericType) controlling the way almost flat
 surface patches are converted to polygons: four polygons (TRUE) or only
 two polygons (FALSE).
$

@\subsubsection{INTERCRV}
!INTERCRV
   Predefined numeric object (NumericType) that if TRUE the Boolean geometry
 operators return the intersection curves instead of the result model.

   Its default value is FALSE.
$

@\subsubsection{INTERNAL}
!INTERNAL
   Predefined Boolean object (NumericType) that if not zero enables displaying
 internal polygon edges (edges created by the convex polygon splitting for
 example). One usually does not want to see these edges, and its default
 value is FALSE.
$

@\subsubsection{MACHINE}
!MACHINE
   Predefined numeric object (NumericType) holding machine type as one of the
 following constants: MSDOS, SGI, HP, SUN, APOLLO, UNIX.
$

@\subsubsection{RESOLUTION}
!RESOLUTION
   Predefined numeric object (NumericType) that sets the accuracy of the
 primitive geometric objects generated. Holds the number of divisions a
 circle is divided into (with minimum value of 4). If, for example, is set
 to 6, then a CONE generated, will effectively be 6 sided pyramid.

   Also controls the fineness freeform curves and surfaces are approximated
 as piecewise linear polylines (for display purposes for example), and the
 fineness freeform surfaces are approximated as polygons.
$

@\subsubsection{VIEW\_MAT}
!VIEW_MAT
   Predefined matrix object (MatrixType) to hold the viewing matrix used/set
 by VIEW and/or INTERACT.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{System constants}
&System constants

 The following constants are used by the various functions of the system to
 signal certain conditions. Internally, they are represented numerically
 although, in general, their exact value is unimportant and may be changed
 in future versions. In the rare situation you would like to know their
 values, here is a sequence that will allow you to do so:

@\begin{verbatim}
    DumpLvl = 1;
    A = BLUE;
    A;
@\end{verbatim}

 in other words, assign the constant to a variable and display its content.

@\subsubsection{APOLLO}
!APOLLO
 A constant designates an APOLLO system in the MACHINE variable.
$

@\subsubsection{BLACK}
!BLACK
 A constant defining a BLACK color.
$

@\subsubsection{BLUE}
!BLUE
 A constant defining a BLUE color.
$

@\subsubsection{COL}
!COL
 A constant defining the COLumn direction of a surface mesh.
$

@\subsubsection{CYAN}
!CYAN
 A constant defining a CYAN color.
$

@\subsubsection{E2}
!E2
 A constant defining an E2 (X and Y coordinates) control point type.
$

@\subsubsection{E3}
!E3
 A constant defining an E3 (X, Y, and Z coordinates) control point type.
$

@\subsubsection{FALSE}
!FALSE
 A zero constant. May be used as Boolean operand.
$

@\subsubsection{GREEN}
!GREEN
 A constant defining a GREEN color.
$

@\subsubsection{HP}
!HP
 A constant designates an HP system in the MACHINE variable.
$

@\subsubsection{KV\_FLOAT}
!KV_FLOAT
 A constant defining a floating end condition uniform knot vector.
$

@\subsubsection{KV\_OPEN}
!KV_OPEN
 A constant defining an open end condition uniform knot vector.
$

@\subsubsection{MAGENTA}
!MAGENTA
 A constant defining a MAGENTA color.
$

@\subsubsection{MSDOS}
!MSDOS
 A constant designates an MSDOS system in the MACHINE variable.
$

@\subsubsection{OFF}
!OFF
 Synonym of FALSE.
$

@\subsubsection{ON}
!ON
 Synonym for TRUE.
$

@\subsubsection{P2}
!P2
 A constant defining an P2 (X, Y, and W coordinates) rational control point
 type.
$

@\subsubsection{P3}
!P3
 A constant defining an P3 (X, Y, Z, and W coordinates) rational control
 point type.
$

@\subsubsection{PI}
!PI
 The constant of 3.141592...
$

@\subsubsection{RED}
!RED
 A constant defining a RED color.
$

@\subsubsection{ROW}
!ROW
  A constant defining the ROW direction of a surface mesh.
$

@\subsubsection{SGI}
!SGI
 A constant designates a SGI system in the MACHINE variable.
$

@\subsubsection{SUN}
!SUN
 A constant designates a SUN system in the MACHINE variable.
$

@\subsubsection{TRUE}
!TRUE
 A non zero constant. May be used as Boolean operand.
$

@\subsubsection{UNIX}
!UNIX
 A constant designates a generic UNIX system in the MACHINE variable.
$

@\subsubsection{WHITE}
!WHITE
 A constant defining a WHITE color.
$

@\subsubsection{YELLOW}
!YELLOW
 A constant defining a YELLOW color.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\section{poly3d - A Data Display Program}
!poly3d - A Data Display Program

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\subsection{Introduction}
&Introduction

 poly3d is a display program for data files created by the {\em IRIT} solid
 modeler. Data can be displayed on almost any IBMPC graphic device that has
 Borland's BGI support, for the MSDOS BC++ port, or using any device driver
 that is supported by DJGPP, in the MSDOS DJGPP port.
   Under UNIX systems both MIT's X11 and SGI's GL are supported.

   On SGI's, solid smooth shading is available via normal computation
 support. Displayed images may be saved as postscript files as well as GIF
 images (if poly3d was built with GIF support).

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
 poly3d [-c] [-m] [-i] [-e #Edges] [-n] [-N] [-M] [-I n] [-P] [-S n]
                                                [-f FineNess] [-4] [-z] DFiles
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -c}: Closed object - if an object is closed (such as objects created by
       {\em IRIT} solid medeller) each edge is actually displayed twice - once
       for each adjacent polygon. This flag will ensure every edge will be
       displayed only once.
@\item
  {\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
  {\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
       this option will force displaying them as well.
@\item
  {\bf -e n}: \# Edges to use from each given polygon (default all). Very handy to
       do '-e 2 -4-' or '-e 1 -4' on polygons created from a freeform surface.
@\item
  {\bf -n}: Draw vertex normals if data file has them.
@\item
  {\bf -N}: Draw polygon normals if data file has them (PLANE definition).
@\item
  {\bf -M}: Draw the surfaces control mesh/curves control polygons as well.
@\item
  {\bf -I n}: Specify number of isolines per surface.
@\item
  {\bf -P}: Generate polygonal approximation for surfaces instead of isolines.
@\item
  {\bf -S n}: Specify the log based 2 of number of samples per curve.
@\item
  {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
       This number is log based 2 of roughly the number of subdivisions of
       the surface in each axes (see cagd\_lib for more).
@\item
  {\bf -4}: Force four polygons per flat bilinear in surface to polygon
       conversion. Otherwise two polygons only.
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

   Some of the options may be turned on in poly3d.cfg. They can be then turned
 off in the command line as -?-.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration

   The program can be configured using a configuration file named poly3d.cfg.
   The appropriate configuration file should be copied into poly3d.cfg:
   Under MSDOS BC++ its poly3dms.cfg, under MSDOS DJGPP its poly3ddj.cfg, and
 under UNIX its poly3dun.cfg.
   This is a plain ascii file you can edit directly and set the parameters
 according to the comments there. Executing 'poly3d -z' will show the
 current configuration as read from the configuration file.

   MSDOS version only:

   The configuration file in MSDOS BC++ system can be in any directory which
 is in your path - the same place as the executable is probably a good choice.
   The program supports SuperVGA, VGA/EGA, CGA \& HERCULES graphics card, and
 uses the Turbo C autodetect feature. If this fails you can always coerce it
 to a specific card - see the poly3d.cfg file. For a SuperVGA you will need to
 provide your own BGI driver.
   The program will use 80x87 if it detects one - again uses the Turbo C 80x87
 autodetect, or will run (much!) slower without it...
   The MSDOS DJGPP port can be used with any graphics driver that DJGPP
 support. If not 80x87 is present, the emulator, emu387, must be used.
   In both the BC++ and DJGPP ports, a mouse or a joystick may be used
 if properly selected in poly3d.cfg configuration file.
   A windowing library, called intr\_lib is used (for both BC++ and DJGPP)
 for the interaction and windows which can be resized/moved/poped/pushed etc.
 via a default setting as selected by the configuration file and modified via
 a pop up menu during a session. see Irit solid modeler for more on intr\_lib
 and the interface.

   UNIX version only:

   The configuration file is being searched in the IRIT\_PATH environment
 variable under UNIX hosts. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
   Note IRIT\_PATH must terminate with '/'. If the variables is not set only
 the current directory is being searched.
   Add the following options to your {\em .Xdefaults} if you use X11. Most options
 set are self explanatory. The Trans attributes control the transformation
 window, while View control the view window. SubWin control the subwindows
 within the Transformation window:
# 33 2 0 1
 poly3d*Trans*BackGround:
  NavyBlue
 poly3d*Trans*BorderColor:
  Red
 poly3d*Trans*BorderWidth:
  3
 poly3d*Trans*TextColor:
  Yellow
 poly3d*Trans*SubWin*BackGround:
  DarkGreen
 poly3d*Trans*SubWin*BorderColor:
  Magenta
 poly3d*Trans*Geometry:
  =150x500+500+0
 poly3d*Trans*CursorColor:
  Green
 poly3d*View*BackGround:
  NavyBlue
 poly3d*View*BorderColor:
  Red
 poly3d*View*BorderWidth:
  3
 poly3d*View*Geometry:
  =500x500+0+0
 poly3d*View*CursorColor:
  Red
#
   Note the above options are the same as for the irit solid modeler
 itself.

   If poly3d is used under SGI gl library, you can set the prefered windows
 location in poly3d.cfg. No color control is provided at this time.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

   The program is controlled via a transformation menu. The object can be
 rotated, translated, or scaled in screen or object based corrdinate system
 and with orthographic or perspective projected.

  Two operations are fundamental to the operation of poly3d:

# 10 2 0 1
 EXECUTE
  $<$Return$>$ key on the keyboard, or left  mouse button if exists.
 ABORT
  $<$Space$>$  key on the keyboard, or right mouse button if exists.
#

   The cursor may be moved via a mouse (if exists) or using the numeric
 keypad/arrows (shifted for faster movement).
   The ABORT may be useful in large data sets when another
 transformation should be applied with no need to wait to the current one to
 complete.

   The menus work in two modes in all implementations. If you click the
 EXECUTE button once on a transformation subwindow, that transformation
 will be applied. Most transformation subwindows have vertical bars in
 the middle. If the cursor is on the vertical bar the {\em amout} of
 transformation applied is {\em zero}. If the cursor is on the leftmost side
 of the subwindow, the {\em amount} will be maximized and if the cursor is on
 the rightmost side, the transformation {\em amount} will be maximized to the
 other direction (inverse transform).
   In addition, if one clicks the mouse (with the affect as above) but hold
 the EXECUTE button while dragging, continuous transformation will be applied.
 Altough implemented in all systems, you would probably like to try this on
 very simplistic models on slow machines.

   Keyboard control support is for MSDOS systems only.

@\subsection{Output Files}
&Output Files

   poly3d can save viewing matrices (to be used by poly3d-h, poly3d-r, or
 irit2ray for example), postscript files of the current view and GIF images
 of the screen if poly3d was built with GIF support.

   The postscript file can be directly sent to a laser printer. The viewing
 matrix should be appended {\em after} the data when any program is to use
 it. The last viewing matrix in the data will be the one used. For example

@\begin{verbatim}
 irit2ray -l -f 20 b58.dat generic0.mat
@\end{verbatim}

 where generic0.mat is the matrix saved bu poly3d.

   All files will be named genericX.EXT where EXT can be one of '.mat', '.ps'
 and '.gif' respectively. X is single digit so up to 10 distinguished files
 of each type can be saved each time.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\section{poly3d-h - Hidden Line Removing Program}
!poly3d-h - Hidden Line Removing Program

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;


@\subsection{Introduction}
&Introduction

    poly3d-h is a program to remove hidden line of a given polygonal model.
 Freeform objects are preprocessed into polygons with controlled fineness.

    The program performes 4 passes over the input:

 1. Preprocesses and maps all polgons in scene, and sorts them.

 2. Generates edges out of the polygonal model and sorts them (preprocesing
    for the scan line algorithm) into buckets.

 3. Intersects edges, and splits edges with non homogeneous visibility (the
    scan line algorithm)

 4. Applies a visibility test of each edge.

        This programs can handle CONVEX polygons only. From {\em IRIT} one can
 ensure a model is consisting of convex polygons only by the CONVEX command:
@\begin{verbatim}
  CnvxObj = convex( Obj );
@\end{verbatim}
 just before saving it into a file. Surfaces are always decomposed into
 triangles only.

    poly3d-h output is of the form of polylines. It is a regular {\em IRIT} data
 file that can be viewed using poly3d, for example.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
 poly3d-h [-b] [-m] [-i] [-e #Edges] [-f FineNess] [-4] [-z] DFiles [> OutFile]
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -b}: BackFacing - if object is closed (such as most models created by {\em IRIT})
       back facing polygons will be deleted, and therefore speed up the
       process by at list factor of two.
@\item
  {\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
  {\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
       this option will force displaying them as well.
@\item
  {\bf -e n}: \# Edges to use from each given polygon (default all). Very handy
       as '-e 1 -4' for freeform data.
@\item
  {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
       This number is log based 2 of roughly the number of subdivisions of
       the surface in each axes (see cagd\_lib for more).
@\item
  {\bf -4}: Force four polygons per flat bilinear in surface to polygon
       conversion. Otherwise two polygons only.
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

   Some of the options may be turned on in poly3d-h.cfg. They can be then
 turned off in the command line as -?-.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration

   The program can be configured using a configuration file named poly3d-h.cfg.
   This is a plain ascii file you can edit directly and set the parameters
 according to the comments there. executing 'poly3d-h -z' will show the
 current configuration as read from the configuration file.

   UNIX and MSDOS DJGPP versions only:

   The configuration file is being searched in the IRIT\_PATH environment
 variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
   Note IRIT\_PATH must terminate with '/'. If the variables is not set only
 the current directory is being searched.

   MSDOS BC++ version only:

   The configuration file in MSDOS system can be in any directory which is in
 your path - the same place as the executable is probably a good choice.
   The program will use 80x87 if it detects one - uses the Turbo C 80x87
 autodetect, or will run (much!) slower without it...

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

   As this program is not interactive, usage is quite simple, and only
 control available is using the command lines options.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\section{poly3d-r - A Simple Data Rendering Program}
!poly3d-r - A Simple Data Rendering Program

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;

@\subsection{Introduction}
&Introduction

 poly3d-r is a simple rendering program for data files created by the {\em IRIT}
 solid modeler. poly3d-r generates GIF images with 8 bits per pixel. As a result
 rendered images are of medium quality. Although reasonably fast, one should
 use one of several raytracing public domain programs available (such as
 RAYSHADE which irit2ray can generate data to) for high quality images.

   poly3d-r uses cosine shading approximation, and flat/Gouraud interpolation.
 The program performes 4 passes over the input:

 1. Process the input (parsing.)

 2. Prepare the polygons by sorting them by their Y after mapping then into
    screen space.

 3. Evaluate colors for vertices (using polygon normals if flat shading, or
    by vertex normals for Gouraud shading).

 4. Scan the data by scan line basis and dump out image.

        This programs can handle CONVEX polygons only. From {\em IRIT} one can
 ensure a model is consisting of convex polygons only by the CONVEX command:
@\begin{verbatim}
  CnvxObj = convex( Obj );
@\end{verbatim}
 just before saving it into a file. Surfaces are always decomposed into
 triangles only.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
 poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize]
       [-S SubSample] [-g] [-b] [-M Mask] [-f FineNess] [-z] DFiles > Image.gif
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -a Ambient}: Sets the ambient intensity (must be in [0.0..1.0] range).
@\item
  {\bf -c N}: number of bits per pixel N (must be in [1..8] range).
@\item
  {\bf -l X Y Z}: specify the light source normal direction. This vector does not
     to be unit vector. Only one light source is supported.
@\item
  {\bf -2} : Force emulation of 2 light sources at opposite directions as selected
     via [-l]. This may be useful for models that has no plane specified (i.e.
     model has no PLANE attribute for its polygons), as the program guess the
     equation from the points themselves, and which can be to the opposite
     direction.
@\item
  {\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
  {\bf -s Xsize Ysize}: specify image dimensions. As the models created by {\em IRIT}
     are mapped to a unit domain (X in [-1..1], Y in [-1..1]) by the
     viewing matrix, objects must be scaled up. The scaling up factor is
     MIN(Xsize, Ysize), which guarantee nothing of the original image will be
     clipped.
@\item
  {\bf -b}: Purge back facing polygons. If the scene contains closed objects (such
     as the ones usually created by {\em IRIT}), the back facing polygons can be
     deleted. This would not change the image, but will speed up the process
     at about %15. Using this option for non complete boundary object and/or
     objects with polygons with no PLANE specified would almost definitely
     create wrong image.
@\item
  {\bf -g}: Use Gouraud shading interpolation (flat shading is used by default).
     This is somewhat slower, but gives nicer results.
@\item
  {\bf -S SubSample}: sub sample, and uses box filter to low pass filter the
     image, using SubSample as grid side of SubSample by SubSample.
     This obviously make things slower, but guess what - it looks much better.
@\item
  {\bf -M Mask}: Create a new GIF file named Mask that is a binary image set to 1
     at any pixel covered by one of the objects or 0 otherwise. As a color of
     an object can become equal to the background at some point, there is no
     way to find whether pixel is background or an object in the background
     color. The Mask can be used instead. This Mask can be used when combining
     images (such as gifcomp utility in the gif\_lib).
     This image is a binary alpha channel.
@\item
  {\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
     This number is log based 2 of roughly the number of subdivisions of
     the surface in each axes (see cagd\_lib for more).
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

   The image is dumped to stdout as a GIF image which can be redirected to a
 file or to be piped to any program that reads GIF images from stdin.

   Some of the options may be turned on in poly3d-r.cfg. They can be then
 turned off in the command line as -?-.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration

   The program can be configured using a configuration file named poly3d-r.cfg.
   This is a plain ascii file you can edit directly and set the parameters
 according to the comments there. executing 'poly3d-r -z' will show the
 current configuration as read from the configuration file.

   UNIX and MSDOS DJGPP versions only:

   The configuration file is being searched in the IRIT\_PATH environment
 variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
   Note IRIT\_PATH must terminate with '/'. If the variables is not set only
 the current directory is being searched.

   MSDOS BC++ version only:

   The configuration file in MSDOS system can be in any directory which is in
 your path - the same place as the executable is probably a good choice.
   The program will use 80x87 if it detects one - uses the Turbo C 80x87
 autodetect, or will run (much!) slower without it...

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

   As this program is not interactive, usage is quite simple, and only
 control available is using the command lines options.

   Some Remarks:

  1. If the input file is degenerate (2 vertices are identical etc.) they
     will be ignored is the next passes. Use [-m] if you want to know about
     them.

  2. The color of the object can be extract via the COLOR attribute as set
     via the {\em IRIT} COLOR command. In addition to this fixed set of colors, one
     can specify the color in RGB space using the ATTRIB command. For example:

@\begin{verbatim}
     attrib( Srf17, "rgb", "255,155,55" );
@\end{verbatim}

     Each of R G B must be integer is the range [0..255].
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Irit2Ray - IRIT To RAYSHADE filter}
!IRIT2RAY - IRIT To RAYSHADE filter

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
  irit2ray [-l] [-4] [-G GridSize] [-f FineNess] [-o OutName] [-g] [-z] DFiles
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
       as a single polygon along their linear direction.
         Although most of the time, linear direction can be exactly represented
       using a single polygon, even a bilinear surface can have a free form
       shape (saddle like) that is not representable using a single polygon.
         Not using this option will better emulate the surface shape but
       will create unnecessary polygons in cases where one is enough.
@\item
  {\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
@\item
  {\bf -G GridSize}: Usually objects are grouped as {\em lists} of polygons.
       This flags will coerce the usage of RAYSHADE {\em grid} constructure,
       with {\em GridSize} being used as the grid size along the object bounding
       box largest dimension.
@\item
  {\bf -f FineNess}: An integer value controling the fineness of surface to
       polygons process. Roughly speaking it will set to the number of polygons
       along one Bezier patch direction. A Bezier patch will have order of
       $FineNess^2$ polygons then. The Order of the surface also affect the
       amount of polygons; The higher the order is, more polygons are created.
         A B-spline surface is first converted into piecewise Bezier to make
       sure C1 discontinuities will show up in the polygonal approximation.
@\item
  {\bf -o OutName}: Name of output files. By default the name of the first data
       file from {\em DFiles} list is used.  See below on the output files.
@\item
  {\bf -g}: Generates the geometry file only. See below.
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

    Irit2Ray converts freeform surfaces into polygons in format that can
 be used by RAYSHADE. Two files are created, one with '.geom' extension and
 one with '.ray'. Since the number of polygons can be extremely large,
 the geometry is isolated in the '.geom' and is included (via '\#include') in
 the main '.ray' file. The later holds the surface properties for all the
 geometry as well as viewing and RAYSHADE specific commands. This allows
 changing shading or viewing properties while editing small ('.ray') files.

    If '-g' is specified, only the '.geom' file is created, preserving the
 current '.ray' file.

    In practice it may be useful to create a low resolution approximation
 of the model, change viewing/shading parameters in the '.ray' file until
 a good view and/or surface quality is found and then run Irit2Ray once more
 to create a high resolution approximation of the geometry using '-g'.

    Here is a simple example:

@\begin{verbatim}
 irit2ray -l -f 5 b58.dat
@\end{verbatim}

 creates b58.ray and b58.geom with low resolution (FineNess of 5).
   At such low resolution it can very well may happen that triangles will have
 normals "over the edge" since a single polygon may approximate a highly
 curves surface. That will cause rayshade to issue an
 "Inconsistant triangle normals" warning. This problem will not exist if
 high fineness is used.
   One can ray trace this scene using a command similar to:

@\begin{verbatim}
 rayshade -p -W 256 256 b58.ray > b58.rle
@\end{verbatim}

 Once done with parameter setting for rayshade, a fine approximation of the
 model can be created with:

@\begin{verbatim}
 irit2ray -l -g -f 25 b58.dat
@\end{verbatim}

 which will only recreate b58.geom (becuase of the -g option).

 Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
 matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:

@\begin{verbatim}
 save( "b58", list( view_mat, b58 ) );
@\end{verbatim}

 However one can overwrite the viewing matrix by appending a new matrix in the
 end of the command line, created by poly3d:

@\begin{verbatim}
 poly3d b58.dat
 irit2ray -l -f 5 b58.dat generic0.mat
@\end{verbatim}

 where generic0.mat is the viewing matrix created by poly3d.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Advanced Usage}
&Advanced Usage

   One can specify surface qualities for individual surfaces of a model.
 Several such attributes are supported by Irit2Ray and can be set within {\em IRIT}.
 See also the ATTRIB {\em IRIT} command.

   If a certain surface should be finer than the rest of the scene, one can
 set a "resolution" attribute which specifies the {\em relative} FineNess resolution
 of this specific surface. For example:

@\begin{verbatim}
 attrib( srf1, "resolution", 2 );
@\end{verbatim}

 will force srf1 to have twice the default resolution, as set via the '-f'
 flag.

   Almost flat patches are converted to polygons. The rectangle can be
 converted into two polygons (by subdividing along one of its diagonals) or
 into four by introducing a new point at the patch center. This behaviour is
 controlled by the '-4' flag, but can be overwritten for individual surfaces
 bu setting "twoperflat" or "fourperflat".

   RAYSHADE specific properties are controlled via the following attributes:
 "specpow", "reflect", "transp", "body", "index", and "texture". Refer to
 RAYSHADE manual for their meaning. For example:

@\begin{verbatim}
 attrib( srf1, "transp", "0.3" );
 attrib( srf1, "texture", "wood" );
@\end{verbatim}

   Surface color is controlled in two levels. If the object has an RGB
 attribute it is used. Otherwise a color as set via {\em IRIT} COLOR command
 is being used if set. The later allowes you to specify only the 3 additive,
 3 substractive and white and black and so is very limited for rendering
 purposes. Example:

@\begin{verbatim}
 attrib( tankBody, "rgb", "244,164,96" );
@\end{verbatim}

   Current implementation allows white spaces in neither the attribute
 name nor in the attribute value.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Irit2Nff - IRIT To NFF filter}
!IRIT2NFF - IRIT To NFF filter

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
  irit2nff [-l] [-4] [-c] [-f FineNess] [-o OutName] [-g] [-z] DFiles
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
       as a single polygon along their linear direction.
         Although most of the time, linear direction can be exactly represented
       using a single polygon, even a bilinear surface can have a free form
       shape (saddle like) that is not representable using a single polygon.
         Not using this option will better emulate the surface shape but
       will create unnecessary polygons in cases where one is enough.
@\item
  {\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
@\item
  {\bf -c}: Output files should be filtered by cpp. By doing so, the usually
       huge geometry file is seperated from the main nff file that contains
       the surface properties and view parameters. By default all data,
       including the geometry, is saved into a single file with type extension
       '.nff'. Use of '-c' will pull out all the geometry into a file with
       the same name but '.geom' extension and which will be included using
       '\#include' command. The '.nff' file should, in that case, be
       preprocessed using cpp before piped into the nff renderer.
@\item
  {\bf -f FineNess}: An integer value controling the fineness of surface to
       polygons process. Roughly speaking it will set to the number of polygons
       along one Bezier patch direction. A Bezier patch will have order of
       $FineNess^2$ polygons then. The Order of the surface also affect the
       amount of polygons; The higher the order is, more polygons are created.
         A B-spline surface is first converted into piecewise Bezier to make
       sure C1 discontinuities will show up in the polygonal approximation.
@\item
  {\bf -o OutName}: Name of output files. By default the name of the first data
       file from {\em DFiles} list is used.  See below on the output files.
@\item
  {\bf -g}: Generates the geometry file only. See below.
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

    Irit2Nff converts freeform surfaces into polygons in format that can
 be used by NFF renderer. Usually one file is created with '.nff' type
 extension. Since the number of polygons can be extremely large, a '-c'
 option is provided and which separate the geometry from the surface
 properties and view specification but requires preprocessing by cpp.
 The geometry is isolated in a file with extension '.geom' and included
 (via '\#include') in the main '.nff' file. The later holds the surface
 properties for all the geometry as well as the viewing specification.
 This allows changing shading or viewing properties while editing small
 ('.nff') files.

    If '-g' is specified, only the '.geom' file is created, preserving the
 current '.nff' file. The '-g' flag can be specified only with '-c'.

    In practice it may be useful to create a low resolution approximation
 of the model, change viewing/shading parameters in the '.nff' file until
 a good view and/or surface quality is found and then run Irit2Nff once more
 to create a high resolution approximation of the geometry using '-g'.

    Here is a simple example:

@\begin{verbatim}
 irit2nff -c -l -f 5 b58.dat
@\end{verbatim}

 creates b58.nff and b58.geom with low resolution (FineNess of 5).

 Once done with parameter setting, a fine approximation of the model can
 be created with:

@\begin{verbatim}
 irit2nff -c -l -g -f 25 b58.dat
@\end{verbatim}

 which will only recreate b58.geom (becuase of the -g option).

 Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
 matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:

@\begin{verbatim}
 save( "b58", list( view_mat, b58 ) );
@\end{verbatim}

 However one can overwrite the viewing matrix by appending a new matrix in the
 end of the command line, created by poly3d:

@\begin{verbatim}
 poly3d b58.dat
 irit2nff -l -f 5 b58.dat generic0.mat
@\end{verbatim}

 where generic0.mat is the viewing matrix created by poly3d.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Advanced Usage}
&Advanced Usage

   One can specify surface qualities for individual surfaces of a model.
 Several such attributes are supported by Irit2Nff and can be set within {\em IRIT}.
 See also the ATTRIB {\em IRIT} command.

   If a certain surface should be finer than the rest of the scene, one can
 set a "resolution" attribute which specifies the {\em relative} FineNess resolution
 of this specific surface. For example:

@\begin{verbatim}
 attrib( srf1, "resolution", 2 );
@\end{verbatim}

 will force srf1 to have twice the default resolution, as set via the '-f'
 flag.

   Almost flat patches are converted to polygons. The rectangle can be
 converted into two polygons (by subdividing along one of its diagonals) or
 into four by introducing a new point at the patch center. This behaviour is
 controlled by the '-4' flag, but can be overwritten for individual surfaces
 bu setting "twoperflat" or "fourperflat".

   NFF specific properties are controlled via the following attributes:
 "kd", "ks", "shine", "trans", "index". Refer to NFF manual for detail.
 For example:

@\begin{verbatim}
 attrib( srf1, "kd", "0.3" );
 attrib( srf1, "shine", "30" );
@\end{verbatim}

   Surface color is controlled in two levels. If the object has an RGB
 attribute it is used. Otherwise a color as set via {\em IRIT} COLOR
 command is being used if set. The later allowes you to specify only the
 3 additive, 3 substractive and white and black and so is very limited for
 rendering purposes. Example:

@\begin{verbatim}
 attrib( tankBody, "rgb", "244,164,96" );
@\end{verbatim}

   Current implementation allows white spaces in neither the attribute
 name nor in the attribute value.
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Dat2Irit - Data To IRIT file filter}
!DAT2IRIT - Data To IRIT file filter

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options

@\begin{verbatim}
   dat2irit [-z] DFiles
@\end{verbatim}

@\begin{itemize}
@\item
  {\bf -z}: Print version number and current defaults.
@\end{itemize}

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage

    It may be sometimes desired to convert .dat data files into a form that
 can be fed in back to {\em IRIT} - a '.irt' file. This filter will do exactly that.
 Example:

@\begin{verbatim}
   dat2irit b58.dat > b58-new.irt
@\end{verbatim}
$

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Data File Format}
!DATAFILE Format

   This section describes the data file format used to exchange data between
 {\em IRIT} and its accompanied tools.

@\begin{verbatim}
 [OBJECT {ATTRS} OBJNAME
     [NUMBER n]

   | [VECTOR x y z]

   | [CTLPT POINT_TYPE {w} x y {z}]

   | [STRING "a string"]

   | [MATRIX m00 ... m03
             m10 ... m13
             m20 ... m23
             m30 ... m33]

     ;A polyline should be drawn from first point to last. Nothing is drawn
     ;from last to first (in close polyline last pt is equal to first).
   | [POLYLINE {ATTRS} #PTS                   ;#PTS = number of points.
         [{ATTRS} x y z]
         [{ATTRS} x y z]
            .
            .
            .
         [{ATTRS} x y z]
     ]

     ;Defines a closed region boundary. Last point is NOT equal to first
     ;and a line from last point to first should be drawn when the polygon
     ;boundary is drawn.
   | [POLYGON {ATTRS} #PTS
         [{ATTRS} x y z]
         [{ATTRS} x y z]
            .
            .
            .
         [{ATTRS} x y z]
     ]

     ;Defines a cloud of points. This entry is not supported by IRIT.
   | [POINTLIST {ATTRS} #PTS
         [{ATTRS} x y z]
         [{ATTRS} x y z]
            .
            .
            .
         [{ATTRS} x y z]
     ]

     ;Defines a bezier curve with #PTS control points. If the curve is
     ;rational, the rational component is introduced first.
   | [CURVE BEZIER {ATTRS} #PTS POINT_TYPE
         [{ATTRS} {w} x y z ...]
         [{ATTRS} {w} x y z ...]
            .
            .
            .
         [{ATTRS} {w} x y z ...]
     ]

     ;Defines a bezier surface with #UPTS * #VPTS control points. If the
     ;surface is rational, the rational component is introduced first.
     ;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
   | [SURFACE BEZIER {ATTRS} #UPTS #VPTS POINT_TYPE
         [{ATTRS} {w} x y z ...]
         [{ATTRS} {w} x y z ...]
            .
            .
            .
         [{ATTRS} {w} x y z ...]
     ]

     ;Defines a BSPLINE curve of order ORDER with #PTS control points. If the
     ;curve is rational, the rational component is introduced first.
     ;Note length of knot vector is equal to #PTS + ORDER.
   | [CURVE BSPLINE {ATTRS} #PTS ORDER POINT_TYPE
         [KV {ATTRS} kv0 kv1 kv2 ...]                    ;Knot vector
         [{ATTRS} {w} x y z ...]
         [{ATTRS} {w} x y z ...]
            .
            .
            .
         [{ATTRS} {w} x y z ...]
     ]

     ;Defines a BSPLINE surface with #UPTS * #VPTS control points, of order
     ;UORDER by VORDER. If the surface is rational, the rational component
     ;is introduced first.
     ;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
   | [SURFACE BSPLINE {ATTRS} #UPTS #VPTS UORDER VORDER POINT_TYPE
         [KV {ATTRS} kv0 kv1 kv2 ...]                ;U Knot vector
         [KV {ATTRS} kv0 kv1 kv2 ...]                ;V Knot vector
         [{ATTRS} {w} x y z ...]
         [{ATTRS} {w} x y z ...]
            .
            .
            .
         [{ATTRS} {w} x y z ...]
     ]
 ]

 POINT_TYPE -> E2 | E3 | P2 | P3

 ATTRS -> [ATTRNAME ATTRVALUE]
          | [ATTRNAME ATTRVALUE] ATTRS

@\end{verbatim}

 Some notes:

 1. This new definition for the text file is design to minimize the
    reading time and space. All information can be read without backward
    or forward referencing (as used to be in the old format).

 2. An OBJECT can hold any number of geometry entities such as POLYGONs or
    CURVEs. It is not recommended at this time to have more than one curve
    or one surface in an object since this feature is not fully implemented
    for free form objects.

 3. An OBJECT must not hold different geometry or other entities.
    I.e. CURVEs, SURFACEs, and POLYGONs must all be in different OBJECTs.

 4. Attributes should be ignored if not needed. The attribute list may have
    any length and is always terminated by a token that is NOT '\verb+[+'. This
    simplified and disambiguous the parsing.

 5. Comments may appear between '\verb+[+OBJECT ...\verb+]+' blocks, or immediatelly after
    OBJECT OBJNAME, and only there.

    A comment body can be anything not containing the '\verb+[+' or the '\verb+]+' tokens
    (signals start/end of block). Some of the comments in the above definition
    are {\em illegal} and appear there only of the sake of clarity.

 6. It is prefered that geometric attributes such as NORNALs will be saved in
    the geometry strurcture level (POLYGON, CURVE or vertices) while graphical
    and others such as COLORs will be saved in the OBJECT level.

 7. Objects may be contained in other objects to any level.

 Here is an example that exercises most of the data format:

@\begin{verbatim}
 This is a legal comment in a data file.
 [OBJECT DEMO
     [OBJECT REAL_NUM
         And this is also a legal comment.
         [NUMBER 4]
     ]

     [OBJECT A_VECTOR
         [VECTOR 1 2 3]
     ]

     [OBJECT CTL_POINT
         [CTLPT E3 1 2 3]
     ]

     [OBJECT STR_OBJ
         [STRING "string"]
     ]

     [OBJECT UNIT_MAT
         [MATRIX
            1 0 0 0
            0 1 0 0
            0 0 1 0
            0 0 0 1
         ]
     ]

     [OBJECT [COLOR 4] POLY1OBJ
         [POLYGON [PLANE 1 0 0 0.5] 4
             [-0.5 0.5 0.5]
             [-0.5 -0.5 0.5]
             [-0.5 -0.5 -0.5]
             [-0.5 0.5 -0.5]
         ]
         [POLYGON [PLANE 0 -1 0 0.5] 4
             [0.5 0.5 0.5]
             [-0.5 0.5 0.5]
             [-0.5 0.5 -0.5]
             [0.5 0.5 -0.5]
         ]
     ]

     [OBJECT [COLOR 63] ACURVE
         [CURVE BSPLINE 16 4 E2
             [KV 0 0 0 0 1 1 1 2 3 4 5 6 7 8 9 10 11 11 11 11]
             [0.874 0]
             [0.899333 0.0253333]
             [0.924667 0.0506667]
             [0.95 0.076]
             [0.95 0.76]
             [0.304 1.52]
             [0.304 1.9]
             [0.494 2.09]
             [0.722 2.242]
             [0.722 2.318]
             [0.38 2.508]
             [0.418 2.698]
             [0.57 2.812]
             [0.57 3.42]
             [0.19 3.572]
             [0 3.572]
         ]
     ]

     [OBJECT [COLOR 2] SOMESRF
         [SURFACE BEZIER 3 3 E3
             [0 0 0]
             [0.05 0.2 0.1]
             [0.1 0.05 0.2]

             [0.1 -0.2 0]
             [0.15 0.05 0.1]
             [0.2 -0.1 0.2]

             [0.2 0 0]
             [0.25 0.2 0.1]
             [0.3 0.05 0.2]
         ]
     ]
 ]
@\end{verbatim}
$

@\section{Bugs and Limitations}
!BUGS and LIMITATIONS

   Like any program of more than one line it is far from been perfect.
 Some limitations as well as simplifications are layed out below.

 1. No intersection of co-planar polygons is allowed. Such case results are
    undefined. Most of the time, one can move one of the operands
    in the Boolean operation by an EPSILON. Such EPSILON should be in the
    order of 10-3 if the system uses float and and 10-6 if doubles are used.
    (the UNIX and MSDOS DJGPP version uses doubles, MSDOS BC++ uses floats).

 2. If the intersection curve of two objects falls exactly on polygon
    boundaries, for all polygons, the system will scream that the two object
    do not intersect at all. Again, try to move one by EPSILON into the other.
    I probably should fix this one - that suppose to be relatively easy.

 3. Avoid degeneracies - intersection that results with a point or a line will
    probably cause wrong propagation of the inner and outer part of one object
    relative to the other. Always extend your object beyond the other object.

 4. If two objects have no intersection in their boundary, {\em IRIT} assumes they
    are disjoint: a union simply combines them, and the other Boolean
    operators return NULL object. One should find FAST way (3D Jordan
    theorem) to find the relation between the two (A in B, B in A, A
    disjoint B) and according to that make a decision.

 5. Sweep of a circular curve along circular curve does {\em not} create an
    exact piece of a torus. This is probably due to the fact that both curves
    are rationals.

 6. No degree raising for Bspline surfaces of order larger than two.
$

@\end{document}