Discussion on Client Graphics

My colleague Xiaodong Liang created a technical paper focusing on client graphics. I thought it would be interesting to present this material. Here is the first installment.

Client Graphics – Introduction

Client graphics provide the ability to draw custom graphics in the Inventor® modeling window. Some common uses of client graphics are to represent custom objects and to create interactive previews during commands, displaying the results of various analyses and for creating custom manipulators within the command. An example is a milling application in CAM, where the toolpath is shown using client graphics. Another example is to show the results of a finite element analysis.

The Inventor API allows you to create these graphics (referred to as Client Graphics) using primitives (points, lines, triangles, text, etc). Client Graphics allow the developer to provide visual cues. Inventor uses this feature itself in many scenarios, for instance, when the user creates an extrusion, a preview of the extruded part is displayed. While defining the extrude feature, a visual cue indicates how the final result will display.  A developer can provide similar visual cues within their own application.

API Object Model:

Types of Client Graphics:

Regular Client Graphics
This type of client graphics is associated with a document. They are transient unless associated with a client feature. One document/sheet/drawing view can have more than one client graphics object associated with it. Each client graphics object can have many graphics nodes. Each node can contain any number and any type of graphic primitives.

Interaction Client Graphics
This type of client graphics is available when using Interaction Events. It is always transient. The InteractionEvents object can have any number of nodes and graphics primitives, like Regular Client Graphics.

Graphics Data:

In Inventor, most client graphics are defined using two different types of objects; graphics data, and graphic primitives. The graphics data defines the low-level information that can be used to define primitives.  By separating the data from the primitives, the data can be re-used by multiple primitives.

Data Objects
For Point, Line, LineStrip, Triangle, TriangleStrip, and TriangleFans, the data object provides the list of coordinates that your graphics will be based upon, and other necessary data sets such as the color and normals.

Definitions

Coordinate Sets: The coordinates used to specify the vertices for the graphic sets.
Color Sets: A set of colors used by a graphic set. It overrides any other color information assigned to the set. Colors in the color set can be bound to the entire graphic set, each individual primitive in the set (e.g. each triangle in a triangle strip), or each vertex in the set (i.e. interpolated color).
Normal Sets: Contains a set of normal vectors to define how the lighting is calculated for the triangles.
Index Sets: Each graphics primitive can access this set to more efficiently use an associated coordinate or color set.

Subsidiary Objects

TransientGeometry: The TransientGeoemtry object is a utility object you use to create various points, curves, surfaces, and mathematical objects like vectors, and matrices. In association with client graphics, the ability to create different types of curves is useful because you can use these as input to define Curve graphics.
TransientBrep: The TransientBRep object is used to create transient surface and solid models. These can be used to create Surface graphics

General Procedure
Creation of Client Graphics follows the general procedure:
1. Get the GraphicsDataSetsCollection object from the Document
2. Add GraphicsDataSets object and create graphics data
(for Curve or Surface, create graphics data by TransientGeometry and Transient)
3. Get the ClientGraphicsCollection from the graphics owner: 
         Component in part/assembly 
         View/Sheet in drawing
         InteractionEvents for Interaction Client Graphics
         ClientFeatureDefintion for Client Feature
4.    Add a ClientGraphics object to ClientGraphicsCollection
5.    Add as many GraphicsNodes as you need
6.    Add GraphicsPrimitive objects to the node(s)
7.    Assign graphics data to the primitives
8.    Update the view(s)

VB.NET Example:
This example will create a simple client graphic using LineGraphics. See the comments in the code for more details: 

Imports Inventor
 
Public Class Form1
 
    Dim m_inventorApp As Inventor.Application _
                                      = Nothing
 
    Private Sub Button1_Click(ByVal sender As  _
                                System.Object, _
                  ByVal e As System.EventArgs) _
                        Handles Button1.Click
 
        ' Get an active instance of Inventor
        Try
            m_inventorApp = System.Runtime. _
                   InteropServices.Marshal. _
       GetActiveObject("Inventor.Application")
 
        Catch 'Inventor not started
            System.Windows.Forms.MessageBox. _
             Show("Start an Inventor session")
            Exit Sub
        End Try
 
        'Call the Sub
        DrawLineGraphics()
    End Sub
 
    'Draw LineGraphics (two points)
    Public Sub DrawLineGraphics()
        If m_inventorApp.Documents.Count _
                                  < 1 Then
            System.Windows.Forms.MessageBox. _
         Show("Make Assembly or Part current")
            Exit Sub
        End If
 
        Dim oDoc As Document
        oDoc = m_inventorApp.ActiveDocument
 
        If oDoc.DocumentType = DocumentTypeEnum _
                        .kPartDocumentObject Or _
                            oDoc.DocumentType = _
    DocumentTypeEnum.kAssemblyDocumentObject Then
            Try
 
                'Get GraphicsDataSetsCollection
                ' object from the Document. 
                'Add a GraphicsDataSets object
                Dim oDataSets As GraphicsDataSets
 
                oDataSets = oDoc. _
         GraphicsDataSetsCollection.Add("TestCG")
 
                Dim oCompDef As ComponentDefinition
                oCompDef = oDoc.ComponentDefinition
 
                'Get the ClientGraphicsCollection 
                'from the graphics owner. 
                'Add a ClientGraphics
                Dim oClientGraphics As ClientGraphics
                oClientGraphics = oCompDef. _
               ClientGraphicsCollection.Add("TestCG")
 
                Dim coordSet As GraphicsCoordinateSet
                coordSet = oDataSets. _
                               CreateCoordinateSet(1)
 
                'Create graphics data.  
                'In this case, prepare two points 
                'for line graphics
                Dim oPointCoords(5) As Double
                oPointCoords(0) = 0 _
              : oPointCoords(1) = 0 _
              : oPointCoords(2) = 0   'point 1
                oPointCoords(3) = 1 _
              : oPointCoords(4) = 0 _
              : oPointCoords(5) = 0   'point 2
 
                Call coordSet.PutCoordinates _
                                      (oPointCoords)
 
                'Add GraphicsNodes
                Dim oGraphicsNode As GraphicsNode
                oGraphicsNode = oClientGraphics. _
                                         AddNode(1)
 
                'Add GraphicsPrimitive to node
                Dim oGraphic As LineGraphics
                oGraphic = oGraphicsNode. _
                                   AddLineGraphics
 
                'Assign graphics data 
                'to the primitives
                oGraphic.CoordinateSet = coordSet
 
                'update the view
                m_inventorApp.ActiveView.Update()
 
            Catch ex As Exception
                System.Windows.Forms. _
                   MessageBox.Show(ex.ToString())
                System.Windows.Forms. _
 MessageBox.Show("Prob creating Client Graphics")
            End Try
 
        Else
            System.Windows.Forms. _
   MessageBox.Show("Make Assembly or Part Active")
        End If
    End Sub
End Class