Data Model

Introduction

HOOPS Publish enables the creation of interactive documents featuring distinct data and view layers.

For example, data can be stored within a data table, which can later be bound to widgets such as a scroll table or a list box.

Moreover, the relationship between distinct data tables can define dynamic behavior within a PDF, updating the content displayed in a widget whenever a specific event (such as a mouse-click selection) occurs elsewhere in the document.

The subsequent sections provide a more detailed explanation of how this functionality operates.

Creating a Data Table

A Data Table is a tabular data structure that stores an array of pointers to strings of type A3DUTF8Char.

struct {
    A3DInt32      uNbRow;
    A3DInt32      uNbCol;
    A3DUTF8Char** m_ppcTexts;
} A3DPDFDataTableData;

It can be utilized to store content intended for display in various field or high-level widget types, such as text fields, list boxes, buttons, scroll tables, and more.

To display the following items in a list box, define a table with five rows:

../../_images/defining_data_table.png

The content displayed in a particular widget can change depending on the selection made in another widget. In this example, the information shown in the “Required Parts” list box is updated based on the item selected in the “Procedure Steps” list box.

../../_images/table_relationships.png

In this case, Table 2 is used to define all the content that could potentially be displayed in the “Required Parts” list box.

Setting a Relationship Between Tables

In the previous example, clicking on an item in the “Procedure Steps” widget dynamically populates the data in the “Required Parts” list box.

To define this, a relationship table must be established:

struct {
    A3DPDFDataTableData* pTable1;
    A3DPDFDataTableData* pTable2;
    A3DInt32             m_iSizeMap;
    A3DPDFMapIndexData*  m_pMapIndexes;
} A3DPDFDataRelationshipData;

This table will establish a relationship (a data mapping) between Table 1 and Table 2, specifying what content from Table 2 will be displayed whenever an item in Table 1 is selected:

../../_images/table_relationships_b.png

Binding a Data Table

Once the data tables have been created, they need to be bound to widgets that are used to display their content. This is achieved using the BindToTable functionality, which can be applied to:

  • TextField

  • ScrollTable

  • ListBox

  • DropDownList

  • ViewCarousel

  • DataFilter

  • 3DNodeScene

  • 3DViewList

Binding columns

The columns of the widgets need to be associated with columns of the bound data table. This association is accomplished by providing a map of columns in the binding function call. Specific columns can be designated in a data table to associate actions with the selection of a row. These columns are not displayed in the widget. These action columns must be bound to the widgets using the A3DPDFWidgetBindColumnsActions() function.

Defining a Widget Behavior on Interaction

Finally, a behavior type must be defined to describe how widgets will be updated when an item is selected in another source widget.

In the following example, the data in the Required Parts listbox will be updated after a Procedure Step is selected.

Isolated

Highlighted

isolated

highlighted

Three types of behavior can be defined: Isolate, Highlight and Selected.

Setting the behavior is done by calling A3DPDFWidgetSetTargetBehaviour(). See the function description for more information. The following example chooses the “isolate” behavior:

A3DPDFWidgetSetTargetBehaviour(pListBox_ProcedureStep, pListBox_Requiredpart, kA3DPDFDataIsolate);

Setting up Highlight Properties

On PDF files generated with the datamodel API, customers can configure properties for highlighting behavior within 3D scenes. With this, customers need to write some JavaScript at the document level (typically on the UI widgets on a page) to set the highlight properties.

Getting HighlightManager Object

To set the highlight mode on a 3D annotation customers must first select this annotation in the document. Then the HighlightManager object of the annotation is required to set properties. JavaScript functions are provided by HOOPS Publish to do that:

getHighlightManagerFor3DAnnotWithId(3dannotuniqueid)

This full JavaScript line of code can be get with the HOOPS Publish function A3DPDF3DAnnotGetJavascriptHighlightManagerName().

Note that an alternative version of the function is provided to specify the 3D annotation with the page index and the index of annotation into this page.

getHighlightManagerFor3DAnnot(pageIndex, annotIndex)  // to specify the page index and 3D annot index on the page

Setting Properties to HighlightManager Object

Following properties are supported by using set methods on HighlightManager object:

  • setHighlightColor(r,g,b): Highlight color in Red/Green/Blue component, each channel in [0.0;1.0] space. Default is red.

  • setLevelOpacity(dLevelOpacity): Percentage of opacity applied in transparency mode, in [0.0;1.0] (defaults to 0.2).

  • setIsBlinking(bIsBlinking): When true the highlighted nodes are blinking.

  • setBlinkNumber(iBlinkNumber): Number of times the nodes are blinking (default: 3).

  • setBlinkPeriod(iBlinkPeriod): Duration of blink in ms (default: 300) .

  • setHighlightMode(eHighlightMode): Set highlight modes with following values:

    • _TS3D_HIGHLIGHTED_MESHES_MODE.ISOLATED_NOTCOLORED_OPACIFIED: the highlighted nodes are isolated, not colored, and opacified.

    • _TS3D_HIGHLIGHTED_MESHES_MODE.ISOLATED_COLORED_TRANSPARENT: the highlighted nodes are isolated, colored, and set transparent.

    • _TS3D_HIGHLIGHTED_MESHES_MODE.COLORED_OPACIFIED_OTHERSOPACIFIED: the highlighted nodes are colored and opacified, other nodes in the scene are opacified

    • _TS3D_HIGHLIGHTED_MESHES_MODE.COLORED_OPACIFIED_OTHERSTRANSPARENTS: the highlighted nodes are colored and opacified, other nodes in the scene are set transparent

    • _TS3D_HIGHLIGHTED_MESHES_MODE.COLORED_TRANSPARENT_OTHERSTRANSPARENTS: the highlighted nodes are colored and set transparent, other nodes in the scene are set transparent

    Note that some of these modes are meaningful only when the highlighted entities are faces.

  • setEnableAutoFit(bEnableAutoFit): When true, automatically fits the scene to the highlighted nodes.

An example of usage of this code is implemented in the DemoDataModel sample

Miscellaneous

For a working example of how interaction between 3D annotations and the documents can be set up, please see the DemoDataModel sample (only available for HOOPS Publish Advanced customers).