Properties in Assembly Modeling
A standard operation in both assembly and part modeling is the application of properties, such as color, to an object. In ACIS Part Modeling, properties are applied to an entity (for example, a FACE) by attaching an attribute which specifies the property (for example, ATTRIB_RGB) to it. In ACIS Assembly Modeling, properties are still specified by attributes, but they modify assembly modeling objects, specifically, components.
In addition, the assembly model in which the property is applied determines which assemblies are modified; a "red" color applied in a car model to its front-left wheel does not modify the axle assembly or wheel sub-models. A "blue" color applied in the axle assembly to its left wheel directly modifies the axle assembly model and also modifies the car (because the car uses the axle assembly through model references). In other words, applying a property within a model also modifies all assemblies which include that model, but does not modify any sub-assemblies of that model.
This process determines the "actual" color of a component of the assembly; if both the "red" and "blue" color properties discussed above were applied, then the front-left wheel in the car would attempt to be both red (from the front-left wheel property) and blue (from the left wheel property) and a set of rules must be used to resolve the ambiguity.
This set of rules is analogous to the part modeling rules which determine whether body color should override face color or vice-versa.
Note: The actual color of the front-left wheel in this example would be red, because that property was applied at a higher level (car) in the assembly tree. The rear-left wheel would be blue, of course, because it is contained within the rear reference to the axle assembly model, which has (due to the blue property) a blue left wheel.
Note: Component entity properties are not supported by ACIS Assembly Modeling at this time.
The properties which can be applied in ACIS Assembly Modeling fall into one of following categories: physical, rendering, and other.
A physical property, such as suppression, changes the physical properties, such as bounding box or mass properties, of the assembly model. Only ACIS can define physical property attributes which are to be recognized by ACIS Assembly Modeling.
If you wish to introduce a physical property attribute (for example, density), then you must recode the affected assembly modeling operations (for example, mass properties) in terms of an aggregation of part modeling operations to account for the new property. This property attribute, however, will not be understood by other ACIS-based applications.
If you require a physical property attribute type that is not supplied by ACIS, contact Spatial for this enhancement request. At present, the only physical property provided is "suppress".
A rendering property, such as "color" or "transparency", does not change the physical properties of the model but does change the model's appearance. Unlike physical properties, you can use your own attributes to specify new rendering properties, for example, a "blinker" attribute. (HOOPS customers will, of course, need to provide an entity converter which properly renders the new attribute.) The rendering properties provided by ACIS Assembly Modeling (and recognized by the default HOOPS/ACIS Bridge entity converter) are color, transparency, and hiding.
An other property (usually meta-data) modifies neither the physical properties nor the appearance of the model. As with rendering properties, you may define your own attributes to specify "other" properties. The name property is an "other" property. Note that asmi_component_find_name treats the name property in a slightly different manner than the corresponding routines to find, for example, color or transparency. The name "property" is not inherited, that is, a component's name is unaffected by name properties applied to its parents. For example, naming the front axle assembly "fa" has no effect on the name of the front left wheel, even though the front axle assembly is a parent component of front left wheel.
Assembly Modeling Operations
The ACIS Assembly Modeling interface is designed to hide the complexities of property management behind an easy to use interface. The two fundamental operations are:
- Adding properties to components
- Querying a component for its "actual" properties
In addition, convenience routines are provided for adding and querying properties such as color, hiding, suppression, names and transparency which allow you to avoid working directly with property attributes.
Adding Properties to Components
When adding a property (using the routine api_asm_component_add_property), only the following pieces of information need to be provided:
- A pointer to the attribute which specifies the property
- The component which is modified by the property
- The model in which the property is being applied. (Optional)
If an owning model is not specified, then the root model of the modified component is used. For example, the owning model for a property applied to the left wheel in the axle assembly defaults to the axle assembly model, and the applied property changes the axle assembly model. If the owning model is specified to be the car model, then it is the car model that is changed. The appearance of the axle assembly in the car model (and all model-references of the car model in models higher in the assembly tree) is the same as if the owning model were the axle assembly. Yet, the axle assembly itself is un-modified.
Note: The interface routine for adding a property is an ACIS (part modeling) API, not an asmi (assembly modeling) routine, because an API takes an entity (the property attribute) as an argument.
Specifically, this API modifies the attributes of the ASM_ASSEMBLY entity belonging to the property's owning model (that is, the API actually attaches the property attribute to a "property owner" attribute belonging to the assembly entity). The API must be called while the history stream associated with the owning model is active. Also, the property attribute must be created in the history stream associated with the owning model, because it will be attached to an attribute of the ASM_ASSEMBLY object. In other words, you create a property attribute and add it to the owning model using api_asm_component_add_property in the same way (in terms of active history streams) that you create and attach an attribute to a BODY in part modeling, for example. Applying a property changes the ENTITYs associated with the model in which the property was applied; thus the property rolls with that model's history operations.
Important: When preparing to use api_asm_component_add_property, you will quite often want to know if a property of the appropriate type has already been added to the component in question. This service is provided by the routine api_asm_component_get_property. This routine takes the same argument list as api_asm_component_add_property, with the exceptions that it also takes an attribute type as an input and the property attribute is returned by reference, rather than being an input parameter. If no such property has been added to the component in the model specified by the asm_property_options object, then a value of NULL is passed back; otherwise, you can modify the existing property attribute that is returned.
Querying Components and Models for Properties
The interface for querying for "actual" properties, such as the color with which a component should be rendered, is designed to be analogous to the part modeling interface for finding attributes on an entity. The following routines are provided:
- asmi_component_find_property finds the property attribute of the specified type of highest priority for the component.
- asmi_component_find_next_property finds the attribute of next highest priority.
- api_asm_model_find_components_with_property finds all components in a model that have the specified property attribute.
The interface for specifying the attribute type is somewhat simpler than in ACIS Part Modeling; only the type ID of the attribute class being searched needs to be specified, as opposed to the type IDs of all its parent classes. Refer to Assembly Modeling Macros and Notification Mechanisms for a further discussion of the need for activating a model when using entities contained within that model.
These routines work by determining all properties which have been applied with in an assembly and its sub-assemblies which can affect the component(s) in question. These will be properties which have been applied to components whose model-reference paths form a subset of the model-ref path of the component(s) in question. These properties are then ordered according to the following priority rules.
Property Priority Rules
ACIS Assembly Modeling has three rules which determine the relative priority of component properties.
Priority Rule 1: The Model in Which the Property Is Applied Is Dominant
Properties applied in (that is, owned by) higher models always override properties applied in lower models. This rule is in place because properties are used to modify the way in which existing models are included in an assembly. The properties applied in lower models are part of those lower models; hence, they are subject to modification.
Priority Rule 2: The Property Decorating the Component with the Higher Root Model Overrides the Other
When considering two properties that were applied in the same model, the next criterion concerns the root models of the components to which the properties were applied.
The property decorating the component with the higher root model overrides the other. For example, a color applied to the "right wheel" in a car model is overridden by a color applied to the "right wheel in front axle assembly," because the latter has a higher root model (the car).
Note: Applying a color to the "right wheel" in the car model has the same effect as a color being applied in the axle model, but does not change the axle model. This is achieved by passing an asm_property_options object into the call to asmi_model_set_color with the car model set as property_owning_model. If no asm_property_options object were passed in, then the owning model would be the root model of the component, that is, the axle assembly.
This rule is never relevant unless non-default values of property_owning_model were used when applying the component colors. This is because, lacking an asm_property_options object, properties are always applied in the component's root model, in which case Rule 2 is identical to Rule 1.
Priority Rule 3: The Property Decorating the Component with the Lower End Model Overrides Alternative Properties
When considering two properties for which the above two criteria are tied, this final criterion concerns the end models of the components to which the properties were applied.
The property decorating the component with the lower end model overrides the other. For example, a color applied to the car model's "right wheel in front axle assembly" overrides a color applied to the car model's "front axle assembly". This rule allows general properties to be set on large groupings of components (an axle-assembly component) which are then overridden by more specific properties applied to particular components within the group (a particular wheel within that axle-assembly component). Note that the advanced interface allows you to find all the properties that have been applied to a particular component if you want to implement different override behaviors. This, however, would be a large task.
In addition to the interfaces described above for working with arbitrary property attributes, ACIS Assembly Modeling provides "helper" asmi functions for common properties such as color, suppression, and transparency asmi_component_find_color is especially useful, because there are several different attribute types associated with color which must be considered simultaneously when deciding which color has highest priority.
Has Modifications Query
The component property mechanism described above is designed to allow sharing (using model references) of "modified" models. Consider, for example an axle assembly with a blue left wheel and a black right wheel, where both wheels have identical geometry. If component property specification were not permitted, then two-wheel models would have to be defined (at twice the cost in memory) in order to create the axle assembly model: one blue and one black. By supporting component properties, ACIS Assembly Modeling allows the end user to create only one wheel model as a "master", but to modify its inclusions into assemblies. In other words, the properties (for example, color and mass) of a component (for example, front-left wheel) and the properties of the component's model (for example, wheel model) are not necessarily the same. Because a component is an "actual" constituent of the assembly, you must know if the component is explicitly specified in the assembly as its unmodified model, or if modifications to its model need to be applied in order to render it, for example. This is the purpose of the asmi_component_has_*_modifications interface routines.
The above discussion has described the "basic" interface for assembly modeling properties, which should be sufficient for initial assembly modeling implementations within customer code. For customers desiring more direct access and/or control over the manner in which properties are queried, ACIS Assembly Modeling also provides "advanced" interface functions discussed below.
Three types of modifications that may apply to a component being expressed in an assembly include: component, parent, and child.
The component's model is directly modified by a property applied in a parent model, for example, properties applied to the front-left-wheel component of a car or to the left-wheel component of the axle assembly used by the car are both direct modifications of the front-left-wheel component. However, a property applied to the rear-left-wheel cannot directly modify the front-left-wheel, even though both have the component "wheel" in their model reference path.
A parent component of this component has been directly modified. For example, the front-left wheel has a parent modification if the front axle assembly has been colored green, because the front axle assembly is a parent of the front-left wheel.
A child component of this component has a direct modification that was applied in a parent model of this component. For example, the front axle assembly has a child modification if the front-left wheel was colored green in the car model. Coloring the left-wheel component in the axle assembly model, however, does not cause a child modification (nor component or parent modifications) to the front axle assembly component. This is a result of having the property applied in the axle assembly model itself, rather than in a parent of the front axle assembly component.
The significance of this discussion is for those customers who wish to avoid duplication of effort when working with multiple components which share the same model, for example, the four wheels of a car model. The basic interface methodology is to treat each component separately, for example, querying for top-level entities (facets) such as color and transparency, individually for each of the four wheel components when rendering a car assembly. Although this is simple and safe, it does not take advantage of the possibility of re-using the common rendering data associated with the wheel model.
An advanced implementation might attempt to only make one copy of the facet data and share it between the four wheels, for example. Such sharing is only safe, however, if the model has no child modifications. For example, if one of the wheels has had an assembly-level cut applied (not yet supported) in the car model, then the wheel will have different facets than the standard, unmodified wheel that is referenced in the axle assembly model. For a concrete example of the use of asmi_component_has_*_modifications, refer to Converting ACIS Assembly Models into Customer Assemblies.
Component Property Owners
An even more advanced level of interface involves working directly with the objects to which the component property attributes are attached. These are of type ATTRIB_COMPONENT_PROP_OWNER, and are lazily attached to the ASM_ASSEMBLY entity in the property's owning model as necessary. This interface provides three asmi functions:
- asmi_component_get_property_owners is a query for a handle for the component property owner attribute to which are attached properties applied to a specific component within a specific (assembly) model. The caller can request that one be created if it is not present. This attribute can be searched for (property) attributes (like any other ACIS entity) and queried for its owner, which will be the ASM_ASSEMBLY object of the model specified.
- asmi_component_get_property_owners returns a list of entity handles representing the prioritized list of all property owners which modify the component in question (highest priority first). The owner attributes in this list can be processed individually if the customer needs to implement complicated interactions between attributes of different type (for example, having multiple attribute types for specifying color). It is very important to note that, in general, the attributes in this list will be contained in different models. Care should be taken to activate the correct model for each attribute when ENTITY pointers are obtained from the handles while processing the list.
- api_asm_model_get_owned_property_owners returns an ENTITY_LIST containing all of the property owner attributes owned by a particular model. This is an API routine, and so should only be called with the appropriate history stream active.