Mechanical Modeler

What You Will Learn With This Use Case

The goal of this article is to show how to edit a User Feature.

On a User Feature you can modify:

1. The value on an input, that is set a new input feature in place of an old one
2. The value of a published parameter.

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

[Top]

The CAAMcaUdfEdition Use Case

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

[Top]

What Does CAAMcaUdfEdition Do

In the CAAUdfModelWithInstances Part document we have two instances of the User Feature reference CAAUserFeatureSample. This User Feature reference has been created by the use case "Creating a User Feature Reference" [2], and the two instances have been created thanks to the use case "Instantiating a User Feature Reference" [3].

Fig.1: The CAAUdfModelWithInstances Part Document

On the first instance CAAUserFeatureSample.1 we will change the inputs. Its inputs are Point.3 and Point.1 and will become Point.1 and Point.2 respectively.

Fig.2: Image before Modifications

Fig.3: Image after Modifications

On the second instance "The Loft With Point2 and Point3", we will change the value of the first published parameter "Radius of the circle placed at the first input". This value is 10mm and will become 50mm.

Fig.4: Image before Modifications

Image after modifications:

Fig.5: Image after Modifications

The interactive scenario:

Launch CATIA, When the application is ready :

• On the File menu, click Open
• In the File Selection Dialog box click CAAUdfModelWithInstances.CATPart [see how to find this part ] and click Open
• Double click on CAAUserFeatureSample.1 in the specifications tree
• A UserFeature Edition dialog box appears
  • Click the Inputs tab
    • Click the first line, and click Point.1 in the specification tree
    • You are now on the second line, Click Point.2 in the specification tree
    • Click OK
• Double click on The Loft with Point2 and Point3 in the specification tree
• A UserFeature Edition dialog box appears
  • Click the Parameters tab
    • In the first editor, dedicated to the parameter "Radius of the circle placed at the first input" , enter 50.
    • Click OK

[Top]

How to Launch CAAMcaUdfEdition

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

mkrun -c CAAMcaUdfEdition InputPath [OutputPath]

• InputPath: The path of the file CAAUdfModelWithInstances.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 CAAUdfModelWithInstancesModified.CATPart. If this path is empty, the output file is created in the current directory.

[Top]

Where to Find the CAAMcaUdfEdition Code

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

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

This section does not follow exactly the use case code. We have chosen to show, from the use case, the main steps of one edition.

1. Prolog
2. Retrieving the User Feature
3. Beginning Modifications
4. Modifyingthe Inputs
5. Modifying the Published Parameters
6. Ending Modifications
7. Epilog

[Top

Prolog

CAAMcaUdfEdition begins creating a session, and opening the CAAUdfModelWithInstances Part document. Next it retrieves the root container of this Part. This is the usual sequence for loading a Part document [5].

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

Retrieving the User Feature

This piece of code is almost the same for the first and the second User Feature to modify. For the first User Feature, the second argument of CAAMcaGetGeometry is CAAUserFeatureSample.1, and for the second feature it is The Loft With Point2 and Point3.

  CATBaseUnknown * pOnInstance = NULL ;
  CATIUdfFeatureInstance * pIUdfFeatInstance = NULL ;
  rc = ::CAAMcaGetGeometry(spSpecObjectCAAUdfModelPart,"CAAUserFeatureSample.1",&pOnInstance);
  if ( FAILED(rc) ) return 1 ;
  rc = pOnInstance->QueryInterface(IID_CATIUdfFeatureInstance,(void **) &pIUdfFeatInstance);
  if ( FAILED(rc) )  return 1;
  ...

The goal of this section is to find in the CAAUdfModelWithInstances Part document the feature CAAUserFeatureSample.1 (i.e The Loft With Point2 and Point3).

CAAMcaGetGeometryis a function which returns a pointer, pOnInstance, on the object whose name is the second argument. This object is a User Feature which implements CATIUdfFeatureInstance. pIUdfFeatInstance is the pointer to this interface.

[Top]

Beginning Modifications

  rc = pIUdfFeatInstance->Init();
  if ( FAILED(rc) ) return 1;
  ...

This step is mandatory for any modification on the instance. Only after calling the Init method you can modify the instance.

[Top]

Modifying the Inputs

This step is done on the first User Feature instance CAAUserFeatureSample.1. This User Feature has two inputs.

Modification of the first input:

  CATBaseUnknown * pInput = NULL ;
  rc = ::CAAMcaGetGeometry(spSpecObjectCAAUdfModelPart,"Point.1",&pInput);
  if ( FAILED(rc) )  return 1 ;

  CATPathElement * pPathFirstInput = new CATPathElement(pInput);
  rc = pIUdfFeatInstance->SetNewInput(1,pPathFirstInput);
  if ( FAILED(rc) )  return 1 ;
  ...

The feature associated with the first input is Point.3. (See the use case Instantiating a User Feature Reference [3]). We change it to the Point.1 feature.

Point.1 is found in the CAAUdfModelWithInstances Part document thanks to the CAAMcaGetGeometry function. This function returns a pointer to this feature, pInput .

We create a path, pPathFirstInput, with the pointer pInput. At last, we use the SetNewInput method on the pIUdfFeatInstance to modify the first input of the User Feature. The first argument of this method is the number of the input, here it is 1 and the second argument is the complete path of the new input, pPathFirstInput.

Note: pIUdfFeatInstance is the CATIUdfFeatureInstance interface pointer of the first instance defined in the Retrieving the User Feature step.

For the second input:

  rc = ::CAAMcaGetGeometry(spSpecObjectCAAUdfModelPart,"Point.2",&pInput);
  if ( FAILED(rc) )  return 1 ;
  
  CATPathElement * pPathSecondInput = new CATPathElement(pInput);
  rc = pIUdfFeatInstance->SetNewInput(2,pPathSecondInput);
  if ( FAILED(rc) )  return 1 ;

  ...

The feature associated with the second input is Point.1. (See the use case Instantiating a User Feature Reference [3]). We change it by the Point.2 feature.

Point.2 is found in the CAAUdfModelWithInstances Part document thanks to the CAAMcaGetGeometry function. This function returns a pointer on this feature, pInput .

We create a path, pPathSecondInput , with the pointer pInput. At last, we use the SetNewInput method on the pIUdfFeatInstance to modify the second input of the User Feature. The first argument of this method is the number of the input, here it is 2 and the second argument is the complete path of the new input, pPathSecondInput .

[Top]

Modifying the Published Parameters

This step consists in modifying the value of the published parameters of the User Feature instance.

This step has been done on the second User Feature instance The Loft With Point2 and Point3.

  CATListValCATBaseUnknown_var * pListParam = NULL ;
  rc = pIUdfFeatInstance->GetParameters(pListParam) ;
  if ( FAILED(rc) ) return 1 ;
     
  CATICkeParm_var spCkeParm = (*pListParam)[1] ;
  if ( NULL_var != spCkeParm)
  {
         spCkeParm->Valuate(0.050f);
  }
  	 
   ...

pIUdfFeatInstance is the CATIUdfFeatureInstance interface pointer of the instance.The GetParameters method retrieves the list of all the published parameters.

In this use case, the value of the first parameter, (*pListParam)[1] has been changed by using the valuate method of CATICkeParm interface.

[Top]

Ending Modifications

  rc = pIUdfFeatInstance->Reset();
  if ( FAILED(rc) ) return 1;
  ...

This step is mandatory after any modification on the instance. After the Reset call you cannot modify the instance any longer.

Epilog

The last actions of the CAAMcaUdfEdition use case are the following: save the CAAUdfModelWithInstances.CATPart as CAAUdfModelWithInstancesModified.CATPart, close it and delete the session. It is also described in the Loading a Document use case [5].

[Top]

In Short

This use case has demonstrated how to edit a User Feature:

• Retrieves the User Feature to modify thanks to a local global function. This feature implements the CATIUdfFeatureIntance interface
• Begins the modifications by calling the Init method
• Modifies the User Feature, either the inputs or the published parameters
• End the modifications in calling the Reset method

[Top]

References

History

Copyright © 2001, Dassault Systèmes. All rights reserved.