Product Synthesis & Knowledgeware

DMU Navigator

Reading a Product's Motion in a Replay

From simulation to file
Use Case

Abstract

This article discusses the CAASiiReadReplay use case. This use case explains how to open a CATProduct document and explore its content from a simulation perspective, down to the replay entities that capture the motion of a product contained in the CATProduct document.


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 and validate interactively a set of trajectories to move some products within DMU Navigator
  2. when trajectories are validated, a batch utility translate them in another system
  3. translated data are used to perform a task.

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 suppose the other system read a text file with a dedicated format.

This picture represents a *.CATProduct document containing some trajectories.

This picture represents a text file which results from the use of the sample on the *.CATProduct document.

[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 :

[Top]

The CAASiiReadReplay Use Case

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

[Top]

What Does CAASiiReadReplay Do

The goal of CAASiiReadReplay is to:

[Top]

How to Launch CAASiiReadReplay

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

Launch the use case as follows:

where:

inputDirectory The directory in which inputFile.CATProduct is located
inputFile.CATProduct The file that contains the use case CATProduct document
outputFile The file that will contain the resulting file

[Top]

Where to Find the CAASiiReadReplay Code

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

Windows InstallRootDirectory\CAASimulationInterfaces.edu\CAASiiReadReplay.m\
Unix InstallRootDirectory/CAASimulationInterfaces.edu/CAASiiReadReplay.m/

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

[Top]

Step-by-Step

There are seven main steps in CAASiiReadReplay:

  1. Prolog
  2. Getting Access to the Replays of the Document
  3. Getting Access to All Channels of the Replay
  4. Filtering the Product Move Channels
  5. Getting the Channel Information
  6. Cleaning the Environment
  7. Epilog

We will now comment each of those sections by looking at the code.

[Top]

Prolog

The use case is the CAASiiReadReplay 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]. It also opens the output file: outputFile refers to it.

[Top]

Getting Access to the Replays of the Document

...
  //==========================================================================================
  // 4 - Read all the replays of the document
  //==========================================================================================
  CATIReplayList* piListOfReplays = new CATIReplayList();
  HR = CATListReplays (pDocument, piListOfReplays);
  if (SUCCEEDED(HR))
  {
    for (int i = 1; i <= piListOfReplays->Size(); i++)
    {
...

A CATProduct document contains from zero to many Replays. Access to the list of all replays included in the document is made through the global function CATListReplays using pDocument as an input. As a result, it provides a CATIReplayList collection.

The number of replays of a list is given by the CATIReplayList::Size method.

[Top]

Getting Access to All Channels of the Replay

...
      //======================================================================================
      // 5 - Read all the channels of the replay
      //======================================================================================
      int numberOfChannel = 0;
      HR = (*piListOfReplays)[i]->GetNumberOfChannel(&numberOfChannel);
      if (SUCCEEDED(HR))
      {        
        // Print the name of the replay
        CATIAlias* piAliasOnReplay = NULL;
        if (SUCCEEDED((*piListOfReplays)[i]->QueryInterface(IID_CATIAlias,(void**)&piAliasOnReplay)))
        {
          outputFile << "Replay " << piAliasOnReplay->GetAlias().ConvertToChar() <<endl << flush;
          piAliasOnReplay->Release();
          piAliasOnReplay = NULL;
        }
        // Loop on all channels
        for (int j = 1; j <= numberOfChannel; j++)
        {
...

Every replay of the list is accessible using CATIReplayList::operator[] like in (*listOfReplays)[i]. The rank varies from one to the number of replays.

The number of channels which belong to a replay, is read through CATIReplay::GetNumberOfChannel method.

The CATIAlias interface is used to retrieve the name of the replay to be output on the file.

Then use case loops on all the channels of the replay.

[Top]

Filtering the Product Move Channels

...
          //==================================================================================
          // 6 - Filter the product motion channels
          //==================================================================================
          CATIReplayChannel* piChannel = NULL;
          HR = (*piListOfReplays)[i]->GetChannel(j, &piChannel);
          if (SUCCEEDED(HR))
          {
            CATIReplayChannelProductMove* piProductMoveChannel = NULL;
            HR = piChannel->QueryInterface(IID_CATIReplayChannelProductMove,(void**)&piProductMoveChannel);
            if (SUCCEEDED(HR))
            {
...

Each individual channel is accessible using CATIReplay::GetChannel method. The rank varies from one to the number of channels.

To find out the type of the channel, one might use the query interface method : if it succeeds,the channel is from the right type. To access product motion, the sample queries the CATIReplayChannelProductMove interface.

[Top]

Getting the Channel Information

...
              //==============================================================================
              // 7 - Read product, time, position of all the samples of the channel and print the data
              //==============================================================================
              CATIProduct* piProduct = NULL;
              HR = piProductMoveChannel->GetProduct((CATBaseUnknown**)&piProduct);
              if (SUCCEEDED(HR))
              {
                CATIAlias* piAliasOnProduct = NULL;
                HR = piProduct->QueryInterface(IID_CATIAlias,(void**)&piAliasOnProduct);
                if (SUCCEEDED(HR))
                {  
                  // Print the name of the product
                  outputFile << "   Product " << piAliasOnProduct->GetAlias().ConvertToChar() <<endl << flush;
                  piAliasOnProduct->Release();
                  piAliasOnProduct = NULL;
                  // Loop on the samples 
                  int numberOfSample = 0;
                  HR = piProductMoveChannel->GetNumberOfSample(&numberOfSample);
                  for (int k = 1; k <= numberOfSample; k++)
                  {
                    // Print sample information
                    double time;
                    HR = piProductMoveChannel->GetSampleTime(k, &time);
                    double productMove[12];
                    HR = piProductMoveChannel->GetSample(k, productMove);
                    outputFile << "      " << time << " = ";
                    for (int l = 0; l < 12; l++) outputFile << productMove[l] << "; ";
                    outputFile << endl << flush;
                  }
                  outputFile << "   EndProduct" <<endl << flush; 
                }
...

The 'Product Move' channel refers the product to move : it can be read using the CATIReplayChannelProductMove::GetProduct method.

The CATIAlias interface is used to retrieve the name of the product to be output on the file.

A channel is made of samples : the CATIReplayChannel::GetNumberOfSample method is used to retrieve the number of samples in the channel.

Each sample is associated to a time value which can be read using the CATIReplayChannel::GetSampleTime method.

For a product motion, the sample contains the position of the product : the position matrix (with respect to the root product axis system) is accessible thru the CATIReplayChannelProductMove::GetSample method.

[Top]

Cleaning the Environment

...  
                // Release the reference to the product
                piProduct->Release();
                piProduct = NULL;
              }
              // Release the reference to the product move channel
              piProductMoveChannel->Release();
              piProductMoveChannel = NULL;
            }
            // Release the reference to the channel
            piChannel->Release();
            piChannel = NULL;
          }
        }
        outputFile << "EndReplay" <<endl << flush;
      }
      // Release the reference to the replay
      (*piListOfReplays)[i]->Release();
      (*piListOfReplays)[i] = NULL;
    }
  }
  // Clean the list
  delete piListOfReplays;
  piListOfReplays = NULL;

  // Close the output file
  outputFile.close();
...

The next step consist 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.

The output file is closed using standard method.

[Top]

Epilog

The document is closed using its LifeCycleObject interface and more specifically the remove method. 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 closing a document, and for deleting the session [3].

[Top]


In Short

This use case has demonstrated the way to programmatically navigate a CATProduct document, from the document itself down to the entities that hold the motion associated with one of its' products.

More specifically, you have learn how to access:

[Top]


References

[1] Simulation Overview
[2] Building and Launching a CAA V5 Use Case
[3] Creating a New Document
[Top]

History

Version: 1 [Jan 2000] Document created
[Top]

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