How to use Assembly Tree

Table of Contents

• Generalities
• Component Types
  • Catalog component
  • Prototype component
  • Instance component
  • Virtual component
• Using attributes across the Assembly Tree
• Accessing Graphical information

Generalities

After enabling readers you want to use, then starting the Dtk_API, you must call the Dtk_API::OpenDocument() method to get a Dtk_MainDoc.
It contains a root Dtk_Component representing the assembly tree.
This step is allowing typically to get all information to build a BOM.

Generally, all part-level data (geometries, PMIs...) are available at Prototype component level.

Here is a sample model and its corresponding representation in Dtk_Component :

Some components may be artificially added at an assembly level, depending on CAD abilities and datakit support :

• in case of assembly-level features resulting in geometry creation
• in case of component or part substitutions

Parts within an assembly can be linked through Dtk_Constraint (contacts and positions).

Depending on the CAD format, you may retrieve additional cache data :

• thumbnail image previews : How to use Preview thumbnails
• graphical 2D/3D representations : Accessing Graphical information

Note

Dtk_API contains a file search engine to set your preferences for searching for files that are part of an assembly : How to use Search File Engine

Component Types

Each Dtk_Component has a type, a name and children.
It can also have specific attributes like color, layer, visibility and metadata, all gathered in a Dtk_Info object.
Graphical attributes might be stacked across the component tree and have inheritance rules (see Using attributes across the Assembly Tree)

There are 4 different component types :

Catalog component

A Catalog component is a top-level component that may be the entry point for :

• a collection of CAD models stored in the CAD file. In this case Dtk_MainDoc::IsMultiModel() returns DTK_TRUE
• variations of the same CAD model with different configurations (both parts and assemblies)

The default catalog entry is what is shown in the original CAD software when opening the file.
It is given by method Dtk_Component::GetDefaultChildInCatalog().

Note

The CAD file may not include any collection nor variation. In this case, there is no catalog component and the model browsing starts directly with a Prototype component.

Prototype component

A Prototype component represents a model that can have 0 or several children.
It must be referenced by an Instance component or a Catalog component (except if he is root).

From Dtk_Component you have to call Dtk_API::ReadComponent to get corresponding construction tree.
This will lead to the part-level definitions (see How to use Construction Tree).

Dtk_NodePtr RootNode;
Dtk_API *inAPI = Dtk_API::GetAPI();
 
Dtk_string ComponentName = inComponent->Name();
 
/*Get the Construction tree for this prototype */
err = inAPI->ReadComponent( inComponent, RootNode );
if (err == dtkNoError && RootNode.IsNotNULL())
{
    user_WriteNode(RootNode);
}
 
/*We close the opened Component and free his construction tree*/
err = inAPI->EndComponent(inComponent);

Instance component

An Instance component has only one child which is the Prototype component and a placement matrix.
It can be referenced itself by a Instance component.

Virtual component

A Virtual component is an auxiliary component used to possibly gather other component types, or to add extra information.
It might not actually match a component from the original CAD model.

Using attributes across the Assembly Tree

At an assembly level, some attributes can be stacked across the children tree.
In this case, a few general rules need to be observed when dealing with e.g. colors and visibilities :

Dtk_Component colors should prevail on any other defined colors
A single blue cube could be instantiated as green and red :

• Green and red colors are stored at upper level (Instance component)
• Blue is stored at child level (Prototype component) or in construction tree level (Dtk_Node).

At screen, you'll see one red cube and one green cube.

The same kind of rules apply for visibility attribute.

Accessing Graphical information

Some formats allow both graphical and semantic representation.

If you need only data for visualisation you can :

• call Dtk_API::OpenDocumentGraphic() to get a Dtk_MainDoc object then
• call Dtk_API::ReadComponentGraphic() on the Dtk_Component.

This method gives you a set of meshes for 3D files and a set of drawing for 2D files.

Note

These graphical representations might not be up-to-date, depending on what the CAD software saved to the file last time it loaded it.

Not all files contains such information so result may be empty. In this case you have to :

• call Dtk_API::ReadComponent() to get all data as semantics and browse the different node types.

Dtk_GraphicalData GraphData;
Dtk_API *inAPI = Dtk_API::GetAPI();
 
Dtk_string ComponentName = inComponent->Name();
/*Get the Image Preview for this prototype */
Dtk_Preview Preview = inComponent->GetPreview();
                                                                                                                               
/*Get the Graphical data for this prototype */
err = inAPI->ReadComponentGraphic( inObject, GraphData );
if (err == dtkNoError && GraphData.IsNotNULL())
{
            user_WriteGraphicalData(GraphData);
}                                                                                                                 
/*We close the opened Component and free his construction tree*/
err = inAPI->EndComponent(inComponent);