Assembly: Simplified Representations
Creo TOOLKIT gives programmatic access to all the simplified representation functionality of Creo Parametric. You can create simplified representations either permanently or at runtime, and you can save, retrieve, or modify them by adding or deleting items.
Overview
Using Creo TOOLKIT, you can create and manipulate assembly simplified representations just as you can using Creo Parametric interactively.
Note
Creo TOOLKIT supports retrieval and activation of both part and assembly simplified representations. In addition, Creo TOOLKIT supports creation and modification of assembly simplified representations. Functions not appropriate for part mode are identified in the description.
Simplified representations are identified by the DHandle ProSimprep. As with other DHandles such as ProFeature and ProGeomitem, the ProSimprep handle contains just enough information to uniquely identify the object in the database—the model owner, type, and identifier.
The information required to create and modify a simplified representation is stored in a series of ProSimprepdata structures, which are visible data structures. The data structure contains the following fields:
•  ProName name—The name of the simplified representation
•  ProBoolean temp—Specifies whether it is a temporary, simplified representation
•  ProSimprepActionType action_type—The rule that controls the default treatment of items in the simplified representation
•  ProSimprepitem *items—An array of assembly components and features and the actions applied to them in the simplified representation
A ProSimprepitem is identified by the ProIdTable that defines the assembly component path to that item. (Even if the ID table path is only one level, use the ProIdTable and not the feature id for assemblies). Each ProSimprepitem has its own ProSimprepAction assigned to it. ProSimprepAction is a visible data structure that includes a variable of type ProSimprepActionType.
ProSimprepActionType is an enumerated type that specifies the possible treatment of items in a simplified representation. You can specify the following types of actions on the component:
•  PRO_SIMPREP_NONE—Specifies that no action is specified.
•  PRO_SIMPREP_REVERSE—Specifies that the reverse of the default rule must be applied to the component. For example consider that the default rule is to exclude a component. When you set the value PRO_SIMPREP_REVERSE, the component is included in the simplified representation.
•  PRO_SIMPREP_INCLUDE—Specifies to include the component in the simplified representation.
•  PRO_SIMPREP_EXCLUDE—Specifies to exclude the component in the simplified representation.
•  PRO_SIMPREP_SUBSTITUTE—Specifies to substitute the component in the simplified representation.
•  PRO_SIMPREP_GEOM—Specifies to use geometric representation.
•  PRO_SIMPREP_GRAPHICS—Specifies to use graphical representation.
•  PRO_SIMPREP_SYMB—Specifies to use symbolic representation.
•  PRO_SIMPREP_BOUNDBOX—Specifies to use boundary box representation.
•  PRO_SIMPREP_DEFENV—Specifies to use the default envelope representation.
•  PRO_SIMPREP_LIGHT_GRAPH—Specifies to use light weight graphics representation.
•  PRO_SIMPREP_AUTO—Specifies to use automatic representation.
Simplified Representations in Session
Functions Introduced:
  • ProSolidSimprepVisit()
    		•
  • ProSimprepInit()
  • ProSimprepSelect()
    		•
  • ProSimprepActivate()
    		•
  • ProSimprepActiveGet()
    		•
  • ProSimprepTypeGet()
    		•
  • ProSimprepIsDefault()
    		•
    This section describes the utility functions that relate to simplified representations.
    ProSolidSimprepVisit() is like the other visit functions, and visits all the simplified representations of a parent ProSolid. The function visits only user-defined representation.
    As all other visit functions, it takes four arguments—a pointer to the parent ProSolid, a filter function, the visit function itself, and a ProAppData field.
    The function ProSimprepInit() initializes a ProSimprep structure. The function takes the following arguments:
    •  ProNamerep_name— The name of the simplified representation in the solid. If you specify this argument, the function ignores the rep_id.
    •  intrep_id—The identifier of the simplified representation, if you did not specify rep_name (you specified NULL).
    •  ProSolidp_solid—The parent solid that contains the simplified representation.
    •  ProSimprepp_simp_rep—The handle to the newly initialized simplified representation.
    The function ProSimprepSelect() creates a Creo Parametric menu to enable interactive selection. The function takes the parent solid as input, and outputs the handle to the selected simplified representation. If you choose the Quit menu button, the function returns the value PRO_TK_USER_ABORT. If the user selects the master representation, the returned simplified representation structure has an identifier of –1.
    ProSimprepActivate() enables you to set the currently active simplified representation. To set a simplified representation to be the currently displayed model, you must also call ProSolidDisplay(). This function enables you to bring inactive submodels into memory, and use their handles without displaying them.
    ProSimprepActivate() does not support activation of part simplified representations, because part simplified representation handles cannot be passed to this function. You can display the simplified representation in a window using ProSolidDisplay().
    ProSimprepActiveGet() enables you to find the currently active simplified representation. Given a model handle, ProSimprepActiveGet() returns the handle to the currently active simplified representation. If the current representation is the master representation, the identifier of the handle is set to –1.
    The function ProSimprepTypeGet() returns the type of a specified simplified representation using the enumerated data type ProSimprepType:
    •  PRO_SIMPREP_MASTER_REP—Specifies a fully detailed assembly. The model tree lists all its components and identifies them as included, excluded, or substituted.
    •  PRO_SIMPREP_USER_DEFINED—Specifies a representation from the selected component.
    •  PRO_SIMPREP_GRAPH_REP—Specifies a representation that contains only information for display. You can quickly browse through a large assembly. Graphics representations cannot be modified or referenced.
    •  PRO_SIMPREP_GEOM_REP—Specifies a representations that contains complete component geometry information. As compared to graphics representations, geometry representations take longer to retrieve and require more memory.
    •  PRO_SIMPREP_SYMB_REP—Specifies a representation that allows you to represent components with a symbol.
    •  PRO_SIMPREP_DEFENV_REP—Specifies a representation that allows you to represent assembly components with an default envelope.
    •  PRO_SIMPREP_LIGHT_GRAPH_REP—Specifies a lightweight graphics representations of assemblies that contains assembly information and 3D thumbnail graphics representations of assembly components.
    •  PRO_SIMPREP_AUTO_REP—Specifies a representation for retrieving the minimum data that is required for presenting the assembly in the most accurate way. You can perform actions such as measuring distances between points on a light surface without retrieving the part geometry.
    Note
    When two standard representations of the same model are retrieved, for better memory usage, only one representation is used in the memory. The lower detailed representation is integrated into higher detailed representation. This higher detailed representation is used to retrieve both the representations.
    If you retrieve a lower detailed representation when a higher detailed representation is already in the memory, this higher detailed representation is used and actually no retrieval is done.
    The hierarchy for the representations is as follows with Master Simplified Representation being the highest representation level:
    •  Boundary Box Simplified Representation
    •  Symbolic Simplified Representation
    •  Graphic Simplified Representation
    •  Geometry Simplified Representation
    •  Master Simplified Representation
    Refer to the Creo Parametric help for more information on Assembly Design.
    The function ProSimprepIsDefault() determines if the specified simplified representation is the default representation for the owner model.
    Retrieving Simplified Representations
    Function Introduced:
  • ProAssemblySimprepMdlnameRetrieve()
    		•
  • ProSimprepMdlnameRetrieve()
    		•
  • ProMdlRepresentationFiletypeLoad()
    		•
    You can retrieve a named simplified representation from an assembly using the function ProAssemblySimprepMdlnameRetrieve(). This function retrieves the handle of an existing simplified representation from an assembly without getting the generic representation into memory.
    The function takes as arguments—the names of the assembly and simplified representation, the representation data, the type of model to retrieve, and the handle to the assembly. Note that you must provide the name of the assembly. To retrieve an existing simplified representation, specify its name as one of the inputs to the argument of this function. The name of the simplified representation can be NULL if the representation data is provided. In this case, the instructions in the data are used to dynamically create a new simplified representation . The representation data can also be NULL if the name of the simplified representation is provided. Creo Parametric retrieves the simplified representation and any active submodels, and returns the ProAssembly handle.
    You can retrieve geometry, graphics, symbolic simplified, boundary box, and default envelope representations into session using the function ProSimprepMdlnameRetrieve(). The input arguments to the function are:
    •  model_name—Specifies the name of the model whose simplified representation is to be retrieved.
    •  file_type—Specifies the type of model using the enumerated data type ProMdlfileType.
    •  rep_type—Specifies the type of simplified representation using the enumerated data type ProSimprepType.
    •  rep_name—Specifies the name of the simplified representation that must be retrieved.
    .
    Similar to ProAssemblySimprepMdlnameRetrieve(), the function ProSimprepMdlnameRetrieve() retrieves the simplified representation without bringing the master representation into memory. The function outputs the handle to the model. It does not display the simplified representation.
    You can retrieve the simplified representation of a model into memory using the function ProMdlRepresentationFiletypeLoad().
    Retrieving and Expanding LightWeight Graphics Simplified Representations
    Functions Introduced:
  • ProSimprepMdlnameRetrieve()
    		•
  • ProLightweightGraphicsSimprepExpand()
    		•
    The function ProSimprepMdlnameRetrieve() retrieves the light graphics simplified representation of an assembly. Light graphics representations of assemblies contain assembly information and 3D thumbnail graphics representations of assembly components. In the light graphics simplified representation mode, the graphics of a model is represented using the Creo View viewable. The Creo View files must be in the same directory as the model. If the Creo View files are not available in the model directory, then the model is represented with bounding boxes in the light graphics simplified representation mode. Using this function you can initially retrieve and display graphic objects of higher levels of the assembly and then retrieve more detailed information of the sub-assemblies as required. This function is similar to ProAssemblySimprepMdlnameRetrieve(), and retrieves the light graphics assembly in the same way as described in the section Retrieving Simplified Representations.
    Use the function ProLightweightGraphicsSimprepExpand() to expand the light graphics representation of an assembly in the Creo Parametric active window to the specified level using the enumerated type ProLightweightGraphicsSimprepLevel.
    You can expand the representation to the following levels:
    •  PRO_LWG_SIMPREP_LEVEL_NEXT—Expands thumbnails to the next level.
    •  PRO_LWG_SIMPREP_LEVEL_ALL—Expands thumbnails to all levels.
    To expand the sub-assembly level, use the functions ProModelitemInit() and ProSelectionAlloc() to first initialize the ProSelection handle for the component part or sub-assembly. You can pass the ProSelection handle to the function ProLightweightGraphicsSimprepExpand() and expand the component part or sub-assembly node to the required level.
    Retrieving User-Defined Simplified Representations
    Functions Introduced:
  • ProAutomaticSimprepRetrieve()
    		•
  • ProAutomaticSimprepConvert()
    		•
  • ProAutomaticSimprepActivate()
    		•
    The function ProAutomaticSimprepRetrieve() retrieves a user-defined simplified representation as an automatic representation. If error occurs during regeneration, the assembly includes suppressed features. Use the function ProSolidRetrievalErrorsGet() to identify if any errors have occurred during retrieval of the simplified representation. The input arguments follow:
    •  assem_name—Name of the assembly specified using the structure ProFamilyMdlName.
    •  file_type—File type of the assembly specified using the enumerated data type ProMdlfileType.
    •  simp_rep_name—Name of the simplified representation.
    The output argument p_assem is the handle to the assembly specified using the structure ProAssembly.
    The function returns the error PRO_TK_NO_PERMISSION if the function does not have permission to operate on the specified assembly. The function returns the error PRO_TK_E_NOT_FOUND if the function did not find the specified simplified representation in the solid.
    The function ProAutomaticSimprepConvert() converts a user-defined representation to automatic simplified representation while maintaining the excluded or substituted components in the representation.
    The function ProAutomaticSimprepActivate() activates a user-defined representation as an automatic simplified representation. To display the correct simplified representation, you must also call the function ProSolidDisplay().
    Note
    The functions ProAutomaticSimprepRetrieve(), ProAutomaticSimprepConvert() and ProAutomaticSimprepActivate() support only assemblies.
    The function ProAutomaticSimprepActivate() returns the error PRO_TK_E_NOT_FOUND if the function did not find the specified simplified representation in the model.
    Creating and Deleting Simplified Representations
    Functions Introduced:
  • ProSimprepdataAlloc()
    		•
  • ProSimprepCreate()
    		•
  • ProSimprepDelete()
    • Note
    Creo TOOLKIT does not support creation of part simplified representations.
    To create a simplified representation, you must allocate and fill a ProSimprepdata structure by calling the function ProSimprepdataAlloc(). As input, the function requires the name of the new simplified representation, the temp value, and the default rule. The specific structure is initialized by the function in the Creo Parametric database.
    To generate the new simplified representation, call ProSimprepCreate(). This function returns the ProSimprep handle for the new representation.
    The function ProSimprepDelete() deletes a simplified representation from its model owner. The function requires only the ProSimprep handle as input.
    Example 1: Creating a Simplified Representation
    The example in the file UgSimprepCreate.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_simprep, shows how to create a simplified representation.
    Extracting Information About Simplified Representations
    Functions Introduced:
  • ProSimprepdataGet()
    		•
  • ProSimprepdataFree()
    		•
  • ProSimprepdataDefltGet()
    		•
  • ProSimprepdataNameGet()
    		•
  • ProSimprepdataTmpvalGet()
    		•
  • ProSimprepdataitemsVisit()
    		•
  • ProSimprepSubstitutionNameGet()
    		•
  • ProAsmcompSubstitutionTypeGet()
    		•
  • ProAsmcompSubstituteGet()
    • Note
    Creo TOOLKIT supports simplified representation of Assemblies only, not Parts.
    Given the handle to a simplified representation and the address of a pointer to a ProSimprepdata structure, ProSimprepdataGet() fills out the ProSimprepdata structure. This function dynamically allocates storage for the data structure. When the memory is no longer needed, free it using the function ProSimprepdataFree().
    The ProSimprepdataDefltGet(), ProSimprepdataNameGet(), and ProSimprepdataTmpvalGet() functions return the associated values contained in the ProSimprepdata structure. They all take two arguments—the data structure to be queried, and the appropriate data structure for the type to be retrieved. ProSimprepdataTmpvalGet() retrieves the value of the temp field from the specified ProSimprepdata
    The function ProSimprepdataitemsVisit() visits all the items that make up the simplified representation. The action and filter functions both have ProSimprepitem* as their first argument.
    The function ProSimprepSubstitutionNameGet() returns the name of the substituted representation at the given assembly path even when the substituted representation is deleted from the model at the given path.
    The function ProAsmcompSubstitutionTypeGet() returns the substitution type performed on the simplified representation of an assembly component. It takes the path to the component reprsentation that is being substituted, including the component ID, as one of its input arguments.
    The function ProAsmcompSubstituteGet() returns the path to the substituted component representation in the form of and the handle to the substituted component representation in the form of ProAsmcomp. It takes the path to the component reprsentation that is being substituted, including the component ID, as one of its input arguments.
    Example 2: Visiting the Items in a Simplified Representation
    The sample code in UgSimprepInfo.c located at <creo_toolkit_loadpoint>/protk_appls/pt_userguide/ptu_simprep shows how to use the Creo TOOLKIT functions to visit the items in the specified simplified representation.
    Modifying Simplified Representations
    Functions Introduced:
  • ProSimprepActionInit()
    		•
  • ProSimprepdataSet()
    		•
  • ProSimprepdataDefltSet()
    		•
  • ProSimprepdataNameSet()
    		•
  • ProSimprepdataTmpvalSet()
    • Note
    Creo TOOLKIT supports simplified representation of Assemblies only, not Parts.
    Using Creo TOOLKIT, you can modify the attributes of existing simplified representations. After you create or retrieve a simplified representation, you can make calls to the ProSimprepdata*Set() functions listed in this section to designate new values for the fields in the ProSimprepdata structure.
    To modify an existing simplified representation, retrieve it, then get the handle to its ProSimprepdata structure by calling the function ProSimprepdataGet(). (If you created the representation programmatically within the same application, the ProSimprepdata handle is already available.) After modifying the data structure, reassign it to the corresponding simplified representation by calling the function ProSimprepdataSet(). Use the function ProSimprepdataTmpvalSet to specify whether the newly created representation is temporary. Pass the value PRO_B_TRUE to the input argument temp to make the newly created representation a temporary representation.
    Note
    Use the function ProSimprepdataTmpvalSet() to set the value of the temp input argument in the specified ProSimprepdata structure while creating new simplified representations only. Once the simplified representation is created, this attribute is controlled by Creo Parametric. For all the existing representations, Creo Parametric controls the temp input argument and sets its value automatically
    Adding Items to and Deleting Items from a Simplified Representation
    Functions Introduced:
  • ProSimprepdataitemAdd()
    		•
  • ProSimprepdataitemDelete()
    		•
  • ProSimprepdataitemInit()
    • Note
    Creo TOOLKIT supports simplified representation of Assemblies only, not Parts.
    You can add and delete items from the list of components in a simplified representation using Creo TOOLKIT. If you created a simplified representation using the option PRO_SIMPREP_EXCLUDE as the default rule, you would generate a list containing the items you want to include. Similarly, if the default rule for a simplified representation is PRO_SIMPREP_INCLUDE, you can add the items that you want to be excluded from the simplified representation to the list, setting the value of the ProSimprepActionType to PRO_SIMPREP_EXCLUDE.
    To Add Items
    1. Get the ProSimprepdata structure, as described in the previous section.
    2. Specify the action to be applied to the item with a call to the function ProSimprepActionInit().
    3. Initialize a ProSimprepitem structure for the item by calling the function ProSimprepdataitemInit().
    4. Add the item to the ProSimprepdata structure using the function ProSimprepdataitemAdd().
    5. Reassign the ProSimprepdata structure to the corresponding ProSimprep object by calling ProSimprepdataSet().
    To Remove Items
    1. Get the ProSimprepdata structure handle.
    2. Pass the ProSimprepdata handle and the ProSimprepitem handle for the item to be deleted to the function ProSimprepdataitemDelete().
    3. Reassign the ProSimprepdata structure to the corresponding ProSimprep object by calling the function ProSimprepdataSet().
    Gathering Components by Rule
    Function Introduced:
  • ProRuleEval()
    		•
    Creo Parametric provides large assembly management tools. This section describes the access to some of this functionality through Creo TOOLKIT.
    You can specify different types of rules and use them to generate a list of components for which the rule applies. After initializing the rule, call the function ProRuleEval() to generate the list of components that follow this rule.
    Note that the returned list of components is in the form of an expandable array (ProArray), which is allocated by this function. To release the allocated memory, call the function ProArrayFree().
    The components can be gathered using the following rules:
    •  By model name
    •  By parameters, using an expression
    •  By location with a zone
    •  By distance from a point
    •  By size
    •  By an existing simplified representation
    See the Assembly Modeling User’s Guide for more details on this functionality.
    Gathering by Model Name
    Function Introduced:
  • ProRuleInitName()
    		•
    The function ProRuleInitName() initializes the rule for gathering by model name. The name_mask variable can be a wildcard. For more information, see the Creo Parametric help.
    Gathering by Parameters
    Function Introduced:
  • ProRuleInitExpr()
    		•
    You can specify a expression in the relations format to search for components of a particular parameter value. For example, consider the following expression: 
         type == "electrical" | cost <= 10
    When you supply this expression to the rule, it gathers the components that have a “cost” parameter of less than or equal to 10, or whose type parameter is set to “electrical.”
    Theexpr variable is an array of ProLine structures. You allocate this array using the function ProArrayAlloc(). The ProArray* functions are used for all array manipulations.
    Gathering by Zone
    Function Introduced:
  • ProRuleInitZone()
    		•
    When you specify this rule, all the components that belong to the supplied zone feature are gathered.
    See the Assembly Modeling User’s Guide for detailed information about setting up and working with zones.
    When you create a zone, the function creates a feature of type PRO_FEAT_ZONE in the top-level assembly.
    Gathering by Distance from a Point
    Function Introduced:
  • ProRuleInitDist()
    		•
    Using ProRuleInitDist() to set up a rule that specifies distance from a point, Creo TOOLKIT gathers all the components within the specified spherical region.
    By filling the ProRuleDist data structure, you can specify the center and the distance from the center. This information is in the coordinates of the top-level assembly.
    Gathering by Size
    Function Introduced:
  • ProRuleInitSize()
    		•
    By filling the ProRuleSize data structure, you can specify the size of components to be gathered.
    If you want to gather the components greater than the specified size, set the field greater to PRO_B_TRUE. If you set the field to PRO_B_FALSE, the function gathers the components that are less than the specified size.
    If you want the specified size to be in absolute terms, set the field absolute to PRO_B_TRUE. Note that in this case, the function uses the units of the top-level assembly.
    If the information is relative, set the field absolute to PRO_B_FALSE. In this case, the only valid values that can be specified are in the range (0.0, 1.0). The function compares the component size to that of the top-level assembly, and uses this ratio to determine whether the component should be gathered.
    Gathering by Simplified Representation
    Function Introduced:
  • ProRuleInitRep()
    		•
    You can gather components that belong to an existing simplified representation by calling the function ProRuleInitRep(), which initializes the rule.