SMLib Manual
NVIDIA Docs Hub  Solid Modeling Solutions (SMS)  SMLib Manual  General Usage

General Usage

Documentation

Documentation is generated by Doxygen from the header and source files. Header documentation is available here.

Source code documentation is available to source code customers.

In addition to documentation, the manual pages available on the web site here may also be helpful as are many examples provided here.

Source code guidelines

  • Class names and most files begin "Iw" with camel case convention (IwVector3d.cpp, class IwVector3d).
  • Files which do not contain classes or methods for a class are lower case with underscores (iwos_error.h, iwos_error.cpp).
  • Naming conventions for parameters begin with a lower case characters.
    • r - reference ( double & rdRadius ).
    • d, l, p, b - double, long, pointer, boolean (double dParameter, ULONG lCount, long lValue, IwCurve * pCurve, BOOL bTrueOrFalse).
    • c - constant (const IwCurve & crCurve).
    • a - array (double adParameters[5];).
    • s - object on the local stack of the current scope ( IwArray sArray ).
    • v - object passed or used by value as opposed to by pointer or by reference ( class List { IwArray vMyArray; } ).
  • Parameters are clearly marked [in], [out], [in/out] in the header.
  • Default values for optional parameters are clearly marked in the header
  • Most Methods/Functions return an IwStatus flag

Interfacing Between NLib and 'Iw' Objects

SMLib provides an interface which allows users to construct 'Iw' objects directly from NLib structures. The IwBSplineCurve and the IwBSplineSurface both contain equivalent NLib NL_CURVE and NL_SURFACE structures. Structurally they are the same but the memory management utilized in each case is significantly different.The 'Iw' object allocates the corresponding NURBS curve or surface as a single block of memory. NLib allocates a NURBS curve or surface as many smaller components. In terms of usage what this means is that they are interchangeable only for operations where no editing or manipulation of these structures is required. For example you may utilize the NL_CURVE pointer inside of a IwBSplineCurve in query operation such as evaluation but you could not add a knot to it. In general we recommend that you do not try to interchange the forms directly but go through existing interfaces which create the corresponding copies. Only interchange the forms when it is absolutely necessary for performance.

We have several utilities which will help you to transfer data between the libraries. Both the IwBSplineCurve and IwBSplineSurfacehave constructors which will take a pointer to a NLib NL_CURVE or NL_SURFACE. The constructors either create a copy or reference the NLib structure directly. We recommend that you create a copy. There is a section of software below that shows how this process works. You may also obtain the internal pointer to the NL_CURVE or NL_SURFACE by invoking the GetGwNurbPointer methods. You can then use this to create a NLib native NURBS using a copy method. This is shown below also.

This first example shows how to construct a IwBSplineCurve that copies the data from a CURVE generated in NLib.

// create and manipulate curve in NLib
NL_CURVE *cur;
cur = ...

// constructs a NMTLib curve by copying the NLib cur.
IwBSplineCurve *pBSplineCurve = new (pContext)IwBSplineCurve(3, (void*)cur);

This second example shows how to construct an IwBSplineCurve which references an existing NL_CURVE from NLib. This is a little dangerous and is recommended only for expert users.

// prevents copy of cur - it utilizes cur directly inside of the IwBSplineCurve object.
BOOLEAN bIsBorrowed = TRUE;
IwBSplineCurve* pBSplineCurve = new (pContext) IwBSplineCurve(void*)cur, 3, bIsBorrowed);

This third example shows how to create a CURVE from a IwBSplineCurve. pcur is an internal pointer used by the IwBSplineCurve and must not be deleted or edited. new_cur may be edited, deleted, etc.

IwBSplineCurve *pBSplineCurve = .....;
NL_CURVE *pcur = pBSplineCurve->GetGwNurbPointer();

STACKS SL;
NL_CURVE new_cur;
N_CrvInitArrays(new_cur);
N_CrvCopy(pcur,new_cur,SL);

The fourth example shows how to convert a IwCurve into a IwBSplineCurve;

IwCurve *pCurve; IwBSplineCurve *pBSC = IW_CAST_PTR(IwBSplineCurve, pCurve);

There are equivalent methods that can be used to transfer data between the IwBSplineSurface, IwSurface, and the NLib NL_SURFACE.

The fifth example shows how to convert an analytic surface (cylinder, cone etc) into a Nurbs form;

IwCylinder *Cyl = ....;

IwBSplineSurface *pNurbsSrf = new (crContext) IwBSplineSurface (*Cyl);

Geometrical Utility Classes

  • two-dimensional vector - IwVector2d, IwPoint2d
  • three-dimensional vector - IwVector3d, IwPoint3d
  • local coordinate system or transformation - IwAxis2Placement
  • n-dimensional matrix used to solve linear equations - IwMatrix
  • polynomial equation representation - IwPolynomial
  • non-axis aligned bounding box - IwPseudoBox
  • one-dimensional interval - IwExtent1d
  • two-dimensional bounding box - IwExtent2d
  • three-dimensional bounding box - IwExtent3d
  • n-dimensional bounding box - IwExtentNd

Vector Classes

The vector classes IwVector3d and IwPoint2d provide a variety of math operators like cross product, dot product, etc. The vector classes also provide a reasonable set of math operator overloading to help simplify and clarify the vector operations. IwVector2d and IwPoint2d are often used in to describe the surface parameter space, where the "X" component of the vector maps to the "U" parameter of the surface and "Y" maps to the "V" parameter.

Intervals and Domains

Many of the curve methods allow the user to specify a portion of the curve's natural interval. Basically this allows the user to limit the area of interest for a given operation to a subset of the natural interval. For example, the user may request the length of a portion of a curve without actually modifying the curve. To do so, IwExtent1d can be used to specify a portion of the curve's parameterization. The entire curve interval can be determined with GetNaturalInterval().
Similarly a portion of a surface domain can be specified using the uv parameterization of the surface in IwExtent2d . The entire surface domain can be determiend with GetNaturalUVDomain().

There are four extent classes: IwExtent1d, IwExtent2d, IwExtent3d, and IwExtentNd. Extent classes define a domain of the corresponding dimension by specifying the minimum and maximum values for the range of the domain. IwExtent1d defines a one-dimensional domain on the real line. IwExtent2d defines a two-dimensional domain in the real plane. IwExtent3d defines a three-dimensional domain in three space. IwExtentNd defines an N-dimensional domain in N-Space. IwExtent1d is often used to define the parameter interval of a curve. IwExtent2d is often used to define the domain of the parameters of a surface. IwExtent3d is often used to define a three-dimensional axis-aligned bounding box. IwExtentNd is used primarily as the domain representation to limit parameters for solving N-dimensional equations.

Axis Placement

The Axis Placement, IwAxis2Placement, defines a local coordinate system. It contains a point representing the origin and two vectors representing the new X and Y axes. It is derived from the STEP representation of the equivalent name with the exception that the X and Y axes must be orthogonal. The IwAxis2Placement is used primarily to represent transformations from one coordinate system to another.

Pseudo-Box

A Pseudo-Box, IwPseudoBox, is a non-axis aligned bounding volume. In many cases it can provide a much tighter bound on curves and surfaces than the IwExtent3d object.

Parsing the IwSolution Object

The IwSolutionArray stores the result of intersections or global solve. The IwSolutionArray is an array of IwSolution objects that represent individual solution points to the global problem being solved. You will need to parse the IwSolution object to extract the required data. The IwSolution contains the objects (face, curve, edge, vertex) that yielded the given solution and corresponding parameteric values. This function demonstrates how to extract that information from the IwSolution and create a corresponding 3D point. Refer to example.

Continuities

A curve or a surface may have internal continuity changes at the knots. Continuity changes may be caused by either duplicate knots or duplicate control vertices. There are methods on the curve and surface to compute the continuities. Except where stated explicitly (DropCurve on IwSurface), all methods will handle curves and surfaces with internal C0 continuity (discontinuous tangent directions within a curve or a tangent plane discontinuity within a surface). In other words they may find answers which lie on the boundary or internal discontinuity. For example, the minimization between a point and a surface may return a point internal to the surface, on the boundary of the surface, or along a discontinuous edge of the surface.

Another question one might answer is what happens if an answer is produced which is very close to a discontinuity. For example: what if a line intersects a surface near an internal discontinuity? The results obtained would be as if the surface or curve was broken up into homogenous pieces and intersected then the results combined. In our example one might get two intersections, one internal to the surface and one on the discontinuity. Because the answers are not identical both are kept. This conforms to our general philosophy of trying to not loose information. Sometimes this may cause us to return more information than the user needs, but this is better than returning not enough.

Memory Management

The software is now multi-processor compliant. The IwContext is very important object. It contains all global data such as the cache manager and temporary working memory for certain functions. Every time you create an object (IwObject and subclasses) on the heap you will need to use the overridden "new" operator that takes a context. The standard new operator has been made private to prevent creation of heap objects without a context.

IwBSplineCurve *pBSC = new IwBSplineCurve(...); // This is will not compile
IwBSplineCurve *pBSC = new(crContext) IwBSplineCurve(...); // This is correct

Any method that creates an object takes a IwContext object as either an argument to a "Create" method or as an argument in the "new". The context must have scope which is outside of the scope of the existence of the object. Therefore creating a global context at the beginning using the following is recommended if you are keeping objects around between commands.

static IwContext *s_pContext = new IwContext();

If you are just using objects locally you can put the context on the stack as follows:

IwContext sContext;

This way all objects created in a given "Context" can be deleted by deletion of the corresponding "pool". Note that we do not provide a pool based memory manager you will have to purchase or develop one yourself. SmartHeap from MicroQuill does come with a pool based memory management system.

All memory management for the library is handled in the iwos_memory.h and iwos_memory.cpp files. You may modify iwos_memory.cpp if you wish to utilize a different memory mechanism. We also provide an interface to pool based management of memory contained in the IwMemPool object. There are a number of different ways to create an object.

On the stack - cleanup happens automatically via. destructor. In general you should avoid creating IwCurve and IwSurface and their subclasses on the stack. The array based objects (IwTArray, IwSArray, IwSolutionArray) typically should be created on the stack. If the array object is created on the heap you will need an additional context argument to the destructor.

IwTArray sDoubleArray; // This is fine

On the heap - cleanup requires an explicit "delete" or utilization of a stack based clean up object

  • IwTArray *pDoubleArray = new IwTArray(); // Not legal - will produce a compile error
  • IwTArray *pDoubleArray = new(crContext) IwTArray(); // Legal but not good for array objects. Legal and good for other types of objects such as curves and surfaces.
  • IwTArray *pDoubleArray = new(crContext) IwTArray(crContext); // This is the correct way to create array based objects on the heap.

Here are some good "Rules of Thumb" to help you make decisions about how to use the Context:

  1. Never declare curves or surfaces on the stack (IwBSplineCurve sCurve(...)).
  2. Never allocate curves or surfaces on the heap without a context

IwBSplineCurve *pCurve = new IwBSplineCurve(....); // This is bad and will not work
IwBSplineCurve *pCurve = new (crContext) IwBSplineCurve(...); // This is good.

  1. Don't allocate IwTArray objects on the heap unless you give the constructor which takes a context.
  2. You will now not have to worry about managing the Cache. A good default size is created in the IwContext. If you have any declarations of cache managers (IwCacheMgrBrep sCache(1000, 100, 100, 100)). You should just remove them.
  3. We suggest that you create one global IwContext when you start up your program and use that whenever you need to create any of our objects. The only time you would want to use a IwContext on the stack is when all of your TSLib objects are created and destroyed within the given function.

There are three objects which are especially useful in the management and automatic clean up of heap based memory and objects. These objects will automatically delete objects when they go out of scope. You have the option of preventing them from deleting their contents by invoking the corresponding Clear method.

  • IwObjDelete - stack based clean up of IwObject subclasses (see IwObject.h).
  • IwObjsDelete - stack based clean up of arrays of IwObject subclasses (see IwTArray.h).
  • IwMemDelete - stack based clean up of memory allocated on heap.

Caching

Note that the Caching Mechanism is now embedded in the IwContext object. The default is for a context to create a cache manager with a maximum of 1000 curve caches, 200 surface caches, 200 trimmed surface caches, and 200 brep caches. This is a fairly good sized cache and should be sufficient for most applications. You can increase it or decrease it by a factor of 10 and still be reasonably good. If you want to conserve memory decrease it by a factor of 10. If you want better performance for larger models, increase it by a factor of 10.

GSLib utilizes a caching system to improve performance. It caches the tessellated Bezier representation of curves and surfaces and constructs a hierarchical tree structure for fast traversal. You should always have caching turned on and it should have a minimum of 10 cache elements. That is it will keep the tessellation for the last 10 curves/surfaces which it has processed. Depending upon the performance/memory requirements for your application you may want to increase this number. The caching mechanism allows us to achieve a level of performance on global algorithms which is near that of the local Newton based algorithms.

Error Handling

GSLib utilizes an error return based error handling convention. We utilize a set of macros to simplify and hide most of the error processing. At the moment an error is detected an error handling function is called (see iwos_error.h). Currently it prints an error either to the debugger output window in Visual C++ or to stderr on other systems. We suggest that you leave the error printing turned on until you have debugged the software you are implementing using GSLib. Knowing where an error has occurred will also help us to diagnose and fix any problems with our software.

The following macros are the most heavily used (see iwos_error.h):

  • SER - Status Error Return - checks the status returned from a method and returns up the call stack if the status is not IW_SUCCESS
  • NER - Null Error Return - checks the value of a pointer and if it is NULL returns an error up the call stack.

Validity of Curves and Surfaces

Use IW_ASSERT_VALID() for debug messages to detemine validity of any object

  • The end points of curves and boundaries of surfaces must be clamped (i.e. they have knot multiplicity equal to the degree+1).
  • Internally the curve must have G0 continuity (must be a single piece)
  • Control points should be distinct.
  • For surfaces, the only requirement should be G1 continuity ( have no internal creases). Curves that are not G1 must be broken up into G1 segments before they are used for sweeping or skinning into surfaces.
  • Curves and surfaces with up to degree 32 are allowed.

Validity of Trimmed Surfaces

  • The definition of a trimmed surface corresponds to the equivalent definition found in STEP and IGES.
  • The curves and surfaces must conform to the validity criteria defined in the Geometry Introduction
  • The surfaces must have continuity of C0 (smooth) or better.
  • The individual trimming curves must have continuity of G1 or better.
  • Polyline trimming curves are not supported.
  • The trimming loops must be closed to within a given model or parameter space tolerance.
  • There may be only one outer loop which is oriented counter-clockwise relative to the surface normal.
  • There may be zero, one or more inner loops which are oriented clockwise relative to the surface normal.
  • The curves of the trim boundary must not have self-intersections (except for closed curves).
  • The curves of the trim boundary must not intersect each other except where they join the loop at their ends.
  • The curves of one loop must not intersect or touch the curves of another loop.
  • When 3-D model space trimming curves are specified, they must lie on the surface (to within the current model space tolerance of the trimmed surface).
  • When 3-D model space trimming curves are specified, the corresponding ends of the curves in a loop must be within tolerance of each other.
  • When 2-D parameter space and 3-D model space curves are specified, their parameterization must match within the tolerance of the trimmed surface. In other words the point created by mapping a given parameter value of the 2D curve through the surface evaluator must be within the tolerance of the same parameter value as applied to the 3-D curve.

Classification Operations inside, outside, on boundary

  • Parameter space points relative to trim boundary. Use IwFace::PointClassify
  • Parameter space or model space curves relative to trim boundary. Use IwFace::Point3DClassify
  • Classification of 3D point relative to a Brep. Use IwBrep::Point3DClassify
Last updated on Apr 29, 2024.