Entity Managers in Assembly Modeling

Home > User Guide > Implementing ACIS Assembly Modeling in Applications

Entity Managers in Assembly Modeling

A primary aspect of the ACIS Assembly Modeling design is that it allows you to use your own part management system in conjunction with ACIS' assembly modeling system. A part management system is, in essence, a system which groups top-level entities together into a collection of "part" or "document" objects, and manages the collection. Likewise, each part object is responsible for managing its group of entities. Spatial provides (as part of ACIS) a "Part Management" component (SPApart) which contains a part management system that defines the class PART as the object to manage a group of entities. You are not required, however, to use the Part Management component; many customers have implemented their own part management strategies.

Topics include:

Terminology
Association Between Models and Entity Managers
Assembly Models vs Part Models
Virtual Methods
Entity Manager Factories and ASAT Restore
Using Default Entity Manager for "Read-Only" Applications

Terminology

In the following sections, the following terms are used:

client application An ACIS-based application having a part management system implemented. This system may or may not use the ACIS Part Management component.

entity management object An object in the client application’s part management system which manages a group of entities. If the application uses ACIS Part Management, this is an object of type PART.

Note: This is a class object which is defined in client application code; it is NOT an ACIS Assembly Modeling class object.

part document An entity management object which corresponds to a part (as opposed to assembly or sub-assembly) node in the assembly tree.

assembly document An entity management object which corresponds to an assembly node in the assembly tree. This might or might not be of the same class type as a part document object.

entity manager object An object of a class type derived from asm_model_entity_mgr. This is the "bridge" object between the client application's entity management object and ACIS Assembly Modeling. For applications which use ACIS Part Management, Spatial provides the class acis_pm_entity_mgr, which is derived from asm_model_entity_mgr and wraps (has a one-to-one association with) the PART class in the part management component. For applications which use both ACIS Part Management and the HOOPS/ACIS Bridge, Spatial provides the class acis_ha_part_entity_mgr, which is derived from acis_pm_entity_mgr and manages the HOOPS scene graph associated with the assembly’s models.

If you want to use the assembly modeling functionality of ACIS Assembly Modeling and your application does not use ACIS Part Management, you will need to wrap your entity management class (that is, your equivalent of PART) in your own subclass of asm_model_entity_mgr. If you have your own assembly modeling functionality and are only using ACIS Assembly Modeling in order to read or write ASAT files, you will not need to derive your own asm_model_entity_mgr subclass; instead you may use the default_entity_mgr subclass provided by Spatial.

part entities These are entities which are associated with part modeling, rather than assembly modeling, for example, BODY. An entity manager object can manage both part entities and assembly entities. A part document should contain only part entities.

assembly entities These are entities which are specific to ACIS Assembly Modeling, for example, ASM_ASSEMBLY, ASM_MODEL_REF, and the property owner attributes. Among these, only ASM_ASSEMBLY is intended to be top-level. An assembly document should contain an ASM_ASSEMBLY entity. ACIS Assembly Modeling directly supports applications which allow their assembly documents to contain part entities.

Association between Models and Entity Managers

An entity manager object is typically in a one-to-one association with an asm_model object. The exception to the one-to-one relationship occurs when either the asm_model object is not bound to an entity manager or vice-versa. Such a situation is not a fully valid state for either object; this state can occur in the following circumstances:

The typical workflow for a customer to create a new model is for the customer to first create an entity management object, then to create an entity manager wrapping the customer object, and finally to create an asm_model object (using the function asmi_model_create() ) containing the entity manager. The entity manager is created in an unbound state in this workflow.

You can specify with the owned_by_model_vf() method (discussed below) whether an entity manager should be deleted when it is unbound from its asm_model. If the entity manager is not owned by the model, it will be placed into an unbound state in this situation.

During restore, an unbound asm_model object can be created when a problem with the models contents exists:

In atomic restore, the file containing the contents of the model might be unavailable.
The entity manager factory responsible for creating entity managers during a restore might encounter an error condition; this results in unbound model objects.

For these reasons, application code must guard against dereferencing NULL manager and model pointers obtained from model and manager objects, respectively.

Assembly Models vs Part Models

The ACIS Assembly Modeling architecture does not draw a strong distinction between assembly models (which contain an ASM_ASSEMBLY object) and part models (which do not). Because entity manager objects are one-to-one with model objects, little distinction (from the point of view of ACIS Assembly Modeling) exists between an entity manager object wrapping an assembly document and an entity manager object wrapping a part document.

You may use the same or different entity management class types for part and assembly documents with these cautions:

CAUTION:
The set_assembly_ptr_vf() function may be called with a NULL argument by the function asmi_model_del_assembly, which changes the model from an assembly model to a part model. This might cause problems if you want to use different subclasses of asm_model_entity_mgr to wrap part and assembly documents.

CAUTION:
A roll operation which un-deletes a previously deleted ASM_ASSEMBLY entity will turn the model back into an assembly model. Care must be taken to account for this possibility.

Virtual Methods

The asm_model_entity_mgr class (and its subclasses) provides an interface for ACIS Assembly Modeling to communicate with the part and assembly documents being used by the application. asm_model_entity_mgr is the abstract base class whose virtual methods define this interface. In general, these methods will have "protected" access with an "_vf" suffix in the name. The following methods must be implemented by any entity manager subclass:

get_assembly_ptr_vf() This method gets the entity pointer, if any, to the entity manager's assembly object. Your entity management object (or entity manager subclass) is responsible for managing this pointer, including when the assembly object is lost or revived due to history (roll) operations.

set_assembly_ptr_vf() This method (re-)sets the assembly object pointer. Note that this may be called to change an assembly model into a part model (by deleting the assembly) and vice-versa. In this case, it is the entity manager object's responsibility to delete the assembly entity using api_del_entity() or api_del_entity_list()

get_top_level_entities_vf() This is the primary interface for assembly modeling to query for the part entities that are being managed by the entity management object. The caller is required to specify whether the entity management object's ASM_ASSEMBLY entity should be returned as well.

add_entities_vf() This method is called by ACIS Assembly Modeling in two situations, differentiated by the restoring asat flag which is passed into the call:

During ASAT restore, this method is called on a model's entity manager immediately after the model's entities have been restored as part of asmi_restore_model_list(). In this situation, sub-models of the entity manager’s model may have not yet been read in, so this function should merely register the entities with your entity management object and defer any complex processing (such as rendering) until done_restoring_vf() is called. Refer to the section Assembly Modeling Save and Restore for a further discussion of asmi_restore_model_list().
By a call to asm_model::add_entities(). In this situation, the model and its sub-models should all be in a valid state, so that complex processing (such as rendering) can take place immediately.

done_restoring_vf() This method is called on each model’s entity manager at the end of the restore_process, when all models that were successfully restored are in a valid state. This method should be used to complete processing of the entities which were added during restore.

get_history_vf() This method returns a pointer to the document's history stream. This is primarily used during save and restore to determine which models share history. A typical customer application will bind a different history stream to each document, that is, one history stream per model.

get_models_which_share_history_vf This method returns a list of all models (including the manager’s model) which share history with the manager. This method is used during save-with-history to ensure that these models all share the same entity segment. You are not required to override this method, but a failure to do so will result in a much less efficient search being performed which uses get_history_vf().

get_model_info_vf() This method returns a data structure containing information about the application document:

Whether it is an assembly document or a part document
The units associated with the document (for example, mm and inches)
The document's name
The tolerances associated with the document (that is, SPAresabs). Although angular tolerance is provided as a data member of asm_model_info, applications should never reset SPAresnor. The angular tolerance data member is included only for compatibility with the SAT format.

This method is called in two contexts:

The method is written into the entity manager's model's record in the ASAT file.
Units information is used in calculating mass properties, for example, to ensure that physical quantities are rescaled properly from model to model.

clear_vf() This method is called as part of the unbind process which unbinds an entity manager from its model. At a minimum, it should put the customer’s entity management object into a state suitable for part modeling. In particular, it must delete all assembly entities and any backed up copies of these entities which reside in history. It should also delete any entities (and their associated history) that are owned directly by the entity manager (as opposed to the entity management object which it wraps). Entities (including ASM_ASSEMBLY) should be deleted by calling api_del_entity() or api_del_entity_list(); the delta states containing the assembly’s backed up copies can be eliminated by calling api_asm_prune_assembly_history(). You should refer to the source files for the entity managers provided by Spatial, such as default_entity_mgr or acis_pm_entity_mgr to see example implementations of this method.

unbind_vf() This method is called as part of the unbind process which unbinds an entity manager from its model. You do not need to override it; it is intended to give you the opportunity to take further action during the unbind process. For an example, refer to the source file acis_ha_part_entity_mgr.cpp, which uses this opportunity to clean up the HOOPS segments associated with the manager’s model.

owned_by_model_vf() This method is called as part of the unbind process which unbinds an entity manager from its modl. If TRUE is returned, the entity manager will be deleted at the end of unbind().

The following four routines provide the core mechanism for ACIS Assembly Modeling to notify application documents that the mechanism is performing operations on them.

These routines serve two roles:

They allow assembly modeling to request that the entity manager's document be made temporarily active (for example, change history streams, and set units and tolerances).
They allow assembly modeling to notify customer documents that changes have been made to the documents or sub-documents (permitting the document to re-render itself, for example).

nested_activate_vf() This method is called to request that the entity manager's model be made temporarily active. The entity manager is responsible for ensuring that the global history stream, tolerance and units variables are correctly set. The implementation of this method should be very similar to the code that the application executes when changing to a new document through the application interface. A pointer to the previously active model is supplied as an input argument; this pointer will be NULL if this is the outermost call to nested activate. Note that the global history stream should be changed using the nested history mechanism.

entities_changed_vf() This method is called immediately before nested_deactivate_vf() and is intended to inform the document of what changes were made by assembly modeling functionality while the document was active. The outcome of the last API function executed is passed in, along with an event type:

ASM_BREP_GEOM_CHANGE indicates that physical properties of the part entity (as opposed to assembly entity) contents of the document were changed, for example, a Boolean was performed on one of the bodies. The only derived or cached data which needs to be updated is that involving the part entities.
ASM_COMP_GEOM_CHANGE indicates that physical properties of the assembly entity (as opposed to part entity) contents of the document were changed; for example, a model-ref’s transform was moved or a component was suppressed. Cached or derived data associated with the assembly structure needs to be updated.
ASM_BREP_RENDER_CHANGE indicates that physical properties of the part entities were unchanged, but their rendering properties were modified, for example, a color was applied to a BODY.
ASM_COMP_RENDER_CHANGE indicates that physical properties of the assembly were unchanged, but rendering properties were modified, for example, a color or transparency property was added to a component.
ASM_OTHER_CHANGE indicates that physical and rendering properties were unchanged, but some other modification of the document's entities took place, for example, an attribute was added.
ASM_NO_CHANGE indicates that no significant change to the document's contents took place. Note that this does NOT mean that no bulletins will have been generated on the history stream; bulletins may be generated in ACIS by const operations such as boxing due to lazy data being instantiated.

nested_deactivate_vf() This method is called immediately after entities_changed_vf(), and indicates that assembly modeling is done with this set of operations on the document. The entity manager is responsible for ensuring that the global history stream, for example, is reset to the same state it was in before the call to nested_activate_vf(), that is, that the previous document is re-activated. A pointer to the model object that was active before the activate call is provided; if this pointer is NULL, it indicates that this is the outermost deactivation.

sub_model_changed_vf() This method is the mechanism for notifying the parents of a document just de-activated that something has changed in a child. This method is called on the entity managers of all models which have the just de-activated model as a sub-model, and provides a pointer to the model which was de-activated, along with the event type of the change. The intent of this routine is to allow assemblies to re-render themselves (for rendering changes) and/or invalidate cached information about physical properties (for geometric changes).

Entity Manager Factories and ASAT Restore

A major difference between SAT restore and ASAT restore is that, when restoring data from SAT, the application can prepare the document into which the data will be loaded before calling api_restore_entity_list(). This means that the application can perform the following steps:

Create a (part) document.
Call api_restore_entity_list() to read the entities in the part.
Register the restored entities with the document.

When restoring from ASAT, however, the application does not know how many documents need to be created in order to hold the contents of the ASAT file. Multiple documents, in general, are contained within a single ASAT file (or within the atomic files that it references). This means that the ASAT restore routine must choreograph the three steps listed above for each of the documents being restored from the file. Because the documents to be created are application objects, the application must provide some sort of factory method to ACIS Assembly Modeling that asmi_restore_model_list() can call when it needs to create an application document (part or assembly) and its associated entity manager. The interface for this is through an entity manager factory object.

An entity manager factory object is a subclass of the abstract base class entity_mgr_factory. Applications which define a subclass of asm_model_entity_mgr should define a corresponding subclass of entity_mgr_factory, with a create_entity_mgr method which creates an instance of their entity manager object. The create_entity_mgr method provides an asm_model_info object for specifying the parameters of the saved document and a (usually NULL) history stream pointer. If the history stream pointer is non-NULL, then this indicates that the document being created must use that history stream. This occurs if the ASAT file was saved with history. If restoring with history, this will be a pointer to the history stream which was read in from the file. If restoring without history, this will be non-NULL if a document shares history with a preceding model in the file.

Note: This is a subtle difference between ASAT and SAT behavior: saving an ASAT file that was written with history and whose models share history streams is not equivalent, when restored without (that is, ignoring) history, to reading the corresponding ASAT file written without history.

The default entity manager factory is saved as a global variable; this factory can be set and returned by using asmi_set_entity_mgr_factory() and asmi_get_entity_mgr_factory(). If you want to perform a particular restore with a factory other than the default, you can override the default by setting a factory pointer in the asm_restore_options object passed into asmi_restore_model_list(). Note that the ACIS libraries will automatically register the most appropriate factory during ACIS initialization according to which libraries are linked in. For example, if the Part Management component is not linked in, default_entity_mgr_factory will be registered as the global factory. If Part Management is linked in, but HA_Part is not, then acis_pm_entity_mgr_factory will be registered as the global. If HA_Part is linked in, then the global factory will be of type acis_ha_part_entity_mgr.

Using Default Entity Manager for "Read-Only" Applications

Most of the complexity in writing a subclass of asm_model_entity_mgr is involved in passing notifications between the application and ACIS about changes that have been made to the entities associated with a model. Much of this complexity disappears if the application does not modify the contents of models, that is, it is "read-only" on the model contents. An example of such an application might be a viewer application, which only needs to read in the contents of an ASAT file and render them on the screen (and possibly allow simple queries like picking or mass properties). Such applications are likely to have very simple entity management objects; for example, they might just use an ENTITY_LIST to store the entities returned by api_restore_entity_list().

If you are writing such an application (or adding assembly modeling functionality to such and existing application), then you might have your document object wrap a default_entity_mgr object, rather than writing your own asm_model_entity_mgr subclass which wraps your document. The default_entity_mgr object is essentially just an entity manager wrapper for an entity list; it should be easy to replace the ENTITY_LIST used in your application with a default entity_mgr. Note that default_entity_mgr should only be used if your application does not change the contents of model; it was intentionally designed to be a simple container to avoid implementing complex behaviors in the virtual methods which might not be what customers want.

Related topics:

Assembly Modeling Macros and Notification Mechanisms
History and Roll in Assembly Modeling
Implementing Atomic Save and Restore

[Top]

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

client application	An ACIS-based application having a part management system implemented. This system may or may not use the ACIS Part Management component.
entity management object	An object in the client application’s part management system which manages a group of entities. If the application uses ACIS Part Management, this is an object of type `PART`. Note: This is a class object which is defined in client application code; it is NOT an ACIS Assembly Modeling class object.
part document	An entity management object which corresponds to a part (as opposed to assembly or sub-assembly) node in the assembly tree.
assembly document	An entity management object which corresponds to an assembly node in the assembly tree. This might or might not be of the same class type as a part document object.
entity manager object	An object of a class type derived from `asm_model_entity_mgr`. This is the "bridge" object between the client application's entity management object and ACIS Assembly Modeling. For applications which use ACIS Part Management, Spatial provides the class `acis_pm_entity_mgr`, which is derived from `asm_model_entity_mgr` and wraps (has a one-to-one association with) the `PART` class in the part management component. For applications which use both ACIS Part Management and the HOOPS/ACIS Bridge, Spatial provides the class `acis_ha_part_entity_mgr`, which is derived from `acis_pm_entity_mgr` and manages the HOOPS scene graph associated with the assembly’s models. If you want to use the assembly modeling functionality of ACIS Assembly Modeling and your application does not use ACIS Part Management, you will need to wrap your entity management class (that is, your equivalent of `PART`) in your own subclass of `asm_model_entity_mgr`. If you have your own assembly modeling functionality and are only using ACIS Assembly Modeling in order to read or write ASAT files, you will not need to derive your own `asm_model_entity_mgr` subclass; instead you may use the `default_entity_mgr` subclass provided by Spatial.
part entities	These are entities which are associated with part modeling, rather than assembly modeling, for example, `BODY`. An entity manager object can manage both part entities and assembly entities. A part document should contain only part entities.
assembly entities	These are entities which are specific to ACIS Assembly Modeling, for example, `ASM_ASSEMBLY`, `ASM_MODEL_REF`, and the property owner attributes. Among these, only `ASM_ASSEMBLY` is intended to be top-level. An assembly document should contain an `ASM_ASSEMBLY` entity. ACIS Assembly Modeling directly supports applications which allow their assembly documents to contain part entities.

`get_assembly_ptr_vf()`	This method gets the entity pointer, if any, to the entity manager's assembly object. Your entity management object (or entity manager subclass) is responsible for managing this pointer, including when the assembly object is lost or revived due to history (roll) operations.
`set_assembly_ptr_vf()`	This method (re-)sets the assembly object pointer. Note that this may be called to change an assembly model into a part model (by deleting the assembly) and vice-versa. In this case, it is the entity manager object's responsibility to delete the assembly entity using `api_del_entity()` or `api_del_entity_list()`
`get_top_level_entities_vf()`	This is the primary interface for assembly modeling to query for the part entities that are being managed by the entity management object. The caller is required to specify whether the entity management object's `ASM_ASSEMBLY` entity should be returned as well.
`add_entities_vf()`	This method is called by ACIS Assembly Modeling in two situations, differentiated by the restoring asat flag which is passed into the call: During ASAT restore, this method is called on a model's entity manager immediately after the model's entities have been restored as part of `asmi_restore_model_list()`. In this situation, sub-models of the entity manager’s model may have not yet been read in, so this function should merely register the entities with your entity management object and defer any complex processing (such as rendering) until `done_restoring_vf()` is called. Refer to the section Assembly Modeling Save and Restore for a further discussion of `asmi_restore_model_list()`. By a call to `asm_model::add_entities()`. In this situation, the model and its sub-models should all be in a valid state, so that complex processing (such as rendering) can take place immediately.
`done_restoring_vf()`	This method is called on each model’s entity manager at the end of the `restore_process`, when all models that were successfully restored are in a valid state. This method should be used to complete processing of the entities which were added during restore.
`get_history_vf()`	This method returns a pointer to the document's history stream. This is primarily used during save and restore to determine which models share history. A typical customer application will bind a different history stream to each document, that is, one history stream per model.
`get_models_which_share_history_vf`	This method returns a list of all models (including the manager’s model) which share history with the manager. This method is used during save-with-history to ensure that these models all share the same entity segment. You are not required to override this method, but a failure to do so will result in a much less efficient search being performed which uses `get_history_vf()`.
`get_model_info_vf()`	This method returns a data structure containing information about the application document: Whether it is an assembly document or a part document The units associated with the document (for example, mm and inches) The document's name The tolerances associated with the document (that is, SPAresabs). Although angular tolerance is provided as a data member of `asm_model_info`, applications should never reset SPAresnor. The angular tolerance data member is included only for compatibility with the SAT format. This method is called in two contexts: The method is written into the entity manager's model's record in the ASAT file. Units information is used in calculating mass properties, for example, to ensure that physical quantities are rescaled properly from model to model.
`clear_vf()`	This method is called as part of the unbind process which unbinds an entity manager from its model. At a minimum, it should put the customer’s entity management object into a state suitable for part modeling. In particular, it must delete all assembly entities and any backed up copies of these entities which reside in history. It should also delete any entities (and their associated history) that are owned directly by the entity manager (as opposed to the entity management object which it wraps). Entities (including `ASM_ASSEMBLY`) should be deleted by calling `api_del_entity()` or `api_del_entity_list()`; the delta states containing the assembly’s backed up copies can be eliminated by calling `api_asm_prune_assembly_history()`. You should refer to the source files for the entity managers provided by Spatial, such as `default_entity_mgr` or `acis_pm_entity_mgr` to see example implementations of this method.
`unbind_vf()`	This method is called as part of the unbind process which unbinds an entity manager from its model. You do not need to override it; it is intended to give you the opportunity to take further action during the unbind process. For an example, refer to the source file acis_ha_part_entity_mgr.cpp, which uses this opportunity to clean up the HOOPS segments associated with the manager’s model.
`owned_by_model_vf()`	This method is called as part of the unbind process which unbinds an entity manager from its modl. If TRUE is returned, the entity manager will be deleted at the end of `unbind()`.

`nested_activate_vf()`	This method is called to request that the entity manager's model be made temporarily active. The entity manager is responsible for ensuring that the global history stream, tolerance and units variables are correctly set. The implementation of this method should be very similar to the code that the application executes when changing to a new document through the application interface. A pointer to the previously active model is supplied as an input argument; this pointer will be NULL if this is the outermost call to nested activate. Note that the global history stream should be changed using the nested history mechanism.
`entities_changed_vf()`	This method is called immediately before `nested_deactivate_vf()` and is intended to inform the document of what changes were made by assembly modeling functionality while the document was active. The outcome of the last API function executed is passed in, along with an event type: ASM_BREP_GEOM_CHANGE indicates that physical properties of the part entity (as opposed to assembly entity) contents of the document were changed, for example, a Boolean was performed on one of the bodies. The only derived or cached data which needs to be updated is that involving the part entities. ASM_COMP_GEOM_CHANGE indicates that physical properties of the assembly entity (as opposed to part entity) contents of the document were changed; for example, a model-ref’s transform was moved or a component was suppressed. Cached or derived data associated with the assembly structure needs to be updated. ASM_BREP_RENDER_CHANGE indicates that physical properties of the part entities were unchanged, but their rendering properties were modified, for example, a color was applied to a BODY. ASM_COMP_RENDER_CHANGE indicates that physical properties of the assembly were unchanged, but rendering properties were modified, for example, a color or transparency property was added to a component. ASM_OTHER_CHANGE indicates that physical and rendering properties were unchanged, but some other modification of the document's entities took place, for example, an attribute was added. ASM_NO_CHANGE indicates that no significant change to the document's contents took place. Note that this does NOT mean that no bulletins will have been generated on the history stream; bulletins may be generated in ACIS by `const` operations such as boxing due to lazy data being instantiated.
`nested_deactivate_vf()`	This method is called immediately after `entities_changed_vf()`, and indicates that assembly modeling is done with this set of operations on the document. The entity manager is responsible for ensuring that the global history stream, for example, is reset to the same state it was in before the call to `nested_activate_vf()`, that is, that the previous document is re-activated. A pointer to the model object that was active before the activate call is provided; if this pointer is NULL, it indicates that this is the outermost deactivation.
`sub_model_changed_vf()`	This method is the mechanism for notifying the parents of a document just de-activated that something has changed in a child. This method is called on the entity managers of all models which have the just de-activated model as a sub-model, and provides a pointer to the model which was de-activated, along with the event type of the change. The intent of this routine is to allow assemblies to re-render themselves (for rendering changes) and/or invalidate cached information about physical properties (for geometric changes).