Catalog Modeler

Introduction

Users often need a way of storing and classifying the many objects they have at their disposal, whether they be screws, ball bearings or computer parts. These objects may number tens of thousands, each with its own specific characteristics such as shape, color, size, diameter, length, etc. To facilitate fast and easy retrieval of such objects and avoid time-wasting redesign, Version 5 offers the possibility of creating catalogs. 

A catalog is a V5 document and is in the form of a tree structure made up of: 

1. Components: it is a reference to an external entity such as feature (e.g. User Feature, Power Copy), V5 documents (e.g. Part, Product) 
2. Families (end chapters): it is a set of components  
3. Chapters: a chapter references others chapters and families. It is a way of classifying the elements it refers to
4. Keywords: a keyword describes the chapter and the family content. You can associate keywords to chapters and families and thus, perform searches by keyword value to filter their contents.

This external catalog view is internally described by three object types:

1. Keyword:  it is like a property represented by a simple type (integer, real, double) or a knowledge type ( Length, Mass, Volume, Time ...)
2. Description: it contains a reference to an object (chapter, file, description, feature) and keyword values 
3. Chapter : it contains descriptions and keywords

The "Catalog Basis" section  presents all the aspects of these objects: creation, valuation and explains the filtering mechanism. 

A way to create automatically descriptions is done through:

• The Part family mechanism. The "Part family" section describes in details this mechanism and gives you explanations about the options proposed in Tools/Options.
• The Persistent Query mechanism. 

The CAA Application Programming Interface (API) enables you to integrate you own component in a catalog document. It is the topic of the "Integrating a New Type of Component" section.

In addition to this API, you can use a Catalog Browser which enables to visualize the contents of catalogs and to instantiate components. The layout and the usage of this browser is explained in the "Catalog Browser" section.

The last section "Instantiating a Component" explains how to instantiate a catalog component outside the Catalog Browser scope.

Notice that, the Catalog document can be edited using the Catalog Editor workbench. This article makes sometimes references to this workbench. You can also you refer to the "Catalog Architecture" article [1] to have a global view and internal view of the Catalog architecture. 

[Top]

Catalog Basis

The catalog is a V5 document such as Part, Product and so on. It means that to create one, you use the ObjectModelerBase framework API. You can you refer to the "Creating a Catalog" use case [2] for an example.

This document is based on three main features: the chapter, the description and the keyword and on a main mechanism the chapter's filtering thanks the keywords and their values.

The "Browsing a Catalog" use case [3] scans a catalog contents.

Chapter

All the chapters are created thanks to the CATICatalogChapterFactory interface: 

...
 CATICatalogChapter * pICatalogChapterOnNewChapter = NULL ;

 CATUnicodeString ChapterName = "ChapterName" ;
 CATBoolean IsEndChapter = FALSE ;
 rc = pICatalogChapterFactory->CreateChapter(ChapterName,
                                                       IsEndChapter,
                                                       pICatalogChapterOnNewChapter);
...       

Where pICatalogChapterFactory is the CATICatalogChapterFactory interface pointer on the root container of the catalog document. As usual, to retrieve the root container of a document, use the CATInit interface and its GetRootContainer method.  

The CreateChapter method creates a new chapter in the root container:

The first created chapter is the root chapter. It is necessary inside the catalog and you retrieve it thanks the GetRootChapter method of the CATICatalogChapterFactory interface.

Description

The chapter contains a set of descriptions. Each description references an object which can be a chapter, a feature, a file, or a description. 

Creation

Whatever is the contents of the description, its creation is based on the same principle:

• Retrieve a CATILinkableObject interface pointer to the object to link to the description
• Create a new description on the chapter with this CATILinkableObject interface pointer 

...
pICatalogChapter->AddDescription(pICatalogDescription, pILinkableObject);
...

Where pICatalogChapter is the CATICatalogChapter interface pointer on the parent chapter, and pILinkableObject the CATILinkableObject interface pointer to the object to link.

Description referencing a chapter

When the description references chapters that make a chapters tree structure. So once a chapter is created, except of course the root chapter, use the AddDescription method to insert it in the chapter tree structure of the catalog. 

It is also possible to link a description with an external chapter. An external chapter is a chapter from an another catalog. It is recommended to insert "virtual" descriptions on a chapter through a link to an external chapter that create new descriptions in the current catalog. The update modifications are easier. A best way is to create catalogs for each specific topic, and create "super" catalogs pointing these unitary catalogs. The link between catalogs is done by creating in the "super" catalog" a description which references a chapter of the smaller catalog. 

The "Creating a Catalog" use case [2] gives an example of different kinds of chapters (family or not, external or not). 

Description referencing an object other than a chapter

If the description does not reference a chapter, the chapter which has this description is a family. There are three ways to have a such description. In the first two the descriptions are automatically created:

• Through Part Family mechanism - see the "Part Family" paragraph
• Through Persistent Query mechanism - see the "Persistent Query" paragraph
• The third case is, of course, in using the AddDescription method. Notice however that if the referenced object is a document, there is a best way (the document is not opened) to make the reference:

...
CATICatalogDescription * pICatalogDescription = NULL ;
CATUnicodeString Filename ="/../../../MyDoc.CATPart";
pICatalogChapterOnFamily->AddDescription(pICatalogDescription);
pIDescription->SetDocumentName(FileName);
...

Where Filename is the complete path of the document.

The "Creating a Catalog With Part Component" use case [4] is an example where the description is created using the API.

Retrieval the Referenced Object

In all cases, except the chapter case, the object of the description is retrieved thanks to the GetObject method of CATICatalogDescription. For a chapter, there are two ways, the first being easier:

• By using the the GetSubChapter method of the CATICatalogDescription interface.

... CATICatalogChapter * pICatalogChapterOnChildChapter = NULL ; pICatalogChapterOnChildChapter = pICatalogDescription->GetSubChapter(); ...

• By using the GetObject method of CATICatalogDescription and the GetChapter method of CATICatalogQueryResult  

The GetObject method retrieves a temporary object a QueryResult object which implements the CATICatalogQueryResult interface. Use the GetChapter method on this interface to retrieve the referenced object as follow:

... CATBaseUnknown * pReferencedObject = NULL ; pICatalogDescription->GetObject(pReferencedObject); CATICatalogQueryResult * pICatalogQueryResultOnReferencedObject = NULL HRESULT rc = pReferencedObject->QueryInterface(IID_CATICatalogQueryResult, (void**) & pICatalogQueryResultOnReferencedObject ); if ( SUCCEEDED(rc) ) { CATICatalogChapter * pICatalogChapter = NULL ; rc = pICatalogQueryResultOnReferencedObject->GetChapter(pICatalogChapter); ... } ...

Where pICatalogDescription is a CATICatalogDescription interface pointer on a description of a chapter and pICatalogChapter a pointer on its child chapter.

Preview image

On each description there is a preview image. This image is displayed in the "Preview" Tab page of the Catalog Editor [Fig.1] or in the Catalog Browser [Fig.2].

Fig.1 Preview Image in the Catalog Editor

Fig.2 Preview Image in the Catalog Browser

For each type of description there is a default image:

• Chapter



• Family



• Document

The preview image of the document

• Feature

The preview image of the feature

You can change the default image in two ways:

• By giving a CATPixelImage - the image is embedded in the catalog

... CATPixelImage Image = .... ; pICatalogDescription->SetPreview(Image ); ...

• In indicating a file name - the image is outside the catalog

... CATUnicodeString FileName ="..."; pICatalogDescription->SetPreviewName(FileName); ...

Where pICatalogDescription is a CATICatalogDescription interface pointer on a description, and FileName is the complete path of the image. If an embedded image exists, this image is not taken account.

The large image is displayed with 130x110 pixels, so if your image is smaller or larger, it is increased or decreased to this size. 

Keyword

The keywords are associated with the chapters so it is with the CATICatalogChapter interface that you can create them and set their default values. Each description of a chapter can have a own value for each keyword of the chapter. While a keyword is not valuated on a description, its value is the default value kept on the chapter. 

Creation

...
CATICatalogKeyword * pICatalogKeywordOnNewKW = NULL ;
CATUnicodeString KeywordName = "xxxx";
CATUnicodeString KeywordType ="yyy";
pICatalogChapterOnChapter->AddKeyword(KeywordName,KeywordType,pICatalogKeywordOnNewKW );
...

or

...
CATICatalogKeyword * pICatalogKeywordOnNewKW = NULL ;
CATUnicodeString KeywordName = "xxxx";
CATICkeType * pCATICkeTypeOnNewKeyword = ... ;
pICatalogChapterOnChapter->AddKeyword(KeywordName,pCATICkeTypeOnNewKeyword ,pICatalogKeywordOnNewKW );
...

Hidden Keyword

All the keywords for a chapter appear in the "Keywords" tab page in the Catalog Editor - but some can be hidden in the Catalog Browser. Those are suffixed by the star in the Catalog Editor. 

Fig.3: Hidden Keyword 

To hide a keyword:

...
pICatalogKeywordOnNewKW->SetHidden();
...

where pICatalogKeywordOnNewKW is a CATICatalogKeyword interface pointer. 

Keyword Default Value

Once the keyword is created, you can -eventually- set it a default value. 

...
CATICatalogChapter * pICatalogChapterOnChapter  = ... ;  
CATUnicodeString KeywordName=".." ;
pICatalogChapterOnChapter->SetDefaultValue(KeywordName,DefaultValue);
...

The type of the DefaultValue variable depends on the keyword type.

Keyword Value

To valuate a keyword of a description use the SetValue method as follow:

...
CATICatalogDescription * pICatalogDescriptionOnCurrentDescription  = ... ;  
CATUnicodeString KeywordName=".." ;
pICatalogDescriptionOnCurrentDescription->SetValue(KeywordName,Value);
...

The type of the Value variable depends on the keyword type. 

Specific Keyword

The "Name" keyword is a specific keyword. Its value is also the name of the description. In other words, the value returned by the GetName method of the CATICatalogDescription interface is also the value returned by the GetValue method.

In the Catalog Editor, for each chapter the "Name" keyword is created automatically but not in the CAA API case. But even the keyword doesn't exist, the GetValue method of the CATICatalogDescription interface returns the name of the description. 

Query Mechanism

As a data base, a query mechanism enables to research a specific object into a catalog. This mechanism is based on the keywords and their values. As a data base request, you build a query expression with keywords and you apply this request to a chapter. The "Using Query" use case [5] gives you a concrete example.

Query Expression

The query is an expression which has a knowledgeware syntax and the available operators are 

• +,-,*,/,(,),**,==,<>,<,>,<=,>=
• abs,sqrt,cos,sin,tan,log,min,max ...
• Search,Extract,Length,ToUpper ...
• if ... then.., and,or,...

For example: (x.DIAMETER<=4)AND(x.TYPE=="FHC")

Query Request

The chapter implements the CATICatalogQuery interface. Use the Query method to do a request as follow:

...   
CATUnicodeString Expression = "(x.SideNumber==6)";
CATICatalogQueryResult * pIQueryResult = NULL;
rc = piCatalogQueryOnChapter->Query(pIQueryResult,Expression);
...

Where piCatalogQueryOnChapter is a CATICatalogQuery interface on the chapter to filter. The arguments of this method are:

The Query method is not recursive. So if the chapter contains sub-chapters, the research stops at the first level. 

Part Family

This paragraph explains what is a Part Family. Refer you to the "Creating a Part family" use case [6] for a concrete case.

Definition

A Part family is a whole family with Part components created from a single Part which has several configurations referenced in a design table. 

Fig.4: Part Family

On this picture, notice that :

• The design table is a tabulated text file (a Excel file is not UNIX compatible),
• The design table contains the PartNumber header. It is mandatory,
• The keywords of the Part family are the headers name of the design table,
• There are as many descriptions as configuration rows in the design table,
• The values of each description's keyword are the value extracted from the design table.

It is always possible to add keywords to the family after or before having created a Part family. But if the keywords providing from the design table are automatically created and valuated, it is on your charge to valuate the added keywords. 

The PartNumber keyword value is a specific keyword. It has the same role as the "Name" keyword for an another type of chapter. It is also the name of the description.

Once the family is created, use the AddFamilyDescriptionsFromDesignTable method on the CATICatalogChapter interface.

...
pICatalogChapterOnFamily->AddFamilyDescriptionsFromDesignTable(piDesignTable);
...

where pICatalogChapterOnFamily is a CATICatalogChapter interface pointer, and piDesignTable a CATIDesignTable interface pointer. The "Creating a Catalog" use case [2] gives the code to retrieve a design table in a Part document.

Part Resolution

Each description could have a link to a Part generated from a configuration defined in the design table. It is the case when the description is "resolved". The advantage is that when a resolved Part is stored in a catalog, it can be automatically generated during the instantiation. So for the end user, there is no time-wasting for configuration computation during the instantiation.

 It means that for the previous example [Fig.4], if you instantiate:

• The Part document of the first line, you instantiate a Part with 20 mm for the First Limit length and  the diameter
• The Part document of the second line, you instantiate a Part with 30mm for the First Limit length and 10 mm for the diameter
• The Part document of the third line, you instantiate a Part with 40mm for the First Limit length and 10 mm for the diameter

Fig.5: Part Family Configurations

When a Part family is created, in the Reference tab page of the Catalog Editor, you can notice that the type of each descriptions is "Part family configuration". If you resolve a description, the type of the description becomes "Resolved part family configuration" [Fig.6].

Fig.6: Resolved Part Document

On the above picture, you notice that:

• The first description is resolved. The Part has been stored in the "C:\Documents and Settings\..." directory. This location is defined in the Catalog Editor tab page in the Tool Options Command [Fig.7]. The next paragraph "Part Instantiation" describes this tab page.
• The last two are not resolved. The Object Name field contains the path of the Part with the design table.

To resolve a description by using CAA API, use the ResolvedDocumentFromDesignTable method on a CATICatalogDescription interface pointer. 

...
pICatalogDescription->ResolvedDocumentFromDesignTable();
...

where pICatalogDescription is a CATICatalogDescription interface pointer. 

Part Instantiation

In the Tools/Options command, if you select Infrastructure and Catalog Editor, the following tab page appears:

Fig.7: Catalogs Tools/Options

This tab page defines the instantiation mode for components coming from Part family. 

The Folder editor defines the path of the resolved Part. The three others options are exclusive:

• Use the "Create new reference for each instantiation" option to create a component reference from each instantiated reference part (just like the New from... command). In other words, each component instantiation will result in the generation of a Part document saved in the folder you specified.
• The "Allow family component dynamic resolution in catalog" option lets you dynamically resolve components when instantiating them. It means that after such an instantiation, the catalog could  be modified because one of this description could now contain a link towards a resolved Part if it doesn't exist already. 
• The "Instantiate only resolved family components" option lets you instantiate only resolved and stored components. Otherwise, an error message appears to warn you that the component cannot be resolved.

Through this tab page, an administrator can impose the instantiation mode and/or set the location of the resolved Part. 

Persistent Query

A persistent query is associated with a family. It enables you to have a filtered view of an external catalog into a catalog. You can you refer  you to the "Creating Persistent Query" use case [7] for a concrete example.

You can create a sub-set of keywords on the family with the keywords defining the expression. But caution, except the Name keyword, there is no automatic valuation of the family's keyword.

Once the family is created, there are four or five steps to create a persistent query:

1. Use the AddPersistentQuery method of the CATICatalogChapter interface.

... CATUnicodeString PersistentQueryName ="" ; CATICatalogPersistentQuery * pICatalogPersistentQuery = NULL ; pICatalogChapterOnFamily->AddPersistentQuery(PersistentQueryName, pICatalogPersistentQuery); ...

where pICatalogChapterOnFamily is a CATICatalogChapter interface pointer, and pICatalogPersistentQuery a CATICatalogPersistentQuery interface pointer on the new persistent query. 

2. Associate the chapter to filter with the new persistent query

... CATICatalogChapter * piChapterToFilter =... ; pICatalogPersistentQuery->SetResolutionChapter(piChapterToFilter); ...

where piChapterToFilter is a CATICatalogChapter interface pointer on the root chapter of the catalog to filter.  

3. Associate an expression with the persistent query

... CATUnicodeString Expression = " xxx" ; pICatalogPersistentQuery->SetExpression(Expression); ...

The expression has a knowledgeware syntax. See the "Query Mechanism" paragraph.

4. Associate default values with the persistent query

This step is not mandatory. For each persistent query of a family it is possible to associate new default value for the keyword's family.

... CATUnicodeString KeywordName= "xxx" ; pICatalogPersistentQuery->SetDefaultValue(KeywordName,DefaultValue); ...

where KeywordName is a keyword of the family. 

5. Resolve the query

The resolution generates the descriptions on the family.

... int ResolveMode = 0 ; CATListValCATICatalogDescription_var * pListExternalDescription = NULL ; pICatalogPersistentQuery->ResolveQuery(ResolveMode,pListExternalDescription); ...

• The ResolveMode argument can have two values 
• 0: it is a simulation. The descriptions are not created on the family
• 1:  it is a resolution. The descriptions are created on the family
• pListExternalDescription contains the list of the simulated or resolved description. 

Integrating a New Type of Component

Natively, the catalog document integrates some components like:

• Documents
• Product
• Part (with or without design table)
• Script 
• Features
• Drafting Details
• Power Copy
• User Feature
• Manufacturing Tools
• Manufacturing Process
• Knowledge
• Fomulas, Rules, Checks
• Rule base
• Generative Knowledge Script (CATGScriptFile)

To integrate a new type of component in a catalog document, you have to implement the three following interfaces:

• CATICatalogInstantiation

  This interface contains the method  which launches an interactive command to create a new instance of the component. 

• CATICatalogSynchronize

  It is not mandatory to implement this interface. It enables you to provide information for the description which has a link to an instance of the component:

  • The display name of the description (GetAlias)
  • An embedded preview image (GetEmbeddedPreview)
  • Keyword values (GetKeywordValue)
• CATICatalogEnable (only for features)

  This interface authorizes the integration of the feature in a catalog document. This interface is without method.

The use case "Integrating a Component" details on a feature the implementation of these three interfaces.

Although the Part and the Product are documents natively integrated in a catalog document, they don't directly implement CATICatalogInstantiation.  

Catalog Browser

The Catalog Browser is an interactive command to browse catalogs and instantiate components in context. It provides:

• The same user interface for all applications 
  • Assembly
  • Part ( PartDesign, ShapeDesign...)
  • Drafting
  • Plant layout, Mold ...
• Instantiation in context with drag&drop, double click or contextual menu

The Catalog Browser is a Dialog box with the following layout:

Fig.8: Catalog Browser

The CAA API enables you to create an instance of this command and customize its layout. The "Using the Catalog Browser" use case is a demonstrator which allows you to understand interactively all the possible options. 

The Catalog Browser is created thanks to the CATICatalogBrowserFactory interface. This interface is implemented by the CATFrmEditor class (ApplicationFrame framework). 

The CATFrmEditor class is the "C" in the MVC paradigm, where M (Model) is the document and V (View) the Visualization world. To be visualized, a document must implement the CATIEditor (ObjectModelerBase framework) interface which provides a CATFrmEditor class instance.

...   
CATFrmEditor * pDocumentEditor = CATFrmEditor::GetCurrentEditor();
CATICatalogBrowserFactory * pICatalogBrowserFactory = NULL;
HRESULT rc = pDocumentEditor->QueryInterface (IID_CATICatalogBrowserFactory, 
                                              (void**) &pICatalogBrowserFactory);
...

Once you have the CATICatalogBrowserFactory interface pointer, use its single method to create a Catalog Browser instance:

...  
CATICatalogBrowser *  pICatalogBrowser = NULL ;
CATCciCatalogBrowserDisplayOptions DisplayOptions = CATCatalogDisplayCombo | 
                                                    CATCatalogDisplayWndBtnOKCancel | 
                                                    CATCatalogDisplayWithLargeIcons ;
int DragAndDropAuthorized = 1 ;
int InstantiationAuthorized =1 ;
pICatalogBrowserFactory->OpenCatalogBrowser (pICatalogBrowser, 
                                             DisplayOptions , 
                                             DragAndDropAuthorized, 
                                             InstantiationAuthorized);
...

Where

• pICatalogBrowser is the new CATICatalogBrowser interface pointer

It is an output argument. With this pointer you can change some layout options and retrieve the end user interactions: its selection, filter value, ...

• DisplayOptions, is a sum of CATCciCatalogBrowserDisplayOptions values 

It is a sum of single option to customize the layout of the dialog box. In the just above example, the value for this argument means that the Catalog browser has:

• CATCatalogDisplayWndBtnOKCancel: The Ok and Cancel buttons (and not the Close button as [Fig.8] )
• CATCatalogDisplayCombo: The  Display options combo (Large and Small icons and Details options)
• CATCatalogDisplayWithLargeIcons : At the beginning the large icons are displayed

It is recommended to always have the CATCatalogDisplayCombo value.

• DragAndDropAuthorized , authorize or not the instantiation by drag and drop
• InstantiationAuthorized, authorize or not the component's instantiation by contextual menu or  by double click on the description

Instantiating a Component

The instantiation can be done through the Catalog Browser:

• Drag and Drop 
• Double click
• Contextual menu

but you can also launch yourself an instantiation. There are two steps 

1. Retrieve the CATICatalogDescription interface pointer on the description which contains the component to instantiate. If it is a description selected by an end user through the Catalog Browser, use the method of the CATICatalogBrowser interface

... CATICatalogDescription * piCatalogDesc = NULL ; rc = _pICatalogBrowser->GetSelectedDescription (piCatalogDesc); ...

Where _pICatalogBrowser is a CATICatalogBrowser interface pointer on the opened Catalog Browser.

2. Instantiate the referenced object thanks to the RunInstantiationCmd method on the CATICatalogDescription interface pointer

... rc = piCatalogDesc->RunInstantiationCmd(_pICatalogBrowser,InstantiateMode,RepeatMode) ...

Where the arguments of this method are the following:

• pICatalogBrowser, a CATICatalogBrowser interface pointer

It is a pointer on the current Catalog Browser (can be NULL). It will possibly be used to temporaryly hide the Catalog Browser during the instantiation or to close it.

• InstantiateMode (int)

This argument is only useful for the document's instantiation into a Product. In this case there are two ways to do an instantiation, the first being recommended:

• 1: The destination Product will have a link to the reference document. 
• 0: It is a "New From" instantiation. It means that a new document is created from the reference document

The second solution is recommended.

• RepeatMode (int)

The instantiation will be done through an interactive command which can have the repeat mode. This mode means that when the command is finished, it is automatically re-launched. So this parameter is often without interest because in most cases the repeat mode is not available (and not recommended) .

To instantiate a component you must not use the RunInstantiationCmd method of the CATICatalogInstantiation interface and that for two reasons:

1. The DS components do not always implement directly the CATICatalogInstantiation interface
2. The current workbench or the current workshop can be called before.

The RunInstantiationCmd method of the CATICatalogDescription interface calls the RunInstantiationCmd  method of the CATICatalogInstantiation interface. 

Advice

• You cannot make an instantiation outside an interactive session. 
• The catalog which contains the component to instantiate must always be opened
• There is no link with the catalog after an instantiation.

[Top]

In Short

The catalog is a document which enables you to classify a lot of objects (file, feature, etc.) to retrieve them quickly. It is made up of three main features:

1. The chapter: It has several descriptions and keywords
2. The description: It contains a referenced object (file, feature, chapter, description)
3. The keyword: It is the way to classify chapters and theirs descriptions

The description's creation on a chapter can be done explicitly or automatically through the

• Part family mechanism: each description comes from a design table configuration.
• Persistent query mechanism: each description comes from a filtered catalog.

The ComponentsCatalogsInterfaces framework provides a component, the Catalog Browser, which allows you to browse a catalog and instantiate components having the same look and feel that the other DS applications.

A component instantiation can be done through the Catalog Browser but also through the CAA API. 

At last, it is possible to integrate a new type of component into the catalog's document.

[Top]

References

History

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