HOOPS Exchange Documentation

< Home

< Reference Manual

< File Formats

PROGRAMMING GUIDE

Contents

1.0 Introduction

2.0 Getting started

3.0 Product occurrence

4.0 Reading geometry

5.0 Entity attributes

6.0 Views and PMI

7.0 Advanced functions

6.0 Managing views and PMI

In HOOPS Exchange, markup refers to PMI and all the supporting infrastructure related to displaying it with the model. HOOPS Exchange groups this data into the markup module. Most markup is represented as tessellation, although text can be represented as either tessellation or semantic data.

A model containing PMI

Despite being an important part of the PRC standard, markup is not represented by an entity type. Instead, one of three annotation entities are used. Annotation entities are represented by A3DMkpAnnotationEntity structures, and the structure can be one of three types:

Annotation entities may be present on product occurrences or part definitions.

Parsing annotation entities

Each type of annotation entity should be parsed in a slightly different manner in order to extract all information contained within. The following examples demonstrate how to do this. First, you'll want to get the annotation type:

A3DMkpAnnotationEntity* ae = // get annotation entity
A3DEEntityType entityType;
A3DEntityGetType(ae, &entityType);

Next, test the type. If it is an annotation set, this means the entity contains other annotations. Your parsing function should process each one. Here are a few examples of parsing annotation entities based on their types. Annotation sets are quite simple:

if (entityType == kA3DTypeMkpAnnotationSet)
{
A3DMkpAnnotationSetData annotationSet;
A3DMkpAnnotationSetGet(ae, &annotationSet);
for (int i = 0; i < annotationSet.m_uiAnnotationsSize; i++)
{
parseAnnotation(annotationSet.m_ppAnnotations[i];
}
}

If the entity is of type kA3DTypeMkpAnnotationItem, parsing is more complicated as there are possible subtypes. There will also be a markup node hanging off the annotation item in the field m_pMarkup.

else if (entityType == kA3DTypeMkpAnnotationItem)
{
// get the markup node
A3DMkpMarkup* markupNode = aid.m_pMarkup;
// at this point, you can call A3DEntityGetType to test the markup node type
A3DEEntityType markupNodeType;
A3DEntityGetType(markupNode, &markupNodeType);

If markupNodeType comes back as the general type A3DMkpMarkup, then the node contains only tessellation. If it comes back as one of the more specific classes, such as A3DMarkupText or A3DMarkupDimension, then you have tessellation plus semantic data.

NOTE: Tessellation is always available, so you are guaranteed to at least get a A3DMkpMarkup structure. For an illustration of the related type hierarchy, see the diagram in the detailed description of this page.

Since tessellation is always available, you can start by getting it before anything else.

A3DMkpMarkupData markupNodeData;
A3DMkpMarkupGet(markupNode, &markupNodeData);
// since tessellation is always available, you can get it from the markupNodeData
A3DTessMarkupData tessMarkupData;
A3DTessMarkupGet(markupNodeData.m_pTessellation, &tessMarkupData);

In the preceding code snippet, the A3DMkpMarkupData object may also contain definitions for leader lines and linked items. A3DMkpLeader has a tessellation field (which may be NULL), plus an array of linked items. A linked item represents a link between a markup object and an entity such as a solid, a topological entity, a construction entity, a coordinate system, or even another markup.

For example, if you have a dimension line which indicates the distance between two planes, the dimension is a markup object. It will have two A3DMiscMarkupLinkedItem references, and each reference will define a link to a plane.

The next step is to decide how you will parse the markup node. This depends on its entity type. Each markup type is quite different and warrants its own parsing method.

// get entity type
A3DEntityGetType(markupNode, &entityType);
switch (entityType)
{
// the markup is of a general type - only tessellation
// we have a text markup - tessellation plus semantic data
// a dimension markup - tessellation plus semantic data
// test for other types
}
}

Show and delete behaviors

In A3DMiscMarkupLinkedItem, note the boolean fields such as m_bMarkupDeleteControl and m_bLeaderShowControl, which enable you to control what happens when a referenced entity is deleted, hidden, or shown. For example, if the m_bMarkupDeleteControl flag is enabled, then the markup will be deleted when the entity is deleted. Similarly, if the m_bLeaderShowControl is enabled, then the markup is shown when the associated entity is shown.

6.1 Markup views

PMI items are often organized under PMI views. A PMI view includes a camera and defines a particular model state - often including visibility for particular parts, certain PMI items, highlighted parts, or even has some parts arranged in an exploded view. The purpose of this type of view is to arrange the model to convey a certain idea. The HOOPS Exchange type for a PMI view is A3DMkpViewData. This object can be part of a product occurrence or a part definition.

To get data associated with a view:

// get parent object - in this case we'll use a product occurrence
CHECK_RET(A3DAsmProductOccurrenceGet(productOccurrence, &pod));
// there may be multiple views - check each one
for (unsigned int j = 0; j < pod.m_uiViewsSize; j++)
{
// get view data object
A3DMkpViewGet(pod.m_ppViews[j], &mvd);
// get view name
A3DRootBaseData rbdView;
A3DRootBaseGet(pod.m_ppViews[j], &rbdView);
rbdView.m_pcName; // field has the view name as a string
// get camera
A3DGraphSceneDisplayParametersData* displayParameters = mvd.m_psSceneDisplayParameters;
A3DGraphCamera camera = displayParameters.m_pCamera; // field has the camera
// get display filters to show or hide your geometry
}

PMI is often arranged on a single plane. The view object defines this plane in the A3DMkpMarkupViewData::m_pPlane field.

For more information on using filters, see this link.