1. Customizing Autodesk® Navisworks® 2013 with the .NET API
Simon Bee
Software Development Manager IPG-PDC Group

2. Class Summary
This class will introduce you to customizing Autodesk Navisworks using the new .NET API. It will cover how to create add-ins that sit inside the product and allow you to integrate with your own programs, how to automate the product to perform process-intensive and repetitive tasks, and how to embed the .NET controls in your own application to leverage the powers of Navisworks.

3. Learning Objectives At the end of this class, you will be able to:
Write a simple .NET plugin for Autodesk Navisworks Manage 2013.
Understand how to automate Autodesk Navisworks.
Write a simple application that uses the Autodesk Navisworks .NET controls.

4. Introduction to the Navisworks .NET API

5. About Navisworks History of product
8 major releases, about 10 years old
Acquired about 2 years ago, first ADSK release version 2009.
2011 introduced ribbon UI and .NET API.
Core features – Design review, large model handling, wide file format support
Plugins – TimeLiner, Clash Detective, Presenter, Animator

6. .NET API NWcreate COM API Navisworks APIs
Quickly mention three different APIs
Nwcreate – for creating files
COM API – legacy COM, ActiveX control, automation, plugins
.NET API – replacement for COM API, controls, automation, plugins, etc.
.NET API
COM API

7. “Easy things should be easy, hard things should be possible”
Design Philosophy
“Easy things should be easy, hard things should be possible”
A quick note on the design philosophy used.
Follows standard .NET API design guidelines.

8. Applications of the .NET API
Plugins
Automation
Plugins – allow you to extend functionality in Navisworks.
Automation – allows you to automate basic Roamer functionality.
Applications - .NET controls can be added to your own applications.
Control-based Applications

9. Assemblies Autodesk.Navisworks.Api Autodesk.Navisworks.Automation
Main assemblies:
Autodesk.Navisworks.Api – Core API classes and functionality
Autodesk.Navisworks.Automation – Support for automating Navisworks
Autodesk.Navisworks.Controls - .NET controls for use in third-party applications
Autodesk.Navisworks.ComApi – COM API interop support classes
We will take a look at each of these in more detail.
Autodesk.Navisworks.Automation
Autodesk.Navisworks.Controls
Autodesk.Navisworks.ComApi

10. The Main Navisworks .NET API

11. Autodesk.Navisworks.Api Create Plugins Load and Save Documents
Query and Manipulate Models
Create Plugins
Load, Save and Append documents/models
Query the model to extract information (e.g. BIM), and manipulate the model.

12. Main API Classes Four main classes. Application
Provides access to the main document. Note that MainDocument and ActiveDocument refer to same object.
Also has properties for the GUI, and provides access to the plugins.
Has events to tell you when the active document is changing.
Provides events for progress, and when the GUI is being created or destroyed.
Document
Has methods for loading, appending, and saving and publishing files.
Contains all document-related data, including models, current selection, and viewpoints.
Has events for when the active view is changing.
Model
Represents a loaded file.
Has properties to access data such as source filename, vectors (e.g. Up, north), and root model item.
ModelItem
Represents a single item in a model, such as a group node or a geometry node.
Can be seen in the selection tree in Navisworks.
Has properties for accessing geometry, attributes and children (if a group node)

13. Main API Classes Autodesk.Navisworks.Api.Application
These are the class names.
Note how they related to each other.
Autodesk.Navisworks.Api.Document
Autodesk.Navisworks.Api.Model
Autodesk.Navisworks.Api.ModelItem

14. Querying The Model Active Document Get First Model Get Root Item
Document doc = Application.ActiveDocument;
First, get access to the active document. Mention MainDocument property. Currently same as ActiveDocument, but in future we might support multiple documents (Roamer is SDI).
Then access the first model. Can have multiple models appended into one document. Here, accessing as an array, zero based as usual.
The get hold of the root model item. This will normally be the partition. From here, can traverse children manually. Will cover items later on.
The query the model item.
Get First Model
Model model = doc.Models[0];
Get Root Item
ModelItem root = model.RootItem;
Query Item
bool is_hidden = root.IsHidden;

15. Object Properties
Properties are split into categories, and are displayed in the Properties window in the GUI. Each category has its own tab. Here, we can see some Inventor properties.
Within the category are a series of properties. Value can be of various data types (e.g. String, numeric, linear, angluar, time, etc.).

16. Object Properties Autodesk.Navisworks.Api.PropertyCategory
The two main classes. Each has an associated collection class too.
The UML shows the relationship between these classes and the ModelItem.
Autodesk.Navisworks.Api.DataProperty

17. Access Object Properties
Finding Property Category
PropertyCategory prop_cat =
root.PropertyCategories.FindCategoryByName(
PropertyCategoryNames.Item);
First, we look for the property category. Look for a category by either internal name or display name. From an API point of view, former is preferred because will work across localised versions. Some built-in category and property names are defined by the API so you don’t need to remember them.
The access the property value. Here, we are converting to a string for display, but it could be any type.
Accessing Property Value
DataProperty prop =
prop_cat.Properties.FindPropertyByName(
DataPropertyNames.ItemName);
string value = prop.Value.ToDisplayString();

18. Finding Items Search Iteration LINQ Search s = new Search();
ModelItemCollection searchResults = s.FindAll(false);
Finding items is a large part of the API, and there are three main mechanisms.
Firstly, using the Search API. This corresponds to the Find Items functionality found in Roamer. Fast because all in native code, but can only do what Roamer can do.
Next, basic iteration. ModelItem can be iterated over using Ienumerable<> interface, and can manually examine items.
Finally, highest level uses LINQ, which allows much expression, but is slowest because has to call back and forth between managed and native code.
Iteration
foreach (ModelItem item in
Application.ActiveDocument.CurrentSelection.SelectedItems) {
// Examine item here. }
IEnumerable<ModelItem> items =
from item in Application.ActiveDocument.Models.GetRootItems().DescendantsAndSelf
where ItemPrice(item) > 100
select item;
LINQ

19. Searching The Model Search has two main parts:
Selection – what to search (i.e. Where to look).
Conditions – what to find.
A Condition is basically a test against an object property.
Has a few other options that are properties on the Search class.

20. Using The Search Class Create A Search Add Selection and Conditions
Search search = new Search();
First, create a new search.
Add a selection and conditions. Here, we are searching the entire document. Next we add a search for the Revit Element category where it is equal to the string value “Stairs”.
Finally execute the search. Returns a model collection.
Show demo?
Add Selection and Conditions
search.Selection.SelectAll();
search.SearchConditions.Add(
SearchCondition.HasPropertyByName("LcRevitData“,
"LcRevitPropertyElementCategory").
EqualValue(VariantData.FromDisplayString("Stairs")));
Execute Search
ModelItemCollection items = search.FindAll(Application.ActiveDocument,
false);
Application.ActiveDocument.CurrentSelection.CopyFrom(items);

21. Mixing Search Methods Combine Search With LINQ
IEnumerable<ModelItem> expensive_items =
from item in search.FindIncremental(Application.ActiveDocument, false);
where ItemPrice(item) > 100
select item;
Combine Search With LINQ
Can combine mechanisms. First, use Search to select a subset of the model, then use LINQ to perform more sophisticated searches over the selection.

22. Modifying The Model
Can also apply basic modifications to the model, which largely match what you can do in Roamer. So far, can override element colour, transparency, visibility and required status. We expect more modifications to be available later on.
All modifications to the document occur via DocumentParts. These live under a different namespace. Currently, there are three document parts.
DocumentCurrentSelection – allows you to modify the contents of the current selection (such as adding or removing items in the selection).
DocumentModels – provides access to override attributes of model items (e.g. Colour, transparency, visibility).
DocumentTool – controls currently active tool/paradigm.

23. Document Parts Application.ActiveDocument.CurrentSelection
DocumentParts are accessed as properties from the Document object. Here, we are accessing them via the ActiveDocument property. See the relationship below.
Application.ActiveDocument.Models
Application.ActiveDocument.Tool
Application.ActiveDocument.SelectionSets

24. Modifying The Model Change Current Selection Override Colour
IEnumerable<ModelItem> items =
Application.ActiveDocument.Models.GetRootItems().DescendantsAndSelf.
Where(x => x.IsHidden = false);
Application.ActiveDocument.CurrentSelection.CopyFrom(items);
Firstly, we can modify the current selection. Here, we are using LINQ to select all visible items, and then selecting them.
Next, we are using the DocumentModels part to override the colour to red.
And finally we are changing the active tool to the Select tool.
Override Colour
Application.ActiveDocument.Models.OverridePermanentColor(items, Color.Red);
Change Tool
Application.ActiveDocument.Tool = Tool.Select;

25. Responding To Events DocumentPart Events Changed
ModelGeometryMaterialChanged
Document parts all have events for when the part of the document they represent changes, or is about to change in some cases. A couple of example events are shown here.
You can respond to these events in the normal .NET way.
First, you add an event handler to the event,
Then write your event handler. This one takes the standard event args, but some other events might take more specialised event args.
Event Handlers
Application.ActiveDocument.CurrentSelection.Changed +=
new EventHandler<EventArgs>(CurrentSelection_Changed);
private void CurrentSelection_Changed(object sender, EventArgs e) {
// Respond to event... }

26. Creating Plugins
Currently, can only create one type of plugin, the AddIn plugin.
Plugins appear on the Add-Ins tab. Here you can see the tab with all the example plugins.

27. AddInPlugin Autodesk.Navisworks.Api.Plugins.AddInPlugin
Plugins simply derive from AddInPlugin (in the Plugins namespace).
Need to define a couple of attributes:
The plugin name, and the developer ID. The combination must be unique. Here, we are using the Autodesk identifier. You can apply for your own developer identifier via the ADN programme to avoid conflicts with other plugins. Same identifier is used across all Autodesk products.
Couple of optional attributes are specified here too. A display name for the plugin, and some tooltip text.
AddInPlugins must implement the Execute method, which is called when the user clicks on the button. In this case, the parameters will be empty. Plugins can also be executed through Automation or the command line, and in this case we can pass in additional arguments.
Inside Roamer, the return code is ignored. When run on the command line, is returned back. (???)
[PluginAttribute("MyPlugin", "ADSK",
ToolTip = "My Plugin", DisplayName = "My Plugin")]
public class MyPlugin : Autodesk.Navisworks.Api.Plugins.AddInPlugin {
public override int Execute(params string[] parameters) //
// Do stuff here!
return 0; }

28. Let’s Write Some Code! Plugins In Action Switch to Visual Studio.
Create a new project.
Define basic plugin.
Add in pre-built form.

29. The Navisworks Automation API

30. Autodesk.Navisworks.Automation
Automate Navisworks
Perform Batch Jobs
Automation lets you control the Roamer application.
Useful for performing batch jobs such as nightly tasks to convert files or make bulk edits.

31. Main Automation Class
Autodesk.Navisworks.Api.Automation.NavisworksApplication
The automation interface is pretty sparse.
Most heavy lifting is expected to be done by a plugin.
Can also do everything here from the command line, but code might be required to do something a bit more sophisticated (e.g. Load all files from a directory).
static void Main(string[] args) {
NavisworksApplication app = new NavisworksApplication();
app.ExecuteAddInPlugin(“Colouriser.ADSK"); }

32. Time To Automate Navisworks...
Automation In Action
Time To Automate Navisworks...

33. The Navisworks .NET Controls

34. Autodesk.Navisworks.Controls
.NET Controls for 3rd Party Applications
Utilise Large Model Capability
We provide .NET controls that you can add to your own application.
Need to have NavisWorks installed to use; no option yet for OEM-style controls
Typical uses might be to provide view of model in some other application (e.g. Facilities management or component manager)

35. Main Control Classes
Autodesk.Navisworks.Api.Controls.ApplicationControl
ApplicationControl – required for any application. Contains core functionality. Initialise/terminate API via this control.
DocumentControl – stores a document, which can have multiple models.
ViewControl – provides a view onto a model.
Autodesk.Navisworks.Api.Controls.DocumentControl
Autodesk.Navisworks.Api.Controls.ViewControl

36. The Main Controls Here we have two views.
Each is referencing the same document.
Note how selection is on the document, not the view, so share same selection.
ApplicationControl in the background controls things.

37. A Very Simple Component Viewer
Controls In Action
A Very Simple Component Viewer

38. The Navisworks COM Interop API

39. Autodesk.Navisworks.ComApi
Autodesk.Navisworks.Api
.NET API provides functionality, but older COM API currently has a bit more in it.
We might want to utilise this functionality via the COM API.
Can do this using the auto-generated Interop.ComApi assembly. This is a standard COM/Interop assembly auto generated.
To make a bit easier to use with .NET API, the ComApi assembly provides helper methods to convert between two systems.
Autodesk.Navisworks.Interop.ComApi
COM
Autodesk.Navisworks.ComApi

40. Using COM Interop Accessing Saved Views Converting to .NET API
InwOpState10 state = ComApiBridge.State;
InwSavedViewsColl views = state.SavedViews();
foreach (InwOpSavedView view in views) {
comboBox1.Items.Add(view.name); }
Here, we might want to populate a combo box with all the selection sets. So use COM API to access.
Can then still convert a COM selection object to a .NET API selection object using the ComApiBridge.
Note the COM API indexing is 1-based!!
Converting to .NET API
InwOpSelectionSet set = (InwOpSelectionSet)sets[1];
ModelItemCollection items =
ComApiBridge.ToModelItemCollection(set.selection); Application.ActiveDocument.CurrentSelection.CopyFrom(items);

41. Q&A
Any questions?

42. Autodesk, AutoCAD* [*if/when mentioned in the pertinent material, followed by an alphabetical list of all other trademarks mentioned in the material] are registered trademarks or trademarks of Autodesk, Inc., and/or its subsidiaries and/or affiliates in the USA and/or other countries. All other brand names, product names, or trademarks belong to their respective holders. Autodesk reserves the right to alter product and services offerings, and specifications and pricing at any time without notice, and is not responsible for typographical or graphical errors that may appear in this document. © 2012 Autodesk, Inc. All rights reserved.