% % prog_man.tex - The IRIT programmer's manual - main module. % % Author: Gershon Elber % Computer Science Dept. % Technion, IIT % %\documentstyle[10pt]{book} \documentstyle{book} \setlength{\oddsidemargin}{0.0in} \setlength{\evensidemargin}{0.0in} \setlength{\topmargin}{-0.1in} \setlength{\textwidth}{6.5in} \setlength{\textheight}{9.5in} \makeindex \begin{document} \small \setlength{\baselineskip}{0.85\baselineskip} \tableofcontents %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Introduction} This manual describes the different libraries of the IRIT solid modeling environment. Quite a few libraries can be found to manipulate geometry in general, freeform curves and surfaces, symbolic computation, trimmed surfaces, freeform trivariate functions, Boolean operations, input output data file parsing, and miscelleneous. All interface to the libraries should be made via the appropriate header files that can be found in the include subdirectory. Most libraries have a single header file that is named the same as the library. Functions and constants that are visible to the users of the libraries are prefixed with a unique prefix, usually derived from the library name itself. External definitions that start with an underscore should not be used, even if found in header files. The header file {\bf include/irit\_sm.h} must be sourced by every source file in the solid modeller. In most cases, this file is sourced indirectly via local header files. The following libraries are avaliable in IRIT: \begin{center} \begin{tabular}{|l|l|} \hline Name of Library & Tasks \\ \hline bool & Boolean operations on polygonal models. \\ cagd & Low level freeform curves and surfaces. \\ geom & General geometry functions. \\ misc & memory allocation, configuration files, attributes, etc. \\ prsr & input and output for file/sockets of objects of IRIT. \\ symb & Symbolic manipulation of curves and surfaces. \\ trim & Trimmed surfaces support. \\ triv & Freeform trivariate functions. \\ xtra & Public domain code that is not part of IRIT. \\ \hline \end{tabular} \end{center} The following chapters reference the different function of different libraries. Chapter~\ref{chap-examples} provides several examples of writing C code using the IRIT libraries. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Boolean Library, bool\_lib} \section{General Information} On of the crucial operation in any solid modeling environment is the ability to perform Boolean operations among different geometric objects. The interface of the library is defined in {\em include/bool\_lib.h}. This library supports only Boolean operations of polygonal objects. The Boolean operations of OR, AND, SUBtract, NEGate, CUT, and MERGE are supported via the {\bf BoolOperType} typedef: \begin{center} \begin{tabular}{||c|c||} \hline BoolOperType & Meaning \\ \hline BOOL\_OPER\_OR & Union of two geometrical objects \\ BOOL\_OPER\_AND & Intersection of two geometrical objects \\ BOOL\_OPER\_SUB & The difference of two geometrical objects \\ BOOL\_OPER\_NEG & Unary Inside-out of one geometrical object \\ BOOL\_OPER\_CUT & Boundary of one object outside the other \\ BOOL\_OPER\_MERGE & Simple merge without any computation \\ \hline \end{tabular} \end{center} The {\bf BoolOperType} typedef is used in two dimensional Boolean operations invoked via {\bf Boolean2D}. Three dimensional Boolean operations are invoked via {\bf BooleanXXX} where XXX is one of OR, AND, SUB, NEG, CUT or MERGE, denoting the same as in the table above. In addition several state functions are available to control the way the Boolean operations are conducted. Functions to enable the dump of (only) the intersection curves, to handle coplanar polygons, and to set the axis along which the sweep is performed are provided. All globals in this library have a profix of {\bf Bool}. \section{Library Functions} \input{prog_man/bool_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{CAGD Library, cagd\_lib} \section{General Information} This library provides a rich set of function to create, convert, display and process freeform Bezier and NURBs curves and surfaces. The interface of the library is defined in {\em include/cagd\_lib.h}. This library mainly supports low level freeform curve and surface operations. Supported are curves and surfaces from scalars to five dimensions as E1/P1 to E5/P5 using the {\bf CagdPointType}. Pi is a rational (projective) version of Ei, with an additional W coefficient. Polynomial in the power basis have some very limited support as well. Different data structures to hold UV parameter values, control points, vectors, planes, bounding boxes, polylines and polygons are defined as well as the data strcutures to hold the curves and surfaces themselves, \begin{verbatim} typedef struct CagdCrvStruct { struct CagdCrvStruct *Pnext; struct IPAttributeStruct *Attr; CagdGeomType GType; CagdPointType PType; int Length; /* Number of control points (== order in Bezier). */ int Order; /* Order of curve (only for Bspline, ignored in Bezier). */ CagdBType Periodic; /* Valid only for Bspline curves. */ CagdRType *Points[CAGD_MAX_PT_SIZE]; /* Pointer on each axis vector. */ CagdRType *KnotVector; } CagdCrvStruct; typedef struct CagdSrfStruct { struct CagdSrfStruct *Pnext; struct IPAttributeStruct *Attr; CagdGeomType GType; CagdPointType PType; int ULength, VLength; /* Mesh size in the tensor product surface. */ int UOrder, VOrder; /* Order in tensor product surface (Bspline only). */ CagdBType UPeriodic, VPeriodic; /* Valid only for Bspline surfaces. */ CagdRType *Points[CAGD_MAX_PT_SIZE]; /* Pointer on each axis vector. */ CagdRType *UKnotVector, *VKnotVector; } CagdSrfStruct; \end{verbatim} Curves and surfaces have a geometric type {\bf GType} to prescribe the type of entity (such as CAGD\_SBEZIER\_TYPE for Bezier surface) and a point type {\bf PType} to prescribe the point type of the entity (such as CAGD\_PT\_E3\_TYPE for three dimensional Euclidean control points). {\bf Length} and {\bf Order} slots are used to hold the number of control points in the mesh and or control polygon and the order(s) of the basis functions. {\bf Periodic} flag(s) are used to denote periodic end conditions. In addition, {\bf KnotVector} slot(s) are used if the entity exploits Bspline basis functions, or NULL otherwise. The control polygon and/or mesh itself is organized in the {\bf Points} slot as a vector of size {\bf CAGD\_MAX\_PT\_SIZE} of vectors of {\bf CagdRType}s. For surfaces, the mesh is ordered U first and the macros of {\bf CAGD\_NEXT\_U} {\bf CAGD\_NEXT\_V}, and {\bf CAGD\_MESH\_UV} can be used to determine indices in the mesh. All structures in the cagd library can be allocated using New constrcutures (i.e. {\bf CagdUVNew} or {\bf CagdCrfNew}, freed using Free destructores (i.e. {\bf CagdSrfFree} or {CagdBBoxFree}, linked list free using FreeList destructores (i.e. {\bf CagdPolylineFreeList}), and copied using copy constructores {i.e. {\bf CagdPtCopy} or {\bf CagdCtlPtCopyList}). This library has its own error handler, which by default prints an error message and exit the program called {\bf CagdFatalError}. Most globals in this library have a prefix of {\bf Cagd} for general cagd routines. Prefix of {\bf Bzr} is used for Bezier routines, prefix of {\bf Bsp} for Bspline specific routines, prefix of {\bf Cnvrt} for conversion routines, and {\bf Afd} for adaptive forward differencing routines. \section{Library Functions} \input{prog_man/cagd_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Geometry Library, geom\_lib} \section{General Information} This library handles general geometric queries such as a distance between two lines, bounding boxes, convexity of polygons etc. Several header files can be found for this library: \begin{center} \begin{tabular}{||c|c||} \hline Header (include/*.h) & Functionality \\ \hline bbox.h & Bounding boxes related functions \\ convex.h & Convexity of polygons and convex polygon decomposition \\ geomat3d.h & General three dimensional geometry queries \\ geomvals.h & Area, Volume, and Size queries on polygonal objects \\ intrnrml.h & Internal normal interpolation for polygonal models \\ ln\_sweep.h & A line sweep implemetation \\ poly\_cln.h & Clean up degenerated polygons/polylines \\ primitiv.h & Constructors of polygonal BOXes, CYLINDERs, etc. \\ \hline \end{tabular} \end{center} \section{Library Functions} \input{prog_man/geom_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Miscelleneous Library, misc\_lib} \section{General Information} This library holds general miscelleneous functions such as reading configuration files, low level homogeneous matrices computation, low level attributes and general machine specific low level routines. Several header files can be found for this library: \begin{center} \begin{tabular}{||c|c||} \hline Header (include/*.h) & Functionality \\ \hline config.h & Manipulation of configuration files (*.cfg files) \\ dist\_pts.h & Enegry based distribution of points. \\ gen\_mat.h & Homogeneous matrices manipulation \\ getarg.h & Command line parsing for application tools \\ imalloc.h & Low level dynamic memory functions for IRIT \\ miscattr.h & Low level attribute related functions \\ priorque.h & An implementation of a priority queue \\ xgeneral.h & Low level, machine specific, routines \\ \hline \end{tabular} \end{center} \section{Library Functions} \input{prog_man/misc_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Prsr Library, prsr\_lib} \section{General Information} This library provides the data file interface for IRIT. Functions are provided to read and write data files, both compressed (on unix only, using {\em compress}), and uncompressed, in binary and/or ascii text modes. This library is also used to exchange data between the IRIT server and the display devices' clients. Several header files can be found for this library: \begin{center} \begin{tabular}{||c|c||} \hline Header (include/*.h) & Functionality \\ \hline allocate.h & High level dynamic allocation of objects \\ attribut.h & High level attributes for objects \\ ip\_cnvrt.h & Freeform to polygon and polyline high level conversion \\ iritprsr.h & Main interface to reading and writing data \\ irit\_soc.h & Socket communication for data exchange \\ \hline \end{tabular} \end{center} \section{Library Functions} \input{prog_man/prsr_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Symbolic Library, symb\_lib} \section{General Information} This library provides a rich set of function to symbolically manipulate freeform curves and surfaces. This library heavily depends on the cagd library. Functions are provided to low level add, subtract, and multiply freeform curves and surfaces, to compute fields such as curvature, and to extract singular points such as extremums, zeros, and inflections. High level tools to metamorph curves and surfaces, to compute layout (prisa) of freeform surfaces, to compute offset approximations of curves and surfaces, and to compose curves and surfaces are also provided. The interface of the library is defined in {\em include/symb\_lib.h}. This library has its own error handler, which by default prints an error message and exit the program called {\bf SymbFatalError}. Globals in this library have a prefix of {\bf Symb} for general symbolic routines. Prefix of {\bf Bzr} is used for Bezier routines, and prefix of {\bf Bsp} for Bspline specific routines. \section{Library Functions} \input{prog_man/symb_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Trimmed surfaces Library, trim\_lib} \section{General Information} This library provides a set of function to manipulate freeform trimmed Bezier and/or NURBs surfaces. This library heavily depends on the cagd library. Functions are provided to create, copy, and destruct trimmed surfaces to extract isoparametric curves, to evaluate, refine and subdivide, to read and write trimmed surfaces, degree raise, and approximate using polygonal representations. The interface of the library is defined in {\em include/trim\_lib.h}. This library has its own error handler, which by default prints an error message and exit the program called {\bf TrimFatalError}. All globals in this library have a prefix of {\bf Trim}. \section{Library Functions} \input{prog_man/trim_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Trivariate Library, triv\_lib} \section{General Information} This library provides a rich set of function to manipulate freeform Bezier and/or NURBs trivariate. This library heavily depends on the cagd library. Functions are provided to create, copy, and destruct trivariates, to extract isoparametric surfaces, to evaluate, refine and subdivide, to read and write trivariates, to differentiate, degree raise, make compatible and approximate iso-surface at iso values using polygonal representations. The interface of the library is defined in {\em include/triv\_lib.h}. This library has its own error handler, which by default prints an error message and exit the program called {\bf TrivFatalError}. All globals in this library have a prefix of {\bf Triv}. \section{Library Functions} \input{prog_man/triv_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Extra Library, xtra\_lib} \section{General Information} This library is not an official part of IRIT and contains public domain code that is used by routines in IRIT. The interface of the library is defined in {\em include/extra\_fn.h}. \section{Library Functions} \input{prog_man/xtra_lib.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \chapter{Programming Examples} \label{chap-examples} This chapter describes several simple examples of C programs that exploits the libraries of IRIT. All external function are defined in the {\em include} subdirectory of IRIT and one can 'grep' there for the exact include file that contains a certain function name. All C programs in all C files should include 'irit\_sm.h' as their first include file of IRIT, before any other include file of IRIT. Header files are set so C++ code can compile and link to it without any special treatment. \section{Setting up the Compilation Environment} In order to compile programs that uses the libraries of IRIT, a makefile has to be constructed. Assuming IRIT is installed in {\em /usr/local/irit}, here is a simple makefile that can be used (for a unix environment): \begin{verbatim} IRIT_DIR = /usr/local/irit include $(IRIT_DIR)/makeflag.unx OBJS = program.o program: $(OBJS) $(CC) $(CFLAGS) -o program $(OBJS) $(LIBS) -lm $(MORELIBS) \end{verbatim} The simplicity of this makefile is drawn from the complexity of makeflag.unx. The file makeflag.unx sets the CC, CFLAGS, LIBS, and MORELIBS for the machined using among other things. Furthermore, makeflag.unx also sets the default compilation rules from C sources to object files. The file makeflag.unx had to be modified once, when IRIT was installed on this system. If the used system is not a unix environment, then the file makefile.unx will have to be replaced with the proper makeflag file. In an OS2 environment, using the emx gcc compiler, the makefile is even simpler since the linking rule is also defined in makeflag.os2: \begin{verbatim} IRIT_DIR = \usr\local\irit include $(IRIT_DIR)\makeflag.os2 OBJS = program.o program.exe: $(OBJS) \end{verbatim} Finally, here is a proper makefile for Windows NT: \begin{verbatim} IRIT_DIR = \usr\local\irit include $(IRIT_DIR)\makeflag.wnt OBJS = program.obj program.exe: $(OBJS) $(IRITCONLINK) -out:program.exe $(OBJS) $(LIBS) $(W32CONLIBS) \end{verbatim} \section{Simple C Programs using IRIT} Now that we have an idea how to compile C code using IRIT, here are several examples to read, manipulate and write IRIT data files. You will be able to find all these examples in the doc/cexample directory. \subsection{Compute Area of a Polygonal Model (polyarea.c)} Here is a simple program to compute the total area of all polygons in the given data file. The program expects one argument on the command line which is the name of the file to read, and it prints out one line with the total computed area. \input{cexample/polyarea.tex} \subsection{Converts a Freeform Surface into Polygons (polygons.c)} This true filter reads a single surface from stdin and dumps out a polygonal approximation of it to stdout. They are several parameters that controls the way a surface is approximated into polygons and in this simple filter they are being held fixed in a set of integer variables. \input{cexample/polygons.tex} \subsection{Linear Transformations' Filter (transfrm.c)} This little more complex program transfroms all the geometry in the read data which can be any number of files according to the specified transformations on the command line. The command line is parsed via {\bf GAGetArgs} and its associated functions. The transformation matrix is then computed with the aid of the matrix package and applied to the read geometry at once. \input{cexample/transfrm.tex} Here is the result of running 'transfrm -h': \begin{verbatim} This is Transform... Usage: Transfrm [-x Degs] [-y Degs] [-z Degs] [-t X Y Z] [-s Scale] [-h] DFiles \end{verbatim} When you are considering the usefulness of this tool remember that the transformations are applied to the geometry in an internal order which is different from the command line order. That is, \begin{verbatim} transfrm -x 30 -y 30 geometry.dat > tgeometry.dat \end{verbatim} will compute the exact same transfrom as, \begin{verbatim} transfrm -y 30 -x 30 geometry.dat > tgeometry.dat \end{verbatim} This, while rotation is not a commutative operation. Nonetheless, you may split the operations. That is: \begin{verbatim} transfrm -y 30 geometry.dat | transfrm -x 30 - > tgeometry.dat \end{verbatim} or \begin{verbatim} transfrm -x 30 geometry.dat | transfrm -y 30 - > tgeometry.dat \end{verbatim} will do exactly what one expects. \subsection{Least sqaures curve fitting and process communication (lst\_sqrs.c)} This example creates a Bspline curve that least squares approximates a given set of data points. In the default values, a quadratic Bspline curve of 10 control points least sqaures approximates a set of 100 three dimensional points. Also shown is a polyline of the original (100) points. Arbitrary number of curves will be displayed every, one for every keystroke until Q is typed. \input{cexample/lst_sqrs.tex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \twocolumn \input{prog_man.ind} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \end{document}