Mod the Machine

Working with Sketches

In this post, on our slow journey towards creating a command that creates a slot shape in a sketch, I’m going to discuss the main principles when working with sketches.

You can create a sketch in a part or assembly but I’m only going to address parts for now.  A sketch is basically a 2D coordinate system positioned in 3D space.  The API has a special type of object for this type of sketch called a PlanarSketch since it’s defining a plane in 3D space.  There is also a DrawingSketch which is slightly different since a drawing is already 2D.  Typically, sketches are created by referencing an existing planar entity, either a planar face or a work plane.  The sketch is associatively related to the entity so that if the entity moves the sketch moves with it.

When you pick a face or work plane, Inventor has some logic that it uses to determine the orientation and origin of the 2D coordinate system that’s defined during the creation of the sketch.  You typically don’t care about this orientation because the default is usually what you expect and the main thing it affects is the horizontal and vertical directions.  The origin doesn’t matter since you dimension the sketch geometry relative to other geometry in the model so the actual x-y coordinates of the sketch geometry is immaterial.  The picture below shows a selected face on a part where I want to create a sketch.

 

After creating the sketch it is possible to see and even edit the coordinate system that was defined for this sketch.  You can do this using the “Edit Coordinate System” command that’s accessed through the context menu for the sketch.  A 2D triad is displayed indicating the origin and the direction of the x and y axes.  While in this command you can edit these to reorient the sketch on the plane.

    

The yellow lines you see in the picture above are sketch lines that were automatically created by projecting the edges of the selected face onto the sketch.  This is the default behavior of Inventor but is controlled using the setting in the Application Options dialog as shown below.

 

To create a sketch using the API you need to use the collection object for sketches.  Remember from the discussion in the previous post that collection objects provide access to existing objects of a certain type and also support methods to create new objects of that type.  Below is a simplified view of the object hierarchy to get to the PlanarSketches object.  We’ve already discussed how to create a PartDocument object but most of the data that we think of as part specific data, (features, work features, parameters, imates, etc.) are part of the PartComponentDefinition object.  There is always a one-to-one relationship between a PartDocument and a PartComponentDefinition object.  Don’t get too caught up in why there is a PartComponentDefinition object but instead just remember that for part information you’ll need to take that one extra step to get the PartComponentDefinition from the PartDocument. 

Below is some code that creates a new part document and creates a new sketch on the X-Y work plane of the part. 

' Connect to a running instance of Inventor.
Dim invApp As Inventor.Application
invApp = System.Runtime.InteropServices.Marshal.GetActiveObject _
                                            ("Inventor.Application")

' Get the Documents collection.
Dim docs As Inventor.Documents docs = invApp.Documents

' Create a new part document.
Dim partDoc As Inventor.PartDocument
partDoc = docs.Add(Inventor.DocumentTypeEnum.kPartDocumentObject)

' Get the component definition.
Dim partDef As Inventor.PartComponentDefinition
partDef = partDoc.ComponentDefinition

' Get the X-Y work plane.
Dim xyPlane As Inventor.WorkPlane = partDef.WorkPlanes.Item(3)

' Create a new sketch.
Dim sketch As Inventor.PlanarSketch
sketch = partDef.Sketches.Add(xyPlane, False)

 

The code above uses the ComponentDefinition property of the PartDocument object to get the PartComponentDefinition object associated with the part.  In most cases the name of the property matches the name of the object is returns but that’s not always the case as in this example. 

Next it gets the X-Y work plane from the part.  It does this by getting the WorkPlanes collection object from the PartComponentDefinition and gets a work plane from it using the Item property.  The WorkPlanes collection object contains all of the work planes in a part and also supports several Add methods to create new work planes.  All parts will always have at least three work planes, three work axes, and one work point.  Below is a picture of the browser for a new, empty part.  You can see the base work features that exist in every part.  When accessing these through the API they are returned by the API collection objects in the same order they’re shown in the browser.  For example, getting WorkPlanes.Item(1) will return the YZ Plane.  Getting WorkAxes.item(2) will return the Y axis. and getting WorkPoints.Item(1) will always return the origin work point.  The user cannot delete or reorder these base work features so this is guaranteed to always be true.  In this case I’m getting item 3 from the WorkPlanes collection, which is the XY Plane.

The last section of code, shown below, creates a new sketch.  There are a couple of things that I want to point out here.  There are several things happening on the line where the sketch gets created.  First, the Sketches property of the PartComponentDefinition is called.  This returns a PlanarSketches object.  Next, the Add method of the PlanarSketches object is called.  This line could have been broken up into multiple lines by first getting the PlanarSketches object and then calling the Add method.  Most languages support the ability to combine these calls into a single line to allow for less code.  Just be aware that there are several calls being made on that single line, which can sometimes make problems a little more difficult to debug because if that line fails it’s difficult to know which call failed.

' Create a new sketch.
Dim sketch As Inventor.PlanarSketch
sketch = partDef.Sketches.Add(xyPlane, False)

The Add method to create a new sketch is fairly simple.  It has two arguments.  The first is the planar object you want to create the sketch on.  This can be a work plane, like in this example, or it can be a planar face.  The second argument indicates if the edges of the face should be copied into the sketch.  This is the equivalent of the “Auto Project” option discussed above.  The API ignores the application setting for the auto project and allows you to control it explicitly when you create a sketch.  This setting is only used when you’re creating a sketch on a face and is ignored when a work plane is used.  In fact the second argument is defined to be an optional argument so I could have left it out.  It defaults to False if you don’t specify it.

The work plane created is the same as if you had interactively created it in Inventor, in that the origin and orientation of the plane is automatically inferred by Inventor.  The PlanarSketches collection also supports an AddWithOrientation method that lets you specify the origin and orientation when you create it.  In practice this is rarely used.

If you run the code above it will create a new part and you’ll see a new empty sketch in the part.  Each time you run the program you get a new part with a sketch.  Not too exciting yet, but in the next post we’ll look at drawing geometry on the sketch.  Then it gets a lot more fun .

-Brian

Objects in the API

Here’s another post in the getting series where we’re looking at the creation of a new sketch command to create slot shapes.  I’ll be adding each of the posts in this series to the Getting Started Tutorial category.

This post is more discussion than coding so you will have some background to follow what’s coming next.  First, I want to go back to the previous program and look at that code in a bit more detail.  The code below is from the previous post with the error handling removed and one of the lines has been broken into two to make it easier to follow what’s happening

1.  ' Connect to a running instance of Inventor.
2.  Dim invApp As Inventor.Application
3.  invApp = System.Runtime.InteropServices.Marshal.GetActiveObject _
4.                                          ("Inventor.Application")
5.  ' Get the Documents collection.
6.  Dim docs As Inventor.Documents
7.  docs = invApp.Documents
8.
9.  ' Create a new part document.
10. Dim partDoc As Inventor.PartDocument
11. partDoc = docs.Add(Inventor.DocumentTypeEnum.kPartDocumentObject)

Line 2 declares a variable to be of type Inventor.Application.  The “Inventor” portion of the declaration is specifying the library and the “Application” portion is the name of the object.  The Inventor API is exposed as objects.  You’re already used to this concept since that’s also how Visual Basic works.  For example, when you place a button control on a form, that results in the creation of a button object that you can access in your program.  The button has properties that you can read and write to manipulate the button.  It also has methods you can call and it has events that notify you when certain things happen to the button, like when it is clicked. 

Inventor objects have the same concept but instead of representing something on a form, they represent something within Inventor.  For example, for every extrude feature in a part there is an ExtrudeFeature object that you can access and use in a program.  Inventor is a large and fairly complicated application and the API reflects that.  Inventor 2013 has 1365 objects which have a total of 20,462 properties, methods, and events.  Don’t let these big numbers discourage you though because you don’t need to understand all of it be able to use it.

These objects are accessed through something known as the object model or object hierarchy.  A useful tool in working with the API is the object model chart, which is shown below.  You can download a printable pdf version of the chart here. 

 

Below is a snapshot of the upper-left corner of the chart that includes the few objects that are used in the small program discussed here.  You can see in the chart that the top-level object is the Application object.  This object represents the Inventor application and has functionality that lets you manipulate the entire application; things like resizing the main window and accessing application options.  However, the most important thing the Application object does is support properties that return other objects.  This is how you gain access to the other objects in the hierarchy.  For example, the Application object supports the Documents property which returns the Documents object.  This is illustrated in line 7 in the code sample above and that relationship can be seen in the chart below.

 

You can also view all of the objects and their associated methods, properties, and events from within Visual Basic using the Object Browser.  To access the Object Browser in Visual Basic Express 2010, press F2. The Object Browser is shown below, with the Inventor library selected.

Below is the Object Browser with the Documents object selected in the list on the left and the Item property selected on the right.  The Object Browser provides a convenient way to see the objects and what functionality they support.  You can see in the picture below that the Item property is read-only and has a single argument called Index which is an Integer.  You can also see that it returns an Inventor.Document object. (You can ignore the _ character in front of Document.  It has something to do with how the API was implemented internally and I don’t understand it either. )

 

Tip: You can expose additional capabilities in the Visual Basic Express 2010 interface by changing your settings to “Expert Settings” in the “Tools” menu, as shown below.  After doing this the “Object Browser” command will be displayed in the “View” menu.

 

Line 6, in the sample above, declares a variable to be of type Documents.  The Documents object is a special type of object known as a collection object.  Collection objects are used extensively throughout the API and are an important concept to understand.  

Collection objects are utility objects used in the API.  They don’t represent specific objects within Inventor but instead provide access to a group of related objects and in many cases also provide the ability to create new objects.  The Documents object illustrates both of these.

The Documents object provides access to all of the documents that are currently open in Inventor.  All collection objects support the properties Count and Item.  The Count property tells you how many items are in the collection and the Item property lets you access the items within the collection.  If you add the following to the end of the previous program it will display a message box telling you how many documents are currently open.

' Display the number of documents.
MessageBox.Show("There are " & docs.Count & " documents open.") 

You use the Item property of a collection to get a specific object from the collection.  This is somewhat similar to an array but the first item has in index of 1.  Some collections will also let you specify the name of the object you want.  The code below uses both the Count and the Item properties of the Documents object to iterate over all of the open documents and display the name of each one in the output window.  (You may need to turn on the display of the output window from the menu “View –> Other Windows –> Output” or  “Ctrl + Alt + O”.)

' Iterate over the open documents
For i As Integer = 1 To docs.Count
    Debug.Print("Doc Name: " & docs.Item(i).DisplayName)
Next

If you’re iterating through a collection a more efficient technique for is to use the For Next statement.  Code using a For Each vs. the For To will typically run faster and is easier to read.  This is demonstrated below.

' Iterate over the open documents
For Each doc As Inventor.Document In docs
    Debug.Print("Doc: " & doc.DisplayName)
Next

The Item property of the Documents collection does not support indexing by name.  You can determine which Item properties do support this by looking at the description of the property in the API help.  The Documents object supports a separate property for named lookup called ItemByName where instead of providing the index number you supply the filename of the document.  If you specify an out of range number or a name that doesn’t exist the call will fail.

Adding objects to a collection is done by using the Add methods of the collection.  This was demonstrated in the original program above in line 11 where the Add method is called.  Some collections won’t have any add methods and others will have several.  The arguments to the add methods will also vary greatly depending on what is being created.  It’s takes much different information to create a new document versus creating a new extrude feature.

We’ll look at practical applications of collection objects and using them to create new objects in the upcoming posts.  In the next post I’ll talk about creating sketches.

Another useful tool to look at Inventor’s objects is VBA’s debugger.  I’ve described this in a previous post on program prototyping.

Creating and Setting up Your Project

If you’ve gone through the lessons in the book I suggested earlier, or any of the online Microsoft tutorials that are available you should be familiar with what projects are and how to create them.  I won’t go into a lot of detail but will go through the steps below.

Here are the steps to creating an exe program that will access and control Inventor using the API.

1. After running Visual Basic 2010 Express, select the “New Project…” option, which is outlined in red below.
   
    
2. In the New Project dialog select “Windows Forms Application” as the type of project and enter “DrawShape” for the project name. 
   
   
3. The project you’ve just created is a standard Windows application and doesn’t have any knowledge about Inventor’s API.  In order to access Inventor’s API you need to make your project aware of the API and what it supports.  You do this by referencing Inventor’s Interop library.  The interop completely describes the API in a .Net friendly way.
   
   To add the reference choose the “Add Reference…” command from the Project menu, as shown below.
   
   
   In the Add Reference dialog choose the Browse tab and browse to the directory below (for whatever version of Inventor you’re using). 
   
      C:\Program Files\Autodesk\Inventor 2013\bin\Public Assemblies
   
   Select “Autodesk.Inventor.Interop.dll”, as shown below and click OK.
   
    
   You can view the references a project has by using the Project window and selecting the “Show All Files” button highlighted in red below.  All of the references will be displayed in the “References” folder.
   
   
4. I’ll talk more about this in my next post, but just so we end this post with your program doing something somewhat useful, add a button to your form, (I called mine btnRun), and add the code below into the Click event of the button.  (Sorry about the weird line continuations but the width of a line in this blog interface is very limited.)

' Connect to a running instance of Inventor. 
Dim invApp As Inventor.Application 
Try 
    invApp = _
           System.Runtime.InteropServices.Marshal.GetActiveObject _
                                            ("Inventor.Application") 
Catch ex As Exception 
    MessageBox.Show("Inventor must be running.") 
    Exit Sub 
End Try

' Create a new part document. 
Dim partDoc As Inventor.PartDocument 
partDoc = invApp.Documents.Add( _
                      Inventor.DocumentTypeEnum.kPartDocumentObject)

Now when you run your application and click the button the program will connect to Inventor if it’s running or display a warning message if it’s not.  If it is running it will create a new part document.  Each time you click the button a new part will be created.  In the next post we’ll look at this code in more detail and discuss the basics of working with documents.

-Brian

What Should I Use to Program Inventor?

Before actually beginning to write any code I wanted to spend some time discussing what language to use when programming Inventor.  I wrote a post on this a while ago that still applies but my opinion has changed a bit since then.  In that post I recommended that you begin with Inventor’s VBA.  VBA still does have a few advantages but I think the advantages some of  the other languages have now outweighs the advantages VBA has.

If you’re a fairly new programmer, I recommend Visual Basic.  The latest version is Visual Basic 2010.  It comes as one of several languages in Visual Studio 2010.  The Professional version of Visual Studio, which is the least expensive full version, is approx. $500 and it probably has everything you’ll ever need.  You can also download Visual Basic 2010 Express from Microsoft, which is a trimmed down version and is free.  This is the version that’s used for the book I recommended in my previous post.  There are a couple of things missing from this version that you’ll wish you had when you begin some more advanced Inventor development but we’ll look at some workarounds later when we get to those topics.  For now the free Express edition has more than enough capabilities to begin learning Inventor’s API and is a great way to get started.

If you’re an old C++ programmer then you’ll likely prefer C# over Visual Basic.  I believe Visual Basic is easier to use for a new programmer but C# is very similar so it really is a personal preference rather than a question of which one is better.  You can also use Visual C++, but it is much harder, especially for a new programmer, to use than either Visual Basic or C#.  For this series of posts on getting started with the API, I’ll stick primarily with Visual Basic, but will also do some coverage of C# when there are differences.  I’m not going to spend any time on C++ but plan to write a separate post covering using C++ with Inventor.

In the next post we’ll actually begin writing some code.

-Brian

Getting Started Programming Inventor

It’s good to be back now that Inventor 2013 is out the door.  I ended up with my hands in too many projects this release and didn’t get much of a chance to work on the blog.  A big thanks to Wayne for keeping it going.

Over the past few months my son has developed an interest in programming and I’ve been working with him on learning to program Inventor.  I thought it might be useful to write up for the blog some of exercises I’ve gone through with him to help him learn how to program in general, and Inventor’s programming interface specifically.

Over the next several weeks I want to go through a lot of topics, each building on top of the other, to create a relatively sophisticated Inventor command.  The command will be a new sketch command that creates a slot shape.  I know there have been requests in the past to have this functionality in Inventor.  Inventor 2013 does introduce new commands to create center point rectangles but it doesn’t yet address the creation of slot shapes, so we’ll create our own.

As we go through these exercises I want to focus on the Inventor API (Application Programming Interface) side of programming and am going assume you already know the basics of general programming.  I know this is a big assumption and probably incorrect in many cases.  It was also something that my son didn’t know and to help get him started I did some research to find a good book.  The one I found and ordered for him I’m quite happy with and feel I can recommend it to others that are getting started programming or are a bit rusty in their programming skills.  The book is Sams Teach Yourself Visual Basic 2010 in 24 Hours by James Foxall.  It’s relatively inexpensive and is available on Amazon in both a printed and Kindle version.

 

If you’re new to programming, this is a simple way to get started and then being able to apply many of the basics you learn from the book as we begin writing the new Inventor command will help to reinforce what you’ve just learned by seeing practical uses for it.

-Brian