Mechanical Design

3D Functional Tolerancing & Annotation

Browsing a Toleranced Model

Accessing and reading tolerancing information
Use Case

Abstract

This article discusses the CAATpiBrowseTolerances use case. This use case explains how to browse and read tolerances defined in a CATIA V4 model inserted in a CATProduct document.


What You Will Learn With This Use Case

This use case is intended to help you to use Technological Product Specifications (TPS) interfaces [1]. This set of interfaces allows you to navigate and read tolerancing information.

[Top]

The CAATpiBrowseTolerances Use Case

CAATpiBrowseTolerances is a use case of the CAATPSInterfaces.edu framework that illustrates CATTPSInterfaces framework capabilities.

[Top]

What Does CAATpiBrowseTolerances Do

The use case analyzes the model illustrated below. This model has been toleranced with CATIA V4 FDT function. First, this model is inserted into a CATProduct document. Then the use case retrieves tolerancing information using TPS interfaces and dumps them in an output text file.

Toleranced Model Browsed: the CAATpiBrowseInModel1.model
CAATpiBrowseInModel1.gif

The following output text file is generated: CAATpiBrowseOutText1.txt

COPYRIGHT DASSAULT SYSTEMES 2000
------------------------ Set.0.Tolerance.0 -----------------------
SuperType:                     Datum
Type:                          Simple datum
Link to surface:               1 TTRS, Planar
------------------------ Set.0.Tolerance.1 -----------------------
SuperType:                     Form
Type:                          Flatness
Semantic behavioral itfs:      CATITPSToleranceZone
                               CATITPSMaterialCondition
Link to surface:               1 TTRS, Planar
Tolerance zone value:          0.008 mm
------------------------ Set.0.Tolerance.2 -----------------------
SuperType:                     Form
Type:                          Straightness
Semantic behavioral itfs:      CATITPSToleranceZone
                               CATITPSMaterialCondition
Link to surface:               1 TTRS, Planar
Tolerance zone value:          0.003 mm
------------------------ Set.0.Tolerance.3 -----------------------
SuperType:                     Datum
Type:                          Simple datum
Link to surface:               1 TTRS, Cylindrical
------------------------ Set.0.Tolerance.4 -----------------------
SuperType:                     Size
Type:                          Linear
Semantic behavioral itfs:      CATITPSDimensionLimits
                               CATITPSEnvelopCondition
Link to surface:               1 TTRS, Prismatic
Up limit:                      0.015 mm
Low limit:                     0.000 mm
...

[Top]

How to Launch CAATpiBrowseTolerances

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

Launch the use case as follows:

where:

inputDir The CNext/resources directory of CAATPSInterfaces.edu into which CAATpiBrowseOutText1.model is stored
outputDir The directory where you want to generate the file
CAATpiBrowseInModel1.model The model to process
CAATpiBrowseOutText1.txt The file generated from the model

[Top]

Where to Find the CAATpiBrowseTolerances Code

The CAATpiBrowseTolerances use case is located in the CAATpiBrowseTolerances.m module of the CAATPSInterfaces.edu framework:

Windows InstallRootDirectory\CAATPSInterfaces.edu\CAATpiBrowseTolerances.m\
Unix InstallRootDirectory/CAATPSInterfaces.edu/CAATpiBrowseTolerances.m/

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

Materials for this use case are located in CAATPSInterfaces.edu/CNext/resources (CAATpiBrowseInModel1.model, CAATpiBrowseOutText1.txt).

[Top]

Step-by-Step

This diagram can be used as a guide to follow the differents steps of the use case.

There are ten logical steps in CAATpiBrowseTolerances:

  1. Prolog
  2. Inserting the Model into the Product
  3. Retrieving the CATITPSDocument Interface on the Document
  4. Retrieving TPS Sets in Document
  5. Retrieving Tolerances from Set
  6. Analyzing Tolerance's Semantic Validity
  7. Analyzing Tolerance's Link with Geometry
  8. Reading Tolerance Zone Information
  9. Reading Dimension Limits Information
  10. Epilog

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

[Top]

Prolog

The use case is a main program (batch) with two input arguments. First, the path to an existing CATIA V4 model, second, the path to a dump text file. The usual sequence for creating a document is used to create a new Product document [3]. The pDoc variable used forward is a pointer on this document.

[Top]

Inserting the Model into the Product

  // Retrieve root product
  CATIDocRoots_var spDocRootOnDoc (pDoc);
  if ( spDocRootOnDoc == NULL_var ) return (2);

  CATListValCATBaseUnknown_var* RootsList = spDocRootOnDoc->GiveDocRoots();
  if ( RootsList == NULL || RootsList->Size() < 1 ) return (3);

  CATIProduct_var spProductOnDocRoot ((*RootsList)[1]);
  if (spProductOnDocRoot == NULL_var) return (4);

  // Add a receipt Product
  CATUnicodeString Name("TolerancedModel");
  CATIProduct_var spChildProduct = spProductOnDocRoot -> AddProduct(Name);

  // Transform command line argument in a path with correct string type
  CATUnicodeString ModelPath(iapArgv[1]);
  CATBSTR ModelPathAsBSTR;
  ModelPath.ConvertToBSTR(&ModelPathAsBSTR);

  // Add model in receipt Product
  CATIAProduct_var spChildProductJnl( spChildProduct );

  if ( spChildProductJnl == NULL_var ) return (5);

  int ier = spChildProductJnl -> AddMasterShapeRepresentation(ModelPathAsBSTR);
  if ( ier != 0 ) return (6);
...

A new product is added  under the root product. The model path provided as first argument is transformed in BSTR string type. The model is used to provide shape representation to the created product. 

[Top]

Retrieving the CATITPSDocument Interface on the Document

  HRESULT rc = E_FAIL;

  // Retrieve TPS entry point interface on document
  CATITPSDocument * piTPSDoc = NULL;
  rc = pDoc -> QueryInterface (IID_CATITPSDocument, (void**) &piTPSDoc);
...

Standard QueryInterface on document. CATITPSDocument is the entry point for accessing tolerancing data  included in document.

[Top]

Retrieving TPS Sets in Document

  // Retrieve list of tolerancing sets in document as a CATITPSList
  CATITPSList * piSetList = NULL;
  piTPSDoc -> GetSets(&piSetList);
  ...
  // Retrieve set count
  unsigned int SetCount = 0;
  piSetList -> Count(&SetCount);

  // Iterate on list of set and for each set analyze tolerances
  for( unsigned int SetIdx = 0; SetIdx < SetCount; SetIdx++ )
  {
    // Retrieve set in the list
    CATITPSComponent* piCompOnSet = NULL;
    piSetList->Item (SetIdx, &piCompOnSet);

    // Analyze sets of piTPSDoc
    CATITPSSet* piSet = NULL;
    HRESULT rc = piCompOnSet ->QueryInterface(IID_CATITPSSet, (void **)&piSet);
...

Tolerancing sets included in document are retrieved as a CATITPSList. This list interface is implemented by a temporary object. List size is provided  by the Count method.  List members are returned by the Item method as CATITPSComponent. A query on the wanted interface (here CATITPSSet) can then be done.

[Top]

Retrieving Tolerances from Set

    // Retrieve tolerances that belong to set as a CATITPSList
    CATITPSList* piToleList = NULL;
    piSet -> GetTPSs(&piToleList);

    // Retrieve tolerances count in set
    unsigned int ToleCount = 0;
    piToleList -> Count(&ToleCount);

    // Analyze tolerances of set
    for ( unsigned int ToleIdx = 0; ToleIdx < ToleCount; ToleIdx ++ )
    {
      // Get ToleIdx tolerance in set
      CATITPSComponent * piCompOnTole = NULL;
      piToleList -> Item (ToleIdx, &piCompOnTole);
...
      // Dump tolerance informations
      CAATpiDumpCATITPSSemanticValidity (piCompOnTole, pStream);
      CAATpiDumpCATITPS                 (piCompOnTole, pStream);
      CAATpiDumpCATITPSToleranceZone    (piCompOnTole, pStream);
      CAATpiDumpCATITPSDimensionLimits  (piCompOnTole, pStream);

      piCompOnTole -> Release();
    }
...

Tolerances included in a set are accessible  with GetTPSs method that returns a CATITPSList. Tolerances can then be retrieved as list members. For each tolerance the four functions CAATpiDumpxxx are called. The purpose of each function is to illustrate how to use a TPS interface and to dump the retrieved information to the output stream pStream. The four following steps describes these functions. 

[Top]

Analyzing Tolerance's Semantic Validity

void CAATpiDumpCATITPSSemanticValidity (CATITPSComponent * ipiTole,
                                        FILE * ipStream)
{
  // Retrieve CATITPSSemanticValidity interface on input tolerance.
  CATITPSSemanticValidity * piSemantic = NULL;
  HRESULT rc = ipiTole -> QueryInterface (IID_CATITPSSemanticValidity,
                                          (void **)& piSemantic);
  if ( SUCCEEDED(rc) )
  {
    //-------------------------------------------------------------------------
    // Identify SuperType and Type
    //-------------------------------------------------------------------------
  
    // Retrieve tolerance SuperType as an IID
    IID * pSuperTypeAsIID = NULL;
    piSemantic -> GetSuperType (&pSuperTypeAsIID);
  
    // Retrieve tolerance Type as an IID
    IID * pTypeAsIID = NULL;
    piSemantic -> GetType (&pTypeAsIID);
  
    // Transform SuperType and Type IID in strings
    CATUnicodeString Type ("Unknown");
    CATUnicodeString SuperType ("Unknown");
  
    // Form tolerances
    // If SuperType IID is the same that IID of CATITPSForm interface then this
    // tolerance belongs to the Form Super Type.
    if ( CATCmpGuid(&IID_CATITPSForm, pSuperTypeAsIID) == TRUE )
    {
      SuperType = "Form";
  
      // If Type IID is the same that IID of CATITPSStraightness interface then
      // this tolerance is a Straightness tolerance.
      if ( CATCmpGuid(&IID_CATITPSStraightness, pTypeAsIID) == TRUE )
        Type = "Straightness";
      else if ( CATCmpGuid(&IID_CATITPSFlatness, pTypeAsIID) == TRUE )
        Type = "Flatness";
      else if ...
...

    //-------------------------------------------------------------------------
    // Access list of behavioral interfaces implemented on tolerance
    //-------------------------------------------------------------------------

    // Retrieve list of behavioral interfaces that must be analyzed for a 
    // correct and plenty semantic understanding of this tolerance.
    // List is returned as a pointer on an array of pointers (IID adresses)
    int    SemanticItfCount = 0;
    IID ** ppSemanticItfList = NULL;

    rc = piSemantic -> GetUnderstandingSemanticsItf (&SemanticItfCount,
                                                     &ppSemanticItfList);

    // First and second IID in list (idx 0,1) are SuperType and Type of 
    // tolerance. Here start to iterate directly on index 2.
    // The list of semantic interfaces can contains interface IID that are not 
    // published yet. In order to be protected against misunderstanding, the 
    // client code must assume that, if one or some semantic interfaces are
    // unknown, all the interfaces and thus the whole tolerance must be
    // ignored.
...

Super type and type of tolerances must be retrieved via CATITPSSemanticValidity interfaces. Types are returned as Global Unique Identifiers (GUID or IID) which correspond to TPS typing interface IID's. The CATCmpGuid method can be used to compare IID.

Behavioral TPS interfaces implemented on tolerance are returned by GetUnderstandingSemanticsItf method. All behavioral interfaces must be analyzed for a correct and plenty semantic understanding of this tolerance.

[Top]

Analyzing Tolerance's Link with Geometry

void CAATpiDumpCATITPS (CATITPSComponent * ipiTole,
                        FILE * ipStream)
{
  // Retrieve CATITPS interface on input tolerance
  CATITPS * piTPS = NULL;
  HRESULT rc = ipiTole -> QueryInterface (IID_CATITPS, (void **)&piTPS );
  if ( SUCCEEDED(rc) )
  {
    // Links to toleranced surfaces is retrieved as a TTRS list
    unsigned int Count = 0;
    CATITTRSList * piTTRSList = NULL;
    CATITTRS * piTTRS = NULL;
    CATMmrTTRSClass TTRSClass = CATMmrUnknownTTRSClass;
    // Type CATMmrTTRSClass is an enum that describe functional surface class.
    // It can take values such as spherical, cylindrical, planar...
    // Unknown is a default value used for initialization purpose.

    rc = piTPS -> GetTTRS (&piTTRSList);

    if ( SUCCEEDED(rc) )
    {
      // Dump TTRS count
      piTTRSList -> Count (&Count);
      fprintf(ipStream, "%d%s", Count, " TTRS");

      // Iterate on TTRS list, and for each of them read 
      // and dump his surface class
      for ( unsigned int i = 0; i < Count; i++ )
      {
        // Retrieve TTRS number i in the list as a CATITTRS
        piTTRS = NULL;
        piTTRSList -> Item (i, &piTTRS);

        // Read TTRS class
        TTRSClass = CATMmrUnknownTTRSClass;
        piTTRS -> GetTTRSClass(TTRSClass);
...

Link to geometry is defined for each tolerance with TTRSs. The CATITPS interface provides the GetTTRS method which returns a TTRS list that can be manipulated with the Count and Item methods. Each TTRS defines a functional surface to which a tolerance is applied. A complete geometric and topologic analyze of this functional surface can be realized from the TTRS object. Here we only access the geometrical class of this functional surface by  using the GetTTRSClass method.

[Top]

Reading Tolerance Zone Information

A tolerance zone is a region of space where the toleranced surface of a real part must be within to respect a geometric TPS.

void CAATpiDumpCATITPSToleranceZone (CATITPSComponent * ipiTole,
                                     FILE * ipStream)
{
  // Retrieve tolerance zone interface on input tolerance
  CATITPSToleranceZone * piToleZoneOnTPS = NULL;
  HRESULT rc = ipiTole -> QueryInterface (IID_CATITPSToleranceZone, 
                                          (void **)&piToleZoneOnTPS);

  // QueryInterface succeeded only if CATITPSToleranceZone is a behavioral
  // interface of tolerance
  if ( SUCCEEDED(rc) )
  {
    // Read tolerance zone value
    double ToleZoneValue = 0.0;
    rc = piToleZoneOnTPS -> GetValue (&ToleZoneValue);
...

Tolerance zone value is accessible on TPS that implements the CATITPSToleranceZone interface.

[Top]

Reading Dimension Limits Information

Dimension limits define an interval for a dimension TPS. The real part dimension must be inside this interval to respect the specification .

void CAATpiDumpCATITPSDimensionLimits (CATITPSComponent * ipiTole,
                                       FILE * ipStream)
{
  // Retrieve dimension limits interface on input tolerance
  CATITPSDimensionLimits * piDimLimitsOnTPS = NULL;
  HRESULT rc = ipiTole -> QueryInterface (IID_CATITPSDimensionLimits,
                                          (void **)&piDimLimitsOnTPS);

  // QueryInterface succeeded only if CATITPSDimensionLimits is a behavioral
  // interface of tolerance. (Tolerance is a dimension)
  if ( SUCCEEDED(rc) )
  {
    // Try to read up and bottom limits of the dimension
    double UpLimit = 0.0;
    double BottomLimit = 0.0;
    rc = piDimLimitsOnTPS -> GetLimits (&BottomLimit, &UpLimit);

    // HRESULT returned by GetLimits must be tested, because E_FAIL is returned
    // when, for instance, dimension is defined as "10 max". In that case, it
    // is a single limit dimension. Modifier on this dimension can be read by 
    // using GetModifier method.
    if ( SUCCEEDED(rc) )
    {
      // Dump up and bottom dimensions limits values
      ...
    }
    else
    {
      // Read modifier on single limit dimension 
      CATTPSSingleLimit Modifier = CATTPSSLNotDefined;
      rc = piDimLimitsOnTPS -> GetModifier (&Modifier);
      ...

      // Dump modifier
      ...
    }
...

When tolerance is a dimension, the CATITPSDimensionLimits interface provides access to up and bottom limits or single limit modifier.

[Top]

Epilog

The use case finishes by freeing memory (release interface pointers) and closing the output stream, the document and the session [3].

[Top]


In Short

This use case has demonstrated the way to browse a toleranced model included in a CATProduct document by retrieving first tolerancing Sets then TPS. 

For a TPS:

[Top]


References

[1] Technological Product Specification Overview
[2] Building and Launching a CAA V5 Use Case
[3] Browsing a Product Structure

[Top]


History
Version: 1 [Mar 2000] Document created

[Top]


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