Feature Element Tree
This section explains feature creation in Creo Object TOOLKIT Java.
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 Java 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 Element objects.
3. Pass the FET structure to Creo Parametric to create the feature by calling the function wfcSolid.WSolid.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 ElementTree object. The root and branch points in FET are called “elements”. Each element is modeled by Element 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 Java, 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 Java 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 Java and Creo TOOLKIT 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, and 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 Selection 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 Java 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:
  • wfcElementTree.Element.GetValue
    		•
  • wfcElementTree.Element.SetValue
    		•
    The element values are represented by ArgValue objects. They can be set and obtained using the methods wfcElementTree.Element.GetValue and wfcElementTree.Element.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:
  • wfcElementTree.SpecialValue_Create
    		•
  • wfcElementTree.SpecialValue.GetComponentModel
    		•
  • wfcElementTree.SpecialValue.SetComponentModel
    		•
  • wfcElementTree.SpecialValue.GetSectionValue
    		•
  • wfcElementTree.SpecialValue.SetSectionValue
    		•
    The method wfcElementTree.SpecialValue_Create enables you to create a special value for a specified feature element.
    The method wfcElementTree.SpecialValue.GetComponentModel returns the value of the element PRO_E_COMPONENT_MODEL for the specified feature. Use the method wfcElementTree.SpecialValue.SetComponentModel to set the value for the element PRO_E_COMPONENT_MODEL.
    The method wfcElementTree.SpecialValue.GetSectionValue returns the value of the element PRO_E_SKETCHER for the specified feature. Use the method wfcElementTree.SpecialValue.SetSectionValue to set the value for the element PRO_E_SKETCHER. This value is a object of type Section.
    Feature Element Paths
    Methods Introduced:
  • wfcElementTree.ElementPath_Create
    		•
  • wfcElementTree.ElementPath.GetItems
    		•
  • wfcElementTree.ElementPath.SetItems
    		•
  • wfcElemPathItem.ElemPathItem_Create
    		•
  • wfcElementTree.ElemPathItem.GetId
    		•
  • wfcElementTree.ElemPathItem.SetId
    		•
  • wfcElementTree.ElemPathItem.GetType
    		•
  • wfcElementTree.ElemPathItem.SetType
    		•
    An element path is used to describe the location of an element in an element tree. Use the method wfcElementTree.ElementPath_Create to create an element path in an element tree and the input argument to this method is items. The full path is represented by the class ElementPath, which contains the list of ElemPathItem objects. Each ElemPathItem provides the element ID and its ElemPathItemType. The element path from an array element to one of its member arrays contains the array index of that element. The enumerated type ElemPathItemType gives the array index. To get the path length, use the method wfcElementTree.ElementPath.GetItems, and then use wfcElementTree.ElemPathItems.getarraysize. Use to set path length using the method wfcElementTree.ElementPath.SetItems path length.
    Use the method wfcElemPathItem.ElemPathItem_Create to create an element path item. The input arguments to create an element path item are type and Id.
    The methods wfcElementTree.ElemPathItem.GetId and wfcElementTree.ElemPathItem.SetId retrieve and set the element IDs of the element path item.
    The methods wfcElementTree.ElemPathItem.GetType and wfcElementTree.ElemPathItem.SetType retrieve and set the type of the element path item using the enumerated type wfcElementTree.ElemPathItemType.
    Feature Element Tree
    Methods Introduced:
  • wfcElementTree.ElementTree.ListTreeElements
    		•
  • wfcElementTree.ElementTree.GetElement
    		•
  • wfcElementTree.ElementTree.IsElementArray
    		•
  • wfcElementTree.ElementTree.IsElementCompound
    		•
  • wfcElementTree.ElementTree.IsElementMultiVal
    		•
  • wfcElementTree.ElementTree.CreateDtmCsysElemTreeFromFile
    		•
  • wfcElementTree.ElementTree.WriteElementTreeToFile
    		•
  • wfcSession.WSession.CreateElementTreeFromXML
    		•
  • wfcSession.WSession.CreateElementTree
    		•
  • wfcFeature.WFeature.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 Element object. It is the property of wfcElementTree.
    The method wfcElementTree.ElementTree.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.ElementTree.WriteElementTreeToFile to save the full FET to a file.
    Use the method wfcSession.WSession.CreateElementTreeFromXML to build the FET from an XML file. The method wfcSession.WSession.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 Elements.
    The method wfcFeature.WFeature.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:
  • wfcSolid.WSolid.WCreateFeature
    		•
  • wfcSelect.WSelection.CreateFeature
    		•
    The WSolid object identifies the solid that is to contain the new feature. The method wfcSolid.WSolid.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 wfcSelect.WSelection.CreateFeature to create a feature in an assembly component.
    When using the method wfcSolid.WSolid.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 pfcExceptions.XToolkitGeneralError.
    •  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 wfcSelect.WSelection.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 wfcFeatureInstructions.FeatCreateOption.
    •  Instrs— Specifies the regeneration instructions as wfcSolidInstructions.WRegenInstructions object. Refer to the section Regenerating a Solid for more information on regeneration instructions.
    Feature Elements
    Methods Introduced:
  • wfcFeature.WFeature.GetDimensionId
    		•
  • wfcSession.WSession.GetElemWstrOption
    		•
  • wfcSession.WSession.SetElemWstrOption
    		•
  • wfcSession.ElementWstringOption_Create
    		•
  • wfcSession.ElementWstringOption.GetExpression
    		•
  • wfcSession.ElementWstringOption.SetExpression
    		•
  • wfcSession.ElementWstringOption.GetPositive
    		•
  • wfcSession.ElementWstringOption.SetPositive
    		•
  • wfcSession.ElementWstringOption.GetSign
    		•
  • wfcSession.ElementWstringOption.SetSign
    		•
  • wfcElementTree.wfcElementTree.Element_Create
    		•
  • wfcElementTree.Element.GetIdAsString
    		•
  • wfcElementTree.Element.GetIsArray
    		•
  • wfcElementTree.Element.GetIsCompound
    		•
  • wfcElementTree.Element.GetIsMultival
    		•
  • wfcElementTree.Element.GetChildren
    		•
  • wfcElementTree.Element.GetValueAsString
    		•
  • wfcElementTree.Element.SetValueAsString
    		•
  • wfcElementTree.Element.GetId
    		•
  • wfcElementTree.Element.SetId
    		•
  • wfcElementTree.Element.GetLevel
    		•
  • wfcElementTree.Element.SetLevel
    		•
  • wfcElementTree.Element.GetDecimals
    		•
  • wfcElementTree.Element.SetDecimals
    		•
  • wfcElementTree.Element.GetSpecialValueElem
    		•
  • wfcElementTree.Element.SetSpecialValueElem
    		•
  • wfcElementTree.Element.GetElemCollection
    		•
  • wfcElementTree.Element.SetElemCollection
    		•
    The method wfcFeature.WFeature.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 wfcSession.WSession.GetElemWstrOption and wfcSession.WSession.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 wfcElementTree.Element.GetValueAsString to display the string representation of elements.
    The method wfcSession.ElementWstringOption_Create creates a string value of a specified element in a tree.
    The method wfcSession.ElementWstringOption.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 wfcSession.ElementWstringOption.SetPositive sets the option to retrieve the values as positive. This method is applicable to double and integer value elements.
    The method wfcSession.ElementWstringOption.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 wfcElementTree.wfcElementTree.Element_Create creates a new instance of the Element object that contains information about the parameters of the element.
    The method wfcElementTree.Element.GetIdAsString returns the string representation of the specified element ID.
    The methods wfcElementTree.Element.GetIsArray, wfcElementTree.Element.GetIsCompound, and wfcElementTree.Element.GetIsMultival are used to determine the type of the specified element in a tree. The methods wfcElementTree.Element.GetIsArray and wfcElementTree.Element.GetIsCompound determine if the specified element contains an array of elements, or is a compound. The method wfcElementTree.Element.GetIsMultival determines whether the input element can have multiple values.
    The method wfcElementTree.Element.GetChildren populates an array of children elements, if the specified element is a compound element, or an array.
    The method wfcElementTree.Element.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 wfcElementTree.Element.GetId and wfcElementTree.Element.SetId to get and set the element identifier for the specified element.
    Use the methods wfcElementTree.Element.GetLevel and wfcElementTree.Element.SetLevel to get and set the location of the element in the element tree with respect to the root element.
    Use the methods wfcElementTree.Element.GetDecimals and wfcElementTree.Element.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 wfcElementTree.Element.GetSpecialValueElem to obtain the pointer representation for the specified element. The method wfcElementTree.Element.SetSpecialValueElem sets the pointer representation for the specified element.
    Use the method wfcElementTree.Element.GetElemCollection to extract a collection object from an element of a feature element tree of the following types:
    •  CurveCollection
    •  SurfaceCollection
    Use the method wfcElementTree.Element.SetElemCollection to assign a collection object to an element of a feature element tree of the type CurveCollection and SurfaceCollection.
    Creating Patterns
    Methods Introduced:
  • wfcFeature.WFeature.CreatePattern
    		•
    You can create patterns by calling the method wfcFeature.WFeature.CreatePattern on the feature.
    Redefining Features
    Method Introduced:
  • wfcFeature.WFeature.RedefineFeature
    		•
    You can use the method wfcFeature.WFeature.RedefineFeature to redefine features.
    Element Diagnostics
    Methods Introduced:
  • wfcElementTree.Element.GetDiagnostics
    		•
  • wfcElementTree.ElementDiagnostic_Create
    		•
  • wfcElementTree.ElementDiagnostic.GetDiagnosticMessage
    		•
  • wfcElementTree.ElementDiagnostic.SetDiagnosticMessage
    		•
  • wfcElementTree.ElementDiagnostic.GetSeverity
    		•
  • wfcElementTree.ElementDiagnostic.SetSeverity
    		•
    The method wfcElementTree.Element.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 wfcElementTree.ElementDiagnostic_Create to create an element diagnostic in an element tree.
    The methods wfcElementTree.ElementDiagnostic.GetDiagnosticMessage and wfcElementTree.ElementDiagnostic.GetSeverity get the message and severity of the diagnostic item of the element.