Home > User Guide > Modeling Operations > Intersectors, Booleans, and Stitching > Stitching

Tolerant Stitching

Tolerant Stitching is an operation of api_stitch and api_stitch_nonmanifold when the stitch_options object that is passed into these APIs is of class tolerant_stitch_options. Tolerant stitching stitches two faces only if the common edges/vertices have approximately the same geometry. After stitching is completed, the resulting model is checked for gaps. Edges or vertices with gaps are replaced with TEDGEs and TVERTEXs. This form of stitching should be used in situations where gaps exist between edges that should be stitched together. This situation typically arises with models that have been translated into ACIS from another modeler.

Tolerant stitching has the following characteristics:

Figure. Example of a Difficult Tolerant Stitching Operation

Tolerant stitching uses an incremental algorithm. Stitching attempts to stitch the body together by starting with a small tolerance (the minimum tolerance) and stitching together as many faces as possible. Then, the tolerance is increased by a small amount and as many remaining faces are stitched as possible. At each tolerance value, edges that are smaller than the tolerance are either removed or merged, depending on their relationship to the adjoining edges. This process is continued until the entire set of faces can be stitched together, or the maximum tolerance is reached. This algorithm provides robustness against difficult stitching problems that can arise, like the one illustrated in the previous figure.

In Tolerant stitching mode, api_stitch and api_stitch_nonmanifold will operate only on BODYs or free FACEs. A free FACE is a FACE that is a top-level entity and has no owner. Note that free FACEs are not legal in ACIS, but the API still accepts them. It is recommended, however, that the API be passed only BODYs.

Two lists: ENTITY_LIST output_bodies and ENTITY_LIST new_bodies, are returned as output from api_stitch and api_stitch_nonmanifold. The list ENTITY_LIST output_bodies contains the complete set of bodies that is output from the API and belong to the caller. In tolerant stitching mode, if free FACEs are passed into the API, then the API will wrap these free FACEs in new BODYs, which are also returned to the output_bodies list. Note that any new BODY created by the API is also returned to the new_bodies list. The list ENTITY_LIST new_bodies contains all the new bodies resulting from the API. This list becomes a subset of ENTITY_LIST output_bodies. This list is provided in order to make it convenient for the callers to determine ownership of the new bodies. The callers may have to register new bodies in their application and/or do memory management of these bodies.

Non-manifold Stitching

The API api_stitch_nonmanifold performs non-manifold stitching between parting faces and part bodies. This API may be used for stitching more than two coedges per edge. This API is specifically catered to support mold and die design processes. The picture below illustrates a primary body, along with its parting faces (just to clarify the terms primary body and parting faces used in this document).

Figure. Primary Body and Parting Faces

For more details on how this API performs non-manifold stitching, refer to the documentation of api_stitch_nonmanifold.

Limitations

Failsafe Stitching

The APIs api_stitch and api_stitch_nonmanifold have a failsafe behavior. These APIs attempt to succeed as much as possible and not fail, even in cases where they encounter any geometry and topology related errors. These APIs undo the current atomic transaction that fails due to such errors, raise a sys_warning with the same error message, and proceed further. In cases where the APIs succeed and outcome is successful, you can call the method, outcome::encountered_errors() to determine whether the APIs had encountered any error(s) and still proceeded further.

Warning:  If outcome::encountered_errors() returns TRUE, the model may have geometric or topological defects that need to be corrected. To turn off the failsafe behavior, push TRUE into the careful option.

You can determine the result of the APIs by using the return values of the following methods:

Note:  Even though these APIs have been made failsafe, they will still continue to fail on certain errors that are irrecoverable. The list of irrecoverable messages are:

INVALID_STITCH_MAX_TOL             "Stitch maximum tolerance less than SPAresabs"
COINCIDENT_FACES                         "Attempting to stitch coincident faces is not allowed" (Appears in SPA_STITCH_COIN_ERROR mode only)
INPUT_NOT_AN_EDGE                       "Input list has an entity which is not an EDGE"
EDGE_ALREADY_STITCHED                "Input edge is already stitched"
EDGE_HAS_NO_FACE                         "Input edge is not connected to any face"
NOTHING_TO_STITCH                       "Nothing to stitch"
FACE_WITH_OWNER                           "Encountered face with owner"
UNACCEPTABLE_ENTITY                   "Unsupported topology encountered"
EDGE_HAS_FACE_WITH_NO_BODY     "Top level owner of EDGE is neither a FACE nor a BODY"
IMPROPER_STITCH_OPTION             "Improper stitch_option"
FREE_FACE_NOT_SINGLE                 "Free face contains information of other faces"

In addition to these messages, api_stitch_nonmanifold has an additional irrecoverable message:

PARTING_FACELIST_EMPTY             "Parting faces list is empty"

Coincident Face Detection

A common situation with incoming stitch data is coincident faces where a pair of surfaces are "back-to-back" along an edge that has to be stitched. This is an illegal configuration for tolerant stitching; it usually signifies the presence of duplicate and/or construction faces in the incoming data. The APIs have been set up to detect coincident (back-to-back) faces during the tolerant stitching process. The APIs are not guaranteed to detect all coincident faces. Coincident faces are detected only if they are encountered by the APIs in the process of stitching. The detection and processing of the coincident faces by the APIs depend upon the mode set in tolerant_stitch_options or edge_tolstitch_options object passed into api_stitch, and tolerant_stitch_options passed in api_stitch_nonmanifold. The behavior under different modes is as mentioned below:

The information about clusters of coincident faces found by api_stitch and api_stitch_nonmanifold is stored in the tolerant_stitch_options object that was passed in. The are three levels of organization that can be queried:

Using clustering information obtained from the tolerant_stitch_options object, you can remove coincident faces from the initial face list and try the stitch again. In later stitch attempts, you might want to use restricted tolerant stitching, passing in only edges with one coedge.

Note:  The order of stitch attempts is changed by removing faces from the list, so that multiple passes of this procedure may be required as more coincident faces are discovered in later passes.

Thes APIs also store information about the clusters of back-to-back, partially and nearly coincident faces in the outcome it returns. These APIs detect faces that are nearly coincident, although not coincident and reports them as problems in the outcome it returns. Nearly coincident faces are geometrically valid, but they could be indications of possibly unintended design. Stitching nearly coincident faces can produce sharp wedge-like shapes.

A sample Use Case has been provided to illustrate tolerant stitching and demonstrate how the errors and problems encountered by api_stitch and api_stitch_nonmanifold may be obtained from the outcome.

Shell Containment Solving

If tolerant stitching results in multiple shells, then these shells need to be solved on the basis of their containment relationships with each other. The shells also need to be properly oriented if they are contained in other shells. The following figure illustrates containment relationships of six shells A, B, C, D, E and F.

Figure. Containment Relationships among Shells

Shell A contains Shell B and Shell D.
Shell B contains Shell C.
Shell E and F have no containment relationships with other shells.
All shells belong to different bodies in the input.

A shell containment graph plotted for this case will be as shown in the following figure.

Figure. Shell Containment Graph Showing Levels

The level of containment is given by the position of a shell in the shell containment graph. The shells A, E, and F are at level 0, B and D are at level 1, and C is at level 2.

Stitching rearranges the shells based on the shell containment graph as follows:

Stitching outputs the following based on the shell containment graph shown in Figure. Shell Containment Graph Showing Levels.

Stitching can also be disallowed from returning back void shells. In this case, all shells are output as peripheral shells. Refer to tolerant_stitch_options on how to disallow stitching from returning back void shells.

IMPORTANT:  The shell solving mechanism assumes that every shell is either completely inside or completely outside another shell. If shells partially intersect, then the output of shell solving is unpredictable. If you are uncertain whether the shells will have a clean containment, then Spatial advises that you disallow stitching from returning void shells.

Problem Reporting

The APIs api_stitch and api_stitch_nonmanifold puts into the outcome object returned, the diagnostic information about any problem that they encounter during the operation. The caller of these APIs can obtain this information by calling outcome::get_error_info_list(). For more details on how this information can be obtained, refer to documentation of outcome class.

Notes

Related topics:

Tolerant Stitching Sample Code

[Top]

© 1989-2007 Spatial Corp., a Dassault Systèmes company. All rights reserved.