Product Synthesis & Knowledgeware

What You Will Learn With This Use Case

This use case is intended to help you make your first steps in programming the CATIA simulation modeler. Its main intent is to introduce the API of the simulation modeler, and ways to use it.

The scenario is based on an industrial process:

1. users define a set of trajectories to move products within a given system, for instance a test bed
2. a batch utility translate them in DMU Navigator
3. translated data are used to validate and replay the trajectories in DMU Navigator.

To perform the first and last operations, the user works with on-the-shelf softwares. But a utility to translate trajectories from any system to another does not exist on the shelf.

The target of this use case is to learn how to build such utility. To simplify explanations, we will skip the parsing phasis.

This picture represents a CATProduct document containing trajectories: the run of the use case will add one replay.

[Top]

Simulation Concepts

Before getting to the use case itself, it is important to get an understanding of some of the concepts that are at the heart of the Simulation, since the use case basically navigates among objects that represent those concepts. They are presented in Simulation Overview [1].

These concepts are:

• Replay
• Channel
• Sample

[Top]

The CAASiiCreateReplay Use Case

CAASiiCreateReplay is a use case of the CAASimulationInterfaces.edu framework that illustrates SimulationInterfaces framework capabilities.

[Top]

What Does CAASiiCreateReplay Do

The goal of CAASiiCreateReplay is to:

• Open a CATProduct document, whose pathname is passed in argument
• Create a replay in the document
• Create a channel in the replay
• Create samples in the channel
• Set the information in samples
• Store the document.

[Top]

How to Launch CAASiiCreateReplay

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

Launch the use case as follows:

• With Windows

  e:> CAASiiCreateReplay inputDirectory inputFile.CATProduct outputDirectory

• With UNIX

  $ CAASiiCreateReplay inputDirectory inputFile.CATProduct outputDirectory

where:

[Top]

Where to Find the CAASiiCreateReplay Code

The CAASiiCreateReplay use case is made of a single class named CAASiiCreateReplay whose header and source files are located in the CAASiiCreateReplay.m module of the CAASimulationInterfaces.edu framework:

where InstallRootDirectory is the directory where the CAA CD-ROM is installed. The CAASiiCreateReplay class derives from CATInteractiveApplication. The described code is located in the BeginApplication method.

[Top]

Step-by-Step

There are five main steps in CAASiiCreateReplay:

1. Prolog
2. Creating the Replay
3. Creating the Channel
4. Saving the Document
5. Epilog

We will now comment each of these steps by looking at the code.

[Top]

Prolog

The use case is the CAAKiiCreateMechanism class that derives from CATInteractiveApplication and that is simply instantiated. It runs in one shot and the described code is located in the BeginApplication method. It begins by creating a session, and by opening the use case CATProduct document passed as an argument: pDocument refers to it. This is the usual sequence for creating a CATIA document [3].

The last step is to simulate the parsing of a file containing the motion data in a structure. This structure is a set of arrays containing references to the moving products apiProductOnProduct, the numer of samples for each products aNumberOfSamples, the times aInputTime and the positions aInputProductMove. To fill the references to moving products, one search the first product in the product structure.

[Top]

Creating the Replay

...
  //==========================================================================================
  // 4 - Create a replay in the document
  //==========================================================================================
  CATIReplay* piReplay = NULL;
  HR = CATCreateReplay (pDocument, &piReplay);
  if (SUCCEEDED(HR))
  {
    // Search for the factory of channels
    CATIReplayChannelProductMoveFactory* piReplayChannelProductMoveFactory = NULL;
    HR = piReplay->QueryInterface(IID_CATIReplayChannelProductMoveFactory,(void**)&piReplayChannelProductMoveFactory);
    if (SUCCEEDED(HR))
    {
      for (int j = 0; j < numberOfProducts; j++)
      {
...

The creation of a replay in the document is made through the global function CATCreateReplay using pDocument as an input.

This replay can be used as a factory of 'product move' channel finding its CATIReplayChannelProductMoveFactory interface.

Then the use case loops on all products to create a channel for each.

[Top]

Creating the Channel

...
        //====================================================================================
        // 5 - Create a channel for each product and fill it
        //====================================================================================
        CATIReplayChannelProductMove* piReplayChannelProductMove = NULL;
        HR = piReplayChannelProductMoveFactory->CreateInstance ((CATBaseUnknown**)&apiProductOnProduct[j],&piReplayChannelProductMove);
        if (SUCCEEDED(HR))
        {
          // Create the samples
          for (int i = 0; i < aNumberOfSamples[j] && SUCCEEDED(HR); i++)
          {
            HR = piReplayChannelProductMove->AddSample (aInputTime[j][i], aInputProductMove[j][i]);
          }
          // Release the reference to the channel
          piReplayChannelProductMove->Release();
          piReplayChannelProductMove = NULL;
        }
        // Release the reference to the product
        apiProductOnProduct[j]->Release();
        apiProductOnProduct[j] = NULL;
      }
      // Release the reference to the factory
      piReplayChannelProductMoveFactory->Release();
      piReplayChannelProductMoveFactory = NULL;
    }
    // Release the reference to the replay
    piReplay->Release();
    piReplay = NULL;
  }
...

The channel is created using CATIReplayChannelProductMoveFactory::CreateInstance method using the reference to the moving product to indicate the product of the channel.

Then the use case loops on all the samples and creates them using CATIReplayChannelProductMove::AddSample method with the corresponding time and position.

The next step consists in cleaning the environment and releasing all resources. The technique is fairly simple: all references to interfaces have to be released using CATBaseUnknown::Release and then the list is deleted. All pointer are nullified.

[Top]

Saving the Document

...  
  //==========================================================================================
  // 6 - save the document
  //==========================================================================================
  char outputPath[CATMaxPathSize]; 
  CATMakePath (argv[3], argv[2], outputPath);
  HR = CATDocumentServices::SaveAs(*pDocument, outputPath);
  if (!SUCCEEDED(HR))
  {
    cout << outputPath << " could not be stored"<< endl;
    _returnCode = 4;
    return;
  }
...

The document is saved using CATDocumentServices::Saveas method with the right path, that is in the directory passed as the third argument when launching the use case, and with the same name as the input document.

[Top]

Epilog

After being saved, it is is closed using the remove method of its LifeCycleObject interface. The environment is cleaned, and the session is deleted by the Delete_Session global function, which is passed the same identifier that was used to open it. This is the usual sequence for saving and closing a document, and for deleting the session [3].

[Top]

In Short

This use case has demonstrated the way to programmatically create a product motion in a CATProduct document.

More specifically, you have learn how to create:

• replays in a CATProduct document
• channels within a replay
• samples within a channel.

[Top]

References

History

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