Feature Element Tree
This section explains feature creation in Creo Object TOOLKIT C++.
Overview of Feature Creation
There are many kinds of features in Creo Parametric and each feature can contain a large and varied amount of information. All this information must be complete and consistent before a feature can be used in regeneration and create the geometry.
You must build all the information needed by a feature into a data structure before passing that whole structure to Creo Parametric. This structure is called Feature Element Tree (FET). The FET structure is in the form of a tree containing the data elements. Creo Object TOOLKIT C++ defines this structure as an object that can be allocated and filled using special classes.
You must use the following steps to create a feature in Creo Parametric:
1. Allocate the FET structure as wfcElementTree.
2. Fill the FET structure by creating wfcElement objects.
3. Pass the FET structure to Creo Parametric to create the feature by calling the function wfcWSolid::WCreateFeature.
The feature is created in a sequence of manageable steps with the error checking along the way.
The full FET is represented by a wfcElementTree object. The root and branch points in FET are called “elements”. Each element is modeled by wfcElement class.
FET contains all the information required to define the feature. It includes the following information:
•  All the options and attributes. For example, the material side and depth type for an extrusion or slot, placement method for a hole, and so on.
•  All the references to existing geometry items. For example, the placement references, up to surfaces, sketching planes, and so on.
•  All the references to Sketcher models used for sections in the feature.
•  All dimension values.
The values of dimensions used by the feature are in the FET. However, there are no descriptions or references to the dimension objects themselves.
Each element in the FET is assigned an element ID. The element ID is an unique to every element. No two elements at the same level in the tree can have the same identifier, unless they belong to an array element.
You cannot create all feature types using Creo Object TOOLKIT C++, but the FET structure is capable of defining any feature type. This allows you to extend the range of features.
Note
The Creo Object TOOLKIT C++ is based on the same toolkit that is used to build Creo Parametric. Changes in Creo Parametric may require the definition of the element tree to be altered for some features. PTC will support upward compatibility in most of the cases. However, there may be cases where the old application will not run with the new version of Creo Parametric. You must rewrite the application's code to conform to the new definition of the feature tree.
The Creo Object TOOLKIT C++ and Creo Object TOOLKIT C++ can be used together.
They share the same definitions of FET element IDs and values. To use a specific element, you must refer to
the header files in <creo_toolkit_loadpoint>/includes for feature-specific element trees, then insert the actual integer value of the constant which defines the element ID or the element value.
•  PRO_E_FEATURE_TYPE
•  PRO_E_FEATURE_FORM
•  PRO_E_EXT_DEPTH
•  PRO_E_THICKNESS
•  PRO_E_4AXIS_PLANE
Element Tree Types
There are four different element types:
•  Single-valued
•  Multi-valued
•  Compound
•  Array
A single-valued element can contain various types of value, for example integer, string, double, and so on. The simplest is an integer. An integer can be used to define the type of the feature, or one of the option choices, such as, the material side for a thin protrusion. The wide string can be used define the name of the feature, and a double can be used to define the depth of a blind extrusion. If the element defines a reference to an existing geometry item in the solid, its value contains an entire pfcSelection object that allows it to refer to anything in an entire assembly. If the element represents a collection, its values contain an entire wfcCollection object. The collection can be a curve collection or a surface collection.
A multi-valued element contains several values of one of the mentioned types. Multi-valued elements occur at the lowest level of the element tree at the “leaves”.
A compound element is the one that acts as a branch point in the tree. It does not have a value of its own, but acts as a container for elements further down in the hierarchy.
An array element is also a branch point, but one that contains many child elements with the same element ID.
Building Features Using Element Trees
The feature element tree allows you to build a complex feature in stages, with only a small set of functions. However, the form of the tree required for a particular feature needs to be clearly defined. This helps you identify what elements and values must be added. This also helps Creo Object TOOLKIT C++ can check for errors each time you add a new element to the tree.
The header files in <creo_toolkit_loadpoint>/includes describe the Feature Element Trees with the following two types of description:
•  Feature element tree
•  Feature element table
The feature element tree defines the structure of the tree, specifying the element ID (or role) for the elements at all levels in the tree. It also defines which elements are optional. The feature element table defines the following for each of the element IDs in the tree:
•  A description of its role in the feature
•  The value type it has (that is, whether it is single value or compound; or an array of integer, double, or string)
•  The range of values valid for it in this context
Feature Element Values
Methods Introduced:
  • wfcElement::GetValue
    		•
  • wfcElement::SetValue
    		•
    The element values are represented by pfcArgValue objects. They can be set and obtained using the methods wfcElement::GetValue and wfcElement::SetValue methods. For more information on pfcArgValue objects, refer to the section Managing Application Arguments in Task Based Application Libraries.
    Feature Element Special Values
    Methods Introduced:
  • wfcSpecialValue::GetComponentModel
    		•
  • wfcSpecialValue::SetComponentModel
    		•
  • wfcSpecialValue::GetSectionValue
    		•
  • wfcSpecialValue::SetSectionValue
    		•
    The method wfcSpecialValue::GetComponentModel returns the value of the element PRO_E_COMPONENT_MODEL for the specified feature. Use the method wfcSpecialValue::SetComponentModel to set the value for the element PRO_E_COMPONENT_MODEL.
    The method wfcSpecialValue::GetSectionValue returns the value of the element PRO_E_SKETCHER for the specified feature. Use the method wfcSpecialValue::SetSectionValue to set the value for the element PRO_E_SKETCHER. This value is a object of type wfcSection.
    Feature Element Paths
    Methods Introduced:
  • wfcElementPath::GetItems
    		•
  • wfcElementPath::SetItems
    		•
    An element path is used to describe the location of an element in an element tree. The full path is represented by the class wfcElementPath, which contains the list of wfcElemPathItem objects. Each wfcElemPathItem provides the element ID and its wfcElemPathItemType. The element path from an array element to one of its member arrays contains the array index of that element. The enumerated type wfcElemPathItemType gives the array index. To get the path length, use the method wfcElementPath::GetItems, and then use wfcElemPathItems::getarraysize. Use to set path length using the method wfcElementPath::SetItems path length.
    Feature Element Tree
    Methods Introduced:
  • wfcElementTree::ListTreeElements
    		•
  • wfcElementTree::GetElement
    		•
  • wfcElementTree::IsElementArray
    		•
  • wfcElementTree::IsElementCompound
    		•
  • wfcElementTree::IsElementMultiVal
    		•
  • wfcElementTree::CreateDtmCsysElemTreeFromFile
    		•
  • wfcElementTree::WriteElementTreeToFile
    		•
  • wfcWSession::CreateElementTreeFromXML
    		•
  • wfcWSession::CreateElementTree
    		•
  • wfcWFeature::GetElementTree
    		•
    The Feature Element Tree (FET) is represented by wfcElementTree object. This class has methods that can obtain the list of elements in the element tree or obtain a specific feature element by its path, as well as querying element type (array, compound, and multi-valued).
    Note
    This type is not stored within wfcElement object. It is the property of wfcElementTree.
    The method wfcElementTree::CreateDtmCsysElemTreeFromFile allocates required steps of the element tree to create coordinate system from a transformation file.
    The input argument filename should be name of the file with the extension .trf. The name must be in lowercase only. The file should contain a coordinate transform such as:
    X1 X2 X3 Tx
Y1 Y2 Y3 Ty
Z1 Z2 Z3 Tz
    where
    •  X1 Y1 Z1 is the X-axis direction,
    •  X2 Y2 Z2 is the Y-axis direction,
    •  X3 Y3 Z3 is not used (the right hand rule determines the Z direction),
    •  Tx Ty Tz is the origin of the coordinate system.
    Use the method wfcElementTree::WriteElementTreeToFile to save the full FET to a file.
    Use the method wfcWSession::CreateElementTreeFromXML to build the FET from an XML file. The method wfcWSession::CreateElementTree builds the element tree from start. If the FET is built from start, all the mandatory elements in the element tree must to be populated and added sequentially in the sequence wfcElements.
    The method wfcWFeature::GetElementTree creates a copy of the feature element tree that describes the contents of a specified feature. The specified feature can be a regular feature or a pattern.
    Creating FET Using WCreateFeature
    Methods Introduced:
  • wfcWSolid::WCreateFeature
    		•
  • wfcWSelection::CreateFeature
    		•
    The wfcWSolid object identifies the solid that is to contain the new feature. The method wfcWSolid::WCreateFeature creates a feature from the FET.
    Note
    This method cannot be used to create a feature in the component of an assembly. Use the method wfcWSelection::CreateFeature to create a feature in an assembly component.
    The syntax of wfcWSolid::WCreateFeature is as follows:
    wfcWFeature_ptr wfcWSolid::WCreateFeature (
   wfcElementTree_ptr Tree, 
   wfcFeatCreateOptions_ptr Options, 
   optional wfcWRegenInstructions_ptr Instrs);
    When using the method wfcWSolid::WCreateFeature while working with a multi-CAD model, the following scenarios are possible depending on the value of the configuration option confirm_on_edit_foreign_models. The default value of the configuration option confirm_on_edit_foreign_models is yes.
    •  If the configuration option confirm_on_edit_foreign_models is set to no, the non-Creo model is modified without any notification.
    •  If the configuration option confirm_on_edit_foreign_models is set to yes, or the option is not defined in the configuration file, then in batch mode the application will throw the exception pfcXToolkitGeneralError.
    •  In some situations you may need to provide input in the interactive mode with Creo. Refer to the Creo Parametric Data Exchange online help, for more information.
    The method wfcWSelection::CreateFeature creates a feature from the Feature Element Tree. Use this method to create a feature in an assembly component. The input arguments are:
    •  Tree— Specifies the Feature Element Tree object.
    •  Options— Specifies the options which must be used to create the feature. The options are specified using the enumerated data type wfcFeatCreateOption.
    •  Instrs— Specifies the regeneration instructions as wfcRegenInstructions object. Refer to the section Regenerating a Solid for more information on regeneration instructions.
    Examples of Feature Creation
    The folder <creo_otk_loadpoint_app>\otk_examples\otk_examples_feat contains OTKXWriteFeatAsCxx.cxx, which provides the generator of C++ code for feature creation. To generate the code for a specific feature, you must create a model with that feature, start Creo Parametric with otk_examples, open the model and use Save Feature as cxx or Save All Features as cxx option.
    Feature Elements
    Methods Introduced:
  • wfcWFeature::GetDimensionId
    		•
  • wfcWSession::GetElemWstrOption
    		•
  • wfcWSession::SetElemWstrOption
    		•
  • wfcElementWstringOption::Create
    		•
  • wfcElementWstringOption::GetExpression
    		•
  • wfcElementWstringOption::SetExpression
    		•
  • wfcElementWstringOption::GetPositive
    		•
  • wfcElementWstringOption::SetPositive
    		•
  • wfcElementWstringOption::GetSign
    		•
  • wfcElementWstringOption::SetSign
    		•
  • wfcElement::Create
    		•
  • wfcElement::GetIdAsString
    		•
  • wfcElement::GetIsArray
    		•
  • wfcElement::GetIsCompound
    		•
  • wfcElement::GetIsMultival
    		•
  • wfcElement::GetChildren
    		•
  • wfcElement::GetValueAsString
    		•
  • wfcElement::SetValueAsString
    		•
  • wfcElement::GetId
    		•
  • wfcElement::SetId
    		•
  • wfcElement::GetLevel
    		•
  • wfcElement::SetLevel
    		•
  • wfcElement::GetDecimals
    		•
  • wfcElement::SetDecimals
    		•
  • wfcElement::GetSpecialValueElem
    		•
  • wfcElement::SetSpecialValueElem
    		•
  • wfcElement::GetElemCollection
    		•
  • wfcElement::SetElemCollection
    		•
    The method wfcWFeature::GetDimensionId returns the integer identifier of the dimension in the Creo Parametric database used to define the value of the specified single-valued element.
    The methods wfcWSession::GetElemWstrOption and wfcWSession::SetElemWstrOption get and set the options used to retrieve the string values of elements. The options set in this method are used by the method wfcElement::GetValueAsString to display the string representation of elements.
    The method wfcElementWstringOption::Create creates a string value of a specified element in a tree.
    The method wfcElementWstringOption::SetExpression sets the option to retrieve values as expressions or relations, if they exist, instead of string representations of the actual value. This method is applicable only to double value elements.
    The method wfcElementWstringOption::SetPositive sets the option to retrieve the values as positive. This method is applicable to double and integer value elements.
    The method wfcElementWstringOption::SetSign sets the option to retrieve values with special sign formatting (+/-), etc. This method is applicable to both double and integer value elements.
    The method wfcElement::Create creates a new instance of the wfcElement object that contains information about the parameters of the element.
    The method wfcElement::GetIdAsString returns the string representation of the specified element ID.
    The methods wfcElement::GetIsArray and wfcElement::GetIsCompound determine if the specified element contains an array of elements, or is a compound. The methods wfcElement::GetIsArray, wfcElement::GetIsCompound, and wfcElement::GetIsMultival are used to determine the type of the specified element in a tree. The method wfcElement::GetIsMultival determines whether the input element can have multiple values.
    The method wfcElement::GetChildren populates an array of children elements, if the specified element is a compound element, or an array.
    The method wfcElement::GetValueAsString returns a string value representation for double and integer elements. The options set in the object wfcElementWstringOption decide the format of the output.
    Use the methods wfcElement::GetId and wfcElement::SetId to get and set the element identifier for the specified element.
    Use the methods wfcElement::GetLevel and wfcElement::SetLevel to get and set the location of the element in the element tree with respect to the root element.
    Use the methods wfcElement::GetDecimals and wfcElement::SetDecimals obtain and set the number of decimal places to be used for the double value of an element in the feature.
    Use the method wfcElement::GetSpecialValueElem to obtain the pointer representation for the specified element. The method wfcElement::SetSpecialValueElem sets the pointer representation for the specified element.
    Use the method wfcElement::GetElemCollection to extract a collection object from an element of a feature element tree of the following types:
    •  wfcCurveCollection
    •  wfcSurfaceCollection
    Use the method wfcElement::SetElemCollection to assign a collection object to an element of a feature element tree of the type wfcCurveCollection and wfcSurfaceCollection.
    Creating Patterns
    Methods Introduced:
  • wfcWFeature::CreatePattern
    		•
    You can create patterns by calling the method wfcWFeature::CreatePattern on the feature.
    Redefining Features
    Method Introduced:
  • wfcWFeature::RedefineFeature
    		•
    You can use the method wfcWFeature::RedefineFeature to redefine features.
    Element Diagnostics
    Methods Introduced:
  • wfcElement::GetDiagnostics
    		•
  • wfcElementDiagnostic::Create
    		•
  • wfcElementDiagnostic::GetDiagnosticMessage
    		•
  • wfcElementDiagnostic::SetDiagnosticMessage
    		•
  • wfcElementDiagnostic::GetSeverity
    		•
  • wfcElementDiagnostic::SetSeverity
    		•
    The method wfcElement::GetDiagnostics collects the element diagnostics. The diagnostics include warnings and errors about the value of the element within the context of the feature and the remainder of the element tree.
    Use the method wfcElementDiagnostic::Create to create an element diagnostic in an element tree.
    The methods wfcElementDiagnostic::GetDiagnosticMessage and wfcElementDiagnostic::GetSeverity get the message and severity of the diagnostic item of the element.