Mod the Machine

A Problem with Attribute Helper and a Fix

A partner notified me about a problem he had found with my Attribute Helper add-in that I wasn’t aware of. He told me that if you have the new “Interactive Tutorial” and “Attribute Helper” add-ins both loaded, then Inventor will crash when you shut it down with the dialog below.

 

As I said, I wasn’t aware of the problem but had a good idea of the cause. I wasn’t following my own advice from this post almost a year ago.  I made the changes recommended there so that my Deactivate method of the add-in went from this:

Public Sub Deactivate() Implements Inventor.ApplicationAddInServer.Deactivate
    ' Release objects.
    Marshal.FinalReleaseComObject(g_inventorApplication)
    g_inventorApplication = Nothing

    If Not m_attributeButtonDef Is Nothing Then
        Marshal.FinalReleaseComObject(m_attributeButtonDef)
    End If

    If Not m_UIEvents Is Nothing Then
        Marshal.FinalReleaseComObject(m_UIEvents)
        m_UIEvents = Nothing
    End If

    System.GC.WaitForPendingFinalizers()
    System.GC.Collect()
End Sub

To this:

Public Sub Deactivate() Implements Inventor.ApplicationAddInServer.Deactivate
    ' Release objects.
    m_attributeButtonDef = Nothing
    m_UIEvents = Nothing
End Sub

 

With that change, the crash went away. I hadn’t published a new version of the “Attribute Helper” add-in for a couple of years so I’ve made this change and created a new installer.  You can get the latest version of “Attribute Helper” here.  After installing make sure that you’re running the latest version by checking that the version is 2.6, as shown below.

And if attributes are new to you, you can learn more about what they are here.  The source code for the add-in is also available on GitHub.

-Brian

Store and restore occurrence position

If you want to store the position of a ComponentOccurrence in order to be able to restore it later on, then you could simply store the Transformation values of the occurrence. They could be saved in a separate file, in Attributes, some other place - up to you where.

This VBA sample will store the values in an AttributeSet:

Sub StorePosition()
  Const kAttSetName = "Adam.OccurrencePosition"
  Const kCellNamePrefix = "cell"
  
  Dim asm As AssemblyDocument
  Set asm = ThisApplication.ActiveDocument
  
  Dim occ As ComponentOccurrence
  Set occ = asm.SelectSet(1)
  
  Dim cells() As Double
  Call occ.Transformation.GetMatrixData(cells)
  
  Dim attValues(15) As Variant
  Dim attNames(15) As String
  Dim attTypes(15) As ValueTypeEnum
  
  Dim i As Integer
  For i = LBound(cells) To UBound(cells)
    attValues(i) = cells(i)
    attNames(i) = kCellNamePrefix + Trim(str(i))
    attTypes(i) = kDoubleType
  Next
  
  Dim attSet As AttributeSet
  If occ.AttributeSets.NameIsUsed(kAttSetName) Then
    Set attSet = occ.AttributeSets("Adam.OccurrencePosition")
  Else
    Set attSet = occ.AttributeSets.Add("Adam.OccurrencePosition")
  End If
  
  Dim attEnum As AttributesEnumerator
  ' If the name was not Trim()-ed this would give an error
  Set attEnum = attSet.AddAttributes(attNames, attTypes, attValues, True)
End Sub

Sub RestorePosition()
  Const kAttSetName = "Adam.OccurrencePosition"
  Const kCellNamePrefix = "cell"
  
  Dim asm As AssemblyDocument
  Set asm = ThisApplication.ActiveDocument
  
  Dim occ As ComponentOccurrence
  Set occ = asm.SelectSet(1)
  
  Dim attSet As AttributeSet
  If occ.AttributeSets.NameIsUsed(kAttSetName) Then
    Set attSet = occ.AttributeSets("Adam.OccurrencePosition")
  Else
    Call MsgBox("Position data was not stored for this occurrence!")
    Exit Sub
  End If
  
  Dim cells(15) As Double
  Dim i As Integer
  For i = 0 To 15
    Dim cellName As String
    cellName = kCellNamePrefix + Trim(str(i))
    If Not attSet.NameIsUsed(cellName) Then
      Call MsgBox("Not all position data stored for this occurrence!")
      Exit Sub
    End If

    cells(i) = attSet(cellName).value
  Next
  
  Dim mx As Matrix
  Set mx = occ.Transformation
  
  Call mx.PutMatrixData(cells)
  
  occ.Transformation = mx
End Sub

The code in action:

-Adam

Understanding Reference Keys in Inventor

Reference keys is a topic that not many people know about or understand and is an area I’ve seen people struggle with and misuse. Reference keys are not something you’ll use often in your programs but can be very handy in certain cases.

 

What is a Reference Key?
A reference key is the ID of an object within Inventor. You use the GetReferenceKey method of an object to get its ID, or “key”. You save the ID and at a later time use it to get the same object back. A reference key doesn’t have any time limits, which means you can get the reference key from an object, and the document can go through many changes and versions, and you can still use the reference key to find the same object, even though the object may have changed from when you originally got its reference key. Of course, this assumes the object still exists and hasn’t been deleted or removed through some edit operation.

Below is some sample code that gets the reference key from a selected assembly occurrence. By changing the selection filter the code below will work with any object that supports reference keys except for B-Rep objects (SurfaceBody, FaceShell, Face, Edge, Vertex, EdgeLoop, and EdgeUse) which are discussed later.

Public Sub GetRefKey()
    ' Get the active document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument

    ' Have an object selected.
    Dim selection As Object
    Set selection = ThisApplication.CommandManager.Pick( _
                                    kAssemblyOccurrenceFilter, _
                                    "Select an occurrence.")

    ' Get a reference key from the selected entity. This will
    ' fail if the selected object doesn't support reference keys.
    Dim refKey() As Byte
    Call selection.GetReferenceKey(refKey)

    ' Convert the reference key to a string to make saving it easier.
    Dim strKey As String
    strKey = doc.ReferenceKeyManager.KeyToString(refKey)

    ' Print out the reference key string.
    Debug.Print "RefKey: """ & strKey & """"
End Sub

There are a couple of interesting things to note in the above sample. First, a reference key is an array of bytes. A byte is a number between 0 and 255 so a reference key is just a list of small numbers. Second, Inventor creates the reference key and returns it but it’s up to you to save it somewhere so you can use it later. If you’ll be writing out the reference key to a file it’s easier to deal with a String instead of an array of numbers. The KeyToString method does this for you by converting the array of bytes into a String. Later, when you need to use the key, you can use the StringToKey method to convert the String back into an array of bytes.  The sample above just prints the result to the immediate window, which in my test resulted in: “AgEBAAQAAAABAAAA”.

General reference key functionality is exposed through the ReferenceKeyManager object which is obtained from a Document object. Every object that supports reference keys has the GetReferenceKey method.

Now that you have a reference key you can use it at any time, with the same document, to get back the same object. The sample below demonstrates this.

Public Sub BindRefKey()
    ' Get the active document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument
   
    ' Convert the string back into an array of bytes.
    Dim refKey() As Byte
    Call doc.ReferenceKeyManager.StringToKey("AgEBAAQAAAABAAAA", _
                                             refKey)

    ' Bind the key back to the object.
    Dim obj As Object
    Set obj = doc.ReferenceKeyManager.BindKeyToObject(refKey)
   
    ' Select the object to be able to see the found object.
    doc.SelectSet.Clear
    Call doc.SelectSet.Select(obj)
End Sub

 

Basic Reference Key Workflow 
The concept of a reference key is fairly simple. The steps are:

1. Get a reference key from an object.
2. Save the reference key.
3. Use the reference key at a later time to get back the same object.

 

Common Problems
There are a few gotchas to be aware of that I’ve seen people struggle with before.

• A reference key is only good with the same document you originally got it from.
• You should ignore the actual value of a reference key. You shouldn’t compare reference keys themselves to check if two reference keys came for the same object. It’s possible that reference keys with different values will bind back to the same object. Because of this you should always bind both reference keys back to their objects and then compare the objects to see if they’re the same.
• You must use a reference key context when working with B-Rep entities. This is discussed below. It’s not needed with other types of objects.

 

B-Rep Entities and Reference Keys
When using reference keys with B-Rep entities the concepts shown above still apply but there is some additional work that you need to do. B-Rep entities don’t have a simple internal identifier like other objects. It’s much more complicated for Inventor to be able to find a specific B-Rep entity because they can go through significant changes as modeling operations are performed. A way to visualize how Inventor can find a specific B-Rep entity is to think of the reference key as a set of instructions that identify a particular entity. For example a specific edge might be identified as the intersection of two faces and the faces might be identified by which sketch line was used to create that face as part of an extrusion. Because of the large amount of information that could be in these instructions, a reference key to a B-Rep entity can be quite large. In order to minimize the size of B-Rep reference keys and also improve performance, the idea of a reference key context was introduced. You can think of the context as a table where the instructions are saved. Several reference keys might use one or more of the same instructions.  Having this information in a table allows individual instructions to be re-used. What this means is that a B-Rep reference key isn’t the full set of instructions but is a set of references into this table. This significantly reduces the size of each reference key.

Here is the process of using reference keys for a B-Rep entity, where the new steps are in bold.

1. Create a reference key context.
2. Ask an object for its reference key and also providing the key context.
3. Continue to get reference keys from other objects, using the same key context.
4. Save the reference keys.
5. Save the key context.
6. Use the reference key and the key context at a later time to get back the same object.

The process is essentially the same as described above for non B-Rep entities except for when you ask an object for a reference key or bind back a reference key to an object you also need to provide the key context. The program below is similar to the previous sample except it works for B-Rep entities.

Public Sub GetBRepRefKey()
    ' Get the active document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument
   
    ' Have a face and edge selected.
    Dim selFace As Face
    Set selFace = ThisApplication.CommandManager.Pick( _
                                  kPartFaceFilter, "Select face.")
    Dim selEdge As Edge
    Set selEdge = ThisApplication.CommandManager.Pick( _
                                  kPartEdgeFilter, "Select edge.")

    ' Set a reference to the ReferenceKeyManager object.
    Dim refKeyMgr As ReferenceKeyManager
    Set refKeyMgr = doc.ReferenceKeyManager

    ' Create a key context.
    Dim keyContext As Long
    keyContext = refKeyMgr.CreateKeyContext
   
    ' Get reference keys from the selected entities.
    Dim faceRefKey() As Byte
    Call selFace.GetReferenceKey(faceRefKey, keyContext)
    Dim edgeRefKey() As Byte
    Call selEdge.GetReferenceKey(edgeRefKey, keyContext)

    ' Get the key context as an array of bytes and
    ' convert it to a string.
    Dim contextArray() As Byte
    Call refKeyMgr.SaveContextToArray(keyContext, contextArray)
    Dim strContext As String
    strContext = refKeyMgr.KeyToString(contextArray)
   
    ' Convert the reference keys to strings to make saving it easier.
    Dim strFaceKey As String
    strFaceKey = doc.ReferenceKeyManager.KeyToString(faceRefKey)
    Dim strEdgeKey As String
    strEdgeKey = doc.ReferenceKeyManager.KeyToString(edgeRefKey)
   
    ' Save the results to a file.
    Open "C:\Temp\RefKeys.txt" For Output As #1
    Print #1, strContext
    Print #1, strEdgeKey
    Print #1, strFaceKey
    Close #1
End Sub

 

You may have noticed in the last sample that the variable used for the key context is typed as a Long. Of course, this value isn’t the key context table but is a pointer to the context. Whenever a key context is needed you pass the pointer to the context and when you create a context, a pointer is returned for you to use. When you save the key context along with the reference keys you need to save the full table, not the pointer. The SaveContextToArray method returns an array of bytes that is the full table. This is the data that you need to save, along with any reference keys that were created. The code below binds back to the B-Rep entities.

Public Sub BindBRepRefKey()
    ' Get the active document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument
   
    ' Get a reference to the reference key manager.
    Dim refKeyMgr As ReferenceKeyManager
    Set refKeyMgr = doc.ReferenceKeyManager
   
    ' Read the reference key strings from the file.
    Dim context As String
    Dim edgeKey As String
    Dim faceKey As String
    Open "C:\Temp\RefKeys.txt" For Input As #1
    Line Input #1, context
    Line Input #1, edgeKey
    Line Input #1, faceKey
    Close #1
   
    ' Convert the string to byte arrays.
    Dim edgeRefKey() As Byte
    Dim faceRefKey() As Byte
    Dim contextArray() As Byte
    Call refKeyMgr.StringToKey(edgeKey, edgeRefKey)
    Call refKeyMgr.StringToKey(faceKey, faceRefKey)
    Call refKeyMgr.StringToKey(context, contextArray)

    ' Create the context by loading the data.
    Dim refKeyContext As Long
    refKeyContext = refKeyMgr.LoadContextFromArray(contextArray)
   
    ' Bind back the face and edge.
    Dim foundFace As Face
    Dim foundEdge As Edge
    Set foundFace = refKeyMgr.BindKeyToObject(faceRefKey, _
                                              refKeyContext)
    Set foundEdge = refKeyMgr.BindKeyToObject(edgeRefKey, _
                                              refKeyContext)
   
    ' Highlight the found entities.
    doc.SelectSet.Clear
    doc.SelectSet.Select foundFace
    doc.SelectSet.Select foundEdge
End Sub

 

Differences with B-Rep Entities when Binding Back
There’s a difference when binding back B-Rep entities from other types of entities. The BindKeyToObject method can return an ObjectCollection in the case where the original B-Rep entity has been split into two or more pieces. The picture below shows the progression of a model and the changes that can take place to a face. In the last step face 2 is split into two pieces by an extrude feature. When binding back, both faces will be returned in an ObjectCollection.

Below is some modified code from the sample above that handles this case. When multiples are returned the first one in the collection is considered the “best” match with no priority for the rest of the entities.

' Bind back the face and edge.
Dim foundFaces As Object
Dim foundEdges As Object
Set foundFaces = refKeyMgr.BindKeyToObject(faceRefKey, refKeyContext)
Set foundEdges = refKeyMgr.BindKeyToObject(edgeRefKey, refKeyContext)

' Highlight the found entities, special casing for the case where
' more than one might have been returned
doc.SelectSet.Clear
If TypeOf foundFaces Is ObjectCollection Then
    Dim obj As Object
    For Each obj In foundFaces
        doc.SelectSet.Select obj
    Next
Else
    doc.SelectSet.Select foundFaces
End If

Important Points
Here are a few points that I want to emphasize when using reference keys with B-Rep entities.

• A single context can be used, and is intended to be used, for multiple reference keys.  That’s the reason that the concept of the reference key context was created; so that multiple keys can share the same set of instructions for finding specific entities.
• A reference key context and reference keys will only work with the same document they were originally obtained from.
• Reference keys will only work with the same reference key context they were originally created with.
• When working with B-Rep entities, write code that can handle the return of either a single object or an ObjectCollection.
• The BindKeyToObject method can fail if the entity is not available.  The CanBindKeyToObject method can be used to first check to see if the key can bind back.

 

Why Use Reference Keys?
An expected question at this point might be why would anyone want to use reference keys? They’re a generic tool that can be used in many ways but here are some examples.

Support associativity in an external read-only application
This is one of the more common uses of reference keys. Applications are able to use Apprentice to read B-Rep data and display the model in their application. When the user selects geometry in their applications they’re able to get the corresponding geometry in Apprentice and get the reference key. For example, the geometry might used for a tool path or to position a load or constraint for analysis. Getting reference keys from objects does not require write access to the model. When the model is edited in Inventor they can read in the new geometry and use the reference keys to find the geometry and update their data if the geometry has changed.

Maintaining a reference over a re-compute
This is one of the more common general uses of the functionality. An example of this is if you want to write a program that finds all of the circular planar faces in a model and places a hole feature at the center of each one. The first part of your programs finds all of the circular planar faces and then it begins placing holes on each one. The problem is that any references to B-Rep entities are no longer valid after any change has been made to the model. Creating the first hole invalidated all of the references you have to the circular faces. You don’t want to do the analysis again to find circular faces because you’ve potentially added new circular faces by placing the new feature.

Reference keys can help you solve this. Instead of maintaining a reference to a Face object you can get the reference key of each circular planar face. Reference keys are still valid after a compute, so after you create the first hole you can find the next circular planar face by using the saved reference key.

Attributes
Attributes can be used in some cases to solve the same issues that reference keys do by providing a way of adding information to an object to find it later. Attributes have the advantage that they’re self-contained and you don’t have to save any information. They also have the advantage of supporting a more powerful search mechanism. They have the disadvantage that they require write access to the file and will require the document to be saved. They also have the disadvantage that they don’t return multiple objects in the case where B-Rep entities have been split.

 

What Are Transient Keys?
There’s one more thing that I want to quickly touch on, which is transient keys. Transient key functionality is only available with B-Rep entities. Each of the B-Rep entities supports the TransientKey property which returns a Long value. This is a simple identifier for that specific B-Rep entity. You can bind back to the B-Rep entity with the transient key using the BindTransientKeyToObject method on the SurfaceBody object. This is much simpler than reference keys because it’s just a single Long and you don’t need a key context. However, there’s a BIG limitation with transient keys. They’re only good as long as the model has not been modified. They’re similar to a live reference to a B-Rep entity in that it doesn’t survive through a model compute.

The purpose of transient keys is to provide the ability to match up B-Rep entities when copying bodies. For example, the AlternateBody property of the SurfaceBody returns a copy of the body it was called on. The new body may even be slightly different than the original body, (for example, some faces may have been split into two). The new body has transient keys that you can get from each B-Rep entity. You can use the BindTransientKeyToObject method to find the equivalent B-Rep entity on the original body. It’s also possible to write out a body as SAT where the transient keys are also output as attributes on the SAT data. This again allows you to match up the B-Rep entities from this output model to the original Inventor model, as long as the model has not been edited since the copy was created.

-Brian

Attribute Helper Update

Quite a few years ago I wrote a little utility that lets you create, view, and edit attributes within a document.  If you’re relatively new to the Inventor API and are wondering what attributes are, here’s a post giving a quick introduction. 

I’ve used the utility quite a bit over the years and haven’t had any problems but someone recently reported a problem they were having and I had a hard time believing that the problem could exist.  I was finally able to reproduce the problem and found out it could be a fairly common problem, it’s just that I happened to always use a certain workflow that avoided it.  That’s why it’s always good to get someone else to help test your programs.  

I’ve fixed the problem and have a new version available.  If you already have a version of “Attribute Helper” installed, you should first uninstall the version you have, which you can do using the standard Windows uninstall utility where you should see “Attribute Helper” listed as one of the installed programs, as shown below.

Once it’s uninstalled, you can install the new version of Attribute Helper.  There is some help documentation delivered with the utility with instructions on how to use it and you can quickly determine if it was installed correctly by checking to see if the Attribute Helper command is now available in the Tools panel when you have a document open.

And when you run the Attribute Helper command, you should see the dialog below with the version displayed being “2.4”, as shown below.

 

I’ve also made the source code available on GitHub

As always, please let me know if you find any problems or have suggestions for improvement.

-Brian

Attribute Helper Update

One of the most useful utilities I’ve written has been the Attribute Helper add-in which I first discussed here. I’ve updated it and fixed a few problems. The new version is now available. It’s for Inventor 2013 and later. To install it, just download the zip file, unpack it and run AttributeHelperSetup.exe which will install it on your machine.  You should now see the Attribute Helper command in the Tools tab of the ribbon as shown below.  There is some documentation delivered with the utility that describes in more detail how to use it.

If you ever want to use attributes you should install this utility because it makes working with them much easier. Download AttributeHelperSetup.zip (823.5K)

To learn more about attributes see this previous post.

Please let me know if you find any problems or have suggestions for enhancements.

-Brian

Update (August 10, 2015): This post is now out of date because a newer update is now available.  You can learn more about it and get it here.

Attribute Utility

Working with attributes can sometimes be a bit frustrating because the only access you have to attributes is through the API.  You can’t quickly create, edit, or view an attribute without writing a program to do it.  Because of this I became a bit frustrated when working on my first program that made extensive use of attributes.  For the program to function correctly the attributes it was using all had to be correct and it was difficult to debug problems to determine if the problem was my program or the attributes it was trying to access.

For my own sanity I wrote a little utility that would let me view all of the attributes in a document.  That helped a lot but I never felt it was finished because it only allowed me to view existing attributes and I still couldn’t easily create or edit an existing attribute without writing code.  As part of the series of blog posts I’ve I’m writing about attributes, I’ve completely re-written the utility so that it provides full creation, edit, and viewing of attributes.  This new version of the utility is an add-in.  To use it just download and install the add-in and look at the readme that’s installed for instructions on how to use it.  When installing you have the option of also installing the source code, if you’re interested in the internals of how it works.  It was written using the Visual Basic language in Visual Studio 2008.

Let me know if you have suggestions or find any problems.

---------------------------

Update (Aug. 10, 2015) - I've updated this utility.  The update can be found here.

Introduction to Attributes

This is the first of at least two posts on attributes.  This first one will cover the basics and subsequent postings will go into some more advanced aspects.  Most programs your write will likely only need the information covered in this post.

The attribute functionality of Inventor is something that’s only available through the API; it doesn’t have a user-interface.  The basic concept of attributes is very simple; it’s the ability to associate information with Inventor entities.  Where it get’s a little more complicated is in understanding when this functionality might apply to your programs and how you can take advantage of it.

First, let’s look at the API for attributes.  Every object that supports attributes has the AttributeSets property from which you can access the attributes associated with that particular object.  Below is the object model for attributes.
 

The “Inventor Entity” is any object that supports the AttributeSets property.  The AttributesSets object returned by this property is an object collection that lets you access all of the AttributeSet objects associated with the object, and it also lets you create new AttributeSet objects.  An AttributeSet is exactly what the name implies; a set of attributes.  They provide a way of grouping the attributes associated with an object.  Typically, each application that adds an attribute to an object will create their own attribute set so that their attributes aren’t mixed with another application’s attributes.

Creating an Attribute
An AttributeSet object is also a collection object and provides access to the Attribute objects it contains and provides the ability to create new attributes.  Below is an example VBA macro that demonstrates this by creating a new attribute set on a selected entity and then adds an attribute to that set.

Public Sub CreateAttribute()
    ' Get the active document.  It can be any type of document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument 

    ' Get the selected entity.
    Dim entity As Object
    On Error Resume Next
    Set entity = doc.SelectSet.Item(1)
    If Err Then
        MsgBox "You must select an entity."
        Exit Sub
    End If

    ' Get the AttributeSets object from the selected entity.
    Dim attribSets As AttributeSets
    Set attribSets = entity.AttributeSets
    If Err Then
        MsgBox "You must select an entity that supports attributes."
        Exit Sub
    End If
    On Error GoTo 0 

    ' Create an attribute set.
    Dim attribSet As AttributeSet
    Set attribSet = attribSets.Add("SampleSet")

    ' Create an attribute on the set.
    Dim attrib As Inventor.Attribute
    Set attrib = attribSet.Add("SampleAttribute", _
                               kStringType, "A Test")
End Sub

The first portion of the program gets the entity that is currently selected within the active document.  Notice that the variable “entity” is declared as Object, indicating that any type of object can be handled.  The error handling is used to catch the case where no entity has been selected.

The next section of the program gets the AttributeSets object from the selected entity.  Since the program allows you to select anything, the error handling is used to catch the case where the selected object doesn’t support the AttributeSets property.

Finally, we have an AttributeSets object that was obtained from the selected entity.  The next section creates an AttributeSet object using the Add method of the AttributeSets object.  It supplies the name to use for the AttributeSet.  The name must be unique with respect to the other AttributeSet objects associated with that particular AttributeSets object.  Typically you would append the set name with your company or application name to make it unique, i.e. “modmachineSampleTest”.

The final section of the program creates an attribute within the attribute set.  The creation of the attribute takes three arguments; name, type, and value.  The name must be unique with respect to the other attributes within this attribute set.  Since it’s likely you’re the only one adding attributes to your set this is easily managed by you.  Attributes can be one of four different types; Double, Integer, String, or array of Bytes.  In the example above it creates a String attribute with the value of “A Test”.

Getting an Existing Attribute From an Entity
Now that you’ve seen how to create an attribute on an entity, how do you get that attribute back at a later time?  There are two ways of accessing attributes.  The first uses the objects we’ve already looked at; AttributeSets and AttributeSet.  The sample code below illustrates getting the attribute that was just created.

Public Sub GetAttribute()
    ' Get the active document.  It can be any type of document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument

    ' Get the selected entity.
    Dim entity As Object
    On Error Resume Next
    Set entity = doc.SelectSet.Item(1)
    If Err Then
        MsgBox "You must select an entity."
        Exit Sub
    End If

    ' Get the AttributeSets object from the selected entity.
    Dim attribSets As AttributeSets
    Set attribSets = entity.AttributeSets
    If Err Then
        MsgBox "You must select an entity that supports attributes."
        Exit Sub
    End If
    On Error GoTo 0

    ' Check to see if it has the "SampleSet" attribute set.
    If attribSets.NameIsUsed("SampleSet") Then
        ' Get the attribute set.
        Dim attribSet As AttributeSet
        Set attribSet = attribSets.Item("SampleSet")

        ' Get the attribute on the set.
        Dim attrib As Inventor.Attribute
        Set attrib = attribSet.Item("SampleAttribute")
        MsgBox "Attribute " & attrib.name & " = " & attrib.Value
    Else
        MsgBox "The entity does not have the expected attribute set."
    End If
End Sub

Most of the code in the sample above is the same as the previous sample.  However, once it has the AttributeSets object from the selected entity it uses the NameIsUsed property of the AttributeSets object to see if there is an attribute set named “SampleSet”.  If there is then it gets the attribute named “SampleAttribute”.  Finally it displays the name and value of that attribute.

The approach demonstrated above illustrates how you can get an attribute from an known entity.  The problem with this approach is that in many cases you don’t have a reference to the entity the attribute is attached to.  For example, you might have attached an attribute to a face so you can use the attribute at a later time to find that face again.  Using the technique shown above you would need to iterate over every face in the model until you found the one that had the “SampleSet” attribute set.  Not a very efficient way to find the attribute.  Another approach of getting attributes is discussed below.

Getting an Existing Attribute Using the Attribute Manager
The other way to find existing attributes is to use the AttributeManager object.  This is an object you obtain using the AttributeManager property of the Document object.  The most common use of the attribute manager is to query for attributes that exist in the document.  For example, the code below will find all entities that have an attribute set called “SampleSet”.

Public Sub GetAttributeUsingManager()
    ' Get the active document.  It can be any type of document.
    Dim doc As Document
    Set doc = ThisApplication.ActiveDocument 

    ' Get the attribute manager.
    Dim attribMgr As AttributeManager
    Set attribMgr = doc.AttributeManager

    ' Find all attribute sets named "SampleSet".
    Dim foundEntities As ObjectCollection
    Set foundEntities = attribMgr.FindObjects("SampleSet")

    MsgBox "Found " & foundEntities.Count & " entities."
End Sub

You can see this is much easier, and faster, than looking through all of the entities to see if they have a particular attribute set.

There are three different Find methods to choose from and you’ll choose one over the other depending on which type of object will be the most convenient for you to use in your program.  The three find methods are FindAttributes, FindAttributeSets, and FindObjects.  All three of them take the same input arguments and do the same type of search with the only difference being what they return.  The FindAttributes method returns a list of Attribute objects as an AttributesEnumerator object.  The FindAttributeSets method returns a list of AttributeSet objects as an AttributeSetsEnumerator object.  The FindObjects returns a list of entities as an ObjectCollection object.

The three Find methods have three arguments.  The first is the name of the attribute set, the second is the name of the attribute, and the third is the value of the attribute.  You can use wild cards when searching.  For example if I had added the following attribute sets to several different entities, SampleSet1, SampleSet2, SampleSet3, and SampleSet4, the following query would find and return all four attribute sets.  Notice the asterisk wild card at the end of “SampleSet”

    ' Find all attribute sets named "SampleSet".
    Dim foundSets As AttributeSetsEnumerator 
    Set foundSets = attribMgr.FindAttributeSets("SampleSet*")

The following query will find all attribute sets named “SampleSet” that contain an attribute named “TableType”.

    ' Find all attribute sets named "SampleSet".
    Dim foundSets As AttributeSetsEnumerator 
    Set foundSets = attribMgr.FindAttributeSets("SampleSet", _

                                                "TableType")

This last one find all attribute sets that have an attribute whose value is “ACME Fastener”.

    ' Find all attribute sets named "SampleSet".
    Dim foundSets As AttributeSetsEnumerator 
    Set foundSets = attribMgr.FindAttributeSets("*", "*", _

                                                "ACME Fastener")

As discussed above, the various find methods return different types of objects.  Frequently you may have a reference to one type of object but also need the associated objects.  We’ve already seen how how you can walk down the object model from an entity to get an associated AttributeSet object and from the AttributeSet object to get the Attribute objects.  You can also walk up the object model.  If you start with an Attribute object you can use its Parent property to get the AttributeSet object it is associated with.  You can use the Parent property of the AttributeSet object to get the parent AttributeSets object.  And finally, you can use the AttributeSets object’s Parent property to get the entity the attribute set is associated with. 

Why Use Attributes?
A common question when first learning about attributes is “why/how would you use them?”.  Attributes don’t do anything by themselves but only serve as a tool to enable other things.  Because of this they are used in many different ways for many unique applications.  Here are a some examples that illustrate how attributes can be used.  They also demonstrate why you would choose one of the find methods of the AttributeManager object over another. 

Probably the most common use of attributes is for naming an entity so you can find it later.  For example, you might be automating the creation of an assembly and need to find the entities that will be used as input when creating constraints to position the parts in the assembly.  One approach is to add an attribute set to the entity so you can use one of the AttributeManager find method find it later.  In this case it’s the entity that’s of interest and the attribute is just serving as the mechanism to find the entity and using the FindObjects method makes sense because it directly returns the object so you can easily use it to create the constraint.

Another common example of the use of attributes is adding additional information to an entity that’s important for your application. For example you might write a program to create a custom table in a drawing.  In this case each row of the table represents something unique to your application is not something that Inventor is aware of.  You can use the API to create a custom table with the data you want to display but you can also add an attribute set to the custom table that contains additional information that will be useful to you to understand where the data in the table came from so you can easily update it.  In this case it’s probably the AttributeSets object that’s the most interesting since it gives you easy access to the attributes to allow you to query them to determine the table information.  Using the FindAttributeSets method makes more sense in this case.

Here’s an example where Inventor takes advantage of attributes.  I talked this in a previous post, http://modthemachine.typepad.com/my_weblog/2009/04/controlling-layers-in-your-flat-pattern-export.html.  In this example, you add attributes to the edges of a flat pattern and the translator will use the attributes to determine which layer to create the corresponding geometry on.

Another example is face colors.  You can right-click on a face in a part and select the Properties command to change the color of that face.  Internally, Inventor remembers the color you selected by adding an attribute to that face that has the name of the color.