Understanding what Autodesk® Inventor® Apprentice Can Do for You

15 Pages·2011·0.93 MB·English

by  Patricia Lundberg

Understanding what

Autodesk® Inventor® Apprentice Can Do for You
Brian Ekins – Autodesk, Inc.

CP5605
Inventor Apprentice is a freely available programming component that can be used by a program to read
information from Inventor files. In a few cases, it is also possible to write information. A key part of
understanding how to use Apprentice is to understand what its capabilities are, both what it can and
cannot do. This class will look at the functionality of Apprentice using several sample programs to
illustrate its capabilities. This is a programming class and previous experience with the Inventor API is
beneficial.

Learning Objectives
At the end of this class, you will be able to:
 Explain how Apprentice can be applied to automate common workflows.
 Clearly describe what Apprentice is.
 Explain what Apprentice can and cannot do.
 Write a program that uses Apprentice.

About the Speaker
Brian is the designer of the Autodesk Inventor programming interface. He began working in the CAD
industry over 25 years ago in various positions, including CAD administrator, applications engineer, CAD
API designer, and consultant. Brian is the original designer of the Inventor and Solid Edge API’s.
[email protected]

Version 1
Understanding what Autodesk® Inventor® Apprentice Can Do for You
What is Apprentice?
Apprentice is based on the same set of code that Inventor is, but uses a subset of that code to
provide access to Inventor data. An analogy is to think of Inventor as a very well equipped
motor home and Apprentice as the engine. Using the motor home you can accomplish all kinds
of things, like moving from point A to point B, cooking a meal, sleeping, etc. Using only the
engine, there’s not much you can do. The engine is only useful when it’s providing power to
some type of device, like the motor home. Apprentice is very much like the engine. All by itself
it’s completely useless and only when it’s connected to something else can you make use of its
power and capabilities.

Apprentice doesn’t have any user-interface.
That’s the purpose of the vehicle. In order for
you take advantage of Apprentice you’ll need to
create the vehicle it can run within. Your vehicle
is unlikely to be as full featured as Inventor, but
is more likely to be something like that shown to
the right. However, something simple is often
the better choice, and is much easier than
designing and building a complex vehicle.
Technically, Apprentice is a COM component
that runs in-process to your program. It gives
you the ability to open, read, and do some
editing of Inventor files. Because it doesn’t have
a user-interface, uses only a portion of Inventor’s code, and is optimized to take advantage of
no user-interface, it can perform many tasks much faster than if you used the Inventor API to do
the same thing. There are also a few things that Apprentice can do that Inventor can’t.
2
Understanding what Autodesk® Inventor® Apprentice Can Do for You
How do I get Apprentice?
There are two ways to get Apprentice. First, it’s installed as part of Inventor. The second way is
to install Inventor View, which is available as a free download. You can download the Inventor
View installer from www.autodesk.com/inventorview. Most of the download size of Inventor
View is Apprentice. Inventor View is a relatively small application that uses Apprentice.
What Functionality does Apprentice Support?
Apprentice provides access to Inventor files by supporting a subset of the Inventor API. The
picture below gives a good idea of the how much of the Inventor API that Apprentice supports.
The objects you see highlighted are those that are accessible through Apprentice. Even for
many of the objects that it does support it supports them in a limited way, (typically they are
read-only and do not support any creation or edit). For the functionality that Apprentice does
support it is likely to be much faster than Inventor, and as mentioned before, there are some
things that Apprentice can do that Inventor currently cannot.

3
Understanding what Autodesk® Inventor® Apprentice Can Do for You
At first glance it would seem that Apprentice isn’t very useful because of its limited capabilities,
but it all depends on what you’re trying to do. Here are some of the things that Apprentice does
support.
 Full support, including edit, of iProperties and is much faster than Inventor.
 Read access to assembly structure.
 Access to assembly BOM information.
 Read access to B-Rep and geometry data in parts.
 Ability to write bodies as SAT.
 Read and edit support for file references.
 Read and write access to attributes.
 Support for printing.
 Access to units of measure utilities.
 Access to sheets in drawings to support printing.
 Support for projects.
 Ability to display Inventor files in your dialogs.
 Other miscellaneous capabilities.
Here are a handful of things that you CANNOT do with Apprentice.
 Create, query, or edit features or sketches.
 Access parameters in any way.
 Create or edit an assembly.
 Create or edit a drawing.
If what you need to do only needs the small subset of capabilities that Apprentice supports then
Apprentice can be a great tool.
How do I Access Apprentice?
Accessing Apprentice is relatively
easy. First, you need to reference
the Inventor object library into your
project. This makes your project
aware of the Inventor objects. The
Inventor object library contains all of
Apprentice, plus Inventor. When
you use it with Apprentice you’ll be
using a small portion of the
functionality the library defines.
The picture to the right shows
referencing the Inventor library in
Visual Basic 2010 Express using
the Add Reference command in the
Project menu of Visual Basic.
Once you’ve added the reference
you can add code to create an instance of Apprentice. This will cause Windows to load the
Apprentice dll’s within your application’s process. As a result of loading Apprentice, you’re
returned a reference to the ApprenticeServerComponent object, which is top-level Apprentice
object, and is somewhat the equivalent to the Inventor Application object.
4
Understanding what Autodesk® Inventor® Apprentice Can Do for You
Below is some code that demonstrates this. In this example, the variable referencing
Apprentice is declared as a member of the form class so it will be accessible from anywhere
within the form and its lifetime will be the lifetime of the form. The first highlighted line is the
declaration. The second highlighted line in the Load event of the form is where Apprentice is
actually created and the reference is returned and stored in the member variable.

Public Class Form1
Private apprentice As Inventor.ApprenticeServerComponent

Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs)
apprentice = New Inventor.ApprenticeServerComponent
End Sub
End Class

Below is another example where Apprentice is defined and created within the scope of a sub, so
it’s only accessible within that sub and its lifetime is the lifetime of the sub. This works when
you only need Apprentice for a single task that is completed within the sub. In this case the
variable is declared and assigned in the same statement.

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs)
Dim apprentice As New Inventor.ApprenticeServerComponent
End Sub

There are a few things you can do directly with the ApprenticeServerComponent object, like
accessing project information, getting the Apprentice version, and some file utilities. This is
done in the same way as when using Inventor. For example, to access the project functionality
you use the DesignProjectManager property of the ApprenticeServerComponent object, which
returns a DesignProjectManager object, just the same as the DesignProjectManager property of
the Inventor Application object.
How do I Access Documents Using Apprentice?
Working with documents is quite different between Apprentice and Inventor. The first big
difference is that documents in Apprentice are represented by a different object type than in
Inventor. In Apprentice all document types are represented by the ApprenticeServerDocument
object except for drawing documents which use the ApprenticeServerDrawingDocument object.
The code below demonstrates opening a part document and assigning it a variable.

Dim doc As Inventor.ApprenticeServerDocument = apprentice.Open("C:\Temp\Part1.ipt")

You’ll notice that there isn’t a Documents collection like there is in Inventor and that the Open
method is directly on the ApprenticeServerComponent object. It’s up to you to manage any
open documents. Their lifetime is the lifetime of the variable referencing them and you can also
close them using the Close method of the ApprenticeServerDocument object.
Once you have a reference to the document it’s very similar to using Inventor for the same
tasks. In fact, a lot of Inventor code can be re-used at this point without much change. This is
because Apprentice uses the same API objects as Inventor for most of its functionality. It’s just
that some functionality on those objects may not work when used with Apprentice. For
example, from the ApprenticeServerDocumentObject you can get a ComponentDefinition
object. This is the same object that’s used in Inventor. It has an Occurrences property that
returns a ComponentOccurrences object. In Inventor you use this object to access all of the
occurrences in an assembly and use the various Add methods on the object to create new
5
Understanding what Autodesk® Inventor® Apprentice Can Do for You
occurrences. In Apprentice only the ability to query the assembly is supported so all of the Add
methods will fail.
Below is some code that will work with both Apprentice and Inventor. Given a SurfaceBody
object, it reports if a model contains any free-form surfaces and also the volume of the model.

Private Sub GetPartInfo(ByVal Body As Inventor.SurfaceBody, _
ByRef HasFreeform As Boolean, _
ByRef Volume As Double)

' Iterate over the faces looking for any B-Spline surfaces.
HasFreeform = False
For Each face As Inventor.Face In Body.Faces
' Check to see if this face is a B-Spline susrface.
If face.SurfaceType = Inventor.SurfaceTypeEnum.kBSplineSurface Then
' B-Spline was found, so set the return value and exit the loop.
HasFreeform = True
Exit For
End If
Next

' Get the volume, if the body is a solid.
If Body.IsSolid Then
Volume = Body.Volume(0.1)
Else
Volume = 0
End If
End Sub

Here’s the Apprentice code that calls the function above.

Private Sub TestGetPartInfo()
' Create an instance of Apprentice.
Dim apprentice As New Inventor.ApprenticeServerComponent

' Open a part document.
Dim doc As Inventor.ApprenticeServerDocument
doc = apprentice.Open("C:\Temp\Part1.ipt")

' Get the first body in the part.
Dim body As Inventor.SurfaceBody = doc.ComponentDefinition.SurfaceBodies.Item(1)

' Call the function to evaluate the body.
Dim hasFreeform As Boolean
Dim volume As Double
GetPartInfo(body, hasFreeform, volume)

' Report the results.
MsgBox("Body has free-form surfaces: " & hasFreeform & vbCr & _
"Volume: " & volume & " cm^3")
End Sub

6
Understanding what Autodesk® Inventor® Apprentice Can Do for You
How do I Save Documents Using Apprentice?
As mentioned earlier, working with documents in Apprentice is quite different than in Inventor.
The previous section shows how opening documents is different but saving documents is also
very different. The ApprenticeServerDocument object does not support a Save method like the
Inventor Document object does. However, it’s not especially common to save documents using
Apprentice since the edit capabilities are so limited and you only need to save a document if
you’ve made changes that you want to keep.
Another limitation in saving documents with Apprentice is that you can only save documents
that were saved in Inventor using the same version as the Apprentice version you’re working
with. The reason for this is that Apprentice is unable to migrate documents. Using Inventor you
can open any document that is the current version or older, make changes to it and save it.
When an older document is opened, Inventor migrates the data to the current version and if you
save it, it is saved as the current version. Because Apprentice is unable to migrate documents
you cannot edit and save older documents. You can determine if a document can be saved or
not by checking the NeedsMigrating property of the ApprenticeServerDocument object. If this is
True, the document is an older document and cannot be saved with Apprentice.
To save documents using Apprentice, you use the FileSaveAs object. You get the FileSaveAs
object through the FileSaveAs property of the ApprenticeServerComponent object. It’s a bit
more complicated to use than the Save or SaveCopyAs methods in Inventor, but it also
supports some additional capabilities that Inventor doesn’t. The code below demonstrates
saving a document using Apprentice.

Private Sub SaveFileSample
' Create an instance of Apprentice.
Dim apprentice As New Inventor.ApprenticeServerComponent

' Open a part document.
Dim doc As Inventor.ApprenticeServerDocument
doc = apprentice.Open("C:\Temp\Geometry.ipt")

' Do something to edit the document.

' Get the FileSaveAs object. Getting this can fail if the document
' that's open needs migrating.
Dim fileSave As Inventor.FileSaveAs = apprentice.FileSaveAs

' Add the document to the list of files (in this case, one file) to be saved.
fileSave.AddFileToSave(doc, doc.FullFileName)

' Perform the save.
fileSave.ExecuteSave()
End Sub

With the FileSaveAs object you add the documents you want to save using the AddFileToSave
method and then call the ExecuteSave, ExecuteSaveAs, or ExecuteSaveCopyAs methods to do
the actual save. When calling the AddFileToSave method there are two arguments. The first is
the reference to the document you want to save and the second is the filename. In the case
when you’re saving a file to the same name and are using the ExecuteSave method, the
specified filename has to be the same as the document being saved, or you can provide an
empty string as the filename.
7
Understanding what Autodesk® Inventor® Apprentice Can Do for You
When you use the ExecuteSave or ExecuteSaveAs methods, Apprentice creates a new
document using the specified name. When using the ExecuteSave it also updates the current
file, whereas the ExecuteSaveAs doesn’t change the current files but only creates new ones. In
both cases, files referencing the files being saved will also be updated. This is a very powerful
feature of Apprentice that’s not in Inventor and is discussed in more detail in the File References
section below.
What’s Special about Apprentice and iProperties?
The API uses for iProperties is the same API in Apprentice and Inventor. That is, the same
objects are used in both and behave in the same ways. iProperties in Apprentice is an
exception in that they’re not limited to read-only access but you can create and modify them.
The PropertySets object is accessible directly from the ApprenticeServerDocument object. Any
iProperty code that you currently have that works with Inventor will work just as well with
Apprentice.
So if everything is the same, why the topic about what’s different? There’s a property on the
PropertySets object call FlushToFile. This method only works in Apprentice and will fail if you
try to call it in Inventor. What FlushToFile does is save any iProperty changes to the document.
It only has to save the iProperty changes and not the rest of the document, so it is very fast.
After making iProperty changes you need to save the document to save the changes. It’s
possible to use the FileSaveAs object, as described above, but it will take much longer to do the
save. The example code below illustrates opening a file, editing some properties and saving
them.

Private Sub EditPropertiesSample()
' Create an instance of Apprentice.
Dim apprentice As New Inventor.ApprenticeServerComponent

' Open a part document.
Dim doc As Inventor.ApprenticeServerDocument
doc = apprentice.Open("C:\Temp\Geometry.ipt")

' Get the PropertySets object.
Dim propSets As Inventor.PropertySets = doc.PropertySets

' Get the Design Tracking property set.
Dim dtProps As Inventor.PropertySet = propSets.Item("Design Tracking Properties")

' Change the values of two properties.
dtProps.Item("Engineer").Value = "Thomas Edison"
dtProps.Item("Designer").Value = "Benjamin Franklin"

' Save the change.
propSets.FlushToFile()
End Sub

How Does Apprentice Work with File References?
File references is another area where Apprentice has capabilities that Inventor doesn’t. In fact,
Design Assistant, the primary Inventor tool for working with file references, is built on top of
Apprentice. A very common use of Apprentice that I’ve seen in the past is to create a program
that is a simplified version of Design Assistant that better meets a particular company’s needs.
8
Understanding what Autodesk® Inventor® Apprentice Can Do for You
First, here’s a quick refresher on file references. Below is a drawing of an assembly. The idw
references the assembly to get the geometry. The assembly contains two occurrences of
another assembly, so it references that other assembly and depends on it for the geometry.
The subassembly contains two occurrences, so it references the two part documents from
which it gets the geometry. The parts contain the actual geometry and do not have references
to other files. However they can have file references in the case of derived parts and references
to other types of files like Excel spreadsheets.

File References
Drawing.idw

└TopAssembly.iam
└SubAssembly.iam

├Bracket.ipt

└Block.ipt

When the top-level document (the drawing in this example) is opened, Inventor reads the list of
files that are referenced, finds, and opens them. In this example it opens TopAssembly.iam.
Inventor again reads the list of file references in the file just opened and finds and opens those
files. This continues until no more references are found.
As long as file names remain unchanged, everything works great. One common misconception
is that you need to change references when the path of a file changes. For example, if you
move a file from one directory to another. This is not true because Inventor does not use the
original full path to find the file, but relies on the current project settings. As long as the
9
Understanding what Autodesk® Inventor® Apprentice Can Do for You
directory the file was moved to is in the one of the paths defined by the project, Inventor will find
the file. You do need to edit references when file names are changed. For example, in the
assembly above if I need to rename Bracket.ipt to L-Bracket.ipt, I also need to update the
references in any files that referenced Bracket.ipt, which is Subassembly.iam in this example.
Otherwise when Subassembly.iam is opened it will still be looking for Bracket.ipt.
The CopyDesign sample finds all drawings in a specified directory, finds all of the files that are
referenced through the drawings (both directly and through the reference tree), creates a copy
of each file with a new name, and updates all of the references so they reference the new files.

Apprentice supports two ways of working with file references. The first is a direct way of
accessing the file references in a document and changing them as needed. This is useful in
cases where files have been renamed for whatever reason and you need to fix the references.
For example, if the file Bracket.ipt in the assembly above is renamed to L-Bracket.ipt, the
reference in Subassembly.iam needs to be changed to reference L-Bracket.ipt. The following
code does that.
Private Sub ChangeRefSample
' Create an instance of Apprentice.
Dim apprentice As New Inventor.ApprenticeServerComponent

' Open a document.
Dim doc As Inventor.ApprenticeServerDocument
doc = apprentice.Open("C:\Temp\Assembly.iam")

' Change the original reference of "C:\Temp\Part.ipt" to "C:\Temp\NewPart.ipt"
For Each docDesc As Inventor.DocumentDescriptor In doc.ReferencedDocumentDescriptors
If docDesc.ReferencedFileDescriptor.FullFileName = "C:\Temp\Part.ipt" Then
docDesc.ReferencedFileDescriptor.ReplaceReference("C:\Temp\NewPart.ipt")

' Since a match was found, save the change and return.
Dim fileSave As Inventor.FileSaveAs = apprentice.FileSaveAs
fileSave.AddFileToSave(doc, doc.FullFileName)
fileSave.ExecuteSave()

Return
End If
Next
End Sub
10