the Document ID Notion

The main idea of the Assemblies CATIA V5 Writing is to add instances of a previously written Document.
For this, DATAKIT APIs introduce the Document ID notion.
The first thing to do is to create Document Reference (DocID) giving a file fullpath and a reference name.
It will result to a Document ID that you can use easily to add an instance into a CATProduct.

The CATProduct writing step-by-step.

First create Document IDs by catiav5w::CreateCGRDocId or catiav5w::CreateV4ModelDocId:
Dtk_string CATPartFileName = L"C:\\sample_files\\catiav5\\V5_sample.CATPart";

Dtk_transfo TransformationMatrix;

//First you have to initialize the CATIA V5 writer

catiav5w::InitWrite(L"C:\\LogFile.log", NULL);

//The ProcessPart is an user implemented function to create a part

Dtk_UUID PartUUID = ProcessPart(inOutputFile, L"essaiPart");

Dtk_Size_t PartID, V4ID, CgrID, ProdID,ProdID2, ProdID3;

//We create Document Reference to the CATPart file

catiav5w::CreatePartDocId(inOutputFile, L"PartFile", PartUUID, PartID);

//...and to a CGR file

catiav5w::CreateCGRDocId("../SampleFiles/cgr/Engine.cgr", "CGRFile", CgrID);

//...and finally to a CATIA V4 '.model' file

catiav5w::CreateV4ModelDocId("../SampleFiles/v4/EngineComponent.model", "V4File", V4ID);

These functions create Reference link to an existing file. For CATIA V4 files, you can only reference '.model' files.
At this time the CatiaV5 Writer can only reference CATPart written by the writer.
The writer can't handle external CATPart references.
So, to reference a CATPart file, you have to provide an additional parameter.
This parameter is the CATPart UUID and it is given by the catiav5w::InitPart function. So you can call the CreatePartDocId function:
Once you have created the Part DocIds, you can create CATProduct file. For this you have to create a CATProduct context with the catiav5w::InitProduct.
//we init a CATProduct context...

catiav5w::InitProduct( L"..\\SampleFiles\\dtk\\SubProduct.CATProduct", L"SubProduct");
Once the CATProduct context is created, you can easily add instances into it by the catiav5w::AddInstance function.
//...to insert a Part instance

TransformationMatrix.setOrigin( 0.0,0.0,0.0);

catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);

//...a CGR instance

TransformationMatrix.setOrigin( 0.0,500.0,0.0);

catiav5w::AddInstance(CgrID, L"CGRInstance", TransformationMatrix);

//...and a V4 instance

TransformationMatrix.setOrigin( 0.0,-500.0,0.0);

catiav5w::AddInstance(V4ID, L"V4Instance", TransformationMatrix);
Finally you have to ends the CATProduct context - to explicitely write the CATProduct file - by the catiav5w::EndProduct function. This function will give you a resulting DocID to insert the CATProduct into multi level Assemblies.
//we close the CATProduct context and retrieve the resulting DocID

catiav5w::EndProduct(ProdID2);

Referencing existing files from a CATProduct

You can reference existing or previously created files into a CATProduct for theses extensions:

File Extension	Function
.CATPart	catiav5w::CreatePartDocId (const Dtk_string &inPartFileName, const Dtk_string &inPartName, Dtk_ID &outDocId)
.CATProduct	catiav5w::CreateProductDocId
.cgr	catiav5w::CreateCGRDocId
.model - V4 file -	catiav5w::CreateV4ModelDocId

The Virtual Component writing step-by-step.

The most important to know is that a virtual component ALWAYS belongs to a CATProduct context.
So you have to cal catiav5w::InitProduct prior calling catiav5w::InitVirtualComponent.
Moreover you can add a virtual component instance only into the same product context that his creation.
So you can only call catiav5w::AddVirtualComponentInstance prior the catiav5w::EndProduct call.
This piece of code is correct:

//we init a CATProduct context...
catiav5w::InitProduct( SubProductFileName, "SubProduct");
 
//we start a virtual component prototype
catiav5w::InitVirtualComponent("VirtualSubComponent1");
TransformationMatrix.setOrigin(0,0,150);
catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);
//we end the component prototype
catiav5w::EndVirtualComponent(CompID1);
 
 
//now we had the component instance into the CATProduct
catiav5w::AddVirtualComponentInstance(CompID1, L"CompInstance", TransformationMatrix);
 
//we close the CATProduct context and retrieve the resulting DocID
catiav5w::EndProduct(ProdID2);
...

...whereas this piece of code is wrong:

...
//we init a CATProduct context...
catiav5w::InitProduct( SubProductFileName, "SubProduct");
 
//we start a virtual component prototype
catiav5w::InitVirtualComponent("VirtualSubComponent1");
TransformationMatrix.setOrigin(0,0,150);
catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);
//we end the component prototype
catiav5w::EndVirtualComponent(CompID1);
 
//we close the CATProduct context and retrieve the resulting DocID
catiav5w::EndProduct(ProdID2);
catiav5w::AddVirtualComponentInstance(CompID1, L"CompInstance", TransformationMatrix); //ERROR: Component instanciation is not it the same context as its creation... 
 
catiav5w::InitVirtualComponent("SubComponent2"); //ERROR this virtual component doesn't belong to any product 
catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);
catiav5w::EndVirtualComponent(CompID2);

Full Sample.

Dtk_UUID ProcessPart(const Dtk_string& inOutputFile, const Dtk_string& inReferenceName)
{
    //You init the Part writer 
    Dtk_UUID PartUUID = catiav5w::InitPart( inOutputFile, inReferenceName );
 
    //you create a Geometrical Set
    catiav5w::CreateNode(catiav5w::NodeTypeGeometricSet, L"MyGeometricalSet");
    //...and you insert a point
    Dtk_Entity TmpPoint = Dtk_EntityPtr::DtkDynamicCast( Dtk_Point::Create(10.,20.,30.) );
    catiav5w::WriteEntity(TmpPoint);
 
    //Finally you close the Geometrical Set...
    catiav5w::CloseCurrentNode();
 
    //...and the Part writer
    catiav5w::EndPart();
 
    //you return the Part UUID
    return PartUUID;
}
 
void ProcessAsm()
{
    Dtk_string CATPartFileName      = L"..\\SampleFiles\\dtk\\V5_sample.CATPart";
    Dtk_string CGRFileName          = L"..\\SampleFiles\\cgr\\Engine.cgr";
    Dtk_string V4ModelFileName      = L"..\\SampleFiles\\v4\\EngineComponent.model";
    Dtk_string SubProductFileName   = L"..\\SampleFiles\\dtk\\SubProduct.CATProduct";
    Dtk_string RootProductFileName  = L"..\\SampleFiles\\dtk\\RootProduct.CATProduct";
    Dtk_transfo TransformationMatrix;
 
    //First you have to initialize the CATIA V5 writer
    catiav5w::InitWrite(L"..\\SampleFiles\\dtk\\V5W_LogFile.log", NULL);
 
    //The ProcessPart is an user implemented function to create a part
    Dtk_UUID PartUUID = ProcessPart(CATPartFileName, L"testPart");
    Dtk_ID PartID, V4ID, CgrID, ProdID,ProdID2, CompID1, CompID2;
 
    //We create Doceument References to the CATPart file 
    catiav5w::CreatePartDocId(CATPartFileName, L"PartFile", PartUUID, PartID);
 
    //...and to a CGR file
    catiav5w::CreateCGRDocId( CGRFileName, "CGRFile", CgrID);
 
    //...and finally to a CATIA V4 '.model' file
    catiav5w::CreateV4ModelDocId( V4ModelFileName, "V4File", V4ID);
 
    //we init a CATProduct context...
    catiav5w::InitProduct( SubProductFileName, "SubProduct");
 
    //we start a virtual component prototype
    catiav5w::InitVirtualComponent("VirtualSubComponent1");
    TransformationMatrix.setOrigin(0,0,150);
    catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);
    //we end the component prototype
    catiav5w::EndVirtualComponent(CompID1);
 
    //we start another virtual component prototype
    catiav5w::InitVirtualComponent("VirtualComponent1");
    //we add the sub component instance...
    TransformationMatrix.setOrigin( 0.0,0.0,0.0);
    catiav5w::AddVirtualComponentInstance(CompID1, L"VirtualSubComponent1_Instance1", TransformationMatrix ); 
    //we close the component prototype
    catiav5w::EndVirtualComponent(CompID2);
 
    //we insert a Part instance...
    TransformationMatrix.setOrigin( 0.0,0.0,0.0);
    catiav5w::AddInstance(PartID, L"PartInstance", TransformationMatrix);
    //...a CGR instance
    TransformationMatrix.setOrigin( 0.0,500.0,0.0);
    catiav5w::AddInstance(CgrID, L"CGRInstance", TransformationMatrix);
    //...and a V4 instance
    TransformationMatrix.setOrigin( 0.0,-500.0,0.0);
    catiav5w::AddInstance(V4ID, L"V4Instance", TransformationMatrix);
    //...and the main component instance
    TransformationMatrix.setOrigin( 0.0,1000.0,0.0);
    catiav5w::AddVirtualComponentInstance(CompID2, L"VirtualComponent1_Instance1", TransformationMatrix);
 
    //we close the CATProduct context and retrieve the resulting DocID
    catiav5w::EndProduct(ProdID2);
 
 
    //we create another CATProduct context
    catiav5w::InitProduct( RootProductFileName, "RootProduct");
    //and we insert another time the a part instance - multinstancing management -
    TransformationMatrix.setOrigin( 0.0,0.0,50.0);
    catiav5w::AddInstance(PartID, L"PartInstance2", TransformationMatrix);
 
    //and two instances to the first CATProduct file
    TransformationMatrix.setOrigin(  1000.0,0.0,0.0);
    catiav5w::AddInstance(ProdID2, L"SubProductInstance", TransformationMatrix);
    TransformationMatrix.setOrigin( -1000.0,0.0,0.0);
    catiav5w::AddInstance(ProdID2, L"SubProductInstance", TransformationMatrix);
    //finally we close the second CATProduct...
    catiav5w::EndProduct(ProdID);
 
    //...and the Main writter
    catiav5w::EndWrite();
}

Here a snapshot of the resulting V5 Assembly (from Full Sample)

Table of Contents

the Document ID Notion

The CATProduct writing step-by-step.

Referencing existing files from a CATProduct

The Virtual Component writing step-by-step.

Full Sample.