Mechanical Design |
3D Functional Tolerancing & Annotation |
Browsing a Toleranced ModelAccessing and reading tolerancing information |
Use Case |
AbstractThis 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. |
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]
CAATpiBrowseTolerances is a use case of the CAATPSInterfaces.edu framework that illustrates CATTPSInterfaces framework capabilities.
[Top]
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.
|
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]
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:
e:>CAATpiBrowseTolerances inputDir\CAATpiBrowseInModel1.model outputDir\CAATpiBrowseOutText1.txt |
$ CAATpiBrowseTolerances inputDir/CAATpiBrowseInModel1.model outputDir/CAATpiBrowseOutText1.txt |
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]
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]
This diagram can be used as a guide to follow the differents steps of the use case.
There are ten logical steps in CAATpiBrowseTolerances:
We will now comment each of these sections by looking at the code.
[Top]
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]
// 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]
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]
// 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]
// 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]
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]
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]
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]
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]
The use case finishes by freeing memory (release interface pointers) and closing the output stream, the document and the session [3].
[Top]
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]
[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.