Tolerant Geometry
[Kernel Functionality]

Collaboration diagram for Tolerant Geometry:


Classes
class	tolerize_entity_opts
	options object for use with api_tolerze_entity <bre> <bf>Role:<> This object allows the user to communicate with the API. More...
Functions
outcome	api_calculate_edge_tolerance (EDGE edge, double &tol, AcisOptions ao=NULL)
	Calculates the tolerance of an edge.
outcome	api_calculate_vertex_tolerance (VERTEX vertex, double &tol, AcisOptions ao=NULL)
	Calculates the tolerance of a vertex.
outcome	api_check_edge_errors (ENTITY_LIST const &edges, ENTITY_LIST &bad_edges, ENTITY &worst_entity, double &worst_error, double tol=SPAresabs, logical stop_immediately=FALSE, ENTITY_LIST &new_edges=(ENTITY_LIST ) NULL_REF, AcisOptions ao=NULL)
	Checks whether `EDGE`s have errors that require them to be made tolerant, and optionally performs this conversion.
outcome	api_check_vertex_errors (ENTITY_LIST const &vertices, ENTITY_LIST &bad_vertices, ENTITY &worst_entity, double &worst_error, double tol=SPAresabs, logical stop_immediately=FALSE, ENTITY_LIST &new_vertices=(ENTITY_LIST ) NULL_REF, AcisOptions ao=NULL)
	Checks the `VERTEX` in the given `ENTITY_LIST` for gaps worse than the specified tolerance.
outcome	api_optimize_tvertex_tolerance (EDGE this_edge, AcisOptions ao=NULL)
	Optimize (minimizes) the `TVERTEX` tolerance at the ends of a `EDGE` or `TEDGE`.
outcome	api_replace_edge_with_tedge (EDGE this_edge, TEDGE &this_tedge, AcisOptions *ao=NULL)
	Replaces an `EDGE` with a tolerant `EDGE` (`TEDGE`).
outcome	api_replace_tedge_with_edge (TEDGE this_tedge, EDGE &this_edge, AcisOptions *ao=NULL)
	Replaces a `TEDGE` with a normal `EDGE`.
outcome	api_replace_tvertex_with_vertex (TVERTEX this_tvertex, VERTEX &this_vertex, AcisOptions *ao=NULL)
	Replaces a `TVERTEX` with a normal `VERTEX`.
outcome	api_replace_vertex_with_tvertex (VERTEX this_vertex, TVERTEX &this_tvertex, AcisOptions *ao=NULL)
	Replaces a `VERTEX` with a tolerant `VERTEX` (`TVERTEX`).
outcome	api_tolerize_entity (ENTITY ent, tolerize_entity_opts opts=NULL, AcisOptions *ao=NULL)
	Tolerizes an entity as needed.
outcome	api_update_tolerance (ENTITY this_entity, logical &updated, AcisOptions ao=NULL)
	Updates the tolerance on an `ENTITY`.

Function Documentation

outcome api_calculate_edge_tolerance	(	EDGE *	edge,
		double &	tol,
		AcisOptions *	ao = `NULL`
	)

Calculates the tolerance of an edge.

Role: This function calculates the tolerance of an EDGE or a TEDGE and returns a tolerance value. It does not use the tolerance value on the TEDGE.

Effect: System routine

Journal: Not Available

Parameters:

	edge	edge to test.
	tol	resulting tolerance.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_calculate_vertex_tolerance	(	VERTEX *	vertex,
		double &	tol,
		AcisOptions *	ao = `NULL`
	)

Calculates the tolerance of a vertex.

Role: This function calculates the tolerance of a VERTEX or a TVERTEX and returns a tolerance value. It does not use the tolerance value on the TVERTEX.

Effect: System routine

Journal: Not Available

Parameters:

	vertex	input vertex / tvertex.
	tol	resulting tolerance.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_check_edge_errors	(	ENTITY_LIST const &	edges,
		ENTITY_LIST &	bad_edges,
		ENTITY *&	worst_entity,
		double &	worst_error,
		double	tol = `SPAresabs`,
		logical	stop_immediately = `FALSE`,
		ENTITY_LIST &	new_edges = `(ENTITY_LIST ) NULL_REF`,
		AcisOptions *	ao = `NULL`
	)

Checks whether EDGEs have errors that require them to be made tolerant, and optionally performs this conversion.

Role: Checks the EDGEs in the given ENTITY_LIST for gaps worse than the specified tolerance. Any such EDGEs are added to the bad_edges list. If new_edges is given, such EDGEs are converted into TEDGEs, and the related VERTEX are converted to TVERTEX if necessary. It is essential that on spherical faces, edges be split at pole crossings before calling api_check_edge_errors. This is done using the api api_split_edges_at_poles.

The bad_edges and new_edges lists are mapped so that bad_edges[i] is converted into new_edges[i].

If the stop_immediately flag is TRUE, processing stops after the first bad edge is found.

The worst_entity and worst_error always get set, even if the error in question was sufficiently small that the entity reported is not actually "bad".

Note that api_check_edge_errors normally converts "bad" EDGEs into tolerant ones. This function is only needed to check for "bad" edges where none of the adjacent edges there needed to be made tolerant.

This API has a fail-safe behavior (i.e. it attempts to do as much as possible and not fail, even in cases when it encounters errors during the operation). This API is broken up internally into atomic operations i.e. checking the error of an individual EDGE and tolerizing it. On an event of a recoverable error this API will undo the current atomic operation that failed due to this error, raise a sys_warning with the same error message, and proceed further. Note that the fail-safe behavior can be switched OFF by pushing a value of TRUE onto the option "careful" before calling this API (and popping it after the call). When the fail-safe behavior is switched off, this API will fail and roll back to its initial state when the first error is encountered.

A user can determine the result of this API using the following:

a. If outcome::encountered_errors() returns FALSE, then the API has fully succeeded. i.e. errors were not encountered.
b. If outcome::encountered_errors() returns TRUE, and outcome::ok() returns TRUE, then it means that the API has encountered error(s), yet it proceeded further successfully. In this case, ENTITY_LIST &new_edges is not guaranteed to be usable and any edges that are not tolerized (due to an error condition) will continue to have gap errors.
c. If outcome::ok() returns FALSE, then the API has failed and rolled the model back to the state before the API was called.

This API puts into the outcome returned, the information about any error or problem that it encounters during its operation. For more details, refer to the documentation of outcome and the technical article.

Effect: Changes model

Journal: Available

Parameters:

	edges	input edges.
	bad_edges	bad edge list.
	worst_entity	worst entity.
	worst_error	worst error.
	tol	given tolerance if TRUE, stop after first bad edge is found.
	stop_immediately	if TRUE, stop after the first bad edge is found.
	new_edges	tolerant edges.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_check_vertex_errors	(	ENTITY_LIST const &	vertices,
		ENTITY_LIST &	bad_vertices,
		ENTITY *&	worst_entity,
		double &	worst_error,
		double	tol = `SPAresabs`,
		logical	stop_immediately = `FALSE`,
		ENTITY_LIST &	new_vertices = `(ENTITY_LIST ) NULL_REF`,
		AcisOptions *	ao = `NULL`
	)

Checks the VERTEX in the given ENTITY_LIST for gaps worse than the specified tolerance.

Role: Checks the vertices in the given list for gaps worse than the specified tolerance. Any such vertices are added to the bad_vertices list. If new_vertices is given, such vertices are converted into tolerant vertices.

The bad_vertices and new_vertices lists are mapped so that bad_vertices[i] is converted into new_vertices[i].

If the stop_immediately flag is TRUE, processing stops after the first bad vertex is found.

The worst_entity and worst_error always get set, even if the error in question was sufficiently small that the entity reported is not actually "bad."

api_check_vertex_errors normally converts "bad" vertices into tolerant ones. This function is only needed to check for "bad" vertices where none of the adjacent edges needed to be made tolerant.

This API has a fail-safe behavior (i.e. it attempts to do as much as possible and not fail, even in cases when it encounters errors during the operation). This API is broken up internally into atomic operations i.e. checking the error of an individual VERTEX and tolerizing it. On an event of a recoverable error this API will undo the current atomic operation that failed due to this error, raise a sys_warning with the same error message, and proceed further. Note that the fail-safe behavior can be switched OFF by pushing a value of TRUE onto the option "careful" before calling this API (and popping it after the call). When the fail-safe behavior is switched off, this API will fail and roll back to its initial state when the first error is encountered.

A user can determine the result of this API using the following:

a. If outcome::encountered_errors() returns FALSE, then the API has fully succeeded. i.e. errors were not encountered.
b. If outcome::encountered_errors() returns TRUE, and outcome::ok() returns TRUE, then it means that the API has encountered error(s), yet it proceeded further successfully. In this case, ENTITY_LIST &new_vertices is not guaranteed to be usable and any vertices that are not tolerized (due to an error condition) will continue to have gap errors.
c. If outcome::ok() returns FALSE, then the API has failed and rolled the model back to the state before the API was called.

This API puts into the outcome returned, the information about any error or problem that it encounters during its operation. For more details, refer to the documentation of outcome and the technical article.

Effect: Changes model

Journal: Not Available

Parameters:

	vertices	input vertex list.
	bad_vertices	bad vertex list.
	worst_entity	worst entity.
	worst_error	worst error.
	tol	given tolerance if TRUE, stop after first bad vertex is found.
	stop_immediately	if TRUE, stop processing after the first bad vertex is found
	new_vertices.	tolerant vertices.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_optimize_tvertex_tolerance	(	EDGE *	this_edge,
		AcisOptions *	ao = `NULL`
	)

Optimize (minimizes) the TVERTEX tolerance at the ends of a EDGE or TEDGE.

Effect: System routine

Journal: Available

Parameters:

	this_edge	edge to optimize.
	ao	ACIS options such as version and journal.

include <kernapi.hxx>

outcome api_replace_edge_with_tedge	(	EDGE *	this_edge,
		TEDGE *&	this_tedge,
		AcisOptions *	ao = `NULL`
	)

Replaces an EDGE with a tolerant EDGE (TEDGE).

Role: Replaces an EDGE and its COEDGE, VERTEX, respectively with a tolerant edge (TEDGE), tolerant coedges (TCOEDGE), and tolerant vertices (TVERTEX).

Effect: Changes model

Journal: Available

Parameters:

	this_edge	edge to replace.
	this_tedge	new tolerant edge.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_replace_tedge_with_edge	(	TEDGE *	this_tedge,
		EDGE *&	this_edge,
		AcisOptions *	ao = `NULL`
	)

Replaces a TEDGE with a normal EDGE.

Role: Replaces a TEDGE and its TCOEDGE and TVERTEX, respectively with a normal EDGE,COEDGE, and VERTEX.

Effect: Changes model

Journal: Available

Parameters:

	this_tedge	tolerant tedge to replace.
	this_edge	new edge.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_replace_tvertex_with_vertex	(	TVERTEX *	this_tvertex,
		VERTEX *&	this_vertex,
		AcisOptions *	ao = `NULL`
	)

Replaces a TVERTEX with a normal VERTEX.

This API does not update the surrounding edges or faces, and may likely cause geometric errors. Spatial recommends that you not employ this API without Technical Support.

Effect: Changes model

Journal: Available

Parameters:

	this_tvertex	tolerant vertex to replace.
	this_vertex	new vertex.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_replace_vertex_with_tvertex	(	VERTEX *	this_vertex,
		TVERTEX *&	this_tvertex,
		AcisOptions *	ao = `NULL`
	)

Replaces a VERTEX with a tolerant VERTEX (TVERTEX).

Role: Replaces a VERTEX with a TVERTEX.

Effect: Changes model

Journal: Available

Parameters:

	this_vertex	vertex to replace.
	this_tvertex	new tolerant vertex.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_tolerize_entity	(	ENTITY *	ent,
		tolerize_entity_opts *	opts = `NULL`,
		AcisOptions *	ao = `NULL`
	)

Tolerizes an entity as needed.

Role: This API finds all the edges and vertices in a part which have gaps larger than resabs and tolerizes them.

The options object allows you to remap pointers, that is, to look up the pointer to the tolerant vertex or edge which replaced a given vertex or edge. This is necessary because when an edge or vertex is tolerized, any pointers to it become stale.

It may be desirable to limit the size of gaps which will be filled in by tolerization, for example, if some edge or vertex has a gap larger than the width of the model. The set_max_gap method of the options object allows you to do this. If an edge or a vertex has a gap exceeding the maximum gap, the outcome returned by the API will have its proceeded_after_errors flag set, and the error_info_list will contain information about which entities this happened to.

You may elect to do tedge repairs after tolerizing by using the set_do_tedge_repair method of the tolerize_entity_opts object. If tedge repair fails, the tedge involved will be reported in the API outcome.

The API has failsafe behavior, that is, if it does not tolerize entities with gaps larger than max_gap, or fails to repair a tedge, bulletin board rollback does not occur.

The API is able to check that tvertex and tedge tolerances exceed the gaps, but this may have a negative performance impact. By default, the API ignores gaps on tolerant vertices and edges. The set_ignore_tentities method of the options object allows you to change this.

Limitations: The output data in the options object is cleared each time the API is called.
If there is an edge in the input model such that the start and end vertices are separated by less distance than the gap attached to the vertices, a model with overlapping tvertices will occur.

Errors: None

Effect: Changes model

Journal: Available

Parameters:

	ent	Specifies the pointer to the entity being tolerized.
	opts	Specifies the tolerize_entity_options object.
	ao	Specifies ACIS options such as versioning and journaling.

include <kernapi.hxx>

outcome api_update_tolerance	(	ENTITY *	this_entity,
		logical &	updated,
		AcisOptions *	ao = `NULL`
	)

Updates the tolerance on an ENTITY.

Role: This function calculates and updates the tolerant topology of the given entity and its children.

Effect: Read-only

Journal: Not Available

Parameters:

	this_entity	entity with tolerance.
	updated	result TRUE is a tolerant entity updated.
	ao	ACIS options.

include <kernapi.hxx>

Tolerant Geometry [Kernel Functionality]

Classes

Functions

Function Documentation

Tolerant Geometry
[Kernel Functionality]