Tolerant Stitching
From DocR22
Tolerant Stitching is the operation of api_stitch and api_stitch_nonmanifold when the stitch_options object that is passed into these APIs is of the 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:
- Handles varying gaps.
- Resolves multiple vertices.
- Splits edges appropriately.
- Ensures consistent face normals.
 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.
Contents |
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).
 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
- This API, 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 this API still accepts them. We recommended, however, that this API be passed only BODYs.
- This API does not support vertex stitching. For example, if you give a primary body (shown in yellow) and a parting face (shown in blue), as shown in the figure below, to be stitched at one common vertex, then this API will not stitch the two at the common vertex.
 Non-manifold Vertex Stitching |
- This API does not always handle sidedness and containment of faces accurately. If you provide sheet bodies (or free faces) in a parting faces list and a primary bodies list for non-manifold stitching, then all the faces of the stitched non-manifold body returned by this API might be marked DOUBLE_SIDED with containment as BOTH_OUTSIDE, even if a portion of the non-manifold body encloses finite volume. However, if you provide one or more solid bodies (along with or without sheet bodies) in a primary bodies list to be stitched with a parting faces list, then all the faces of the incoming solid bodies will be marked SINGLE_SIDED. The faces of the incoming sheet bodies will be marked DOUBLE_SIDED with containment as BOTH_OUTSIDE.
- The API does not support non-manifold stitching between bodies that does not cater to mold and die design process. So the API is not recommended for non-manifold stitching if the customer application/requirement is not related to mold and die design process.
Maximum Stitch Tolerance
The maximum tolerance specifies the point at which stitching stops and therefore needs to be sufficiently large so as to stitch faces with large interface gaps in the body. The maximum stitching tolerance denotes the maximum gap size at which stitching is performed. One should set maximum stitching tolerance such that it is bigger than the size of expected maximum gap between faces to be stitched. Further it should be smaller than the minimum feature size in the model. This is important because the APIs api_stitch and api_stitch_nonmanifold might remove edges smaller than the supplied maximum stitching tolerance. Note, however, that there are internal heuristics that might prevent edges from being stitched, even if their gap is less than this tolerance. (The goal of these heuristics is to avoid creating any sliver TEDGEs whose tolerances are a significant fraction of their respective edge's length.)
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
- When outcome::encountered_errors returns FALSE, the APIs have completely succeeded, that is, no errors were encountered by the APIs. The method outcome::ok should always return TRUE in this case.
- When both outcome::encountered_errors and outcome::ok return TRUE, the APIs have encountered error(s), yet have otherwise proceeded to completion successfully.
- When outcome::ok returns FALSE, the APIs have failed and rolled the model back to its state before the APIs were called.
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:
| Error code | Description |
|---|---|
| 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:
| Error code | Description |
|---|---|
| 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
- SPASTITCH_COIN_SKIP – This is the recommended setting. If stitching detects that two faces are coincident while attempting to stitch them, then it will not stitch them together along that edge. Instead, it will record the face pair internally, throw a warning and continue with the stitching process. At the end of stitching, the caller can query the tolerant_stitch_options object for information about the pairs of faces found.
- SPASTITCH_COIN_ERROR – This is the default mode. In this mode, tolerant stitching has the same behavior as in the R10 version; a system error is thrown and the model is rolled back to its initial state without recording the coincident face information.
- SPASTITCH_COIN_STITCH – This mode is similar to SPASTITCH_COIN_SKIP, except that the coincident faces are stitched together (rather than skipped). The APIs will record the face pair internally, throw a warning and continue with the stitching process. This mode is not recommended, because it can produce back-to-back face pairs that may cause downstream ACIS operations to fail.
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. Three levels of organization that can be queried are:
- Coincident faces – Returns a list of all faces which appeared in a coincident face pair during stitching.
- Coincident face partners – Given a face, it returns a list of all faces that shared a coincident face pair with that face.
- Coincident face clusters – Groups faces that are connected by a sequence of pairs. For example, if A is coincident with B, and B with C, then A, B and C are all in the same cluster (even if A is not coincident with C). Each coincident face found will be listed in one and only one cluster.
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.
The 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.
 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 for this case is depicted in the following figure.
 Shell Containment Graph Showing Levels of Containment |
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:
- All even-level shells (such as 0, 2, 4) in the shell containment graph is output as peripheral shells.
- All odd-level shells (such as 1, 3, 5) in the shell containment graph is output as void shells of lumps having shells of one level higher. In other words, a shell at level 1, for example, is output as a void shell of lump containing a level 0 shell.
Stitching outputs the following based on the shell containment graph shown in the figure, Shell Containment Graph Showing Levels of Containment.
- A body containing peripheral Shell A and 2 void Shells B and D.
- A body containing peripheral Shell C
- A body containing peripheral Shell E
- A body containing peripheral Shell F
Stitching can also be disallowed from returning void shells. In this case, all shells are output as peripheral shells. Refer to tolerant_stitch_options on how to disallow stitching from returning 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 recommends that you disallow stitching from returning void shells. Shells will need to be sorted after stitching and after the geometric and topological problems have been resolved.
Problem Reporting
api_stitch and api_stitch_nonmanifold return diagnostic information about any problem that they encounter during the operation in the outcome object return by the function. You 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 the outcome class.
Notes
- In Tolerant Stitching mode, api_stitch cannot create non-manifold (that is, more than two coedges per edge) bodies. Use api_stitch_nonmanifold for stitching more than two coedges per edge.
- In Tolerant stitching mode, the APIs 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 APIs still accept them. It is recommended, though, that the APIs be passed only BODYs.
- ENTITY_LIST new_bodies contains all the new bodies resulting from the APIs. This list is provided for the caller's convenience 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.
- In order that you may reuse the same tolerant_stitch_options object in multiple calls to api_stitch and api_stitch_nonmanifold, api_stitch and api_stitch_nonmanifold clear any clusters present in the input tolerant_stitch_options object.
- The ENTITY_LIST* returned by get_next_coincident_faces_cluster points to memory owned by the tolerant_stitch_options or edge_tolstitch_options object, and should not be deleted by the customer.
- At every value of the tolerance examined during the incremental stitch process, small ("sliver") edges are removed or merged. If you find that tolerant stitching removes edges that should be kept, you should try setting the max_stitch_tol parameter to be smaller than the minimum feature size and bigger than the maximum gap expected to be stitched in the model. Note, however, that there are internal heuristics that might prevent edges from being stitched, even if their gap is less than this tolerance. (The goal of these heuristics is to avoid creating any sliver TEDGEs whose tolerances are a significant fraction of their respective edge's length.)
- You may not attach cellular topology to an incomplete shell.
