InterOp:Connect SDK/Translating External Data

From DocR23

InterOp provides functionality to add new Representations for translating entities that are not supported by InterOp default set of Representations. In this section you will learn how to enhance InterOp with entities that are not supported by InterOp regular Representations - that is, BRep, Visualization, Mesh, Manufacturing, and Assembly. In this sample example we will translate textual information that is attached to a vertex from a source User Document into a target ACIS Document. To do this, you need to create:

• A custom Representation named "External" that will define how we translate textual entities
• A User Exporter implementing the "External" representation
• An ACIS Importer implementing the "External" representation.

Contents 1 Creating an External Representation 1.1 External Exporter 1.2 Deriving from SPAXExportRepresentation 1.2.1 Implementing GetType 1.2.2 Defining the Representation Protocol 1.3 External Importer 1.4 Deriving from SPAXImportRepresentation 1.4.1 Implementing GetType 1.4.2 Implementing DeclareLinks 2 Creating an External User Exporter 2.1 External User Exporter Class and Library 2.2 Exporting Custom Entities with SPAXIdentifier 3 Creating an External ACIS Importer 3.1 External ACIS Importer Class and Library 3.2 Importing Custom Entities

Creating an External Representation

This example will introduce how to create the base External Importer and External Exporter classes that implement the External Representation.

External Exporter

The External Exporter is implemented as a SPAXExternalExporter class. This class is an abstract class that defines a set of APIs capable of exporting the new Representation in a format independent way. You need to create a sub-class of this class and provide the format specific implementation for the new Representation, similar to what was shown in the former example: Creating a User BRep Exporter. To do this, you need to create the header and source file named: SPAXExternalExporter.h and SPAXExternalExporter.cpp.

Deriving from SPAXExportRepresentation

The SPAXExternalExporter class must derive from SPAXExportRepresentation class. The following code shows the declaration of the SPAXUserExternalExporter class:

class ExportedBySPAXUserExternalExporter SPAXUserExternalExporter : public SPAXExternalExporter
{
//...
};

Implementing GetType

The Exporter must implement the GetType method and return the Representation name, which is used with the user option "Representation" to activate the returned Representation. The following code snipped shows the implementation of the GetType method:

SPAXRepType& SPAXExternalExporter::GetType() const
{
   static SPAXRepType External("External");
   return External;
}

Defining the Representation Protocol

The Exporter class must declare the abstract methods that will be used to translate external entities. In this sample example, the External representation declares 3 abstract methods that give access to:

• The Feature, the textual entity
• The geometry this feature is attached to
• The text itself.

The following code shows the definition of the three abstract methods:

virtual SPAXResult GetExternalFeature( SPAXIdentifier & oExtFeature);
/** 
* Get the linked geometry to given external feature
* @param iExtFeature
* Input external feature
* @param oLinkedGeom
* Output linked geometry to the user data
* @return 
* Success or failure through SPAXResult
*/
virtual SPAXResult GetLinkedGeometry( const SPAXIdentifier & iExtFeature, SPAXIdentifier & oLinkedGeom);
/**
* Get the user data associated with input user external feature
* @param iExtFeature
* Input external feature
* @param oUserData
* Output user data
* @return 
* Success or failure through SPAXResult
*
*/
virtual SPAXResult GetEntityPrivateData( const SPAXIdentifier & iExtFeature, char *& oUserData);

External Importer

The External Importer is implemented as a SPAXExternalImporter class. This class is the common parent class for format specific implementations of the External Importer. You need to create a sub-class to this class and provide the format specific implementation for each supported format similarly to what was shown in the former example: Creating a User BRep Importer. To do this, you need to create the header file and the source named: SPAXExternalImporter.h and SPAXExternalImporter.cpp, as provided.

Deriving from SPAXImportRepresentation

The SPAXExternalImporter class must derive from SPAXImportRepresentation class. The following code shows the declaration of the SPAXUserExternalImporter class:

class ExportedBySPAXUserExternalImporter SPAXUserExternalImporter : public SPAXExternalImporter
{
...
};

Implementing GetType

The Importer must implement the GetType method and return the Representation name, which is used with the user option "Representation" to activate the returned representation. The following code snipped shows the implementation of the GetType method:

SPAXRepType& SPAXExternalImporter::GetType() const
{
static SPAXRepType External("External");
return External;
}

Implementing DeclareLinks

In order to translate the link from the Textual entity to the Geometrical entity, the External Importer uses the InterOp Rep Linker class. The Rep Linker class relies on the information provided in the DeclareLinks method to determine the entities for which link data has to be stored.

Hence, you need to implement the DeclareLinks method. This method may be implemented in a format independent way by using the SPAXExternalExporter abstract class. The following code shows the implementation for the DeclareLinks method:

/**
* Declares the links that needs to be resolved by the representation linker.
* Those are the relations from entities managed by this representation to
* entities that are managed outside of this representation.
* The default implementation takes no action and returns SPAX_S_OK.
* @param ipExporter the export representation that is to be imported
* @param ipLinker the linker to which the links are to be declared
*/
 
SPAXResult SPAXExternalImporter::DeclareLinks(SPAXExportRepresentation* ipExporter, SPAXRepLinker* ipRepLinker)
{
SPAXExternalExporter * pExporter = static<SPAXExternalExporter*>(ipExporter);
 
// Get the user external feature
SPAXIdentifier feature;
pExporter->GetExternalFeature( feature);
...
// Declare the entities for which representation linking is needed
SPAXIdentifier linkedGeom;
pExporter->GetLinkedGeometry( feature, linkedGeom);
SPAXIdentifiers links;
links.add( linkedGeom);
SPAXRepLink link(feature, links);
ipRepLinker->DeclareLink(link);
 
return SPAX_S_OK;
}

Creating an External User Exporter

In this section you will learn how to create an External Exporter for the User format that will work with the SPAXUserDocument class created in the "Creating a User Document" example. The source code for this example is in the SPAXUserExternal directory.

External User Exporter Class and Library

You can create the User External Exporter class and library as shown in the example Creating a User BRep Exporter. The only difference is that the BRep representation is replaced by the External.representation. Hence, the External representation type name must be used instead of the BRep representation type name. And the External Representation abstract methods from the SPAXExternalExporter class must be implemented instead of the ones from SPAXBRepExporter class.

Following the InterOp naming conventions, you need to create a SPAXUserExternalExporter class in a SPAUserExternalExporter library (SPAUserExternalExporter.dll with Windows NT_DLL architecture).

Exporting Custom Entities with SPAXIdentifier

The entities translated by InterOp are provided by an Exporter as Identifier objects to the querying Importer. The Identifier abstraction enables the InterOp components such as the Rep Linker to manipulate the exchanged entity independent of the format and representation. Each Identifier contains the information such as the object it refers to in the source document, type information, and Representation exporting it. The Identifier object is implemented by the SPAXIdentifier class. SPAXUserExternalExporter implements the GetExternalFeature abstract method declared by SPAXExternalExporter by returning a SPAXIdentifier object. The following code shows the implementation of GetExternalFeature:

/**
* Returns user external feature
* as user external feature for demonstration purpose
* @param oExtFeature
* Returned user external feature data
* Here we have assumed some text is linked with a vertex in a cylinder 
* @return argument
* Success or failure through SPAXResult
*/
SPAXResult SPAXUserExternalExporter::GetExternalFeature( SPAXIdentifier & oExtFeature)
{
oExtFeature = SPAXIdentifier( _userExternalFeature, "UserExternalFeature", this, "SPAXUserExternalFeature");
return SPAX_S_OK;
}

Refer to the reference documentation for more details about SPAXIdentifier.

Creating an External ACIS Importer

In this section you will learn how to create an External Importer for the ACIS format that will interface with Spatial InterOp ACIS Document. The source code for this example is in the SPAXAcisExternal directory.

External ACIS Importer Class and Library

You can create the ACIS External Exporter class and library as shown by the example "Creating a User BRep Exporter". The only difference will be that the BRep representation is replaced by the External Representation.

Hence, the "External" representation type name must be used instead of the BRep representation type name.

Following the InterOp naming convention, you need to create a SPAXAcisExternalImporter class in a SPAXAcisExternalImporter library (SPAUserExternalImporter.dll with Windows NT_DLL architecture).

Importing Custom Entities

The SPAXAcisExternalImporter class provides the implementation for the DoImport method. This method queries the Exporter passed as an argument for entities to be translated and creates the corresponding entities (ACIS ENTITY objects) in the target ACIS model. For this sample example, textual data will be obtained from the Exporter and will be translated as an attribute on the ACIS ENTITY which corresponds in the target model to the geometry that the textual data points to in the source model. The following code shows the implementation for the DoImport method:

/**
* Import the exporting representation.
* @param ipExportRepresentation the representation to import.
* @param iOptions the translation options.
*/
SPAXResult SPAXAcisExternalImporter::DoImport(SPAXExportRepresentation* ipExportRepresentation)
{
SPAXResult res=SPAX_E_FAIL;
 
API_BEGIN
 
//...
// This is the place where user external data is populated in ACIS.
// In this case the user external data is some text.
// We are attaching the text to the ACIS VERTEX as ATTRIB_GEN_STRING attribute
SPAXExternalExporter * pExporter=static_cast<SPAXExternalExporter*>(ipExportRepresentation);
... 
SPAXRepLinker * pRepLinker = NULL;
SPAXDocument* pDocument = GetDocument();
//...
res = pDocument->GetRepLinker( pRepLinker);
 
SPAXIdentifier feature;
pExporter->GetExternalFeature( feature);
//...
SPAXIdentifier linkedGeom;
res = pExporter->GetLinkedGeometry( feature, linkedGeom);
//...
SPAXIdentifiers dstTplgy;
//...
res = pRepLinker->GetEntitiesCreatedFrom( linkedGeom, dstTplgy);
int nDstTopols = dstTplgy.size();
for( int i = 0; i < nDstTopols; i++)
{
SPAXIdentifier topol = dstTplgy i;
ENTITY *pEnt = statc_cast<ENTITY *>(topol._entity);
// Attaching user private data as attribute for demonstration purpose
// Name of the attribute is USER_PRIVATE_DATA
char * userPrivData = new char 80;
res = pExporter->GetEntityPrivateData( feature, userPrivData);
new ATTRIB_GEN_STRING( pEnt, "USER_PRIVATE_DATA", userPrivData, SplitCopy);
//...
}
 
API_END
 
return res;
}