Creating a User Feature Reference

Mechanical Modeler		Creating a User Feature Reference Using CATIUdfFactory, CATIUdfFeature, and CATIUdfFeatureSet
Use Case

Abstract

This article shows how to create a User Feature reference.

What You Will Learn With This Use Case
The CAAMcaUdfCreation Use Case
Step-by-Step
In Short
References

What You Will Learn With This Use Case

This use case is intended to show you how to create a user feature reference. Its main intent is to give you the key steps for a successful creation. A user feature reference may be instantiated [1] only if its creation is correct.

Before reading this article, see the technical article about Power Copy and User Feature [2].

[Top]

The CAAMcaUdfCreation Use Case

CAAMcaUdfCreation is a use case of the CAAMechanicalCommands.edu framework that illustrates MechanicalCommands framework capabilities.

[Top]

What Does CAAMcaUdfCreation Do

The use case creates a user feature reference, CAAUserFeatureSample, in using data from the CAALoft.CATPart document. The new user feature reference is compulsorily created in the document which contains data which composes it.

The part contains two Open Bodies:

The "LoftWith2Circles" surfacic features set. It is a loft (Loft.2) defined by two circles ( Circle.3 and Circle.4). These circles are placed on two planes, respectively Plane.1 and Plane.2. These two planes are perpendicular to a line, Line.2, at each of its end points.
The "Inputs" surfacic features set. It contains Point.1 and Point.2. The Line.2 is built using these two points.

The user feature reference will be created in selecting the "LoftWith2Circles" surfacic features set.

"LoftWith2Circles" is the component selected to compose the user feature reference, and the "Inputs" contains all the features, and only them, which are necessary for the component. These features are the inputs, which is where the surfacic features set's name comes from.

This separation between components and inputs is strongly recommended to enhance the understanding of the user feature reference. In the technical article [2], the chapter "Useful Tips" describes how to organize the Part document in the best way.

*Fig.1: The CAALoft Part Document*

The modified document, which contains the new user feature reference, is saved under the name CAAUdfLoft.CATPart.

*Fig.2: The CAAUdfLoft Part Document*

You can notice that the new user feature reference is into a set, Userfeatures, dedicated to the user feature references.

This new user feature reference contains a lot of parameters but we have published only two among them: the radius of the two circles. We have changed the name (role) of the first parameter, to show the importance of an explicit name.

*Fig.3: The Published Parameters*

The two published parameters appear under the user feature reference in the specification tree.

The interactive scenario:

Launch CATIA. When the application is ready:

On the File menu, click Open
In the File Selection Dialog box click CAALoft.CATPart [see how to find this part ] and click Open
On the Insert menu, point to UserFeature and click UserFeature Creation
A UserFeature Definition dialog box appears
- Click the Definition tab
  - Click Loft.2
  - Enter CAAUserFeatureSample in the Name field
- Click the Inputs tab, notice the two points
- Click the Parameters tab
  - Click LoftWith2Circle\Circle.3\Circle center-radius , click Published Name and give a new name such as "Radius of the circle placed at the first input"
  - Click LoftWith2Circle\Circle.4\Circle center-radius and click Published Name

[Top]

How to Launch CAAMcaUdfCreation

To launch CAAMcaUdfCreation, you will need to set up the build time environment, then compile CAAMcaUdfCreation along with its prerequisites, set up the run time environment, and then execute the use case [3].To launch the use case execute the command:

mkrun -c CAAMcaUdfCreation InputPath [OutputPath]

Where:

InputPath : The path of the file CAALoft.CATPart included in the directory CAAMechanicalCommands.edu/InputData
- Unix : InstallRootDirectory/CAAMechanicalCommands.edu/InputData
- Windows : InstallRootDirectory\CAAMechanicalCommands.edu\InputData
OutputPath: The path to write the output file CATUdfLoft.CATPart. If this path is empty, the output file is created in the current directory.

[Top]

Where to Find the CAAMcaUdfCreation Code

The CAAMcaUdfCreation use case is made of a main program located in the CAAMcaUdfCreation.m module of the CAAMechanicalCommands.edu framework:

Windows	`InstallRootDirectory\CAAMechanicalCommands.edu\CAAMcaUdfCreation.m\`
Unix	`InstallRootDirectory/CAAMechanicalCommands.edu/CAAMcaUdfCreation.m/`

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

In the CAAMcaUtilities.m module of the same framework, there is a global function to retrieve data from the input Part, named CAAMcaGetGeometry. It is located in CAAMcaGetGeometry.cpp. The header of this function, CAAMcaGetGeometry.h, is set in the PrivateInterfaces directory of the framework.

[Top]

Step-by-Step

The main steps of CAAMcaUdfCreation are:

Prolog
Retrieving the CATIUdfFactory Interface Pointer on the Root Container
Creating the New User Feature Reference
Changing the Default Icon
Retrieving the Component from the CAALoft Part
Verifying the Component
Filling the New User Feature Reference
Renaming the Inputs
Publishing the Parameters
Renaming the Published Parameters
Putting the User Feature Reference in the UserFeatures Set
Epilog

[Top

Prolog

CAAMcaUdfCreation begins by creating a session, and opening the CAALoft Part document. Next it retrieves the root container of this Part as a pointer to CATIPrtContainer, pIPrtCon. This is the usual sequence for loading a Part document [4].

Thanks to the GetPart method on the root container we retrieve the Mechanical Part. This part is handled by the smart pointer spSpecObjectCAALoftPart.

[Top]

Retrieving the CATIUdfFactory Interface Pointer on the Root Container

  ...
  CATIUdfFactory *pIUdfFactory = NULL ;
  rc = pIPrtCont->QueryInterface(IID_CATIUdfFactory,(void **) &pIUdfFactory);
  if ( FAILED(rc) )return 1 ;
  ...

The root container, pIPrtCont, of the Part document implements CATIUdfFactory. Thanks to this interface you can create a User Feature reference.

[Top]

Creating the New User Feature Reference

  ...
  CATUnicodeString UserFeatureName = "CAAUserFeatureSample" ;
  CATIUdfFeature_var spIUdfFeature = pIUdfFactory->CreateUserFeature(UserFeatureName);
  if ( NULL_var == spIUdfFeature )return 1 ;
  ...

In the Part document, handled by pIUdfFactory, a new User Feature reference is created thanks to the CreateUserFeature method.

But this feature is empty and not really recognized as a User Feature reference as long as it is not put in the User Feature Set (see Putting the User Feature Reference in the UserFeatures Set). The following piece of code proves it: the list returned by GetUserFeatureList, pUserFeatureList , is NULL.

  ...
  CATListValCATISpecObject_var * pUserFeatureList = NULL ;
  pUserFeatureList = pIUdfFactory->GetUserFeatureList();
  if ( NULL != pUserFeatureList ) return 1 ;
  ...

This new feature implements CATIUdfFeature. That interface enables the contents of the User Feature reference to be defined. It is described in the next steps.

[Top]

Changing the Default Icon

This part of code is set in comment in the code. Remove the comment to have the functionality.

  ... 
  CATIIcon_var Icon = spIUdfFeature ;
  if ( NULL_var != Icon )
  {
     Icon->SetIconName("I_CombinedCurve");
  }
  ...

It is possible to associate an icon with the created reference. This icon will be displayed in front of the reference, and in front of each instance of this reference. Here is an image of a reference, and one instance:

You recognize the icon of the combined curve [6].

[Top]

Retrieving the Component from the CAALoft Part

  ...
  CATBaseUnknown * pLoftOpenBody = NULL ;
  rc = ::CAAMcaGetGeometry(spSpecObjectCAALoftPart,"LoftWith2Circles",&pLoftOpenBody);
  if ( FAILED(rc) )return 1 ;

  CATBaseUnknown_var spLoftOpenBody = pLoftOpenBody ;
  pLoftOpenBody->Release();
  pLoftOpenBody = NULL ;
  ...

In the CAALoft Part document we search for the LoftWith2Circles surfacic features set thanks to a global function CAAMcaGetGeometry created for the use case. This surfacic set will be the single component of the User Feature reference.

Note: The best way, in this use case, is to select the surfacic set. But you have the same result if you select all the components of the surfacic set.

[Top]

Verifying the Component

  ...
  CATUnicodeString  message ;
  CATListValCATBaseUnknown_var * pComponentList = NULL ;
  pComponentList  = new  CATLISTV(CATBaseUnknown_var);
  pComponentList->Append(spLoftOpenBody);
  
  rc = spIUdfFeature->VerifyComponents(pComponentList,message);
  if ( FAILED(rc) ) return 1 ;
  ...

This step is mandatory. First fill in a list, pComponentList, with your component spLoftOpenBody. VerifyComponents of CATIUdfFeature checks that an instantiation of the User Feature reference will be possible.

In fact, VerifyComponents checks, among other things, that all external links for each component implement the CATIReplace interface. For more details, read the chapter "Technologies Used" of the technical article about Power Copy and User Feature [2].

[Top]

Filling the New User Feature Reference

  ...
  rc = spIUdfFeature->SetComponents(pComponentList);
  delete pComponentList ;
  pComponentList = NULL ;
  ...

Now the User Feature reference CAAUserFeatureSample, handled by the CATIUdfFeature interface pointer spIUdfFeature, is filled. The component list is no more useful. pComponentList can be deleted.

The main role of the SetComponents method is to determine the inputs. The User Feature reference is a "black box" containing components. Each input is defined by the external links of this black box. For more details, read the chapter "Technologies Used" of the technical article about Power Copy and User Feature [2].

Note: In this use case we have checked the component before calling SetComponents. Calling VerifyComponents first is strongly recommended. You can nevertheless call it after SetComponents and in this case the first argument of VerifyComponents must be NULL. But caution, the SetComponents can not be called twice on the same feature. So if the check fails, you must delete the User Feature to recreate a new one.

Once the User Feature is checked and filled, you can use all methods of CATIUdfFeature to analyze or modify the inputs and the parameters. It is the goal of the two following steps.

[Top]

Renaming the Inputs

Renaming the inputs is strongly recommended to make them speak to the end user.

  ...
  int Nbinput = 0;
  rc = spIUdfFeature->GetInputsNumber( Nbinput );
  if ( SUCCEEDED(rc) )
  {
      CATUnicodeString TheRoleOfTheFirstInput ="The top point of the loft" ;
      rc = spIUdfFeature->SetInputRole( 1, TheRoleOfTheFirstInput );
      ...

In the use case, Nbinput is also equal to 2, because the User Feature reference has two points as inputs.

When you interactively instantiate a User Feature reference, the following dialog box appears:

Notice the list of inputs. The second input Point.2 is not explicit, but the first input is clearer: The top point of the loft. To change the role of an input, use the SetInputRole method. The first argument is the input number.

[Top]

Publishing the Parameters

The contents of the User Feature reference defines a set of knowledge parameters. For more details, read the chapter "Published Parameters" of the technical article about Power Copy and User Feature [2]. Among them, it is possible to publish some. It means that at each instantiation, or during an edition [5], you can modify these parameters on the User Feature instance. A published parameter is a parameter which has a signification for your User Feature reference.

 ...
  CATListValCATBaseUnknown_var * pInternalParametersList = NULL ;

  rc = spIUdfFeature->GetInternalParameters( pInternalParametersList );
  if ( SUCCEEDED(rc) )
  {
     ...
     CATBaseUnknown_var FirstPublishedParam = (*pInternalParametersList)[5] ;
     rc = spIUdfFeature->AddParameter(FirstPublishedParam);
     ...

     CATBaseUnknown_var SecondPublishedParam = (*pInternalParametersList)[8] ;
     rc = spIUdfFeature->AddParameter(SecondPublishedParam);
     ...

We have published two parameters thanks to the AddParameter method. FirstPublishedParam is the fifth parameter returned by the GetInternalParameters method and SecondPublishedParam is the eighth parameter returned by this method. The fifth and the eighth parameters are the radius of the Circle.3 (top) and Circle.4 (bottom) circles respectively. (We have found these two values 5 and 8 interactively.)

All published parameters appear under the User Feature reference in the specification tree, as shown in Fig 3.

[Top]

Renaming the Published Parameters

Like the inputs, it is recommended to change the role of the published parameters to make them speak to the end user.

... CATUnicodeString Name= "Radius of the circle placed at the first input" ; rc = spIUdfFeature->SetParameterRole(FirstPublishedParam,Name); ...

We have changed the role of the first published parameter thanks to the SetParameterRole method.

[Top]

Putting the User Feature Reference in the UserFeatures Set

  ...
  CATIUdfFeatureSet_var  spIUdfFeatureSet = pIUdfFactory->GetFeatureSet(1);

  if ( NULL_var != spIUdfFeatureSet )
  {
     spIUdfFeatureSet->AppendFeature(spIUdfFeature);
  }
  ...

At last you put the new User Feature reference into the UserFeatures set dedicated to them. The GetFeatureSet method with 1 as argument retrieves it. (0 is for the Power Copy set.)

Now we check, with the following piece of code, that the list of User Feature references returned by the GetUserFeatureList method, pUserFeatureList , is not NULL and contains one element.

  ...
  pUserFeatureList = pIUdfFactory->GetUserFeatureList();
  if ( NULL == pUserFeatureList ) return 1 ;
  if ( pUserFeatureList->Size() != 1 ) return 1 ;
  ...

[Top]

Epilog

The last actions of the CAAMcaUdfCreation use case are the following: save the CAALoft.CATPart as CAAUdfLoft.CATPart, close it and delete the session. It is also described in the Loading a Document use case [4].

[Top]

In Short

This use case has demonstrated how to create a User Feature reference:

Retrieves a CATIUdfFactory interface pointer, thanks to a QueryInterface on the root container of the part
Creates a new User Feature reference with the CreateUserFeature method of CATIUdfFactory . This new feature implements the CATIUdfFeature.
Retrieves the component(s)
Verifies the component with the VerifyComponents method of CATIUdfFeature
Fills the User Feature reference with the component thanks to the SetComponents method of CATIUdfFeature
Renames the inputs thanks to the SetInputRole method of CATIUdfFeature
Publishes two parameters thanks to the AddParameter method of CATIUdfFeature
Renames one of the published parameters thanks to the SetParameterRole method of CATIUdfFeature
Puts the new User Feature in the User Feature Set. First retrieves the User Feature set thanks to the GetFeatureSet method of CATIUdfFactory. This set implements CATIUdfFeatureSet. At last, adds to the set the new feature thanks to the AppendFeature method of the CATIUdfFeatureSet.

[Top]

References

[1]	Instantiating a User Feature Reference
[2]	Power Copy and User Features Overview
[3]	Building and Launching a CAA V5 Use Case
[4]	Loading a Document
[5]	Editing a User Feature Reference
[6]	Creating a New Geometrical Feature: the Combined Curve
[Top]

History

Version: 1 [Nov 2001]	Document created
Version: 2 [Feb 2005]	Document Updated to modify the default icon
[Top]

Mechanical Modeler