Adding colors and names to your application. Part 1

If you have to exchange data with other applications via IGES or STEP (or perhaps other formats, if you are a commercial client of the Open CASCADE company), you might want to enrich your application with meta data in addition to geometry. We will consider names and colors which are often asked about on the Open CASCADE forum.

OCC provides a ready-to-use framework – called XDE (eXtended Data Exchange) – which is based on OCAF. XDE offers a pre-defined document sub-structure to store colors, names, layers as well as other attributes (see XDE User’s Guide for details). This is done through a set of attributes defined in the XCAFDoc package that provides API to access data.

*Basic definitions*

Let’s start with assumption that your application uses OCAF for data description. In order to make your OCAF document XDE-compliant, you need to add XCAFDoc_DocumentTool attribute to your label of choice. It will add other required attributes to the sublabels. The easiest way is to extend your application class deriving TDocStd_Application, for example as follows:

class OCC_UT_MyXDEApp : public TDocStd_Application
//singleton pattern
Standard_EXPORT static const Handle(OCC_UT_MyXDEApp)& GetApplication();

virtual void Formats (TColStd_SequenceOfExtendedString& theFormats)
{ XCAFApp_Application::GetApplication()->Formats (theFormats); }

virtual Standard_CString ResourcesName()
{ return XCAFApp_Application::GetApplication()->ResourcesName(); }

Standard_EXPORT virtual void InitDocument (const Handle(TDocStd_Document)& theDoc) const;

OCC_UT_MyXDEApp() {}



const Handle(OCC_UT_MyXDEApp)& OCC_UT_MyXDEApp::GetApplication()
static Handle(OCC_UT_MyXDEApp) anApp = new OCC_UT_MyXDEApp;
return anApp;

void OCC_UT_MyXDEApp::InitDocument (const Handle(TDocStd_Document)& theDoc) const
//create a child of the main label and put XCAFDoc_DocumentTool there (i.e.
//one level below comparing to default XDE)
TDF_Label aL = theDoc->Main().FindChild (1, Standard_True); //0:1:1
XCAFDoc_DocumentTool::Set (aL.FindChild (1, Standard_True), Standard_False); //0:1:1:1

(to be continued)


  1. Maybe you should do a NULL-check as follows... ?

    const Handle(OCC_UT_MyXDEApp)& OCC_UT_MyXDEApp::GetApplication()
    static Handle(OCC_UT_MyXDEApp) anApp;
    if( anApp.IsNull() )
    anApp = new OCC_UT_MyXDEApp;
    return anApp;

  2. Either way is fine. Compiler ensures that the static variable will be created once and only once, upon first call to GetApplication().

    Can double-check as follows:
    Handle(TDocStd_Application) anApp = OCC_UT_MyXDEApp::GetApplication(); //singleton pattern
    Handle(TDocStd_Application) anAppClone = OCC_UT_MyXDEApp::GetApplication();
    assert (anApp == anAppClone);

  3. Nice!
    I did not succeed when I tried to extract colors from a STEP file, so I am looking forward to the next entry :)

  4. I could not run the above code.
    I copied .h and .cpp version and got error in Handle declartion.
    I need help in XDE implementation.

  5. Rajendra,
    Start with Data Exchange User's Guide on XDE.
    As soon as you make yourself familiar with it the above code will be straightforward for you. For handles you will need to #include Standard_DefineHandle.hxx

  6. Thank you Roman sir.
    I was missing to include standard_DefineHandle.hxx file and been stucked on the problem like always.
    I want to implement XDE structure to own tree structure like CTreeView.
    Hope i am in right path to continue to meet targets.
    Your tutorials and guidelines are really helpful.
    thank you a lot

  7. thanks to this post i could do a converter from step to opescengraph. I would like to ask if the XCAFApp_Application can avoid to use a subclassing you presented if i need just to parse the STEP data in a "supported" way.

  8. Unless you need to provide specific storing/retrieval, you do not need to redefine any virtual methods in XCAFApp_Application and hence no need to subclass it

  9. yes as first tutorial it will be easier to understand:

    AppStd_Application anApp;
    Handle(TDocStd_Document) aDoc;
    anApp.NewDocument ("XmlXCAF", aDoc);

    sure if the use needs specific storing/retrieval you may subclass, but seems that the topic of this useful post is to provide name and colors which are standard attributes.