Entity Operations
[Kernel Functionality]

Collaboration diagram for Entity Operations:


Classes
class	ENTITY
	Represents common data and functionality that is mandatory in all classes that are permanent objects in the model. More...
class	entity_and_filter
	Returns `TRUE` if both of its two child filters return `TRUE`. More...
class	entity_binary_filter
	Combines `entity_and_filter` and `entity_or_filter` classes. More...
class	entity_filter
	Provides generic methods and data for all filters. More...
class	entity_handle
	Assembly modeling proxy for an ENTITY object. More...
class	entity_not_filter
	Returns `TRUE` if and only if its child filter returns `FALSE`, and vice versa. More...
class	entity_or_filter
	Returns `TRUE` if either of its two child filters returns `TRUE`. More...
class	entity_test_filter
	Returns `TRUE` if the given C++ test function returns `TRUE`. More...
Typedefs
typedef logical(*	entity_test_proc )(const ENTITY *)
	Procedure which tests an `ENTITY`.
Functions
outcome	api_copy_body (BODY body, BODY &new_body, AcisOptions *ao=NULL)
	Creates a copy of a `BODY`.
outcome	api_copy_entity (ENTITY entity, ENTITY &new_entity, AcisOptions *ao=NULL)
	Creates a copy of an `ENTITY` and all its associated entities.
outcome	api_copy_entity_contents (ENTITY in_ent, ENTITY &copy, const SPAtransf &tr=(const SPAtransf ) NULL_REF, AcisOptions *ao=NULL)
	Creates a copy of an `ENTITY` all its associated subentities.
outcome	api_copy_entity_list (ENTITY_LIST &entity_list, ENTITY_LIST &copied_entity_list, AcisOptions *ao=NULL)
	Creates a copy of all entities in an `ENTITY_LIST` and all their associated entities.
outcome	api_deep_copy_entity (ENTITY entity, ENTITY &new_entity, logical dpcpy_skip=FALSE, AcisOptions *ao=NULL)
	Creates a deep copy of an `ENTITY` and all its associated entities.
outcome	api_deep_copy_entity_list (ENTITY_LIST &entity_list, ENTITY_LIST &new_entity_list, logical dpcpy_skip=FALSE, AcisOptions *ao=NULL)
	Creates a deep copy of all entities in an `ENTITY_LIST` and all their associated entities.
outcome	api_deep_down_copy_entity (ENTITY entity, ENTITY &new_entity, logical dpcpy_skip=FALSE, AcisOptions *ao=NULL)
	Creates a deep (complete) copy of an `ENTITY` and all entities below it in the topology hierarchy.
outcome	api_del_entity (ENTITY given_entity, AcisOptions ao=NULL)
	Deletes the given `ENTITY` and all its associated entities.
outcome	api_del_entity_list (ENTITY_LIST &given_list, AcisOptions *ao=NULL)
	Deletes the entities contained in the given `ENTITY_LIST`.
outcome	api_delent (ENTITY given_entity, AcisOptions ao=NULL)
	Deletes an `ENTITY` and its subentities.
outcome	api_down_copy_entity (ENTITY in_ent, ENTITY &copy, AcisOptions *ao=NULL)
	Creates a copy of an `ENTITY` and all the entities below it in the topology hierarchy.
outcome	api_test_deep_copy (ENTITY_LIST const &entity_list, double numerical_tolerance=SPAresnor, logical report_all_errors=FALSE, char file1=NULL, char file2=NULL, AcisOptions *ao=NULL)
	Tests the deep copy functionality for improper sharing.
outcome	api_test_deep_down_copy (ENTITY_LIST const &entity_list, ENTITY_LIST &return_list, double numerical_tolerance=SPAresnor, logical report_all_errors=FALSE, char file1=NULL, char file2=NULL, AcisOptions *ao=NULL)
	Tests the deep down copy functionality for improper sharing.

Typedef Documentation

typedef logical(* entity_test_proc)(const ENTITY *)

Procedure which tests an ENTITY.

Role: Definition type for a procedure which tests an entity.

include <efilter.hxx>

Function Documentation

outcome api_copy_body	(	BODY *	body,
		BODY *&	new_body,
		AcisOptions *	ao = `NULL`
	)

Creates a copy of a BODY.

Role: Given a BODY as input, copies the given BODY and all its associated ("connected") entities, if any, using each ENTITY's copy and fix-up methods (e.g., copy_scan, copy_data, fix_pointers, etc.). This includes entities that are below the given BODY in the topological hierarchy. For example, copying an BODY copies the LUMPs, SHELLs, FACEs, WIREs, LOOPs, COEDGEs, EDGEs, VERTEXes, etc., as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given BODY is copied.

Errors: The pointer to an original BODY is NULL or does not point to a BODY.

Effect: Changes model

Journal: Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	body	body to be copied.
	new_body	copy returned.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_copy_entity	(	ENTITY *	entity,
		ENTITY *&	new_entity,
		AcisOptions *	ao = `NULL`
	)

Creates a copy of an ENTITY and all its associated entities.

Role: This API copies the given ENTITY and all its associated ("connected") entities, if any, using each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.). This includes entities that are above and below the given entity in the topological hierarchy. For example, copying an EDGE copies the VERTEX, COEDGEs, LOOPs, FACEs, SHELLs, etc., as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given entity is copied.

Note: api_copy_entity copies all entities above and below the input entity, while api_down_copy_entity only copies all entities below the input entity. If api_copy_entity is incorrectly used where api_down_copy_entity is intended, memory requirements could become unnecessarily and adversely large.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Input entity is NULL.

Effect: Changes model

Journal: Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity	entity to be copied.
	new_entity	copy returned.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy

include <kernapi.hxx>

outcome api_copy_entity_contents	(	ENTITY *	in_ent,
		ENTITY *&	copy,
		const SPAtransf &	tr = `(const SPAtransf ) NULL_REF`,
		AcisOptions *	ao = `NULL`
	)

Creates a copy of an ENTITY all its associated subentities.

Role: This API copies the given ENTITY and all its associated subentities, if any. Subentities are those that are below the given ENTITY in the topological hierarchy. It does not copy entities that are above the given ENTITY. The optional transformation is applied to the copied entity, if applicable.

Note: This special-case function only operates on VERTEX, EDGE, COEDGE, WIRE, LOOP, FACE, SHELL, and LUMP entities; for all other entity types, it calls api_copy_entity.

Note: api_copy_entity copies all entities above and below the input entity, while api_copy_entity_contents only copies all entities below the input entity. If api_copy_entity is incorrectly used where api_copy_entity_contents is intended, memory requirements could become unnecessarily and adversely large.

Important: This function was deprecated in R16. The API has been replaced by api_down_copy_entity.

Errors: The pointer to an original entity is NULL.

Effect: Changes model

Journal: Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	in_ent	entity to be copied.
	copy	copy returned.
	tr	optional transformation.
	ao	ACIS options.

See also:: api_copy_entity, api_deep_copy_entity

include <kernapi.hxx>

outcome api_copy_entity_list	(	ENTITY_LIST &	entity_list,
		ENTITY_LIST &	copied_entity_list,
		AcisOptions *	ao = `NULL`
	)

Creates a copy of all entities in an ENTITY_LIST and all their associated entities.

Role: This API copies the entities in the given ENTITY_LIST and all their associated ("connected") entities, if any, using each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.). This includes entities that are above and below the given entity in the topological hierarchy. For example, copying an EDGE copies the VERTEX, COEDGEs, LOOPs, FACE, SHELLs, etc., as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given entities are copied. The returned entity list's entities are in the same order as the given ENTITY_LIST.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Input list is empty.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity_list	list to copy.
	copied_entity_list	copy returned.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy_entity

include <kernapi.hxx>

outcome api_deep_copy_entity	(	ENTITY *	entity,
		ENTITY *&	new_entity,
		logical	dpcpy_skip = `FALSE`,
		AcisOptions *	ao = `NULL`
	)

Creates a deep copy of an ENTITY and all its associated entities.

Role: This API deep copies the given ENTITY and all its associated (connected) entities, if any, using each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.). The difference between a deep copy and a regular copy is that a regular copy may contain references to shared underlying associated entities, but a deep copy will not. This includes entities that are above and below the given entity in the topological hierarchy. For example, deep copying an EDGE deep copies the VERTEX, COEDGEs, LOOPs, FACEs, SHELLs, etc., as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given entity is deep copied.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Attempting to copy an entity that has associated entities that does not support a deep copy routine. The NULL pointer is given to the entity.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity	entity to copy.
	new_entity	deep copy returned.
	dpcpy_skip	flag to skip attributes not deep-copyable.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy_entity

include <kernapi.hxx>

outcome api_deep_copy_entity_list	(	ENTITY_LIST &	entity_list,
		ENTITY_LIST &	new_entity_list,
		logical	dpcpy_skip = `FALSE`,
		AcisOptions *	ao = `NULL`
	)

Creates a deep copy of all entities in an ENTITY_LIST and all their associated entities.

Role: This API deep copies the entities in the given ENTITY_LIST and all their associated (connected) entities, if any, using each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.). The difference between a deep copy and a regular copy is that a regular copy may contain references to shared underlying associated entities, but a deep copy will not. This includes entities that are above and below the given entity in the topological hierarchy. For example, deep copying an EDGE deep copies the VERTEX, COEDGEs, LOOPs, FACEs, SHELLs, etc. , as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given entities are deep copied. The returned ENTITY_LIST's entities are in the same order as the given ENTITY_LIST.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Attempting to copy an entity that has associated entities that does not support a deep copy routine.

The entity_list is empty.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity_list	entities to copy.
	new_entity_list	copies returned.
	dpcpy_skip	flag to skip attributes not deep-copyable.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy_entity

include <kernapi.hxx>

outcome api_deep_down_copy_entity	(	ENTITY *	entity,
		ENTITY *&	new_entity,
		logical	dpcpy_skip = `FALSE`,
		AcisOptions *	ao = `NULL`
	)

Creates a deep (complete) copy of an ENTITY and all entities below it in the topology hierarchy.

Role: This API deep copies the given ENTITY and all its associated ("connected") entities below it in the topology hierarchy. Like api_copy_entity, it uses each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.).

The difference between a deep copy and a regular copy is that a regular copy may contain references to shared underlying associated entities, but a deep copy will not.

The difference between a down copy and a regular copy is that a regular copy will copy all entities connected both up and down the topological heirarchy, but a down copy will only copy connected entities below the input entity.

For example, deep copying a FACE deep copies the LOOPs, COEDGEs, EDGEs, and VERTEXs, as well as all the associated curves, points, attributes, etc. If there are no associated entities, only the given entity is deep copied.

Note: Unlike api_copy_entity, attributes are not automatically copied (via their copy_data). Instead, attributes are notified that their owner was copied using their copy_owner method. This is a required and intentional difference of behavior; attributes are not part of the ACIS topology and therefore do not know how to be "down-copied". Granted, simple attributes could be automatically included in a down-copy; it is complex attributes (attributes that point at entities other than their owner) that are unable to down-copy.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Attempting to copy an entity that has associated entities that do not support a deep copy routine. The NULL pointer is given to the entity.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity	entity to copy.
	new_entity	deep copy returned.
	dpcpy_skip	flag to skip attributes not deep-copyable.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy_entity

include <kernapi.hxx>

outcome api_del_entity	(	ENTITY *	given_entity,
		AcisOptions *	ao = `NULL`
	)

Deletes the given ENTITY and all its associated entities.

Role: This API deletes an ENTITY and all its associated entities. This loses all entities that are connected to the given entity. It will lose multiple BODYs if they are connected by attributes. It does not affect any pointers that were pointing to any of the objects. This allows you to delete an entire entity from anywhere in the entity's topological hierarchy without having to traverse to the top of the topology chain.

Note: Deletes entities above as well as below the specified entity in the hierarchy.

Errors: Pointer to the entity is NULL.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	given_entity	entity to be deleted.
	ao	ACIS options.

See also:: api_delent

include <kernapi.hxx>

outcome api_del_entity_list	(	ENTITY_LIST &	given_list,
		AcisOptions *	ao = `NULL`
	)

Deletes the entities contained in the given ENTITY_LIST.

Role: This API deletes all the entities in an ENTITY_LIST and all their associated entities. This loses all entities that are connected to the given entities. It will lose multiple bodies if they are connected by attributes. It does not affect any pointers that were pointing to any of the objects. This allows deletion of an entire entity from anywhere in the entity's topological hierarchy without having to traverse to the top of the topology chain.

Use this API instead of api_del_entity when you need to delete more than one entity at a time, since calling api_del_entity repeatedly could be dangerous as the user has to keep track of what in the list has already been deleted.

Note: Deletes entities above as well as below the specified entities in the hierarchy.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	given_list	entities to be deleted.
	ao	ACIS options.

See also:: api_del_entity

include <kernapi.hxx>

outcome api_delent	(	ENTITY *	given_entity,
		AcisOptions *	ao = `NULL`
	)

Deletes an ENTITY and its subentities.

Role: This API deletes an ENTITY and all entities below it in the topological hierarchy.

Errors: Pointer to the entity is NULL or not to topology (BODY, LUMP, WIRE, etc.).

Limitations: Pointers above the deleted entity in the topological hierarchy are not guaranteed to be set to NULL. For example, when a lump is deleted, the body pointer to the lump may or may not be set to NULL. This function loses the given topological entity, all lower-level topological entities comprising the given entity, and reduces the use count. It could possibly remove any associated geometry. It does not affect any pointers that were pointing to any of the objects. When using this API, pointers that used to point to the entity need to be fixed, or the item could be unhooked and then deleted.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	given_entity	entity to be deleted.
	ao	ACIS options.

See also:: api_del_entity

include <kernapi.hxx>

outcome api_down_copy_entity	(	ENTITY *	in_ent,
		ENTITY *&	copy,
		AcisOptions *	ao = `NULL`
	)

Creates a copy of an ENTITY and all the entities below it in the topology hierarchy.

Role: This API copies the given ENTITY and all its associated ("connected") entities below it in the topology hierarchy. Like api_copy_entity, it uses each ENTITY's copy and fix-up methods (e.g. copy_scan, copy_data, fix_pointers, etc.).

Note: Unlike api_copy_entity, attributes are not automatically copied (via their copy_data). Instead, attributes are notified that their owner was copied using their copy_owner method. This is a required and intentional difference of behavior; attributes are not part of the ACIS topology and therefore do not know how to be "down-copied". Granted, simple attributes could be automatically included in a down-copy; it is complex attributes (attributes that point at entities other than their owner) that are unable to down-copy.

Note: For additional information on the variations of the entity copying process refer to the Technical Article Copying Objects.

Errors: Input entity is NULL.

Effect: Changes model

Journal: Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	in_ent	entity to be copied.
	copy	copy returned.
	ao	ACIS options.

See also:: api_copy_entity, api_copy_entity_list, api_deep_copy_entity, api_deep_copy_entity_list, api_down_copy_entity

include <kernapi.hxx>

outcome api_test_deep_copy	(	ENTITY_LIST const &	entity_list,
		double	numerical_tolerance = `SPAresnor`,
		logical	report_all_errors = `FALSE`,
		char *	file1 = `NULL`,
		char *	file2 = `NULL`,
		AcisOptions *	ao = `NULL`
	)

Tests the deep copy functionality for improper sharing.

Role: This API deep copies the given list of entities. These entities are saved to SAT files and restored, and then saved out again before and after a deep copy. If this function is called in a debug build, the memory from the original will be pattern filled for additional checking of no sharing after a deep copy. A comparison is done between the two SAT files created : file1.sat (original) and file2.sat (deep copy).

This function is used primarily for internal testing. However, if derived entities are used outside of ACIS, this function can be used to test their deep copy capabilities.

Effect: Changes model

Journal: Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity_list	list of entities to be deep copied.
	numerical_tolerance	tolerance for real value comparisons.
	report_all_errors	flag to skip attributes not deep copyable.
	file1	file of entities saved before deep-copy.
	file2	file of entities saved after deep-copy.
	ao	ACIS options.

include <kernapi.hxx>

outcome api_test_deep_down_copy	(	ENTITY_LIST const &	entity_list,
		ENTITY_LIST &	return_list,
		double	numerical_tolerance = `SPAresnor`,
		logical	report_all_errors = `FALSE`,
		char *	file1 = `NULL`,
		char *	file2 = `NULL`,
		AcisOptions *	ao = `NULL`
	)

Tests the deep down copy functionality for improper sharing.

Role: This API deep copies the given list of entities. These entities are saved to SAT files and restored, and then saved out again before and after a deep copy. If this function is called in an ML build, the memory from the original will be pattern filled for additional checking of no sharing after a deep copy. A comparison is done between the two SAT files created : file1.sat (original) and file2.sat (deep copy). The function also stores the deep down copied entity list in the return_list variable so that the user can perform further checking on it if desired.

This function is used primarily for internal testing. However, if derived entities are used outside of ACIS, this function can be used to test their deep copy capabilities.

Effect: Changes model

Journal: Not Available

Product(s): 3D ACIS Exchange, 3D Viz Exchange, 3D ACIS Modeler

Parameters:

	entity_list	list of entities to be deep copied.
	return_list	copied entity list to return
	numerical_tolerance	tolerance for real value comparisons.
	report_all_errors	flag to skip attributes not deep copyable.
	file1	file of entities saved before deep-copy.
	file2	file of entities saved after deep-copy.
	ao	ACIS options.

include <kernapi.hxx>

Entity Operations [Kernel Functionality]

Classes

Typedefs

Functions

Typedef Documentation

Function Documentation

Entity Operations
[Kernel Functionality]