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

Class Summary This class will introduce you to customizing Autodesk Navisworks 2013 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.

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.

Introduction to the Navisworks .NET API

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

.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

“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.

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

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

The Main Navisworks .NET API

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.

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)

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

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;

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.).

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

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();

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

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.

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);

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.

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.

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

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;

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... }

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.

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; }

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

The Navisworks Automation API

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.

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.OpenFile(@"C:\file\A.nwd"); app.AppendFile(@"C:\file\B.nwd"); app.ExecuteAddInPlugin(“Colouriser.ADSK"); app.SaveFile(@"C:\files\Combined.nwd"); }

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

The Navisworks .NET Controls

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)

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

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.

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

The Navisworks COM Interop API

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

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);

Q&A Any questions?

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.