Home > User Guide > Understanding Assembly Modeling

Standard Workflows in Assembly Modeling

This section provides a brief outline of the assembly modeling operations and interfaces that should be used to perform typical tasks in a customer application.

In general, the asmi functions follow a naming convention of asmi_OBJECT_ACTION or api_asm_OBJECT_ACTION, where OBJECT is the type of object being acted upon, ACTION is the action upon the object, and the api_asmi/asmi prefix indicates whether the operation is an assembly modeling API function (that is, has ENTITY* or ENTITY_LIST in its argument list) or an asmi routine (has only assembly modeling objects such as model and handle objects in its argument list). If a specific workflow does not appear below, its core interface function(s) can often be inferred by browsing through the list of asmi_* and api_asm_* functions provided.

Typical Tasks in a Customer Application

Creating a Model (Assembly or Part)

In order to create an assembly or part model, the customer application needs to open a new document and bind it to ACIS Assembly Modeling. (Refer to the section Entity Managers in Assembly Modeling.) To create a model, do the following:

  1. Create an application document object using customer code.
  2. Create an entity manager object bound to the document object using customer code.
  3. Create an asm_model object bound to the entity manager object by calling asmi_model_create(), using a "create_assembly" flag of TRUE for an assembly document and FALSE for a part document.

Adding a Model Reference to an Assembly Model

To add a model reference to an assembly model, do the following:

  1. Create a SPAtransf object containing the relative positioning of the model reference within the parent assembly model. Note that model reference transforms may only contain translations and proper rotations.
  2. Create a new model reference object with the parent assembly model by calling asmi_model_add_model_ref().

Moving a Model Reference within an Assembly Model

To move a model reference within an assembly model by transforming it, do the following:

  1. Create a SPAtransf object containing the transform to be applied to the model reference.
  2. Apply the transform using asmi_model_ref_apply_transform(). Note that the asmi_model_ref_set_transform() can also be used if the intent is to simply reset the model reference's transform (ignoring its current transform).

Setting the Color of a Component

To set the color of a component, do the following:

  1. Create an rgb_color object specifying the desired color.
  2. Apply the color to the desired component by calling asmi_component_set_color().

Performing an Operation on a Model's Entire Assembly Tree without Knowledge of Component Hierarchy

To perform an operation on a model's entire assembly tree, without needing knowledge of the component hierarchy (for example, calculate bounding box), do the following:

  1. Call asmi_model_get_components (using an asm_get_request of ASM_ALL). This returns a list of all components of the model's assembly tree (for example, "car", "front axle assembly", "rear axle assembly", "chassis", "front-right wheel", and "front-left wheel" for a car model).
  2. For each component:
    1. Get the component's top-level part entities by calling asmi_component_get_entities(). This returns a list of handles for the top-level part entities (that is, not including the ASM_ASSEMBLY entity, if present) being managed by that model's entity manager.
    2. If the top-level entity list is non-empty, do the following:
      1. Get the component's model (that is, the model which owns the entities) by calling asmi_component_get_unmodified_model() on the component.
      2. Make the model active either by using a MODEL_BEGIN macro or by making the model's document active using application code interfaces.
      3. Perform the operation on each of the top-level entities (for example, api_get_entity_box()) and aggregate the result at the component level. You will need to call either api_asm_entity_handle_get_ptr() or the entity_ptr() method in order to obtain and ENTITY pointer for each handle.
      4. Make the model inactive either by using a MODEL_END macro or by making the model's document inactive using application code interfaces.
      5. If the operation changed the model in some way, notify parents of the model of the change by calling the "contents_changed" method on the model (this step is automatically performed by the MODEL_END macro). Refer to the sections Entity Managers in Assembly Modeling and Assembly Modeling Macros and Notification Mechanisms for a discussion of the contents_changed() method.
    3. Obtain the relative transform (including rescaling due to differences in units) between the component's model and the assembly model by calling asmi_component_get_transform() with an include_units_rescaling flag of TRUE.
    4. Transform the aggregated result of the operation on the component's entities by the component's transform and aggregate the result at the assembly model's level.
  3. Return the aggregated result of the operation.

Performing an Operation on a Model's Entire Assembly Tree According to Component Tree's Hierarchal Structure

To perform an operation on a model's entire assembly tree according to the component tree's hierarchal structure, do the following:

  1. Get a component handle corresponding to the root component of the tree by calling asmi_model_get_component_handle() on the root model with an empty list of model reference handles (that is, a zero-length path).
  2. Process the root component by performing (recursively) the following steps:
    1. Perform the operation on the component being processed and record the result.
    2. Get the sub-components of the component being processed by calling asmi_component_get_sub_components() using an asm_get_request of ASM_IMMEDIATE. This returns the list of immediate sub-components belonging to the component. Although this list is very similar in concept to the set of model references belonging to the component's model's assembly, it can differ due to, for example, suppression properties in the assembly model containing the component. Therefore, asmi_model_get_model_refs() should not be used at this step, because it will miss the effects of suppression properties, for example.
    3. If the relative transform between sub-component and component being processed is needed (that is, the equivalent of the corresponding model reference transform), it should be obtained by calling asmi_component_get_relative_transform(). Again, asmi_model_ref_get_transform should NOT be used in this workflow, because it will not take properties into account.
    4. Process each sub-component recursively.

Modifying a Part Document Application-side

This workflow occurs when the end user is working with a part document that is used in an assembly; for example, the end user performs a Boolean on a part. To modify a part document application-side, do the following:

  1. Activate the document and perform the operation using application code
  2. Determine the asm_model object corresponding to the document by using the get_model() method of the document's entity manager.
  3. Notify parents of the changed model by calling the contents_changed method on the model.

Saving to Monolithic ASAT File

To save to a monolithic ASAT file, do the following:

  1. Create an asm_save_options object specifying if history should be saved in the target file.
  2. Create an asm_model_list containing pointers to the primary models that will be saved to the file. The ASAT file contains all primary models and their sub-models. A typical ASAT file contains only one primary model. The primary model list passed to asmi_save_model_list is analogous to the entity list passed to api_save_entity_list.
  3. Open the ASAT file and position the file pointer to the beginning of the ASAT segment, in the same manner that a SAT file is opened for use by api_save_entity_list().
  4. Perform the save by calling asmi_save_model_list(), passing in the primary model list and the save options. If the FILE* signature of asmi_save_model_list is used, then a flag indicating whether the save file is text or binary should also be passed in (this information is not necessary if FileInterface* is use, because it is known by the FileInterface object).

Saving to Atomic ASAT File

To save to an atomic ASAT file, do the following:

  1. Confirm that you have written subclasses of asm_save_file and asm_save_file_factory that are specific to your application. These subclasses should write files with an filename extension specific to your application.
  2. Create an asm_save_options object and set its asm_save_file_factory pointer to point at your save file factory by calling set_save_factory().
  3. Set the history flag in the asm_save_options object by calling set_with_history(), if you want to save with history.
  4. Call asm_save_model_atomic() on the root model of the assembly hierarchy to be saved, passing in the save options object.

Restoring from ASAT File

To restore from an ASAT file, do the following:

  1. Ensure that the global entity manager factory is set to an instance of your entity_mgr_factory by ensuring that asmi_set_entity_mgr_factory() has been called at least once before the save begins. Otherwise, you should pass a pointer to the entity manager factory that you want to be used in through an asm_restore_options object.
  2. Open the ASAT file and position the file pointer to the beginning of the ASAT segment, in the same manner that a SAT file is opened for use by api_restore_entity_list().
  3. Create an asm_restore_options object if one will be needed. Note that this object can be created on the stack, rather than on the heap, if desired.
  4. Confirm that you have written a subclass of asm_restore_file that is specific to your application, if this is an atomic restore. Create an instance of your asm_restore_file class and set the asm_restore_options object to point to it by calling set_restore_file().
  5. Perform the restore by calling asmi_restore_model_list().

Related topics:

Assembly Modeling Overview
Assembly Modeling vs Part Modeling
Basic Concepts in Assembly Modeling
Assembly Modeling Tutorial
Properties in Assembly Modeling
Assembly Modeling Save and Restore
Assembly Modeling Limitations

[Top]

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