Stitching Models

Stitch or sew separate faces together to form a sheet or solid body. More...


Classes
class	edge_tolstitch_options
	Specifies that api_stitch should use restricted tolerant stitching. More...
class	exact_stitch_options
	Specifies that api_stitch should use exact stitching. More...
class	stitch_options
	Abstract base class from which specific stitch options classes, such as `exact_stitch_options`, `tolerant_stitch_options` and `edge_tolstitch_options`, are derived. More...
class	stitch_progress_info
	Abstract base class for providing stitch progress information. More...
class	tedge_repair_options
	Specifies the options for api_check_and_fix_tedge. More...
class	tolerant_stitch_options
	Specifies that api_stitch and api_stitch_nonmanifold should use tolerant stitching. More...
Typedefs
typedef int(*	proc_stitch_progress_callback )(stitch_progress_info *)
	Function pointer to implement stitch progress meter.
Enumerations
enum	STITCH_COIN_MODES
	Specifies how a stitching operation handles coincident faces. More...
enum	STITCH_TYPE
	Specifies the type of stitching to be performed by the stitching operation. More...
Functions
outcome	api_check_and_fix_tedge (TEDGE tedge, logical &fixed, logical &already_good, tedge_repair_options tedrepopts=NULL, AcisOptions *aopts=NULL)
	Attempts to repair level 30 check errors in TEDGEs.
outcome	api_initialize_stitching ()
	Initializes the Stitch Component library.
outcome	api_stitch (const ENTITY_LIST &to_be_stitched, ENTITY_LIST &output_bodies, ENTITY_LIST &new_bodies, stitch_options sopts, AcisOptions aopts=NULL)
	Stitches together the given entities.
outcome	api_stitch_nonmanifold (const ENTITY_LIST &parting_faces, const ENTITY_LIST &primary_bodies, ENTITY_LIST &output_bodies, ENTITY_LIST &new_bodies, tolerant_stitch_options sopts, AcisOptions aopts=NULL)
	Performs tolerant, non-manifold stitching between parting faces and part bodies.
outcome	api_terminate_stitching ()
	Terminates the Stitch Component library.
proc_stitch_progress_callback	get_stitch_progress_callback ()
	Function for getting the stitch progress callback pointer.
void	set_stitch_progress_callback (proc_stitch_progress_callback callback_func_ptr)
	Function for setting the stitch progress callback pointer.

Detailed Description

Stitch or sew separate faces together to form a sheet or solid body.

Typedef Documentation

typedef int(* proc_stitch_progress_callback)(stitch_progress_info *)

Function pointer to implement stitch progress meter.

Enumeration Type Documentation

enum STITCH_COIN_MODES

Specifies how a stitching operation handles coincident faces.

Parameters:

	SPASTITCH_COIN_ERROR	Throw an error if coincident faces are found.
	SPASTITCH_COIN_STITCH	Stitch pairs of coincident faces.
	SPASTITCH_COIN_SKIP	Do not stitch pairs of coincident faces.

include <stchapi.hxx>

enum STITCH_TYPE

Specifies the type of stitching to be performed by the stitching operation.

Parameters:

	TOLERANT_STITCH_TYPE	Perform tolerant stitching.
	EXACT_STITCH_TYPE	Perform exact stitching.
	EDGE_TOLERANT_STITCH_TYPE	Perform tolerant stitching on a user-specified list of edges.

include <stchapi.hxx>

Function Documentation

outcome api_check_and_fix_tedge	(	TEDGE *	tedge,
		logical &	fixed,
		logical &	already_good,
		tedge_repair_options *	tedrepopts = `NULL`,
		AcisOptions *	aopts = `NULL`
	)

Attempts to repair level 30 check errors in TEDGEs.

Role: api_check_and_fix_tedge attempts to fix level 30 check errors in TEDGEs but does not guarantee that these errors will be fixed. The repairing operation will be limited to modifying the ingredients of the TEDGE, its TCOEDGEs and its TVERTEXes. After the repairing operation, if the API detects one or more level 30 check errors in the modified TEDGE, then the API will reinstate the original state of the TEDGE, its TCOEDGEs and its TVERTEXes.
Presently, the API has the capability to fix the following types of errors.

 1.	TCOEDGE and TEDGE geometry appear to be incompatible.		TOL_GEOM_INCOMPATIBLE
 2.	Geometry at start of TCOEDGE and TEDGE appear inconsistent.	START_INCONS_TOL_GEOM
 3.	Geometry at end of TCOEDGE and TEDGE appear inconsistent.	END_INCONS_TOL_GEOM

The first argument tedge is the pointer to the TEDGE that is to be repaired.

The second argument fixed is a logical (by reference). The API puts TRUE in this logical if the resultant TEDGE has no check errors at level 30 (this could be TRUE either because the incoming TEDGE was already good at level 30 or because the API successfully repaired the TEDGE). The API puts FALSE in this logical if the API could not repair the level 30 check error in the TEDGE.

The third argument already_good is a logical (by reference). The API puts TRUE in this logical if the incoming TEDGE was already good at level 30.

The fourth argument takes a pointer to an object of class tedge_repair_options. At the moment, this is a blank class that has been defined and added from the futuristic point of view in order to make it easier to introduce options that can be passed to the API.

The fifth argument is a pointer to an AcisOptions class object. This has a default value of NULL.

Journal: Available

Parameters:

	tedge	TEDGE to repair
	fixed	logical to denote if tedge was repaired.
	already_good	logical to denote TEDGE already good at level 30.
	tedrepopts	configuration information
	aopts	ACIS options

See also:: tedge_repair_options

include <tedrepapi.hxx>

outcome api_initialize_stitching ( )

Initializes the Stitch Component library.

Effect: System routine

Journal: Not Available

include <stchapi.hxx>

outcome api_stitch	(	const ENTITY_LIST &	to_be_stitched,
		ENTITY_LIST &	output_bodies,
		ENTITY_LIST &	new_bodies,
		stitch_options *	sopts,
		AcisOptions *	aopts = `NULL`
	)

Stitches together the given entities.

Role: api_stitch stitches together the given entities based on the mode specified by the stitch_options object given as input.
The three modes are:

EXACT_STITCH
TOLERANT_STITCH
EDGE_TOLERANT_STITCH

Depending on the mode under which this API works the input entities may be

BODYs
free FACEs
EDGEs

This API also takes an AcisOptions object as input.

The output of this API is a list of bodies. This API returns an outcome object that contains information of errors and problems encountered while stitching.
Refer to the Parameters section below for details of input and output parameters.

The behavior exhibited by the API in each of the three modes is as specified under :-

EXACT_STITCH (Exact Stitching)

An exact_stitch_options object needs to be passed using the stitch_options argument for the API to operate in this mode.

Under this mode, this API accepts only a list of

BODYs

The API stitches edges that are coincident within SPAresabs.

TOLERANT_STITCH (Tolerant Stitching)

A tolerant_stitch_options object needs to be passed using the stitch_options argument for API to operate in this mode.

Under this mode, this API accepts a list of

BODYs
free FACEs .
or a combination of both .

NOTE :- 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. However, we recommend that this API be passed only BODYs.

The API stitches edges that are close within the user specified tolerance. The Maximum Stitch Tolerance section elaborates the importance of the user specified tolerance.

Under this mode, the API:

Performs stitching based on the NM_PROCESSING_MODE set in tolerant_stitch_options object.
During manifold stitching, the API makes DOUBLE_SIDED faces for an output sheet body and SINGLE_SIDED faces for an output solid body.
Refer the technical article for properties of output bodies during non-manifold stitching.
Detects coincident (back-to-back) and partially coincident faces during stitching. This detection depends on the coincident face detection mode set in tolerant_stitch_options object. The Coincident Face Detection section elaborates the various coincident face detection modes.
Removes zero-area faces lying in the regions that are likely to be stitched.
Adjusts the orientation of faces by reversing the coedges in its loops. This may be needed in order to have consistent face normal directions across adjacent faces and also to have face normals point away from material side in solids.
Orients and rearranges shells to solve shell containments. A flag controls whether this API is allowed to make void shells or not. The Shell Containment Solving section elaborates on the behavior of this API.

EDGE_TOLERANT_STITCH (Restricted Tolerant Stitching)

An edge_tolstitch_options object needs to be is passed using the stitch_options argument for API to operate in this mode.

Under this mode, this API accepts a list of

EDGEs

Only the EDGEs appearing in the list are chosen as candidates for stitching.

While performing manifold sticthing, this API accepts only free EDGEs. A free EDGE is an edge that is associated with only one FACE and hence, has only one COEDGE. Furthermore, the top-level owner of each given free EDGE should either be a free FACE or should be a BODY.

While performing non-manifold stitching, this API accepts EDGEs that are associated with one or more FACE(s) .

The functional behavior of this API under this mode is the same as that in tolerant_stitch mode.

There is just one subtle difference; in restricted tolerant stitching, adjustment of face normals and rearrangement of shells is controlled by a flag. By default, the face normals are adjusted so that the stitched model is not void. If you are confident that all the face normals on the incoming faces are already correct, then this functionality can be switched off by using the flag. If this functionality is switched off, the flag to allow this API to make void shells will have no impact. This API will not change the orientation of the shells.

Shell Containment Solving

api_stitch orients and rearranges the shells to solve shell containments. Refer to the topic Shell Containment Solving in the Tolerant Stitching Technical Article for details on how stitching rearranges shells in the body(s).
A flag controls whether this API shall be allowed to make void shells or not. This API, by default, is allowed to make void shells. If this API is not allowed to make void shells, then the output shall not contain void shells. All shells in the output will be peripheral shells. New bodies shall be made in this case, if required. For details on how to set this flag, refer to documentation of tolerant_stitch_options.

Caution: The shell solving mechanism assumes that every shell would either be completely inside or completely outside another shell. If shells partially intersect, then the output of the shell solving is unpredictable. Thus, if you are not sure if the shells are going to have a clean containment, then we advise that you disallow stitching from returning void shells.

Maximum Stitch Tolerance

In TOLERANT_STITCH and EDGE_TOLERANT_STITCH mode, you can specify the maximum stitch tolerance value by setting the max_stitch_tol parameter in the corresponding stitch_options object. For details of how to set this parameter, refer to documentation for tolerant_stitch_options.

Accepatable values of max_stitch_tol parameter:-

more than or equal to SPAresabs.

Unaccepatable values of max_stitch_tol parameter:-

less than SPAresabs. The API will fail with an error INVALID_STITCH_MAX_TOL and the state of the model will roll back to its initial state.

Recommended values of max_stitch_tol parameter:-

Smaller than the minimum feature size and greater than the maximum gap to be stitched in the model.

Since the API removes edges that are smaller than max_stitch_tol parameter, if the max_stitch_tol value happens to be greater than the minimum feature size this API may remove edges that should have been kept. Also note that if that maximum gap is greater than the minimum feature size in the model, this API might face problems during stitching.

If the max_stitch_tol is not set, the API internally uses heuristics to set up the necessary internally used stitch tolerances.

The only way to specify the max_stitch_tol parameter to this API is through tolerant_stitch_options. In TOLERANT_STITCH and EDGE_TOLERANT_STITCH mode, this API internally uses heuristics to set up the necessary internally used stitch tolerances. For more details refer to the Stitching Tolerances portion of the Healing Tolerances documentation.

Coincident Face Detection

This API detects coincident (back-to-back) and partially coincident faces during stitching. This detection depends on the coincident face detection mode set in tolerant_stitch_options or edge_tolstitch_options object passed to this API. The API is not guaranteed to detect all coincident faces. It detects coincident faces only if it encounters them in the process of stitching. The coincident faces are recorded and returned as coincident face clusters.

For example, if face A is coincident with face B, and face A is coincident with face C, then faces A, B, C form one cluster. The exact methods to obtain the clusters of coincident faces can be found in the description of tolerant_stitch_options class.

If api_stitch comes across a pair of coincident faces while attempting to stitch these faces along an edge, the behavior of the API in the three different modes is as given below

SPASTITCH_COIN_SKIP mode: Under this option, if api_stitch comes across a pair of coincident faces,
- The two faces are not stitched together along the edge.
- The coincident face pair is recorded internally and these are returned as one or more face-clusters each of which contains a set of coincident faces detected during stitching.
- A warning of COINCIDENT_FACE is thrown.
- Once a coincident pair is detected and recorded, stitching continues.
Although coincident faces are not stitched to each other in this mode, the coincident faces may be stitched independently to other faces. Hence, the coincident faces may ultimately belong to the same body after stitching. This can result in an invalid body. You may obtain information about coincident faces after the first call to api_stitch and manage it appropriately. For more details, refer to the section Recommended Healing Workflow.
SPASTITCH_COIN_STITCH mode: Under this option
- The two faces are stitched together along the edge.
- The coincident face pair is recorded internally and these are returned as one or more face-clusters each of which contains a set of coincident faces detected during stitching.
- A warning of COINCIDENT_FACE is thrown.
- Once a coincident pair is stitched and recorded, stitching continues.
Because this produces back-to-back stitched faces or partially stitched faces, it is likely downstream ACIS operations will fail; therefore, this mode is strongly discouraged.
SPASTITCH_COIN_ERROR mode: Under this option
- The API will immediately return with the error COINCIDENT_FACE.
- The state of the model is rolled back to the unstitched state.

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. Such faces are stitched but reported in the outcome as a "nearly coincident faces" problem encountered by this API. For more details, refer to the section Coincident Faces Detection.

Note: For information on how SPASTITCH_COIN_SKIP, SPASTITCH_COIN_STITCH, and SPASTITCH_COIN_ERROR modes interact with careful global option, refer to the section Failsafe Behavior of this API.

Failsafe Behavior

The API, api_stitch , has a failsafe behavior (for example, this API attempts to do as much as possible and not fail, even in cases when it encounters geometry and topology related errors). On an event of a recoverable error, this API undoes the current atomic transaction that failed due to this error, raises a sys_warning with the same error message, and proceeds further.
The failsafe behavior of this API does not apply to "irrecoverable" errors, such as:

INVALID_STITCH_MAX_TOL
COINCIDENT_FACES (in SPASTITCH_COIN_ERROR mode)
INPUT_NOT_AN_EDGE
EDGE_ALREADY_STITCHED
EDGE_HAS_NO_FACE
NOTHING_TO_STITCH
FACE_WITH_OWNER
UNACCEPTABLE_ENTITY
IMPROPER_STITCH_OPTION
EDGE_HAS_FACE_WITH_NO_BODY

These errors tend to indicate a programmatic mistake in the parameters being passed into this API, rather than geometric or topological errors in the bodies being stitched. Note that the failsafe behavior can be switched OFF by pushing a value of TRUE onto the global option careful before calling api_stitch (and popping it after the call). When the failsafe behavior is switched off, this API will fail and roll back to its initial state when the first error is encountered.

Coincident faces detection by this API also has a failsafe behavior. This API will roll when coincident faces are detected and careful option is set to TRUE.
When careful is TRUE, this API will behave as given:

SPASTITCH_COIN_ERROR mode - This API will roll and exit immediately.
SPASTITCH_COIN_SKIP and SPASTITCH_COIN_STITCH modes - It will record the coincident face information and continue stitching and roll the model back to its initial state before exiting. This API keeps the model unstitched, but provides the coincident face information.

When the careful option is set to FALSE, this API will behave as given:

SPASTITCH_COIN_ERROR mode - This API will roll the model back to its initial state.

Outcome of api_stitch and Problem Reporting

You can determine the result of this API using the following:

If outcome::encountered_errors() returns FALSE, then this API has fully succeeded; that is, errors were not encountered.
If outcome::encountered_errors() returns TRUE, and outcome::ok() returns TRUE, then this API has encountered error(s), yet it proceeded further successfully. In this case, the bodies in the output_bodies list are not guaranteed to be usable for further modelling operations.
If outcome::ok() returns FALSE, then this API has failed and rolled the model back to the state before this API was called.

This API puts information about any error or problem that it encounters during its operation into the outcome returned. For more details, refer to the documentation of outcome and the section Failsafe Behavior. This API reports following errors and problems:

Errors

Input list has an entity which is not an EDGE
Input edge is already stitched
Input edge is not connected to any face
Input edges have stitch attributes already
Coincident faces found
Stitch max tol less than SPAresabs
Nonmanifold edges encountered
Invalid topology encountered
Unsupported topology encountered
Nothing to stitch
Improper stitch_option
Encountered face with owner
Top level owner of EDGE is neither a FACE nor a BODY
Shell not peripheral
Shell reversal failed
Shell containment check failed
Shell orientation check failed
Free face contains information of other faces

Problems

Nearly coincident faces

Limitations

In EXACT_STITCH mode, this API will operate only on BODYs.
In TOLERANT_STITCH mode, this API 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. It is recommended, however, that this API be passed only BODYs.
In EDGE_TOLERANT_STITCH mode, this API will operate only on free EDGEs. A free EDGE is an edge that is associated with only one FACE and hence has only one COEDGE. Further the top level owner of each given free or solid EDGE should either be a free FACE or should be a BODY.
If FACEs to be stitched are intended to become multiple partially or fully overlapping BODYs (for example, connected parts in an assembly), the FACEs for each BODY should be separately sent to this API. If all the FACEs are passed together to this API, then the behavior of API is unpredictable. This holds true for all modes of stitching.
During non-manifold stitching, this API does not handle sidedness and containment accurately. This API never marks any DOUBLE_SIDED face as BOTH_INSIDE. If you intend to stitch a model to make an internal partition embedded in a solid, then although this API will stitch the faces, it will not get the containment correct. So such a stitched model will report check errors. In order to correct such a model, manually set the containment of the internal partition faces to BOTH_INSIDE.
If maximum gap is greater than the minimum feature size in the model, this API might face problems during stitching. For details, refer to the section Maximum Stitch Tolerance.

Effect:
Changes model. This API may remove edges smaller than maximum stitch tolerance and faces with zero area. This API may also split incoming edges in the process of stitching.

Journal: Available

Product(s): 3D InterOp ACIS Healing

Parameters:

	to_be_stitched	This is an input argument. In `EXACT_STITCH` mode, `to_be_stitched` should contain only pointers to `BODYs`. In `TOLERANT_STITCH` mode, `to_be_stitched` should contain only pointers to `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 accepts them as "construction topology." It is recommended, however, that the API be passed only `BODYs`. In `EDGE_TOLERANT_STITCH` mode, `to_be_stitched` should contain only pointers to free `EDGEs`. A free `EDGE` is an edge that is associated with only one `FACE` and hence has only one `COEDGE`. Further the top level owner of each given free `EDGE` should either be a free `FACE` or a `BODY`.
	output_bodies	This is an output argument. The output from this API is only bodies, which will be returned in `output_bodies`. This is the complete set of bodies that belong to the user. In `TOLERANT_STITCH` mode and `EDGE_TOLERANT_STITCH` mode, if free `FACEs` are passed into the API, then the API will wrap these free `FACEs` in new `BODYs`, which will also be returned in the `output_bodies` list. Note that any new `BODYs` created by the API will also be returned back in the `new_bodies` list.
	new_bodies	This is an output argument. `new_bodies` will contain all the new bodies resulting from the API. This list will be a subset of `output_bodies`. This list is provided so that it is convenient to the user to find out the new bodies that the user will have to take ownership of (for example, the users may have to register new bodies in their application and/or do memory management for those).
	sopts	This is an input argument. `sopts` encapsulates optional user parameters that govern the behavior of `api_stitch`. `sopts` must be a pointer to a valid object of either of class `exact_stitch_options`, or class `tolerant_stitch_options` or class `edge_tolstitch_options`. The object defines the mode of api_stitch. The API operates in the `EXACT_STITCH` mode for an `exact_stitch_options` object. The API operates in the `TOLERANT_STITCH` mode for a `tolerant_stitch_options` object. The API operates in the `EDGE_TOLERANT_STITCH` mode for an `edge_tolstitch_options` object There are different options available in each of these sub-classes of class `stitch_options`, for the different modes ofstitching. This argument `sopts` cannot be passed in as a `NULL` pointer. Further class `tolerant_stitch_options` or class `edge_tolstitch_options` also support methods to query coincident-faces related information, if needed, after the API completes.
	aopts	ACIS options.

See also:: stitch_options, edge_tolstitch_options, exact_stitch_options, tolerant_stitch_options

include <stchapi.hxx>

outcome api_stitch_nonmanifold	(	const ENTITY_LIST &	parting_faces,
		const ENTITY_LIST &	primary_bodies,
		ENTITY_LIST &	output_bodies,
		ENTITY_LIST &	new_bodies,
		tolerant_stitch_options *	sopts,
		AcisOptions *	aopts = `NULL`
	)

Performs tolerant, non-manifold stitching between parting faces and part bodies.

This API specifically supports mold and die design processes.

Role: This API performs non-manifold stitching between parting faces and primary bodies.

This API accepts parting faces in the parting_faces list and primary bodies in the primary_bodies list. You can pass free FACEs or sheet BODYs (containing one or more faces) as parting faces, although it is recommended that they be passed as sheet BODYs (even if they contain single faces), because free FACEs are not legal in ACIS.
This API performs manifold and non-manifold stitching among the parting faces.
This API performs manifold and non-manifold stitching between the parting faces and the primary bodies.
This API does not perform any stitching among the primary bodies or within any given primary body; if entities that are intended to be primary bodies need to be stitched, they should be stitched using api_stitch before calling api_stitch_nonmanifold. The parting_faces list cannot be empty. If you supply an empty parting_faces list, then the API reports back the error "Parting face list is empty". However, the primary_bodies list may be empty, in which case the API proceeds to stitch only the parting faces.

Refer to the topic Non-manifold Stitching in the Tolerant Stitching Technical Article for an example of a primary body with its parting faces.

Maximum Stitch Tolerance

You can specify the maximum stitch tolerance value by setting the max_stitch_tol parameter in the tolerant_stitch_options object. For details on how to set this parameter, refer to the tolerant_stitch_options documentation.

You may set the max_stitch_tol parameter to a value more than or equal to SPAresabs. If you set the maximum stitch tolerance to a value less than SPAresabs, then the API will fail with an error INVALID_STITCH_MAX_TOL and the state of the model will roll back to its initial state. The only way to specify the max_stitch_tol parameter to the API is through tolerant_stitch_options. If you do not set any value in max_stitch_tol, then the API uses heuristics to choose a max_stitch_tol by itself. However, this choice may not be suitable to the entities being stitched. The API may remove small (sliver) edges smaller than the max_stitch_tol parameter. Hence you are strongly recommended to set the max_stitch_tol parameter to be smaller than the minimum feature size and greater than the maximum gap to be stitched in the model. Note that if maximum gap is greater than the minimum feature size in the model, this API might face problems during stitching. Refer to the topic Stitching in the Technical Articles for details on the internal tolerances used by the stitching algorithm.

Coincident Face Detection

The API, api_stitch_nonmanifold , detects coincident (back-to-back) and partially coincident faces during stitching. This detection depends on the coincident face detection mode set in tolerant_stitch_options object. api_stitch_nonmanifold is not guaranteed to detect all coincident faces. It detects coincident faces only if it encounters them in the process of stitching.The detection and processing of the coincident faces by this API depends upon the mode set in tolerant_stitch_options object passed to this API. The behavior under different modes is as mentioned below:

SPASTITCH_COIN_SKIP mode: Under this option, while attempting to stitch a pair of faces along an edge, if api_stitch_nonmanifold comes across a pair of coincident faces, it will not stitch the two faces together along the edge, and stitching continues. The coincident face pair is recorded internally, and this API throws a warning of COINCIDENT_FACE. This API optionally returns a list of one or more face-clusters, each of which contains a set of coincident faces detected during stitching. For example, if face A is coincident with face B, and face A is coincident with face C, then faces A, B, C form one cluster. The exact methods to obtain the clusters of coincident faces can be found in the description of tolerant_stitch_options class.
SPASTITCH_COIN_STITCH mode: Under this option, while attempting to stitch a pair of faces along an edge, if api_stitch_nonmanifold comes across a pair of coincident faces, it will stitch the two faces together along the edge, and stitching continues. The coincident face pair is recorded internally, and this API throws a warning of COINCIDENT_FACE. This API optionally returns a list of one or more face-clusters, each of which contains a set of coincident faces detected during stitching. For example, if face A is coincident with face B, and face A coincident with face C, then faces A, B, C form one cluster. The exact methods to obtain the clusters of coincident faces can be found in the description of the tolerant_stitch_options class. Because this produces back-to-back stitched faces, it is likely downstream ACIS operations will fail; therefore, this mode is strongly discouraged.
SPASTITCH_COIN_ERROR mode: Under this option, while attempting to stitch a pair of faces along an edge, if api_stitch_nonmanifold comes across a pair of coincident faces, it will immediately return with the error COINCIDENT_FACE. The state of the model is rolled back to the unstitched state.

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. Such faces are stitched, but reported in the outcome as a "nearly coincident faces" problem encountered by this API. For more details, refer to the topic Coincident Face Detection in the Tolerant Stitching Technical Article.

Note: For information on how SPASTITCH_COIN_SKIP, SPASTITCH_COIN_STITCH and SPASTITCH_COIN_ERROR modes interact with the careful global option, refer to the section Failsafe Behavior below.

Shell Containment Solving

This API orients and rearranges the shells to solve shell containments. Refer to the topic Shell Containment Solving in the Tolerant Stitching Technical Article for details about how stitching rearranges shells in the body(s). A flag controls whether this API is allowed to make void shells. This API, by default, is allowed to make void shells. If it is not allowed to make void shells, then the output will not contain void shells. All shells in the output will be peripheral shells. New bodies will be made in this case, if required. For details on how to set this flag, refer to tolerant_stitch_options documentation.

Caution:

The shell solving mechanism assumes that every shell would either be 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 we advise that you disallow stitching from returning void shells.
This API marks all the faces of the incoming solid bodies SINGLE_SIDED. The faces of the incoming sheet bodies are marked DOUBLE_SIDED with containment as BOTH_OUTSIDE. Refer to the section Limitations below.

Failsafe Behavior

The API, api_stitch_nonmanifold , has a failsafe behavior (for example, this API will attempt to do as much as possible and not fail, even in cases when it encounters geometry and topology related errors). On an event of a recoverable error, this API will undo the current atomic transaction that failed due to this error, raise a sys_warning with the same error message, and proceed further.
The failsafe behavior of this API does not apply to "irrecoverable" errors, such as:

INVALID_STITCH_MAX_TOL
COINCIDENT_FACES (in SPASTITCH_COIN_ERROR mode)
INPUT_NOT_AN_EDGE
NOTHING_TO_STITCH
FACE_WITH_OWNER
UNACCEPTABLE_ENTITY
IMPROPER_STITCH_OPTION
PARTING_FACE_LIST_EMPTY

These errors tend to indicate a programmatic mistake in the parameters being passed into this API, rather than geometric or topological errors in the bodies being stitched. Note that the failsafe behavior can be switched OFF by pushing a value of TRUE onto the global option careful before calling api_stitch_nonmanifold (and popping it after the call). When the failsafe behavior is switched off, this API fails and rolls back to its initial state when the first error is encountered.

Coincident faces detection by this API also has a failsafe behavior. This API rolls when coincident faces are detected and the careful option is set to TRUE.
When careful is TRUE, this API behaves as given:

SPASTITCH_COIN_ERROR mode - This API rolls and exits immediately.
SPASTITCH_COIN_SKIP and SPASTITCH_COIN_STITCH modes - The API records the coincident face information, continues stitching, and rolls the model back to its initial state before exiting. This API keeps the model unstitched, but provides the coincident face information.

When the careful option is set to FALSE, this API behaves as given:

SPASTITCH_COIN_ERROR mode - This API rolls the model back to its initial state.

Outcome of api_stitch and Problem Reporting

You can determine the result of this API using the following:

If outcome::encountered_errors() returns FALSE, then this API has fully succeeded; that is, errors were not encountered.
If outcome::encountered_errors() returns TRUE, and outcome::ok() returns TRUE, this means that this API has encountered error(s), yet it proceeded further successfully. In this case, the bodies in the output_bodies list are not guaranteed to be usable for further modelling operations.
If outcome::ok() returns FALSE, this API has failed and rolled the model back to the state before this API was called.

This API puts information about any error or problem that it encounters during its operation into the outcome returned. For more details, refer to the outcome documentation and the section Failsafe Behavior above. This API reports the following errors and problems:

Errors

Coincident faces found
Stitch max tol less than SPAresabs
Nonmanifold edges encountered
Invalid topology encountered
Unsupported topology encountered
Nothing to stitch
Improper stitch_option
Encountered face with owner
Top level owner of EDGE is neither a FACE nor a BODY
Shell not peripheral
Shell reversal failed
Shell containment check failed
Shell orientation check failed
Free face contains information of other faces
Parting faces list is empty

Problems

Nearly coincident faces

Limitations

This API operates 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 recommend, however, that this API be passed only BODYs.
This API does not support vertex stitching. Refer to the topic Non-manifold Stitching in the Tolerant Stitching Technical Article for an illustration.
This API does not always handle sidedness and containment of faces accurately. If a user provides sheet bodies (or free faces) in parting faces list and 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 the user provides one or more solid bodies (with or without sheet bodies) in the primary bodies list to be stitched with 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.
This API never marks any DOUBLE_SIDED face as BOTH_INSIDE. If you intend to stitch a model to make an internal partition embedded in a solid, then although this API will stitch the faces, it will not get the containment correct. So such a stitched model will report check errors. In order to correct such a model, manually set the containment of the internal partition faces to BOTH_INSIDE. Refer to the topic Non-manifold Stitching in the Tolerant Stitching Technical Article for an illustration.
If maximum gap is greater than the minimum feature size in the model, this API might face problems during stitching. For details, refer to the Maximum Stitch Tolerance section.
The only acceptable non-manifold processing mode in tolerant_stitch_options for this API is NM_STITCH. The API will ignore the non-manifold processing mode in tolerant_stitch_options if set to NM_DETECT or NM_IGNORE. A warning will be issued for this and the API will continue with non-manifold stitching.

Effect:
Changes model. This API may remove edges smaller than maximum stitch tolerance. This API may also split incoming edges in the process of stitching.

Journal: Available

Product(s): 3D InterOp ACIS Healing

Parameters:

	parting_faces	This is an input argument. `parting faces` should contain only pointers to 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. We recommend, however, that the API be passed only BODYs. Refer to the topic Non-manifold Stitching for an illustration of primary body and parting faces.
	primary_bodies	This is an input argument. `primary_bodies` should contain only pointers to BODYs or free FACEs. Refer to the topic Non-manifold Stitching in the Tolerant Stitching Technical Article for an illustration of primary body and parting faces.
	output_bodies	This is an output argument. The output from this API is only bodies, which will be returned in `output_bodies`. This is the complete set of bodies that belongs to the user. Note that any new `BODYs` created by the API will also be returned in the `new_bodies` list.
	new_bodies	This is an output argument. `new_bodies` will contain all the new bodies resulting from the API. This list will be a subset of `output_bodies`. This convenient list allows you to find new bodies of which you may have to take ownership (for example, you may have to register new bodies in your application and/or do memory management for them).
	sopts	This is an input argument. `sopts` encapsulates optional user parameters that govern the behavior of `api_stitch_nonmanifold`. `sopts` must be a pointer to a valid object of class `tolerant_stitch_options`. Further class `tolerant_stitch_options` also support methods to query coincident-faces related information, if needed, after the API completes.
	aopts	ACIS options.

See also:: tolerant_stitch_options

include <stchapi.hxx>

outcome api_terminate_stitching ( )

Terminates the Stitch Component library.

Effect: System routine

Journal: Not Available

include <stchapi.hxx>

proc_stitch_progress_callback get_stitch_progress_callback ( )

Function for getting the stitch progress callback pointer.

Role: The stitch progress callback function pointer can be obtained by get_stitch_progress_callback.

include <stitch_progress_info.hxx>

void set_stitch_progress_callback ( proc_stitch_progress_callback callback_func_ptr )

Function for setting the stitch progress callback pointer.

Role: The callback mechanism is enabled by installing a custom callback function with the set_stitch_progress_callback function. The set_stitch_progress_callback function accepts one argument, which is the custom callback function.

Parameters:

callback_func_ptr

custom callback function pointer.

include <stitch_progress_info.hxx>

Stitching Models

Classes

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation