The Building Coder

External Command Lister and Adding Ribbon Commands

I have been asked a couple of times how you can integrate multiple Revit add-ins from different sources together into a single ribbon panel.

This topic has also been discussed on the web, e.g. towards the end of whether to install to the add-ins tab or make new ribbon tab, and at Autodesk University, where Jose Guia presented CP3766 – Tying All of Your Revit Add-ins into a Pretty Little Ribbon.

Unfortunately, none of these offer any very useful solution, or show or share any code.

I have a very simple approach to suggest, though, which has been around for several years already:

The RvtSamples SDK application reads a text file listing any number of .NET assemblies defining any number of external commands and generates a ribbon panel populated with buttons to launch them all.

Each entry in that file occupies seven lines specifying a group, menu text, description, large image, small image, .NET assembly path and full name of the external command to launch. Here is the first entry in that file:

  Analysis
  EnergyAnalysis Model
  Demonstrates how to use EnergyAnalysisModel API.
  LargeImage: 
  Image: 
  Z:\...\bin\Debug\EnergyAnalysisModel.dll
  Revit.SDK.Samples.EnergyAnalysisModel.CS.Command

Only the two last lines of the entry are really relevant. Al the rest is decorative, and hopefully informative as well.

In fact, that is the one and only method that I use myself to launch both SDK sample external commands and all The Building Coder sample code.

Furthermore, the text file read by RvtSamples includes support for include files that I implemented back in 2008, similar to the standard C #include pre-processor directive.

The only important information required to populate the RvtSamples text file is the .NET assembly filename of the DLL implementing the external command, and the full external command implementation class name, including its namespace prefix.

Here is the complete EnergyAnalysisModel Revit SDK sample add-in manifest, showing the information corresponding to the RvtSamples.txt entry above:

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Command">
    <Assembly>EnergyAnalysisModel.dll</Assembly>
    <ClientId>6f559488-4285-40b7-bfca-043bb69ea0a7</ClientId>
    <FullClassName>Revit.SDK.Samples.EnergyAnalysisModel.CS.Command</FullClassName>
    <Text>EnergyAnalysis Model</Text>
    <Description>Demonstrates how to use EnergyAnalysisModel API.</Description>
    <VisibilityMode>AlwaysVisible</VisibilityMode>
    <VendorId>ADSK</VendorId>
    <VendorDescription>Autodesk, www.autodesk.com</VendorDescription>
  </AddIn>
</RevitAddIns>

As you can see, the content of the Assembly and FullClassName tags correspond exactly to the two last lines specified in RvtSamples.txt.

Where can this information be obtained?

Well, the simplest and most direct source would the add-in manifest, if one is available.

To load an external command on its own, the assembly path and implementation class name are listed in the Assembly and FullClassName add-in manifest tags.

Unfortunately, if the add-in you wish to integrate defines an external application to create a custom panel, it may not list all its command names in the manifest file.

Where can they be obtained from then?

Well, several tools exist which can read .NET assemblies and display their contents.

I talked about Reflector way back in the early days of the blog. It since became commercial. Victor Chekalin mentioned using dotPeek, and my colleague Adam added that he uses the ILSpy .NET decompiler and is perfectly happy with that.

Basically, the information is made accessible via the .NET Reflection namespace functionality.

To make things really simple for you non-programmer guys, I went and implemented a little Revit add-in external command which does nothing but list the full class names of all other external commands defined in any assembly you care to point it at.

It can be run in Revit without even opening a document, in zero document state.

It prompts you to select a DLL file, opens it as a .NET assembly, and uses reflection to determine all the classes defined in it derived from the IExternalCommand interface.

These are listed in a read-only dynamically generated resizable form.

Here is the result of pointing it at the simpler DockableDialog sample I published last week:

The code is very simple.

The ExternalCommandLister class is instantiated with a .NET assembly filename and extracts all external command definitions from it like this:

class ExternalCommandLister
{
  string _assembly_filename;
  string[] _external_commmand_class_names;
 
  /// <summary>
  /// Display error message
  /// </summary>
  /// <param name="msg">Message to display</param>
  void ErrorMsg( string msg )
  {
    Debug.WriteLine( "External Command Lister: "
      + msg );
 
    TaskDialog.Show( "External Command Lister",
      msg );
  }
 
  public ExternalCommandLister(
    string assembly_filename )
  {
    _assembly_filename = assembly_filename;
    _external_commmand_class_names = null;
 
    if( !File.Exists( assembly_filename ) )
    {
      throw new ArgumentOutOfRangeException(
        "assembly_filename", "file not found" );
    }
    try
    {
      // No need to load the Revit API assemblies, 
      // because we are ourselves a Revit API add-in 
      // inside of Revit, so they are guaranteed to
      // be present.
 
      //Assembly revit = Assembly.LoadFrom( "C:/Program Files/Autodesk/Revit Architecture 2014/RevitAPI.dll" );
      //string root = "C:/Program Files/Autodesk Revit Architecture 2014/";
      //Assembly adWindows = Assembly.LoadFrom( root + "AdWindows.dll" );
      //Assembly uiFramework = Assembly.LoadFrom( root + "UIFramework.dll" );
      //Assembly revit = Assembly.LoadFrom( root + "RevitAPI.dll" );
 
      // Load the selected assembly into 
      // the current application domain:
 
      Assembly asm = Assembly.LoadFrom(
        assembly_filename );
 
      if( null == asm )
      {
        ErrorMsg( string.Format(
          "Unable to load assembly '{0}'",
          assembly_filename ) );
      }
      else
      {
        IEnumerable<Type> types = asm.GetTypes()
          .Where<Type>( t =>
            null != t.GetInterface(
              "IExternalCommand" ) );
 
        _external_commmand_class_names = types
          .Select<Type,string>( t => t.FullName )
          .ToArray();
      }
    }
    catch( Exception ex )
    {
      ErrorMsg( string.Format(
        "Exception '{0}' processing assembly '{1}'",
        ex.Message, assembly_filename ) );
    }
  }
 
  public string AssemblyFilename
  {
    get
    {
      return Path.GetFileName( _assembly_filename );
    }
  }
 
  public string[] CommandClassnames
  {
    get
    {
      return _external_commmand_class_names;
    }
  }
}

The one single important line is really just

  IEnumerable<Type> types = asm.GetTypes()
    .Where<Type>( t =>
      null != t.GetInterface(
        "IExternalCommand" ) );

It asks the assembly for all the types it defines and extracts the ones derived from IExternalCommand, i.e. the external command implementation classes.

The external command mainline Execute implementation prompts the user to select a DLL file, instantiates an ExternalCommandLister instance, queries the command names and displays them in a form created on the fly like this:

[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  /// <summary>
  /// Define the initial .NET assembly folder.
  /// </summary>
  const string _assembly_folder_name
    = "C:\\ProgramData\\Autodesk\\Revit\\Addins\\2014";
 
  /// <summary>
  /// Select a .NET assembly file in the given folder.
  /// </summary>
  /// <param name="folder">Initial folder.</param>
  /// <param name="filename">Selected filename on success.</param>
  /// <returns>Return true if a file was successfully selected.</returns>
  static bool FileSelect(
    string folder,
    out string filename )
  {
    OpenFileDialog dlg = new OpenFileDialog();
    dlg.Title = "Select .NET Assembly or Cancel to Exit";
    dlg.CheckFileExists = true;
    dlg.CheckPathExists = true;
    dlg.InitialDirectory = folder;
    dlg.Filter = ".NET Assembly DLL Files (*.dll)|*.dll";
    bool rc = ( DialogResult.OK == dlg.ShowDialog() );
    filename = dlg.FileName;
    return rc;
  }
 
  void DisplayExternalCommands(
    string filename,
    IWin32Window owner )
  {
    ExternalCommandLister lister
      = new ExternalCommandLister( filename );
 
    string[] a = lister.CommandClassnames;
    int n = a.Length;
 
    System.Windows.Forms.Form form
      = new System.Windows.Forms.Form();
 
    form.Size = new Size( 400, 150 );
 
    form.Text = string.Format(
      "{0} defines {1} external command{2}",
      lister.AssemblyFilename, n,
      ( 1 == n ? "" : "s" ) );
 
    form.FormBorderStyle
      = FormBorderStyle.SizableToolWindow;
 
    System.Windows.Forms.TextBox tb
      = new System.Windows.Forms.TextBox();
 
    tb.Dock = System.Windows.Forms.DockStyle.Fill;
    tb.Location = new System.Drawing.Point( 0, 0 );
    tb.Multiline = true;
    tb.TabIndex = 0;
    tb.WordWrap = false;
    tb.ReadOnly = true;
    tb.Text = string.Join( "\r\n",
      lister.CommandClassnames );
 
    form.Controls.Add( tb );
    form.ShowDialog( owner );
  }
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    IWin32Window revit_window
      = new JtWindowHandle(
        ComponentManager.ApplicationWindow );
 
    string filename;
 
    while( FileSelect(
      _assembly_folder_name,
      out filename ) )
    {
      DisplayExternalCommands( filename,
        revit_window );
    }
    return Result.Succeeded;
  }
}

The reason I implemented this as a Revit command instead of a stand-alone command-line console application was simply to be sure that the Revit API assemblies are already present before I try to load the add-in assemblies.

I implemented such a stand-alone console application in the past that loaded RevitAPI.dll itself, but that was a long time ago. Now the number of Revit API assemblies is larger, and other restrictions may have been added as well.

A complex external command may obviously depend on additional dependencies in addition to the Revit API assemblies. In that case, it might be harder or impossible to simply load it as shown above. One option then might be to load the other add-in into Revit first using its own loading mechanism, and then try to access its assembly data.

Another caveat is the ClientId tag in the external add-in manifest. For the simple add-ins that I create, it is hardly used, except for extensible storage access. It might be important for other applications as well, though.

Here is JtExternalCommandLister.zip containing the complete source code, Visual Studio solution and add-in manifest of this external command.

I hope you find this useful and that it helps resolves discussions such as the one pointed to above.

Addendum by Rudolf Honke of Mensch und Maschine acadGraph GmbH:

If different add-ins create custom ribbon panels in the same tab, whichever one of them arrives last will obviously run into a collision attempting to create a tab that already exists.

Worse still: the Revit API provides no method to query the existence of a specific tab. It may be possible using the .NET UI Automation library.

However, you can always attempt to retrieve a tab with a specific name using GetRibbonPanels(tabName). If the tab does not exist, this method will throw an exception.

The two add-ins could therefore safely add their panels to the same tab using the following approach:

public Autodesk.Revit.UI.Result OnStartup(
  UIControlledApplication application )
{
  string tabName = "TBC";
  string panelName = "TBC";
 
  try
  {
    List<RibbonPanel> panels = application
      .GetRibbonPanels( tabName );
  }
  catch
  {
    // Tab "TBC" does not yet exist, 
    // so create new
 
    application.CreateRibbonTab( tabName );
  }
 
  RibbonPanel panel = application
    .CreateRibbonPanel( tabName, panelName );
 
  // Add your buttons here
 
  return Result.Succeeded;
}

In principle, this approach may be regarded as bad coding style, because exceptions are and should remain exceptional.

Since there is no other way to obtain the required information in this case, though, one is left no choice.

Actually an alternative might exist using the .NET UIAutomation library, but such an approach may be awfully slow.

Copy and Paste API Applications and Modeless Assertion

Here is a detailed description of one of the most exciting Revit 2014 API features that you should have heard about by now and promises numerous uses, prompted by a question from a developer on duplicating views from one document to another. Another couple of uses of it cropped up in the past, so it seems like an overview is called for:

• Duplicating a view from one document to another
• Solving the non-unique unique id problem
• Managing materials in adsklib or template files
• Transferring groups between projects
• Revit API use in modeless form throws an exception

Duplicating a View from one Document to Another

Question: I need to perform the following action programmatically:

Insert Tab > Insert from File > Insert view from file > Select File > Select view in this file.

Is there some way to achieve this via API in Revit?

Answer: Yes, you are in luck, this is covered by the new Revit 2014 API.

And even more luckily, the development team selected very good and suitable API samples, so the exact workflow you describe is covered by the new Revit 2014 DuplicateViews SDK sample illustrating the new copy and paste API.

Look at the second bullet item in the overview of Revit 2014 API news, mentioning the new copy and paste API.

Here is the description from the What's New section of the Revit API help file RevitAPI.chm, reproduced here:

Copy & paste elements

The new methods:

ElementTransformUtils.CopyElements(Document, ICollection<ElementId>, Document, Transform)

ElementTransformUtils.CopyElements(View, ICollection<ElementId>, View, Transform)

Transform ElementTransformUtils.GetTransformFromViewToView(View, View)

support copy and paste of arbitrary elements. The first overload supports copy within documents, or from document to document. The second overload also support copying within one document or between two documents, but specifically supports copy and paste of view-specific elements.

The DuplicateViews SDK Sample

DuplicateViews copies and pastes drafting views and schedules from one document to another
, demonstrating use of the CopyPasteOptions, ElementTransformUtils, FilteredElementCollector, IDuplicateTypeNamesHandler and IFailuresPreprocessor classes. The drafting view contents are also copied.

The DuplicateAcrossDocumentsCommand.cs module implements an external command to copy schedules and drafting views across documents and makes use of a number of useful utility classes defined in DuplicateViewUtils.cs.

In detail, DuplicateViews copies all drafting views, image views, and schedules from the currently active document into another document that is currently in memory. All drafting elements in the non-schedule views are also copied, as is all schedule formatting and filtering. It uses API tools to hide any duplicate types warnings that typically arise when doing this from the user interface.

To test this, open any two project documents in Revit. Set the active document to be the document from which you wish to copy views. Launch Add-ins > CopyPaste > Duplicate across documents and enjoy. A popup message will appear listing the number of schedules, drafting views and drafting elements copied by the command.

If you prefer to watch someone else run this sample rather than trying it yourself, it is also demonstrated live in the Revit 2014 DevDays presentation recording.

Solving the Non-unique Unique Id Problem

A couple of times, people mentioned issues caused by copied files, resulting in copied unique ids on certain elements, e.g. thus:

Question: Do you have any recommendation on how to handle unique ids in copied files?

We cannot tell people 'do not copy the files', because they sometimes put in a large effort to create a file that is used as a basic starting point for multiple projects.

Answer: Yes, you are in luck again. The copy and paste API should solve this.

Documents that are copied obviously contain exact copies the ids of their elements. This also can happen when using a document as a template to create another document.

Elements created by copying them through the copy and paste API obviously are assigned new unique ids. That should solve the issue.

Of course, there is no way to change the unique id of an element that already exists.

Managing Materials in Adsklib or Template Files

Question: I would like to know if it is possible to access data stored in adsklib files through API functions. The desired functionality would be to load materials, appearance, physical and thermal assets from an external adsklib file to the current active project document.

The aim is to implement a custom materials library with our application using an adsklib file instead of a project template, as described in the Autodesk wiki on managing material libraries, so only the required materials are included and not all, to decrease the project template size and speed up the material browser.

Is this possible? If so, how?

Answer: Nope, sorry, as far as I know, there is no API support for this.

From my naive grass roots perspective, the adsklib idea was born quite a few years back and has since been displaced by visions of cloud and mobile.

The file formats have died, and long live the new format, ubiquitous JSON or whatever.

You say you "have been looking into this subject for some time already" ... maybe it is time to start looking into something new? I see two possibilities for moving forward, besides the solution that you mention of including all materials in the template file:

1. Store the materials in several separate adsklib files, and only load the ones you really need.
2. Use the new Revit 2014 copy and paste API functionality to copy and paste only the required materials from your or some other project.

Response: Thank you for thinking of other solutions.

Option 1 probably still requires API access to the adsklib file to programmatically transfer the material assets from the adsklib into the project.

I had a quick look at the copy and paste functionality and think this would be a good solution. We could use a separate project or template file as our material library instead of the adsklib one and copy/paste the required materials into the current project.

Transferring Groups Between Projects

I have been working with the Revit API to create a Revit application that can transfer a group type from one project file to another. I am working on a very large project, so we have to separate it into several project files due to performance. We are using groups to ensure that rooms having the same characteristics always are the same and can be updated quickly. But the model separation creates a problem to ensure that all group types in all project files are updated. We tried to use the link functionality instead of groups, but when there are many instances of a link Revit become very slow. We also considered using family nesting to solve the problem, but we want to be able to include system families as well, so that solution won't work.

We have one project file where we create the Groups, use 'Save Group' to create a project file, then 'Load Group' or 'Reload Group' to get it in to the actual project file (we have 21 project files). So what I want is to create a Revit application that optimizes this workflow by transferring groups from one project file to another. But working with the API has raised a couple of questions:

• Why are the user interface functions 'Load Group', 'Save Group', 'Reload group' not accessible from the API? Are there any plans to make them accessible?
• If I want to transfer a group type from one project file to another, is the only way to do this to create every group member in the receiving project file using the API functions for every member, e.g. Wall.Create and then group the members?
• Is there a way to transfer system families from one project file to another using the API? The user interface function transfer project standards is not available, are there any plans to make it available?
• It seems like Revit is more appropriate for small projects, there are some plans to make Revit better for larger projects? For instance by sharing families (system and loadable) and groups across project files?

Answer: I am surprised that you say that Revit is more appropriate for small projects. I was under the impression that the opposite is true.

You may be surprised to hear that the answer to all your questions is yes.

You will be glad to hear that a number of improvements in Revit 2014 are specifically targeted at supporting still larger projects, and many of these improvements specifically target the family management and loading performance.

Regarding all of your other questions, I have one single big suggestion to make to you: please take a look at Revit 2014, and especially at the new copy and paste API functionality it provides. I think that may meet your needs exactly and efficiently.

Response: I took a look at the Revit 2014 API and I must say that the copyElement method is just what I need ;-)

It is a much safer way to transfer groups from one project file to another.

Revit API use in Modeless Form Throws an Exception

Finally, on a completely different topic, several people making illegal use of the Revit API from an invalid context in Revit 2013, e.g. in a modeless form, are now running into a problem. David Rock describes it in his comment on accessing the Revit main window handle:

Question: In Revit 2014 I'm having trouble showing a modeless form and calling a transaction whilst inside the form. It is producing an error stating that "starting a transaction from an external application running outside of API context is not allowed".

Answer: Yes, it looks as if you are calling the Revit API directly from your modeless dialogue running in another thread.

As you should know, actually, that was never supported.

Now, in Revit 2014, an exception is raised when you make such an attempt.

You are lucky that it worked so far without corrupting anything.

The solution is described in depth here on the blog: simply google for "modeless site:thebuildingcoder.typepad.com", or look at the discussions in the Idling category.

In short, make use of the Idling event, or implement an external event, which is a simplified wrapper around that, and base you application on the ModelessForm_ExternalEvent and ModelessForm_IdlingEvent SDK samples.

Do not call the Revit API directly, ever.

A Simpler Dockable Panel Sample

Here is a very nice little sample on using the new Revit 2014 dockable panels by Håkan Wikemar of AEC, Sweden.

In Håkan's words, it is close to the DockableDialogs SDK sample but easier to follow.

The DockableDialogs SDK sample demonstrates modeless dialog design, external events, and the new dockable dialogs UI API framework.

Håkan's DockableDialog sample described here focuses purely on the dockable panel functionality and nothing else.

One thing to note is that you need to register the panel before it can be displayed, and this needs to happen in a zero document state, i.e. with no project open.

In order for the external application ribbon panel to be accessible at all in zero document state, it needs to implement and register an availability class, and the associated command has to use manual transaction mode, as explained in enabling ribbon items in zero document state.

Once this is done, the panel appears like this:

If you try to register it twice, an exception is thrown, naturally, saying "Cannot register the same dockable pane ID more than once. Parameter name: id".

Once the panel has been registered and a project activated, the commands to show and hide the dockable panel are presented:

Those two commands can happily use read-only transaction mode, since they do not modify the database in any way.

The dockable panel is initially displayed sharing the same floating window as the project browser:

It can be dragged off that pane to its own individual floating window:

Clicking 'Hide' removes it again.

Here is the full source code, which unfortunately sports rather long lines. You can copy to a text editor or view the HTML source to see them in full, or simply download the zip file below:

public class Ribbon : IExternalApplication
{
  public Result OnStartup(
    UIControlledApplication a )
  {
    a.CreateRibbonTab( "AEC LABS" );
 
    RibbonPanel AECPanelDebug
      = a.CreateRibbonPanel( "AEC LABS", "AEC LABS" );
 
    string path = Assembly.GetExecutingAssembly().Location;
 
    #region DockableWindow
    PushButtonData pushButtonRegisterDockableWindow = new PushButtonData( "RegisterDockableWindow", "RegisterDockableWindow", path, "DockableDialog.RegisterDockableWindow" );
    pushButtonRegisterDockableWindow.LargeImage = GetImage( Resources.green.GetHbitmap() );
    pushButtonRegisterDockableWindow.AvailabilityClassName = "DockableDialog.AvailabilityNoOpenDocument";
    PushButtonData pushButtonShowDockableWindow = new PushButtonData( "Show DockableWindow", "Show DockableWindow", path, "DockableDialog.ShowDockableWindow" );
    pushButtonShowDockableWindow.LargeImage = GetImage( Resources.red.GetHbitmap() );
    PushButtonData pushButtonHideDockableWindow = new PushButtonData( "Hide DockableWindow", "Hide DockableWindow", path, "DockableDialog.HideDockableWindow" );
    pushButtonHideDockableWindow.LargeImage = GetImage( Resources.orange.GetHbitmap() );
    //IList<RibbonItem> ribbonpushButtonDockableWindow = AECPanelDebug.AddStackedItems(pushButtonRegisterDockableWindow, pushButtonShowDockableWindow, pushButtonHideDockableWindow);
 
    RibbonItem ri1 = AECPanelDebug.AddItem( pushButtonRegisterDockableWindow );
    RibbonItem ri2 = AECPanelDebug.AddItem( pushButtonShowDockableWindow );
    RibbonItem ri3 = AECPanelDebug.AddItem( pushButtonHideDockableWindow );
    #endregion
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown(
    UIControlledApplication a )
  {
    return Result.Succeeded;
  }
 
  private System.Windows.Media.Imaging.BitmapSource GetImage(
    IntPtr bm )
  {
    System.Windows.Media.Imaging.BitmapSource bmSource
      = System.Windows.Interop.Imaging.CreateBitmapSourceFromHBitmap(
        bm,
        IntPtr.Zero,
        System.Windows.Int32Rect.Empty,
        System.Windows.Media.Imaging.BitmapSizeOptions.FromEmptyOptions() );
 
    return bmSource;
  }
}
 
/// <summary>
/// You can only register a dockable dialog in "Zero doc state"
/// </summary>
public class AvailabilityNoOpenDocument
  : IExternalCommandAvailability
{
  public bool IsCommandAvailable(
    UIApplication a,
    CategorySet b )
  {
    if( a.ActiveUIDocument == null )
    {
      return true;
    }
    return false;
  }
}
 
/// <summary>
/// Register your dockable dialog
/// </summary>
[Transaction( TransactionMode.Manual )]
public class RegisterDockableWindow
  : IExternalCommand
{
  MainPage m_MyDockableWindow = null;
 
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneProviderData data
      = new DockablePaneProviderData();
 
    MainPage MainDockableWindow = new MainPage();
 
    m_MyDockableWindow = MainDockableWindow;
 
    //MainDockableWindow.SetupDockablePane(me);
 
    data.FrameworkElement = MainDockableWindow
      as System.Windows.FrameworkElement;
 
    data.InitialState = new DockablePaneState();
 
    data.InitialState.DockPosition
      = DockPosition.Tabbed;
 
    //DockablePaneId targetPane;
    //if (m_targetGuid == Guid.Empty)
    //    targetPane = null;
    //else targetPane = new DockablePaneId(m_targetGuid);
    //if (m_position == DockPosition.Tabbed)
 
    data.InitialState.TabBehind = DockablePanes
      .BuiltInDockablePanes.ProjectBrowser;
 
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    commandData.Application.RegisterDockablePane(
      dpid, "AEC Dockable Window", MainDockableWindow
      as IDockablePaneProvider );
 
    commandData.Application.ViewActivated
      += new EventHandler<ViewActivatedEventArgs>(
        Application_ViewActivated );
 
    return Result.Succeeded;
  }
 
  void Application_ViewActivated(
    object sender,
    ViewActivatedEventArgs e )
  {
    m_MyDockableWindow.lblProjectName.Content
      = e.Document.ProjectInformation.Name;
  }
}
 
/// <summary>
/// Show dockable dialog
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class ShowDockableWindow : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    DockablePane dp = commandData.Application
      .GetDockablePane( dpid );
 
    dp.Show();
 
    return Result.Succeeded;
  }
}
 
/// <summary>
/// Hide dockable dialog
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class HideDockableWindow : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    DockablePaneId dpid = new DockablePaneId(
      new Guid( "{D7C963CE-B7CA-426A-8D51-6E8254D21157}" ) );
 
    DockablePane dp = commandData.Application
      .GetDockablePane( dpid );
 
    dp.Hide();
    return Result.Succeeded;
  }
}

In case you overlooked any of the following aspects, here is a list of the functionality demonstrated in the relatively few lines of code above:

• Implementation of an external application and several external commands in the same assembly
• Creation and population of a custom ribbon tab
• Creation and population of a custom ribbon panel with command buttons
• Loading of button images from .NET assembly resources
• Implementation of a command availability class
• Static enabling a command in zero document state
• Dynamic toggling of command availability based on document state

Here is DockableDialog.zip containing the complete source code, Visual Studio solution and add-in manifest of this external application.

Many thanks to Håkan for this nice sample!

Addendum: Guy Robinson of redbolts.com adds to this and says:

I noticed the post on DockablePanes and Håkan's comment about finding the SDK sample confusing. I did too. I've been testing some UI ideas for a new app today and posted a basic version of something similar if interested.

I didn't want a register command on the ribbon and wanted more abstraction. For instance, I didn't want the Page inheriting IDockablePaneProvider.

Therefore, registration is in the external application and uses some extension methods.

It is not perfect; it would require use of the Win32 API to capture the dock hiding/showing state if hidden from the dock itself.

Anyway, anyone interested can have a look at my DockableUITest project on GitHub.

What's New in the Revit 2014 API

Here is one post that I prepared well for in advance, by publishing the previous 'What's New in the API' sections two months back:

• What's New in the Revit 2010 API
• What's New in the Revit 2011 API
• What's New in the Revit 2012 API
• What's New in the Revit 2013 API

The information provided here is extracted from the document 'Revit Platform API Changes and Additions.docx' provided with the Revit SDK. It is also included in the 'What's New' section in the Revit API help file RevitAPI.chm.

The reason for copying it here on-line as well is to ensure that the valuable information provided is picked up by web searches. More and more people, myself included, perform a web search straight away, first thing, before even looking at the API documentation.

For more detailed information on the pointers provided below, please refer to the complete API documentation and developer's guide.

For a short summary of the main highlights, please refer to the Revit 2014 API overview, which also points to the complete materials from the Revit 2014 DevDays presentations:

• Presentation
• Recording
• Sample code

This document consists of three main sections:

• Major changes and renovations
• Major enhancements to the Revit API
• Small enhancements & interface changes

I hope this proves useful to you and you find the new API features as useful and exciting as I do!

Major Changes and Renovations

Document APIs

Document.Save()

Several modifications have been made to the Document.Save() methods.

• The methods now return void instead of boolean.
• Failures are signaled with specified documented exceptions.
• The new property SaveOptions.Compact allows the caller to specify if the OS should eliminate all dead data from the file on disk.

Document.SaveAs()

Several modifications have been made to the Document.SaveAs() functions.

• The methods now return void instead of boolean.
• Failures are signaled with specified documented exceptions.
• The new property SaveAsOptions.MaximumBackups identifies the maximum number of backups to keep on disk.
• The new property SaveAsOptions.Compact allows the caller to specify if the OS should eliminate all dead data from the file on disk.
• The new property SaveAsOptions.WorksharingOptions offers options specific to workshared files:
• WorksharingSaveAsOptions.SaveAsCentral
• WorksharingSaveAsOptions.OpenWorksetsDefault
• WorksharingSaveAsOptions.ClearTransmitted
• The property SaveAsOptions.Rename has been obsoleted.  The property previously had no effect, use of SaveAs will always modify the document in memory.

In addition, a new version of SaveAs() taking a ModelPath and SaveAsOptions has been introduced.  This offers capabilities similar in behavior to SaveAs(string, SaveAsOptions).

OpenOptions

New options are available in this class:

• OpenOptions.Audit

This Boolean option specifies whether to expand all elements, to check for corruption.  Defaults to false.

• OpenOptions.AllowOpeningLocalByWrongUser

This boolean option specifies whether a local file is allowed to be opened ReadOnly by a user other than its owner.

• OpenOptions.GetOpenWorksetsConfiguration()
• OpenOptions.SetOpenWorksetsConfiguration()

These methods access the WorksetConfiguration.   This class specifies which user-created worksets should be opened/closed when the document is opened.  Once an instance of this class is created, it can be further modified by calling available methods in any order.  It is a specification of a setting for model open; the methods of this class just adjust the specification, and do not themselves open or close worksets.

Only user-created worksets can be specified to be opened or closed.  All system worksets are automatically open.  An open workset allows its elements can be expanded and displayed. For a closed workset, Revit tries to not expand its elements, and to that end, does not display them. This is intended to help with performance by reducing Revit's memory footprint.

An application can determine how to populate this class by looking at workset information from a closed document.  This is done by calling

• WorksharingUtil.GetUserWorksetInfo()

This method returns a collection of WorksetPreview classes containing the workset id, unique id, owner, name and whether or not the workset is default.

Application.OpenDocumentFile(ModelPath, OpenOptions)

This method has been reimplemented.  While the signature has not changed, there are new options available to be set in OpenOptions. 

Failures are now signaled with specific documented exceptions.

Application.OpenDocumentFile(String)

This method has been reimplemented.  While the signature has not changed, failures are now signaled with specific documented exceptions.

UIApplication.OpenAndActivateDocument(ModelPath, OpenOptionsForUI)

The signature and the implementation of this method has changed.

• The class OpenOptionsForUI has been removed.
• The new signature is (ModelPath, OpenOptions, Boolean detachAndPrompt). 

If you wish to let the user answer interactively the prompt of whether to preserve or discard worksets when opening the documented detached from central, set the following values:

• OpenOptions.DetachFromCentralOption = DoNotDetach
• Boolean argument "detachAndPrompt" = true.

Failures are now signaled with specific documented exceptions.

UIApplication.OpenAndActivateDocument(String)

This method has been reimplemented.  Failures are now signaled with specific documented exceptions.

FilteredElementCollector

Iteration and element deletion

When an element is deleted active iterations over the document (via FilteredElementCollector) are now stopped. A new InvalidOperationException is thrown.  The iterator cannot proceed due to changes made to the Element table in Revit's database (typically, this can be the result of an Element deletion). This affects the use of FilteredElementIterator, FilteredElementIdIterator, and foreach loops over a FilteredElementCollector.

The exception can be triggered by direct calls to Document.Delete(), but also by other Revit APIs which change the document resulting in an element being deleted. In general it is best not to make any changes to the document while an iterator is running over the document.

The simplest workaround to fix existing code which encounters this error is to use one of:

• FilteredElementCollector.ToElements()
• FilteredElementCollector.ToElementIds()
• FilteredElementCollector.ToList<Type>() (LINQ method)

to get a standalone collection, then iterate that collection.  Even if elements are deleted from the document, the iteration of the already fetched collection can proceed.

Geometry APIs

Curve creation

New curve creation methods have been added as statics on the associated curve type:

• Curve.CreateTransformed()
• Line.CreateBound()
• Line.CreateUnbound()
• Arc.Create()
• Ellipse.Create()
• NurbSpline.Create()
• HermiteSpline.Create()

The older curve creation properties and methods are now obsolete:

• Curve.Transformed
• Line.Bound
• Line.Unbound
• Autodesk.Revit.Creation.Application.NewLine()
• Autodesk.Revit.Creation.Application.NewLineBound()
• Autodesk.Revit.Creation.Application.NewLineUnbound()
• Autodesk.Revit.Creation.Application.NewArc()
• Autodesk.Revit.Creation.Application.NewEllipse()
• Autodesk.Revit.Creation.Application.NewNurbSpline()
• Autodesk.Revit.Creation.Application.NewHermiteSpline()

Both the old and new curve creation routines are updated to consistently prevent creation of curves smaller than Revit's tolerance. This value is now exposed via:

• Application.ShortCurveTolerance

Some other adjustments have been made to the validation on specific curve creation routines, consult the documentation for details.

Curve utilities

The new methods:

• GetEndPoint()
• GetEndParameter()
• GetEndPointReference()

replace the indexed property utilities on Curve:

• EndPoint
• EndParameter
• EndPointReference

The setter for EndParameter is deprecated and code should be adjusted to call MakeBound(double, double) instead.

Edge utilities

The new methods:

• Edge.GetFace()
• Edge.GetEndPointReference()

replace:

• Edge.Face (property)
• Edge.EndPointReference (property)

Transform initialization

The new methods:

• Transform.CreateTranslation()
• Transform.CreateRotation()
• Transform.CreateRotationAtPoint()
• Transform.CreateReflection()

replace:

• Transform.Translation (property)
• Transform.Rotation (property)
• Transform.Reflection (property)

SketchPlane creation

The SketchPlane creation methods of Autodesk.Revit.Creation.ItemFactoryBase have been replaced.

• SketchPlane.Create(Document, Plane) replaces ItemFactoryBase.NewSketchPlane(Plane)
• SketchPlane.Create(Document, Reference) replaces ItemFactoryBase.NewSketchPlane(Reference)
• Either method may be appropriate to replace calls to ItemFactoryBase.NewSketchPlane(PlanarFace), depending on whether the goal is a sketch plane tied to a Revit geometric reference, or a sketch plane fixed in space to a given plane.

A new SketchPlane creation has been added:

• SketchPlane.Create(ElementId)

This creates a SketchPlane from a grid, reference plane, or level.

SketchPlane also now has two more methods to get related properties of the SketchPlane element.

• SketchPlane.GetPlane() Returns the corresponding Plane.
• SketchPlane.GetPlaneReference()  Returns a reference to this element as a plane.

BeamSystem creation

The BeamSystem creation methods of Autodesk.Revit.Creation.Document have been replaced:

• BeamSystem.Create(Document, IList<Curve>, SketchPlane, int) replaces Document.NewBeamSystem(CurveArray, SketchPlane)
• BeamSystem.Create(Document, IList<Curve>, SketchPlane, XYZ, bool) replaces Document.NewBeamSystem(CurveArray, SketchPlane, XYZ, bool)
• BeamSystem.Create(Document, IList<Curve>, Level, int, bool) replaces Document.NewBeamSystem(CurveArray, Level)
• BeamSystem.Create(Document, IList<Curve>, Level, XYZ, bool) replaces Document.NewBeamSystem(CurveArray, Level, XYZ, bool)

Truss creation

The Truss creation method of Autodesk.Revit.Creation.Document have been replaced.

• Truss.Create(Document, ElementId, ElementId, Curve) replaces Document.NewTruss(TrussType, SketchPlane, Curve)

Family Symbol API

Family symbols that are not used in the document are now inactive until they are used.  A symbol's geometry will be empty and should not be accessed until it is active.  To test if a symbol is active, use

• FamilySymbol.IsActive()

To activate an inactive family symbol, use

• FamilySymbol.Activate()

Units API

The API for Units in Revit has been expanded and changed. The methods

• Document.GetUnits()
• Document.SetUnits()

allow interaction with the units of a document.  The Units class provides access to data such as

• DecimalSymbol
• DigitGroupingAmount
• DigitGroupingSymbol
• FormatOptions

The FormatOptions class provides access to data including:

• Rounding
• Accuracy
• DisplayUnits
• SuppressLeadingZeros
• SuppressTrailingZeros
• SuppressSpaces

LabelUtils.GetLabelFor() has been enhanced so that it can now return the user-visible name for a UnitSymbolType.

Unit Formatting and Parsing

The methods:

• UnitFormatUtils.FormatValueToString()
• UnitFormatUtils.TryParse()

provide the ability to format a value into a string based on formatting options and to parse a formatted string (including units) into a value if possible.

Unit Conversion

The new class UnitUtils contains methods to convert between unit types:

• UnitUtils.Convert() – Converts a value from one unit type to another, such as square feet to square meters.
• UnitUtils.ConvertFromInternalUnits() – Converts a value from Revit's internal unit type.
• UnitUtils.ConvertToInternalUnits() – Converts a value to Revit's internal unit type.

View API changes

Viewport.Create behavioral change

The method

• Viewport.Create()

previously did not consistently align the center of the Viewport with the point supplied.  This has been changed, and now the center will be aligned with the input point.  This should allow easier alignment of multiple viewports on the same sheet.

View.ViewName obsolete

The property

• View.ViewName

is now obsolete.  View.Name can be used.

View.SetVisibility()

The name of this method has now been correctly capitalized.

ViewSchedule changes

ViewSchedule is now a child of TableView.   All previously existing ViewSchedule API is still valid, but TableView also brings in a set of APIs related to:

• Table sections (header and body)
• Table formatting
• The contents of individual table cells

There are methods on TableView (and its constituent TableData and TableSectionData class) that are useful for Electrical Panel Schedules and some varieties of specialized schedules but forbidden for use with standard Revit tabular schedules generated from Revit content (e.g. InsertRow(), RemoveRow()).   Use of these functions on standard Revit schedules will result in an exception.

Some new members were introduced on schedule related classes:

• ScheduleField.SetStyle()
• ScheduleField.GetStyle()
• ScheduleField.IsOverridden
• ScheduleField.ResetOverrides()
• ScheduleField.GetFormatOptions()
• ScheduleField.SetFormatOptions()

relate to the style and formatting applied to schedule columns, and:

• ScheduleField.IsCalculatedField
• ScheduleField.IsCombinedParameterField
• ScheduleField.HasSchedulableField

relate to information about the type of a field.

The new members:

• ViewSchedule.GetFontId()
• ViewSchedule.AddFontId()

provide access to fonts stored in the table and applied to cells.

The new members:

• ViewSchedule.GroupHeaders()
• ViewSchedule.UngroupHeaders()
• ViewSchedule.CanGroupHeaders()
• ViewSchedule.CanUngroupHeaders()

affect header grouping in the schedule.

The new method:

• ViewSchedule.GetTableData()

returns the object which provides access to the sections of the table.

Materials API changes

Applying visual materials

The method

• Material.SetRenderAppearance()

has been deprecated.  The Render appearance properties should be set via the related ApperanceAssetElement. 

Use the new property:

• Material.AppearanceAssetId

to assign the element to the material.

AppearanceAssetElements can be found via element filtering – they expose the following members:

• AppearanceAssetElement.Create() – creates a new asset element for a given rendering Asset and name.
• AppearanceAssetElement.GetAppearanceAssetElementByName() – gets an asset element handle given the name.
• AppearanceAssetElement.SetRenderingAsset() – Sets the rendering Asset to the element

AssetProperty changes

AssetProperty no longer inherits from APIObject. 

New subclasses of AssetProperty are exposed:

• AssetPropertyList – a property consisting of a list of AssetProperty members. 
• AssetPropertyFloatArray – a property consisting of an array of float values.
• AssetPropertyUInt64 – a property of UInt64 value.
• AssetPropertyInt64 – a property of Int64 value.

Some of the return values of AssetProperty.GetTypeName() have been changed as shown here listing input argument, old return and new return:

• APT_Double – "Double1" – "Double"
• APT_DoubleArray2d – "Double2" – "DoubleArray2d"
• APT_DoubleArray3d – "Double3" – "DoubleArray3d"
• APT_DoubleArray4d – "Double4" – "DoubleArray4d"
• APT_Asset – "RenderingAsset" – "Asset"
• APT_FloatArray – "Float3" – "FloatArray"

UI API changes

External commands now supported from Project Browser as active view

API commands and macros are now enabled when the Revit active view is the Project Browser.  

• If there are actively selected elements in the Project Browser, these will be returned from UIDocument.Selection
• However, add-ins cannot prompt for interactive selection when the Project Browser is the active view.
• The enumerated type ViewType now has separate entries for ProjectBrowser and SystemBrowser to allow applications to deal with situations where the Project Browser is active.  These view types used to be returned as ViewType.Internal, so code which keys of off ViewType.Internal may need to be updated to also deal with these new types.

Note that API commands are still disabled when the active view is the MEP system browser. 

Beam and Brace Parameters changes

Revit 2014 includes several changes to control the position of structural framing members like beams and braces.  These changes do not affect the API members but can be accessed via parameters. 

Start/End Extension & Cutback

There are new extension and cutback parameters assigned to Beam and Brace elements.

• BuiltInParameter.START_EXTENSION
• BuiltInParameter.END_EXTENSION
• BuiltInParameter.START_JOIN_CUTBACK
• BuiltInParameter.END_JOIN_CUTBACK

Note: In some families “Start Extension” and “End Extension” family parameters may also exist but it is recommended to use instead new the new built-in parameters.

These parameters work as follows:

• If the Beam or Brace element end doesn’t belong to a join Revit uses the new parameters “Start Extension" or "End Extension”.  Assigning positive values to these parameters lengthens the element).
• If the Beam or Brace element belongs to a join Revit uses the parameters “Start Join Cutback" or "End Join Cutback”.  Assigning positive values to these parameters shortens the element).

In certain cases it may be difficult to detect if an element node belongs to join or not. Therefore, it may be advisable to set both groups of parameters via the API. With both groups of parameters will be set for element, Revit automatically detects which should be applied to the structural element.

Justifications

There are new justification parameters assigned to Beam and Brace elements. The new set of parameters provides more options to manipulate the physical element in relation to its analytical curve.

Here is a list of parameters and the permitted values for each:

• BuiltInParameter.YZ_JUSTIFICATION – YZJustificationOption.Uniform, YZJustificationOption.Independent
• BuiltInParameter.Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.Y_OFFSET_VALUE – double
• BuiltInParameter.Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.Z_OFFSET_VALUE – double
• BuiltInParameter.START_Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.START_Y_OFFSET_VALUE – double
• BuiltInParameter.START_Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.START_Z_OFFSET_VALUE – double
• BuiltInParameter.END_Y_JUSTIFICATION – YJustification.Left, YJustification.Center, YJustification.Origin, YJustification.Right
• BuiltInParameter.END_Y_OFFSET_VALUE – double
• BuiltInParameter.END_Z_JUSTIFICATION – ZJustification.Top, ZJustification.Center, ZJustification.Origin, ZJustification.Bottom
• BuiltInParameter.END_Z_OFFSET_VALUE – double

Previously only Beam elements had any justification parameters.

In Revit 2014, Beams as well as Braces share this set of built-in justification parameters.

The following list shows a mapping from old deprecated justification parameters to new ones:

• BEAM_H_JUSTIFICATION – Y_JUSTIFICATION
• BEAM_V_JUSTIFICATION – Z_JUSTIFICATION
• BEAM_V_JUSTIFICATION_OTHER_VALUE (valid only for Other value set to BEAM_V_JUSTIFICATION) – Z_OFFSET_VALUE (valid for all Z_JUSTIFICATION values)

Old beam parameters can still be used.  When set, they will be used to recalculate the new parameters.  It is strongly recommended to use new justification parameters instead of old ones, because in some cases the old parameters may be not sufficient to correctly describe the element position (for example, when justification is set independently on either end of the member).

Divided surface changes

Divided Surface API

The class DividedSurfaceData and the associated method Element.GetDividedSurfaceData() have been replaced.  The new methods to access DividedSurfaces applied to elements are:

• DividedSurface.GetReferencesWithDividedSurface()
• DividedSurface.GetDividedSurfaceForReference()

The method:

• Autodesk.Revit.Creation.Document.NewDividedSurface()

has been replaced by:

• DividedSurface.Create()

Point clouds

Revit 2014 includes a new point cloud engine.  This new engine supports .rcp and .rcs file formats.  The introduction of this new engine has led to several changes in the client API around Point Cloud elements.

PointCloudType.Create()

The method

• PointCloudType.Create()

no longer supports input of .pcg files to directly create a new PointCloudType.  .pcg files can be indexed to create matching .rcs files, but this does not happen automatically when using this method.

This method does support creation of PointCloudTypes from .rcp or .rcs files, or from custom formats supplied by the Point Cloud Engine API.

PointCloudInstance.GetPoints()

The method

• PointCloudInstance.GetPoints(PointCloudFilter filter, int numPoints)

has been deprecated and replaced by

• PointCloudInstance.GetPoints(PointCloudFilter filter, double averageDistance, int numPoints)

The new averageDistance argument is the desired average distance between "adjacent" cloud points (in Revit units of length).  The smaller the averageDistance the larger number of points will be returned up to the numPoints limit.  Specifying this parameter makes the actual number of points returned for a given filter independent of the density of coverage produced by the scanner. This average distance parameter is only used when extracting points from .rcs or .rcp point clouds, and is not used when extracting from .pcg point clouds or custom point clouds from the Point Cloud Engine API.

Point cloud overrides

The classes

• PointCloudOverrides
• PointCloudOverrideSettings
• PointCloudColorSettings

allow read and write access to point cloud override settings assigned to a given view.  Overrides can be applied to an entire point cloud instance, or to specific scans within that instance. Options for the overrides include making the cloud non-visible, setting it to a fixed color, or to color gradients based on elevation, normals, or intensity.

The property

• PointCloudInstance.SupportsOverrides

identifies point clouds which support override settings (clouds which are based on .rcp or .rcs files).

Point cloud scans

The method

• PointCloudInstance.GetScans()

returns a list of scans contained within the .rcp point cloud.  Scan names can be used to set visibility and fixed color overrides independently for each scan in the PointCloudInstance.

IFC API changes

IFC export now External Service

The capability to override IFC export is now managed as an External Service.  As such, the explicit interfaces in ExporterIFCRegistry are no longer needed and have been marked obsolete.  It is now possible to register more than one external IFC export implementation in the same session, and manage the active implementation using the methods of the SingleServerService wrapper to IFC export.

IFC APIs moved to new assembly

Most IFC API classes have been moved from RevitAPI.dll to a new assembly: RevitAPIIFC.dll. The classes moved include all members of the Autodesk.Revit.DB.IFC namespace which enable development of a custom IFC exporter.

Any Add-In using any of the migrated APIs needs to reference the new DLL and rebuild to work in Revit 2014.

Note that the APIs to invoke an IFC export and import:

• Document.Export(String, String, IFCExportOptions)
• Application.OpenIFCDocument(String)

and the related options class have not moved. Applications which export or import IFC files but do not provide custom implementations do not need to make changes.

PrintParameters

The property HideUnreferencedViewTages was renamed to HideUnreferencedViewTags. 

Obsolete API Removal

API classes and methods previously marked Obsolete in Revit 2013 or earlier have been removed from the API.

Classes removed

• CurtainCellSetIterator and CurtainCellSet – Use generic .NET collection classes instead.
• PipeMaterialType – replaced by Material
• Batch creation argument class types – batch creation is not needed with changes to Revit API regeneration
• ProfiledWallCreationData
• RectangularWallCreationData
• RoomCreationData
• TextNoteCreationData
• Subclasses of ConnectorElement have been removed, access these elements through the parent class
• ElectricalConnector
• ElectricalConnector.SystemType – query the parameter RBS_ELEC_CIRCUIT_TYPE on ConnectorElement and cast to ElectricalSystemType
• DuctConnector
• DuctConnector.LinkedConnector – replaced by ConnectorElement.GetLinkedConnectorElement() and ConnectorElement.SetLinkedConnectorElement()
• DuctConnector.SystemType – query the parameter RBS_DUCT_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM on ConnectorElement and cast to DuctSystemType
• PipeConnector
• PipeConnector.LinkedConnector replaced by ConnectorElement.GetLinkedConnectorElement() and ConnectorElement.SetLinkedConnectorElement()
• PipeConnector.SystemType – query the parameter RBS_PIPE_CONNECTOR_SYSTEM_CLASSIFICATION_PARAM on ConnectorElement and cast to PipeSystemType

Methods and Properties removed

Autodesk.Revit.Creation namespace

Application

• NewMaterialSet() – replaced by .net Generic collection classes
• NewElementArray() – replaced by .net Generic collection classes

Document

• NewAnnotationSymbol(XYZ ,AnnotationSymbolType ,View) – replaced by NewFamilyInstance(XYZ, FamilySymbol, View)
• NewAreaViewPlan(String,Level,AreaElemType) – replaced by ViewPlan.CreateAreaPlan()
• NewCurtainSystem(ReferenceArray,CurtainSystemType) – replaced by NewCurtainSystem2(ReferenceArray, CurtainSystemType)
• NewElectricalSystem(ElementSet,ElectricalSystemType) – replaced by NewElectricalSystem(ICollection<ElementId>, ElectricalSystemType)
• NewFamilyInstances(List<FamilyInstanceCreationData>) – replaced by NewFamilyInstances2(List<FamilyInstanceCreationData>)
• NewGroup(ElementSet) – replaced by NewGroup(System.Collections.Generic.ICollection<Autodesk.Revit.DB.ElementId>)
• NewRooms(Phase, Int32) – replaced by NewRooms2(Phase, Int32)
• NewRooms(Level,Phase) – replaced by NewRooms2(Level, Phase)
• NewRooms(Level) – replaced by NewRooms2(Level)
• NewRooms(List<RoomCreationData>) – there is no single equivalent that creates multiple rooms, this is not needed with Revit API control over regeneration
• NewSpaces(Phase,Int32) – replaced by NewSpaces2(Phase, Int32)
• NewSpaces(Level,Phase,View) – replaced by NewSpaces2(Level, Phase, View)
• NewTextNotes(List<TextNoteCreationData>) – replaced by NewTextNote()
• NewViewPlan(String,Level,ViewPlanType) – replaced by ViewPlan.Create(Document, ElementId, ElementId)
• NewView3D(XYZ) – replaced by View3D.CreateIsometric(Document, ElementId)
• NewViewSection(BoundingBoxXYZ) – replaced by ViewSection.CreateDetail()
• All Wall creation methods replaced by equivalent Wall.Create() methods:
• NewWall(CurveArray,WallType,Level,Boolean,XYZ)
• NewWall(CurveArray,WallType,Level,Boolean)
• NewWall(CurveArray,Boolean)
• NewWall(Curve,WallType,Level,Double,Double,Boolean,Boolean)
• NewWall(Curve,Level,Boolean)
• NewWalls(List<ProfiledWallCreationData> dataList) – there is no single equivalent that creates multiple walls, this is not needed with Revit API control over regeneration
• NewWalls(List<RectangularWallCreationData> dataList) – there is no single equivalent that creates multiple walls, this is not needed with Revit API control over regeneration

FamilyItemFactory

• NewDuctConnector(Reference,DuctSystemType) – replaced by ConnectorElement.CreateDuctConnector()
• NewPipeConnector(Reference,PipeSystemType) – replaced by ConnectorElement.CreatePipeConnector()
• NewElectricalConnector(Reference,ElectricalSystemType) – replaced by ConnectorElement.CreateElectricalConnector()

Autodesk.Revit.DB namespace

BaseArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

CurtainGrid

• UnlockedMullions – replaced by GetUnlockedMullionIds()
• Mullions – replaced by GetMullionIds()
• Cells – replaced by GetCurtainCells()
• UnlockedPanels – replaced by GetUnlockedPanelIds()
• Panels – replaced by GetPanelIds()
• VGridLines – replaced by GetVGridLineIds()
• UGridLines – replaced by GetUGridLineIds()

CurveElement

• LineStyles – replaced by GetLineStyleIds()

Document

• Delete(ElementSet elements) – replaced by Delete(System.Collections.Generic.ICollection<Autodesk.Revit.DB.ElementId> elementIds)
• WorksharingCentralFilename – replaced by ModelPathUtils.ConvertModelPathToUserVisiblePath(Document.GetWorksharingCentralModelPath())
• PrintSettings – replaced by GetPrintSettingIds()
• Element/get_Element – replaced by GetElement method

Element

• PhaseDemolished – replaced by DemolishedPhaseId
• PhaseCreated – replaced by CreatedPhaseId

FamilyInstance

• GetCopings() – replaced by GetCopingIds()
• SetCopings(ElementSet) – replaced by SetCopingIds(ICollection<ElementId> cutters)
• SubComponents – replaced by GetSubComponentIds()

Floor

• SpanDirectionSymbols – replaced by GetSpanDirectionSymbolIds()

GeometryElement

• Objects – replaced by GetEnumerator()

Group

• Ungroup() – replaced by UngroupMembers()
• Members – replaced by GetMemberIds()

LinearArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

Material

• GetMaterialAspectPropertySet(MaterialAspect) – replaced by GetStructuralAssetId() and GetThermalAssetId()
• SetMaterialAspect(MaterialAspect,ElementId,Boolean) – replaced by SetStructuralAssetId() and SetThermalAssetId()
• SetMaterialAspectToIndependent(MaterialAspect) – replaced by SetStructuralAssetId() and SetThermalAssetId()

MEPSystem

• Remove(ElementSet) – replaced by Remove(ICollection<ElementId>)

Part

• ParentDividedElementId – no replacement, concept is removed from Revit
• OriginalDividedElementId – no replacement, concept is removed from Revit
• GetDividedParents() – no replacement, concept is removed from Revit

PartMaker

• IsElementDivided(ElementId elemId) – replaced by IsSourceElement(ElementId)
• GetDividedElementIds() – replaced by GetSourceElementIds()
• SetDividedElementIds(ICollection<ElementId>) – replaced by SetSourceElementIds(ICollection<ElementId>)

PartUtils

• AreElementsValidForDivide(Document, ICollection<ElementId>) – replaced by ArePartsValidForDivide(Document, ICollection<ElementId>)
• AreElementsValidIntersectingReferences(Document, ICollection<ElementId>) – replaced by PartMakerMethodToDivideVolumes.AreElementsValidIntersectingReferences(Document, ICollection<ElementId>)
• IsValidSketchPlane(Document, ElementId) – replaced by PartMakerMethodToDivideVolumes.IsValidSketchPlane(Document, ElementId)
• SetOffsetForIntersectingReference() – replaced by PartMakerMethodToDivideVolumes.SetOffsetForIntersectingReference()
• GetOffsetForIntersectingReference() – replaced by PartMakerMethodToDivideVolumes.GetOffsetForIntersectingReference()
• PartMakerUsesReference() – replaced by PartMakerMethodToDivideVolumes.PartMakerUsesReference()
• IsMaxDivisionDepthReached(Document, ElementId) – no replacement, concept is removed from Revit
• GetDividedParents(Part) – no replacement, concept is removed from Revit
• PlanTopology
• Rooms – replaced by GetRoomIds()

PropertySetElement

• Create(Document, MaterialAspect) – replaced by Create(Document, StructuralAsset)

RadialArray

• CopyMembers – replaced by GetCopiedMemberIds()
• OrigMembers – replaced by GetOriginalMemberIds()

SpatialFieldManager

• UpdateSpatialFieldPrimitive(Int32,FieldDomainPoints,FieldValues) – replaced by UpdateSpatialFieldPrimitive(Int32, FieldDomainPoints, FieldValues, Int32)
• SetUnits(IList<string>, IList<double>) – replaced by AnalysisResultSchema.SetUnits() and SetResultSchema()

View

• ApplyTemplate(View viewTemplate) – replaced by ViewTemplateId/ApplyViewTemplateParameters(View viewTemplate)
• Hide(ElementSet elemSet) – replaced by HideElements(System::Collections::Generic::ICollection<Autodesk::Revit::DB::ElementId^>^ elementIdSet)
• Unhide(ElementSet elemSet) – replaced by UnhideElements(System::Collections::Generic::ICollection<Autodesk::Revit::DB::ElementId^>^ elementIdSet)

View3D

• EyePosition – replaced by ViewOrientation3D.EyePosition/View.Origin
• ViewSheet
• AddView(View,UV) – replaced by Viewport.Create(Document, ElementId, ElementId, XYZ)

Autodesk.Revit.DB.Plumbing namespace

PipeType

• Roughness – replaced by Segment.Roughness
• Material – replaced by PipeSegment.MaterialId

Autodesk.Revit.DB.Structure namespace

AnalyticalModel

• CanDisable() – no replacement, concept removed from Revit
• IsValidAnalyticalProjectionType(AnalyticalDirection,AnalyticalProjectionType) – replaced by IsValidProjectionType(AnalyticalElementSelector, AnalyticalDirection, AnalyticalProjectionType)

AreaReinforcement

• NumBarDescriptions – replaced by GetRebarInSystemIds()
• BarDescription – replaced GetRebarInSystemIds()
• Curves – replaced by GetCurveElementIds()

BeamSystem

• GetAllBeams() – replaced by GetBeamIds()

PathReinforcement

• BarDescription – replaced by GetRebarInSystemIds()
• Curves – replaced by GetCurveElementIds()

Rebar

• GetCenterlineCurves(Boolean) – replaced by GetCenterlineCurves(Boolean,Boolean,Boolean)
• DistributionPath – replaced by GetDistributionPath()
• RebarShape – replaced by RebarShapeId
• Host – replaced by Rebar.GetHostId() and SetHostId(Document, ElementId)
• BarType – replaced by Element.GetTypeId() and Element.ChangeTypeId(ElementId)

Major Enhancements to the Revit API

Worksharing API enhancements

Reload Latest

The method:

• Document.ReloadLatest()

Fetches changes from central (due to one or more synchronizations with central and merges them into the current session. After this call finishes, use

• Document.HasAllChangesFromCentral()

to confirm that there were no Synchronizations with Central performed during execution of ReloadLatest.

Synchronize with Central

The method:

• Document.SynchronizeWithCentral()

performs a reload latest until the model in the current session is up to date and then saves changes back to central.  A save to central is performed even if no changes were made.

Element ownership

The following methods affect element and workset ownership:

• WorksharingUtils.CheckoutElements – Obtains ownership for the current user of as many specified elements as possible.
• WorksharingUtils.CheckoutWorksets – Obtains ownership for the current user of as many specified worksets as possible.
• WorksharingUtils.RelinquishOwnership – Relinquishes ownership by the current user of as many specified elements and worksets as possible, and grants element ownership requested by other users on a first come, first served basis.

Create new local

The new method:

• WorksharingUtil.CreateNewLocal()

takes a path to a central model and copies the model into a new local file for the current user.

Enable Worksharing

The new method Document.EnableWorksharing will enable worksharing in a project.

Enhancements to interactions with links

Several improvements have been made to increase API functionality when working with RVT links.

Identifying links

The property:

• Document.IsLinked

identifies if a document is in session because it is a linked Revit file.

Obtaining linked documents

The method:

• RevitLinkInstance.GetLinkedDocument()

gets the document that corresponds to an Revit Link instance.

Link creation

Two functions have been added to RevitLinkOptions, used to specify options for RevitLinkType.Create. 

• RevitLinkOptions.GetWorksetConfiguration()
• RevitLinkOptions.SetWorksetConfiguration()

This allows the user to specify which worksets should be opened when creating and loading a new Revit link.

Link load and unload

The methods

• RevitLinkType.Load()
• RevitLinkType.LoadFrom()
• RevitLinkType.Unload()

allow a link to be loaded or unloaded, or to be loaded from a new location.   These methods regenerate the document.  The document's Undo history will be cleared by these methods.  As a result, this function and others executed before it cannot be undone.  All transaction phases (e.g. transactions, transaction groups and sub-transactions) that were explicitly started must be finished prior to calling this method.

Link shared coordinates

The methods:

• RevitLinkType.SavePositions()
• RevitLinkType.HasSharedCoordinatesChanges()

support save of shared coordinates changes back to the linked document. While this operation does not clear the document's undo history, you will not be able to undo this specific action, since it saves the link's shared coordinates changes to disk.

Link path type

The property:

• RevitLinkType.PathType

allows read and modification of the path type associated with a link. 

Conversion of geometric references

The new APIs:

• Reference.LinkedElementId
• Reference.CreateLinkReference(RevitLinkInstance)
• Reference.CreateReferenceInLink()

allow conversion between Reference objects which reference only the contents of the link and Reference objects which reference the host. This allows an application, for example, to look at the geometry in the link, find the needed face, and convert the reference to that face into a reference in the host suitable for use to place a face-based instance. Also, they would allow you to obtain a reference in the host (e.g. from a dimension or family) and convert it to a reference in the link, suitable for use in Element.GetGeometryObjectFromReference().

Room tag creation from linked rooms

The new method:

• NewRoomTag(LinkElementId roomId, UV point, ElementId viewId)

can create room tags in Revit Links.

Picking in links

PickObject() and PickObjects() now allow selection of elements in RVT Links.

Views & Display

Graphic Display options

These new members expose read and write of graphic display options:

• View.GetBackground()
• View.SetBackground()
• View.ShadowIntensity
• View.SunlightIntensity
• View.SurfaceTransparency
• View.ShowEdges
• View.ShowSilhouettes
• View.SilhouetteLineStyleId

Category classes override

Display of category classes may be overridden by the user.  The new properties:

• View.AreModelCategoriesHidden
• View.AreAnnotationCategoriesHidden
• View.AreAnalyticalModelCategoriesHidden
• View.AreImportCategoriesHidden

allow an application to determine if a class of categories has been completely hidden.  Note that Category.Visible[View] and View.GetVisibility(Category) does not look to the category classes when it returns the individual visibility status.

Category override

Display of categories can be overridden. This can be done with the new class OverrideGraphicSettings and the new View methods:

• SetCategoryOverrides
• GetCategoryOverrides
• IsOverrideValidForCategory
• IsCategoryOverridable

Element Override

Display of elements can be overridden with the new methods:

• View.GetElementOverrides
• View.SetElementOverrides.

View Filters

A new set of methods on the View class allow getting, setting, adding, and removing filters. Filters can be created using the ParameterFilterElement class and its Create method which existed in previous versions of the Revit API.

Non-rectangular crop region

Views can now be assigned a crop region which is non-rectangular.  The new View members:

• View.GetCropRegionShapeManager()
• View.GetCropRegionShapeManagerForReferenceCallout()
• View.GetReferenceCallouts()

provide access to a ViewCropRegionShapeManager for the view or for a displayed reference callout.

This class allows access and modification of the crop region shape:

• ViewCropRegionShapeManager.GetCropRegionShape()
• ViewCropRegionShapeManager.SetCropRegionShape()
• ViewCropRegionShapeManager.IsCropRegionShapeValid()
• ViewCropRegionShapeManager.RemoveCropRegionShape()
• ViewCropRegionShapeManager.ShapeSet
• ViewCropRegionShapeManager.Valid

The properties:

• View.CropBoxActive
• View.CropBoxVisible

also apply to non-rectangular crop regions which may be assigned to a given view.

Viewport

The new property

• Viewport.Rotation

controls the rotation of the viewport on the sheet.

The new method

• Viewport.MoveCenterTo() 

moves the viewport so that the center of the box outline (excluding the viewport label) is at a given point.

The new method

• Viewport.GetBoxCenter()

returns the center of the outline of the viewport on the sheet, excluding the viewport label.

Exploded Views

The new DisplacementElement class can be used to cause elements to appear displaced from their actual location to create views such as this one where the roof has been moved in the positive Z direction. The DisplacementPath class creates an annotation that depicts the movement of the element from its actual location to its displaced location.

Revisions on sheets

The new methods:

• ViewSheet.GetAllProjectRevisionIds()
• ViewSheet.GetAdditionalProjectRevisionIds()
• ViewSheet.SetAdditionalProjectRevisionIds()

provide access to the ids of project revision elements associated to a particular sheet.  GetAllProjectRevisionIds() returns project revisions ordered from lowest to highest by project revision sequence number.  The results include revisions associated to a revision cloud visible on the sheet and revisions that have been additionally included using the Revisions On Sheet parameter.   GetAdditionalProjectRevisionIds() and SetAdditionalProjectRevisionIds() access specifically the additional revisions added using the Revisions On Sheet parameter.

Note that there is no special class for project revision elements, but that they can be accessed as Elements by filtering on category BuiltInCategory.OST_Revisions.

User interface customization

UIView

Zoom operations

The new methods:

• UIView.ZoomToFit()
• UIView.ZoomSheetSize()
• UIView.Zoom(double zoomFactor)

provide shortcuts to quickly adjust the zoom of the graphical view window.

Close view

The new method:

• UIView.Close()

closes a visible view window. Note that the last open view for a given document cannot be closed by this method.

PreviewControl

The new property:

• PreviewControl.UIView

returns a UIView handle to the preview view. This allows an application to manipulate the zoom and pan settings of the preview view.

The new property:

• PreviewControl.ScrollbarVisibility

accesses the visibility setting for the preview view scrollbars.

Command API

Command event

The event

• AddInCommand.BeforeExecuted

occurs before the command associated with an AddInCommandBinding executes.  This event is read-only, an application can react to this event but cannot make changes to documents, or affect the invocation of the command in any way.

Command posting

The method

• UIApplication.PostCommand()

posts a command to Revit.  Revit will invoke it when control returns from the current API context.   Only certain commands can be posted using this method:

1. Commands listed in the Autodesk.Revit.UI.PostableCommand enumerated type
2. External commands created by any add-in

This restriction prevents posting of contextual commands (because Revit's command framework cannot directly access the accessibility of some contextual commands).

Note that only one command may be posted to Revit at a given time.  If a second command is posted from any API application, the method throws an InvalidOperationException.

The command must be accessible to be executed.  This is determined only at the point where Revit returns from the API context, and therefore a failure to execute the command because the command is not currently accessible will not be reported directly back to the application that posted the command.

To use this API, the application must obtain a RevitCommandId handle for the command.  This can be done using either

• RevitAddInCommand.LookupCommandId(String)
• RevitAddInCommand.LookupPostableCommandId(PostableCommand)

The method

• UIApplication.CanPostCommand

identifies if the given command can ever be posted (that is, it is a member of PostableCommand or an external command).  It does not identify the command can be posted at the given timeframe (that is, it will not attempt to determine if the command is currently accessible). 

Dockable Dialog Panes

Revit now allows addins to register WPF dialogs to dock into the top, left, right, and bottom of the main Revit window, as well as to be added as a tab to an existing system pane, such as the project browser.  Dialogs can be registered with UIApplication.RegisterDockablePane and a user-implementation of the IDockablePaneProvider interface.  Dockable panes can later be retrieved, shown, and hidden through UIApplication.GetDockablePane() and DockablePane.Show() and Hide().

Dimensions & annotations API

Multi-reference annotations for rebar

Revit now supports annotations pointing to more than one reference, consisting of a dimension and associated tag These annotations can be used to label and dimension Rebar elements, and are labeled in the user interface as “Multi-rebar annotations.”

The API exposes this through:

• MultiReferenceAnnotation – the annotation object instance. This class includes a reference to the associated dimension and tag element.
• MultiReferenceAnnotationType – the annotation type.  The type specifies the tag and dimension types to be used in the multi-reference annotation, as well as associated display settings.
• MultiReferenceAnnotationOptions – an options class used to create a new MultiReferenceAnnotation, including specification of the associated elements and options for the dimension and tag placement.
• IndependentTag.MultiReferenceAnnotationId  – returns the ElementId of the MultiReferenceAnnotation that owns a tag.
• Dimension.MultiReferenceAnnotationId – returns the ElementId of the MultiReferenceAnnotation that owns a dimension.

Dimension alternate units

New properties of DimensionStyle provide access to alternate units settings:

• DimensionStyle.AlternateUnits
• DimensionStyle.GetAlternateUnitsFormatOptions()
• DimensionStyle.SetAlternateUnitsFormatOptions()
• DimensionStyle.AlternateUnitsPrefix
• DimensionStyle.AlternateUnitsSuffix

Dimension unit type

The property:

• DimensionStyle.UnitType

returns the type of units supported by this dimension style (length, angle, or slope).

Add-ins and macros

Automatic load of add-ins without restarting Revit

Revit now automatically loads addins from newly added .addin manifest files without restarting Revit.  

After placing a new .addin manifest file into one of the dedicated addins folders, the running Revit session will attempt to load the corresponding addin.  Loaded ExternalCommands will be added to the External Tools pulldown menu.  ExternalApplication and ExternalDBApplication OnStartup methods will be executed upon loading.  An addin's installer may leverage this feature – but it must do so by creating the new .addin file at the end of installation to the dedicated Revit addin folders (the installer must ensure that the addin's assembly is already deployed to the target machine and the assembly path can be resolved in the add-in manifest file). 

Add-ins may decline the ability for Revit to load the .addin in the middle of a session.  To decline this options, add an tag (set to “NO”) in the add-in manifest file. 

Note that when Revit starts an add-in in the middle of the session, some add-in logic may not function identically because of the different interactions with the session.  Specifically:

• If the application's goal is to prevent something from happening, the application may not be able to handle the fact that this activity has already happened in the existing session.
• If the application's goal is to manage external information in synch with documents loaded in the session, the application may not be able to handle documents that were loaded before the application started.
• If the application's logic depends on the ApplicationInitialized event, this event has already been called before the add-in was loaded.

Also, some add-ins may not be able to fully initialize when loading in the middle of the session.  This is because some activities must take place at the start of the Revit session:

• Creation of custom failure definitions
• Establishment of a system-wide IFailureProcessor to handle all failures.
• Registering ExternalServices.

Revit also offers a new UI API method

• UIApplication.LoadAddIn()

to programmatically load the add-in(s) listed in the provided add-in manifest file.   Typically, this API would not be needed because Revit is already loading new .addin files automatically.

MacroManager API

Revit now support an API for listing, creating, removing, editing, debugging, and running macros through several supporting classes and enums

• MacroManager
• Available at the DB.Document or ApplicationServices.Application level; manages the querying, creation, and removal of macro modules
• UIMacroManager
• Available at the UIDocument or UIAppliciation level, manages adding, removing, and editing UI-level modules.
• MacroModule
• Manages the querying, creation, removal, and running of specific macro methods
• ModuleSettings
• A collection of top-level properties of a MacroModule
• Macro
• Represents a single, runnable macro method.
• UIDocumentMacroOptions
• Represents security options for UIDocument-level macros.
• DocumentMacroOptions
• Represents security options for DB.Document-level macros.
• ApplicationMacroOptions
• Represents security options for Application-level macros
• MacroLanguageType
• Represents the language of a given macro, C#, VB.NET, Ruby, or Python
• MacroLevel
• Represents whether a macro is associated with a document the Revit application
• ModuleStatus
• Represents the compiled, loaded, or built status of a MacroModule.

The MacroManager APIs are all in the Autodesk.Revit.DB.Macros namespace and are available in RevitAPIMacros.dll and RevitAPIUIMacros.dll

Macro Attributes

The attributes  

• Autodesk.Revit.UI.Macros.AddinAttribute
• Autodesk.Revit.UI.Macros.VendorIdAttribute

and the interface 

• Autodesk.Revit.UI.Macros.IEntryPoint

have been moved to the namespace Autodesk.Revit.DB.Macros.

Parameters

Shared parameter – create with specified GUID

The new method

• Definitions.Create(String, ParameterType, bool, GUID)

supports creation of new ExternalDefinition objects (shared parameter definitions) which use the designated GUID instead of a random GUID. This allows an application to programmatically create consistent definitions for shared parameters without a shared parameter file or copying elements from one project to another.

Dimension.Label

The property

• Dimension.Label

Has been replaced by a new property

• Dimension.FamilyLabel

As this label applies only to dimension in families and their corresponding family parameter.

Family Parameters

The new property

• FamilyParameter.IsShared

identifies if the family parameter is a shared parameter.

Geometry APIs

JoinGeometryUtils

Revit now supports APIs for joining, unjoining, querying join state, and changing join order of elements in a model through the JoinGeometryUtils class.

Extensible Storage

ExtensibleStorage API changes

The method

• Element.GetEntitySchemaGuids()

returns the Schema Guids of any Entities present on an Element.

The methods

• Schema.GetField()
• Schema.ListFields()

are now restricted based on the read permission defined in the Schema.

ExtensibleStorageFilter

An ExtensibleStorageFilter is a new ElementQuickFilter for finding elements that contain an extensible storage entity of a given Schema Guid.

Translation

Export to Navisworks

The new function:

• Document.Export(String, String, NavisworksExportOptions)

exports a Revit project to the Navisworks .nwc format.  Note that in order to use this function,you must have a compatible Navisworks exporter add-in registered with your session of Revit.  If there is no compatible exporter registered, the function will throw OptionalFunctionalityNotAvailableException.  Use

• OptionalFunctionalityUtils.IsNavisworksExporterAvailable()

to check if there is an exporter registered.

Import/Link SAT

The functions:

• Document.Import(String, SATImportOptions, View)
• Document.Link(String, SATImportOptions, View)

import or link an SAT file into the document.

Import/Link SketchUp

The functions:

• Document.Import(String, SKPImportOptions, View)
• Document.Link(String, SKPImportOptions, View)

import or link an SKP file into the document.

Import DWF Markups

The function:

• Document.Import(String, DWFImportOptions)

imports DWF markups into the document.

Export tables

The new classes

• ExportLayerTable
• ExportLinetypeTable
• ExportPatternTable
• ExportFontTable
• ExportLineweightTable

expose read and write access to the tables used for mapping on export to various formats such as DWG, IFC and DGN.

Site

Editing a TopographySurface

Editing the points in a TopographySurface now requires establishment of an edit scope. The class

• TopographyEditScope

allows an application to create and maintain an editing session for a TopographySurface. Start and end of a TopographyEditScope will also start and end a transaction group. After the TopographyEditScope is started, an application can start transactions and edit the topography surface. Individual transactions the application creates inside TopographyEditScope will not appear in the undo menu.  All transactions committed during the edit mode will be merged into a single one which will bear the given name passed into TopographyEditScope constructor.

The method:

• TopographySurface.AddPoints()

has been modified to operate with the edit scope, and thus cannot be called outside of an edit scope.  The function no longer regenerates the document.

The new methods:

• TopographySurface.DeletePoints()
• TopographySurface.MovePoint()
• TopographySurface.MovePoints()
• TopographySurface.ChangePointElevation()
• TopographySurface.ChangePointsElevation()

provide the ability to modify and delete existing points in the TopographySurface.  Multiple calls to these functions can be included in the same edit scope.

Reading points from a TopographySurface

The new method:

• TopographySurface.ReadPoints()

returns a list of the points stored in the surface.

The method:

• TopographySurface.FindPoints()

filters and returns only the points of the topography surface which lie within the input bounding box.

The method:

• TopographySurface.ContainsPoint()

identifies if the input point is found in points stored in the surface.

The methods:

• TopographySurface.GetBoundaryPoints()
• TopographySurface.IsBoundaryPoint()

identify points which are a part of the boundary of the surface.

Validation

Several new validation methods have been added to the TopographySurface class:

• IsValidRegion() – Identifies whether the points can construct a valid region for a topography surface.
• ArePointsDistinct() – Identifies whether the input points are distinct in XY location.

These methods are newly used in AddPoints() to prevent problematic inputs from causing issues.

SiteSubRegion

The class SiteSubRegion represents a proxy class exposing the interfaces needed to access details of a subregion.   In the Revit database, both TopographySurface elements and subregion elements are represented by the same TopographySurface element subclass, however, in the Revit API, this SiteSubRegion class exists to separate the interfaces for subregions from those of topography surfaces.  The SiteSubRegion class offers these APIs:

• SiteSubRegion.Create() – creates a new subregion given a boundary consisting of one or more curve loops.
• SiteSubRegion.IsValidBoundary() – validates the input boundary for a new subregion
• SiteSubRegion.GetBoundary() – returns the boundary curves
• SiteSubRegion.SetBoundary() – sets the boundary for the subregion
• SiteSubRegion.TopographySurface – the TopographySurface element which this subregion represents
• SiteSubRegion.HostId – the identifier of the topography surface hosting this subregion

BuildingPad

The class BuildingPad represents a building pad element in Revit.  It inherits from CeilingAndFloor and thus offers inherited capabilities from HostObject as well. The API exposes the following specific capabilities around BuildingPads:

• BuildingPad.Create() – Creates a new BuildingPad given a boundary, type and level.
• BuildingPad.GetBoundary() – Returns the sketched boundary curves.
• BuildingPad.SetBoundary() – Assigns a new boundary to the BuildingPad.
• BuildingPad.HostId – The element id of the topography surface hosting this BuildingPad.

The type of the building pad is represented by BuildingPadType.  This inherits from HostObjAttributes and offers inherited capabilities from this parent, including access to the CompoundStructure of the type.  The API exposes these new capabilities for BuildingPadTypes:

• BuildingPadType.CreateDefault() – Creates a new default BuildingPadType in the document.

MEP

Externalized Calculations

Several new interfaces and classes based on external services are supported for pipe and duct calculations.

• Several new interfaces deriving from IExternalServer to support friction, flow, and pressure drop for pipes and ducts have been added.
• IPipePlumbingFixtureFlowServer
• IPipePressureDropServer
• IDuctPressureDropServer
• IDuctFittingAndAccessoryPressureDropServer
• IPipeFittingAndAccessoryPressureDropServer
• IDuctFittingAndAccessoryPressureDropUIServer
• IPipeFittingAndAccessoryPressureDropUIServer
• Several new classes implementing IExternalData to support friction, flow, and pressure drop for pipes and ducts have been added.
• PipePlumbingFixtureFlowData
• PipePressureDropData
• DuctPressureDropData
• DuctFittingAndAccessoryConnectorData
• PipeFittingAndAccessoryConnectorData  
• Several new classes implementing ISingleServerService to support friction, flow, and pressure drop for pipes and ducts have been added.
• PipePlumbingFixtureFlowService
• PipePressureDropService
• DuctPressureDropService
• DuctFittingAndAccessoryPressureDropService
• PipeFittingAndAccessoryPressureDropService
• DuctFittingAndAccessoryPressureDropUIService
• PipeFittingAndAccessoryPressureDropUIService

ElectricalLoadClassificationData

ElectricalLoadClassificationData has several new string properties corresponding to the load classification section of the electrical panel schedule.

• LoadSummaryDemandFactorLabel
• PanelConnectedLabel
• PanelEstimatedLabel
• PanelConnectedCurrentLabel
• PanelEstimatedCurrentLabel
• ActualElecricalLoadNameLabel

CSV Fitting Parameter Removal

Because CSV files are no longer used to drive MEP fitting parameters, Revit supports a new set of APIs to manage fitting parameters through several classes

• FamilySizeTableManager – manages importing and exporting of legacy CSV data and size tables.
• FamilySizeTable – manages specific sizes of fittings.
• FamilySizeTableColumn – manages a specific dimension of a given size in a size table
• FamilySizeTableErrorInfo – reports any errors when importing an file with CSV size table into a FamilySizeTable

Fitting Angle Settings

The members:

• DuctSettings.FittingAngleUsage
• DuctSettings.GetSpecificFittingAngles()
• DuctSettings.GetSpecificFittingAngleStatus()
• DuctSettings.SetSpecificFittingAngleStatus()
• PipeSettings.FittingAngleUsage
• PipeSettings.GetSpecificFittingAngles()
• PipeSettings.GetSpecificFittingAngleStatus()
• PipeSettings.SetSpecificFittingAngleStatus()
• ElectricalSetting.FittingAngleUsage
• ElectricalSetting.GetSpecificFittingAngles()
• ElectricalSetting.GetSpecificFittingAngleStatus()
• ElectricalSetting.SetSpecificFittingAngleStatus()

provide access to fitting angle usage settings for ducts, pipes, cable trays and conduits.

Duct Settings

Duct settings for size prefixes and suffixes, annotations, and  air density and viscosity may now be set through the DuctSettings class.

Curve Creation

Pipes, Ducts,  FlexPipes, and FlexDucts can now be created with a  Pipe, Duct, FlexPipe, or FlexDuct SystemTypeId as a parameter on their respective static Create() methods.

ConnectorElement

The methods

• ConnectorElement.CreatePipeConnector(Document, Document, PipeSystemType, Reference, Edge)
• ConnectorElement.CreateDuctConnector(Document, DuctSystemType, ConnectorProfileType, Reference, Edge)
• ConnectorElement.CreateElectricalConnector(Document, ElectricalSystemType, Reference, Edge)
• ConnectorElement.CreateConduitConnector(Document, Reference, Edge)
• ConnectorElement.CreateCableTrayConnector(Document, Reference, Edge)

allow creation of connector elements in families on centered on internal loops of a given face.

The property

• ConnectorElement.SystemType

accesses the MEPSystemType of the connector

The members:

• ConnectorElement.Direction
• ConnectorElement.FlipDirection()

access the direction of the connector.

Connect Air Terminal to Duct

The new method:

• MechanicalUtils.ConnectAirTerminalOnDuct()

connects an air terminal to a duct directly (without the need for a tee or takeoff). The current location of the air terminal will be projected to the duct centerline, and if the point can be successfully projected, the air terminal will be placed on the most suitable face of the duct. 

General

• CableTray.CurveNormal returns the "up" direction vector of a cable tray segment.
• RoutingPreferenceGroup now supports a new rule type for Cap fittings.
• Caps can be automatically be placed on all open connections of a pipe with PlumbingUtils.PlaceCapOnOpenEnds(Document, ElementId, ElementId)

Reinforcement API 

There are many new reinforcement and rebar-related methods and classes in Revit 2014.

AreaReinforcement

AreaReinforcement has several new methods and properties.

• AreaReinforcement.Create – creates a new AreaReinforcement object from curves.
• AreaReinforcement.IsUnobscuredInView – checks if Area Reinforcement is shown unobscured in a view.
• AreaReinforcement.SetUnobscuredInView – sets Area Reinforcement to be shown unobscured in a view.

PathReinforcement 

PathReinforcement has several new methods and properties.

• PathReinforcement .Create – creates a new PathReinforcement object from curves.
• PathReinforcement .AdditionalOffset - gets and sets length offset.
• PathReinforcement .IsUnobscuredInView – checks if PathReinforcement is shown unobscured in a view.
• PathReinforcement .SetUnobscuredInView – sets PathReinforcement to be shown unobscured in a view.

FabricArea 

FabricArea has several new methods and properties.

• FabricArea.Create – now supports an origin point of direction parameter.
• FabricArea.GetReinforcementRoundingManager – returns an object for managing reinforcement rounding override settings.

FabricSheet 

FabricSheet has several new methods and properties.

• FabricSheet.Create() – new static factory method for creation.
• FabricSheet.GetLocalCoordinateSystem()
• FabricSheet.SetLocalCoordinateSystem()
• FabricSheet.PlaceInHost()
• FabricSheet.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• FabricSheet.HostId
• FabricSheet.FabricLocation – the FabricSheet location in the host.
• FabricSheet.CoverOffset – the additional cover offset of the FabricSheet.
• FabricSheet.IsCoverOffsetValid() – identifies if the specified value is valid for use as a cover offset.

FabricSheetType 

• FabricSheetType.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.

Rebar

Rebar has several new methods and properties.

• Rebar.ComputeDrivingCurves() – compute the driving curves.
• Rebar.GetRebarConstraintsManager() – returns an object for managing the external constraints on the Rebar element.
• Rebar.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• Rebar.HookAngleMatchesRebarShapeDefinition() – checks that the hook angle of the specified RebarHookType matches the hook angle used in the Rebar's RebarShape at the specified end of the bar.
• Rebar.CanUseHookType – checks if the specified RebarHookType id is of a valid RebarHookType for the Rebar's RebarBarType.
• Rebar.ConstraintsCanBeEdited – returns true, if the Rebar element's external constraints are available for editing.
• Rebar.GetHookOrientation() – returns the orientation of the hook plane at the start or at the end of the rebar with respect to the orientation of the first or the last curve and the plane normal.
• Rebar.SetHookOrientation() – defines the orientation of the hook plane at the start or at the end of the rebar with respect to the orientation of the first or the last curve and the plane normal.

RebarType has several new methods and properties.

• RebarType.SetHookTangentLength() – identifies the hook tangent length for a hook type.
• RebarType.GetReinforcementRoundingManager() – returns an object for managing reinforcement rounding override settings.
• RebarBendData – new constructor to specify hook orientation.

RebarHandleType – a new enum to represent  the various types of handles on a Rebar instance that can be joined to References.

RebarConstrainedHandle – a new class to represent a handle on a Rebar that can be joined to a reference.

RebarConstraintType – a new enum to represent the various types of constraints that can be applied to a RebarConstrainedHandle.

RebarConstraintTargetHostFaceType – a new enum  to identify the individual face on a host element to which a Rebar handle is constrained.

RebarConstraint – a new class representing a constraint on the position of a Rebar Element or one of its handles.

RebarConstraintsManager – a  new class used to obtain information about the constrained shape handles (RebarConstrainedHandles) on a Rebar element.

RebarDeformationType – new enum representing the type of deformation of rebar.

RebarHookType.HookAngleInDegrees – a new property representing the angle of a rebar hook.

RebarInSystem

• RebarInSystem.getReinforcementRoundingManager – returns an object for managing reinforcement rounding override settings.
• RebarInSystem.setUnobscuredInView - sets the element to be shown unobscured in a view.

RebarShape

• RebarShape.GetDefaultHookAngle – get the hook angle, expressed as an integral number of degrees (common values are 0, 90, 135, and 180).
• RebarShape.GetDefaultHookOrientation – gets the default rebar hook orientation.

ReinforcementRoundingSource – a new enum listing the possible sources for reinforcement rounding overrides.

ReinforcementRoundingManager – a new class providing access to reinforcement rounding overrides for structural elements.

RebarRoundingManager – new class providing access to element reinforcement roundings overrides.

FabricRoundingManager – a new class providing access to element reinforcement roundings overrides.

ReinforcementSettings

• ReinforcementSettings.GetRebarRoundingManager – returns an object for managing reinforcement rounding override settings used by RebarBarTypes, Rebar and RebarInSystem elements.
• ReinforcementSettings.GetFabricRoundingManager – returns an object for managing reinforcement rounding override settings used by FabricSheetType and FabricSheet elements. 

Custom Export

The Custom Export API provides access to the rendering output pipeline through which Revit sends a processed model (its graphics 3D representation) to an output device. In the case of Custom Export, the "device" is represented by a context object that could be any kind of a device, even a file (in the most common case, actually.) A client of Custom Export provides a context and invokes rendering of a model, upon which Revit starts processing the model and sends graphic data out via methods of the context. The data describes the model exactly as it would have appeared in Revit when the model is rendered. The data includes all geometry and material properties.

The following classes have been made available so far:

CustomExporter

A class that allows exporting 3D views via a custom export context. The Export method of this class triggers standard rendering process in Revit, but instead of displaying the result on screen or printer, the output is channeled through the given custom context that handles processing the geometric as well as non-geometric information.

IExportContext

An interface of which interface is used in a custom export of a Revit model. The instance of this class is passed in as a parameter of a CustomExporter. The methods are then called by Revit at times of exporting entities of the model.

Render Node Classes

Classes of which instance are sent to an export context during a custom export.

• RenderNode – base class for all output nodes
• ViewNode – represents a View
• GroupNode – base class for family and link instances
• InstanceNode – represents an instance of a family
• LinkNode – represents an external link
• ContentNode – base class from RPC, Light, and Daylight nodes
• RPCNode – represents an RPC object
• DaylightPortalNode – represents a daylight portal
• LightNode – represents a light
• MaterialNode – represents a material change

CameraInfo

A class that describes information about projection mapping of a 3D view to a rendered image. An instance of this class can be obtained via a property of ViewNode.

Paint API

The paint tool is now supported in the API

• Document.Paint
• Document.RemovePaint
• Document.IsPainted
• Document.GetPaintedMaterial

Component repeater API

Component repeaters can be used to replicate (repeat) elements hosted on repeating references. The result of the repeating operation is a collection of slots. Each slot contains one repeated component. The ComponentRepeater class provides the repeating functionality and access to the slots.

Each repeating reference is capable of hosting one point of an adaptive component. An initial pattern can be created by populating one or more repeating references with such points. Component repeaters can then be used to replicate the pattern to fill the rest of the repeating references in the particular repeating reference source.

The repeating references in repeating reference source are arranged in one or two dimensional arrays, allowing for different kinds of repeating:

• One dimensional source allows for repeating along a path.
• Two dimensional source allows for repeating across a grid.
• It is also possible to host a point on a zero dimensional reference (a point). This point will be shared by all slots. A zero dimensional source allows for repeating around a single point. It should not be used alone, but together with at least one other repeating reference source (typically one dimensional.) The point hosted on the zero dimensional source serves as a central point around which other points can be repeated on their respective repeating reference sources.

Multiple adaptive components may be hosted on one repeating reference source, and different points of one adaptive component may be hosted on different repeating reference sources, effectively allowing different points of an adaptive component to be repeated using different patterns.

The following classes provide access to the functionality of Component repeaters:

• Autodesk.Revit.DB.RepeatingReferenceSource
• Autodesk.Revit.DB.RepeaterBounds
• Autodesk.Revit.DB.RepeaterCoordinates
• Autodesk.Revit.DB.ComponentRepeater
• Autodesk.Revit.DB.ComponentRepeaterSlot

Small Enhancements & Interface Changes

API validation

No transactions from outside threads

Calling into the Revit API from outside threads and outside modeless dialogs has never been supported, but it was not strictly prohibited, meaning there would be no immediate exceptions when someone tries to modify model from outside of the supported API workflows. That has been changed. It is no longer possible to start a transaction unless the caller is inside a legitimate API call, such as an external command, event, updater, call-back, etc. An exception will be thrown if such attempt is made.

IsValidObject property

If a Revit native object contained within an API wrapper is destroyed, or creation of the corresponding native object is undone, the managed API object containing it is no longer valid. API methods cannot be called on invalidated wrapper objects. The property IsValidObject (added to many API classes) can be used to identify if the corresponding native object has gone out of scope.

Enumerated type validation

Automatic validation has been introduced for enumerated type inputs to API methods and properties. If an value is improperly cast to an enum and is not a valid member of that enum, an ArgumentOutOfRangeException will be thrown.

Elements

Copy & paste elements

The new methods:

• ElementTransformUtils.CopyElements(Document, ICollection<ElementId>, Document, Transform)
• ElementTransformUtils.CopyElements(View, ICollection<ElementId>, View, Transform)
• Transform ElementTransformUtils.GetTransformFromViewToView(View, View)

support copy and paste of arbitrary elements.  The first overload supports copy within documents, or from document to document.  The second overload also support copying within one document or between two documents, but specifically supports copy and paste of view-specific elements.

Materials

Materials applied with the Paint tool and their areas can be found by specifying "true" for the 'usePaintMaterial' argumement in Element.GetMaterialIds and Element.GetMaterialArea

Geometry

FreeForm element

A FreeFormElement is a form sub-type that contains non-parametric geometry created from an input solid outline. The element can be added to families, and can participate in joins and void cuts with other combinable elements.  Planar faces of the element can be offset interactively and programmatically in the face normal direction.

• FreeFormElement.Create() – creates a new FreeForm element.
• FreeFormElement.SetFaceOffset() – offsets a planar face a certain distance in the face normal direction.

Solid & curve intersection

The new method

• Solid.IntersectWithCurve()

calculates the intersection between a closed volume Solid and a curve. There is an option to return details about the segments inside the volume, or outside. Both the curve segments and the parameters of the segments are available in the results.

Face/Face Intersection

The method

• Face.Intersect()

calculates the intersection of the input face with this face and returns the intersection results.  The method can output the intersection geometry if the intersection consists of a single curve.

ReferenceIntersector & RVT Links

The new option findReferencesInRevitLinks allows ReferenceIntersector to find geometry in RVT links.

Rulings of RuledFace

The new method

• RuledFace.RulingsAreParallel

determines if the rulings of the ruled surface are parallel.

Detail elements

Detail element draw order

The class

• DetailElementOrderUtils

now includes routines to BringToFront, BringForward, SendToBack, SendBackward multiple detail members.  The draw order of the members does not change relative to one another.

Stairs

StairsRunJustification

New values LeftExterior and RightExterior have been added to this enum to support jusitification to the left and right supports.

StairsLanding

The new members:

• CreateAutomaticLanding(Document, ElementId, ElementId)
• CanCreateAutomaticLanding(Document, ElementId, ElementId)

provide automatic landing(s) creation and creation validation between two stairs runs.

StairsRun

The new properties:

• StairsRun.ExtensionBelowRiserBase
• StairsRun.ExtensionBelowTreadBase

represent the extension/trim value for the run, depending upon whether the run begins with a riser or tread.

These replace the deprecated property:

• StairsRun.ExtensionBelowBase

which now accesses whichever property listed above depending on the run's configuration.

StairsComponentConnection

The new methods:

• StairsRun.GetConnections()
• StairsLanding.GetConnections()

provide information about connections among stairs components (run to run, or run to landing).

Parameters & filters

Parameter.AsValueString()

This method previously was implemented for only Integer and Double values. It now can also be used with Enums and ElementIds. Optionally it can accept a FormatOptions object to specify units formatting of the returned string.

Parameter.Definition.UnitType

This new property provides access to the UnitType of a parameter definition.

Parameter variance among group instances

The new members:

• InternalDefinition.VariesAmongGroups
• InternalDefinition.SetVariesAmongGroups(Document)

support read and write to the option that the parameter value can vary across groups.  This can be changed only for non-built-in parameters.

FilterCategoryRule

The new class FilterCategoryRule can be used in the definition of a ParameterFilterElement.   It represents a filter rule that matches elements of a set of categories.

The related method:

• ParameterFilterElement.AllCategoriesFilterable()

has been replaced by

• FilterCategoryRule.AllCategoriesFilterable()

Miscellaneous

ThermalAsset.SpecificHeat

This new property provides the specific heat value of a thermal asset in feet per Kelvin, squared-second.

AreaVolumeSettings

This new class provides access to settings related to volume and area computations. The old VolumeCalculationSetting class is obsolete. 

Document.Delete()

This method previously returned null if the element or elements could not be deleted. It now will throw an exception in this situation.

Document level updaters

The new methods:

• UpdaterRegistry.IsUpdaterRegister(UpdaterId, Document)
• UpdaterRegistry.UnregisterUpdater(UpdaterId, Document)

provide the ability to inquire about and to unregister updaters that are associated to specific documents. 

UIThemeManager

The static properties of UIThemeManager provide access to the current UI theme and the default theme.

Families & content

Family category

The property

• FamilyBase.FamilyCategory

can now be set.  This allows the category of an family being edited to be changed.

SpatialElementCalculationLocation

The class SpatialElementCalculationLocation is used to specify the room or space where an element should be considered as placed.

This is a base class with currently subtypes of calculation location:

• SpatialElementCalculationPoint
• SpatialElementFromToCalculationPoints

A SpatialElementCalculationLocation can be added to the family by turning on the family's ROOM_CALCULATION_POINT parameter.   Once the location has been added, you can access the marker position using the MarkerPosition property. 

Note that the MarkerPosition property is no longer settable – this position is determined automatically.

SpatialElementFromToCalculationPoints

SpatialElementFromToCalculationPoints is a subclass of SpatialElementCalculationLocation used to specify the search points for a family instance that connects two rooms or spaces, such as a door or window. The points determine which room or space is considered the "from" and which is considered the "to".    The properties ToPosition and FromPosition govern the coordinates for these points.

Arc through points

The method

• CurveByPointsUtils.CreateArcThroughPoints()

creates an arc curve through three input ReferencePoints.

Events

DocumentChangedEventArgs

For the methods GetAddedElementIds()/GetModifiedElementIds() – internal Revit element ids that are not visible to UI and API are now excluded from the return set.

GetAddElementIds(ElementFilter)/GetModifiedElementIds(ElementFilter)

The new methods:

• DocumentChangedEventArgs.GetAddedElementIds(ElementFilter)
• DocumentChangedEventArgs.GetModifiedElementIds(ElementFilter)

only return ElementIds that pass the input element filter. This helps applications detect only specific changes of interest.

Reinforcement API

Reinforcement Length Tolerance

The new classes:

• RebarRoundingManager
• FabricRoundingManager

contain settings for rounding tolerance for rebar and fabric reinforcement elements.  They can be assigned at the element instance level (Rebar, RebarInSystem, FabricArea, FabricSheet), at the type level (RebarType, FabricSheetType), or at the ReinforcementSettings level.   Lower level settings override the setting of higher levels. 

I hope this is enough for you :-)

Cool, huh?

Compiling the Revit 2014 SDK

Here are some notes on the small issues I encountered compiling the Revit 2014 SDK:

• Compile and install RevitLookup
• Set up the Revit API assembly paths
• First compilation run causes expected errors
• Set up the RevitAddInUtility assembly path
• PointCurveCreation Office reference
• CancelSave RevitAddInUtility Reference
• Set up the RvtSamples application
• Fix errors in RvtSamples.txt
• Download RvtSamples and RevitLookup

I already described this same process during the Revit 2013 timeframe. Let's see if anything changed, or, better still, improved.

Compile and Install RevitLookup

My first step is always to compile, install and test RevitLookup.

This went completely smoothly, so I have nothing to report on that.

Please see below for a link to the version I compiled.

Set up the Revit API Assembly Paths

Before the introduction of Revit Onebox, I used to make copies of the Revit API assemblies for the different flavours.

With the advent of Onebox, I opted for the simpler solution of using the Revit API DLLs path updater RevitAPIDllsPathUpdater.exe. Simply launch it, enter the sample location and DLL folder, and let it do its job. In my case, I entered the following paths:

• C:\a\lib\revit\2014\SDK\Samples\RevitAPIDllsPathUpdater.exe
• Sample location: C:\a\lib\revit\2014\SDK\Samples
• DLL folder: C:\Program Files\Autodesk\Revit Architecture 2014

It completes and reports that it "Replaced 169 files, skipped 0 files."

First Compilation Run Causes Expected Errors

With the correct assembly paths in place, it is time to open the Visual Studio solution SDKSamples2014.sln and compile the samples.

The first run reports Rebuild All: 166 succeeded, 3 failed, 0 skipped.

This no surprise, because there are some expected errors.

Set up the RevitAddInUtility Assembly Path

The first error is caused by the RevitAddInUtilitySample and says: "The type or namespace name 'Autodesk' could not be found (are you missing a using directive or an assembly reference?)"

The RevitAddInUtilitySample references the RevitAddInUtility assembly. It is also located in the Revit API assembly path, but RevitAPIDllsPathUpdater.exe does not take it into account, so you have to open that project and set the assembly path manually instead:

In my case, the correct reference path to it is C:\Program Files\Autodesk\Revit Architecture 2014\RevitAddInUtility.dll.

PointCurveCreation Office Reference

The Massing PointCurveCreation sample references Microsoft.Office.Interop.Excel in order to interact with spreadsheets.

I have not set up Office on my virtual machine, so that caused an error saying "The type or namespace name 'Office' does not exist in the namespace 'Microsoft' (are you missing an assembly reference?)"

For a quick ad hoc solution to this, I simply unloaded this one project for the time being.

CancelSave RevitAddInUtility Reference

The next problem occurs in the Events CancelSave sample: "The type or namespace name 'RevitAddIns' does not exist in the namespace 'Autodesk' (are you missing an assembly reference?)"

Same resolution as above, set the RevitAddInUtility assembly path.

Wow!

That was it!

No more errors, just 345 warnings saying 'There was a mismatch between the processor architecture of the project being built "MSIL" and the processor architecture of the reference "RevitAPI, Version=2014.0.0.0, Culture=neutral, processorArchitecture=AMD64", "AMD64". This mismatch may cause runtime failures. Please consider changing the targeted processor architecture of your project through the Configuration Manager so as to align the processor architectures between your project and references, or take a dependency on references with a processor architecture that matches the targeted processor architecture of your project'.

I assume you can ignore those.

This was a smoother compilation than ever before.

Set up the RvtSamples Application

I always install RvtSamples to load all the other SDK samples if I ever want to test something in one of them.

It saves you from installing them one by one, which might prove a lengthy process, there being well over a hundred of them.

To do so, I first add two files to the RvtSamples project, its add-in manifest and its text file listing all the samples to load:

In the text file, I replace the samples path by my real installation folder, globally replacing "Z:\SDK2013\Samples\" by "C:\a\lib\revit\2014\SDK\Samples\".

At the end, I add placeholders for my two include files, for the Autodesk Developer Network ADN and The Building Coder sample collections:

##include C:\a\lib\revit\2014\adn\src\AdnSamples.txt
#include C:\a\lib\revit\2014\bc\BcSamples.txt

The ADN samples are commented out, because we have not completed their migration yet.

I already migrated The Building Coder samples to Revit 2014, though, so that include file is already active.

I need to add the RvtSamples assembly path to its add-in manifest and install that in the Revit Add-Ins folder, and we are set to go.

Fix errors in RvtSamples.txt

As usual, the list of samples to load specified by RvtSamples.txt is not perfectly set up. Here are some of the add-ins causing errors on my system:

• RotateFramingObjects
• ProjectUnit (missing)
• GenericModelCreation
• ElementViewer
• PointCurveCreation (my fault)
• TraverseSystem
• CreateShared
• BarDescriptions (missing)
• StructuralLayerFunction

ProjectUnit is missing, presumably because the unit API changed in Revit 2014 and the sample has been removed. It is still listed in RvtSamples.txt, and should be removed there as well.

Most of the others are caused by VB.NET samples listed in their 'bin' subfolder, whereas their assembly DLL really lives in 'bin/Debug', at least on my system, and vice versa, in the case of CreateShared.

After my first clean-up pass, the following still cause problems:

• GenericModelCreation
• PointCurveCreation (my fault)
• TraverseSystem
• CreateShared
• BarDescriptions (missing)
• StructuralLayerFunction

Again, these are almost all VB.NET samples. Something strange going on with those.

There is a testing switch you can set in the RvtSamples source code, actually:

  bool testClassName = true;

Setting it to true turns up more errors:

• DeleteObject
• HelloRevit
• RotateFramingObjects
• MaterialProperties
• SlabProperties
• CreateBeamsColumnsBraces
• StructuralLayerFunction

I fixed some of these, but not all.

Anyway, I'll stop fixing this for today, though, because I have other things to do as well.

RvtSamples loads now and most of the samples are available:

Download RvtSamples and RevitLookup

Here is my current version of RvtSamples, and also of RevitLookup, which was missing from some intermediate versions of the SDK samples.

The RvtSamples package includes both the original and my modified add-in manifest and RvtSamples.txt sample list. You can compere them to see the changes I applied, and add analogous changes of your own for any other samples that you wish to activate.

I hope this is of use to you.

This article was picked for TenLinks Daily by www.caddigest.com.

Actually, taking a closer look at the CAD digest listing, I currently count 53 of The Building Coder articles listed there. I was not aware of that before. Surprise, surprise :-)

Getting Started with the Revit API

I am regularly forced to return to this topic, to provide a useful starting point for beginners.

The amount of available material is getting huge, and some help is required deciding where to start exploring the Revit API.

The most important thing to be aware of is the Revit Developer Center.

Start there by looking at the three DevTV video introductions and then work through the My First Revit Plug-in tutorial.

In these tutorials, you are shown how to locate, install and use the most basic development tools and information, including:

• The Revit SDK or Software Developer Kit, including
  • The Revit API help file RevitAPI.chm
  • RevitLookup, an interactive database element and relationship explorer and massive source code example in itself
  • The SDK sample collection, including
  • The samples themselves, each one equipped with its own read-me file
  • SamplesReadMe.htm: documentation and overview
  • SDKSamples2013.sln: a Visual Studio solution to compile all samples in one go
  • RvtSamples: an external application to load, test and debug all samples
• The Revit API Developer Guide

More detailed overviews of the available Getting Started material are provided for both Revit 2012 (still valid for 2013) and 2013. You should also take a look at the list of things to do to prepare for a hands-on Revit API training.

I suggest performing these steps:

• Watch the videos
• Work through the tutorial
• Install and explore the SDK
• Compile, install and test RevitLookup
• Compile the SDK samples
• Install and test RvtSamples
• Use RevitLookup to explore a Revit database or two
• Browse the documentation and developers guide to your heart's content

Once you have completed these steps, you will be amply set up and ready to go, raring to get started properly on your own project.

Here is a list of typical questions you might run into:

• How can I determine the relationship and dependency between elements?
• How can I integrate Revit data with an external database?
• How can I extract DWFX data from Revit?
• How can I modify the DWFX results?
• How can I extract a thumbnail image for a specific element?
• How can I get a total count of properties, attributes and custom attributes for a given element?
• How can I compare the properties of two elements?
• When extracting data from Revit, what is the best approach to organize and retrieve that data?
• Is there a standard for all families and element types (symbols) that remains the same from model to model?
• Is there an easy way to list of all families and element types from a model?
• What methods are there to "walk" all objects?

How can I determine the relationship and dependency between elements?

Revit maintains a huge number of different relationships between database elements. How to determine these depends on the elements in question.

An extremely important tool to explore the relationships between elements in the Revit database is RevitLookup, included with the Revit SDK. Use of RevitLookup to explore the Revit database and relationships between elements is discussed and demonstrated in a large number of subsequent posts on The Building Coder blog.

An important technique to discover relationships that are not officially provided through the Revit API is demonstrated by the object relationship analyser (VB). Use of this technique is also discussed and demonstrated in many places.

Most relationships are accessible through much simpler official means, though.

As said, it depends on what elements you are talking about.

How can I integrate Revit data with an external database?

Please look at the following discussions:

• Database integration
• ERP systems
• Delux database

How can I extract DWFX data from Revit?

Use the Document.Export method taking (String, String, ViewSet, DWFXExportOptions) arguments.

How can I modify the DWFX results?

You can export the DWFX. For any further modifications, you would have to take recourse to the DWF Toolkit.

How can I extract a thumbnail image for a specific element?

Look at the discussions on

• RVT and RFA thumbnail image
• OLE storage
• BasicFileInfo

How can I get a total count of properties, attributes and custom attributes for a given element?

You can easily achieve this, but there is no specific API call provided for this task. You have to implement it yourself, and the number will vary depending on your requirements, criteria, and implementation.

How can I compare the properties of two elements?

[Q] For instance, if two different objects have a property of the same name, can their values be compared or summarized together? E.g., a property of "Material" for a length of pipe might be copper; will a property of the same name on a copper elbow joint have the same "Material" value?

[A] I am pretty sure that a clever user can create a project in which this will not be the case.

When extracting data from Revit, what is the best approach to organize and retrieve that data?

That depends completely on your own needs. You will need to perform a careful analysis. Look at the database integration links listed above.

Is there a standard for all family element types (symbols) that remains the same from model to model?

No, unfortunately, the contrary is true. Families and types are completely user defined, and creating their definitions is just as much an art as a science.

Is there an easy way to list of all families and element types from a model?

Yes. To list all types, just filter for all ElementType objects:

  FilteredElementCollector a
    = new FilteredElementCollector( doc )
      .WhereElementIsElementType();
 
  foreach( Element e in a )
  {
    Debug.Print( "{0} {1} is an ElementType.",
      e.Name, e.Id.IntegerValue );
  }

To retrieve the families that they belong to, you can use the FamilySymbol.Family property.

And: I can promise you some surprises if you start exploring this :-)

What methods are there to "walk" all objects?

The filtered element collector is the only way to access in and retrieve elements from the Revit database, unless you have a unique id or an element id and can access the individual object directly.

Please look at the RevitLookup application, which is provided in source code as part of the Revit SDK.

First of all, it is an invaluable tool both for developers and even end users to interactively explore the database and relationships such as the ones you are asking about.

Secondly, it iterates the entire database and walks all the objects, so you can use that code directly.

Conclusion

I hope you find this useful.

In general, almost every single question that you run into in your initial steps of implementing a Revit add-in has already been asked and answered somewhere. Make good use of the help file, global search of the sample code, developer guide and then turn to an Internet query.

Believe me, it is easy and it is fun... both the development part and the research... it is all creative :-)

Good luck!

Project Tracking for Kids

Oh, and one last thing... where tracking is child's play... a few days late for April first :-)

The Revit 2014 Pre-release API and SDK

Below, we look at how ADN members can obtain the Revit 2014 pre-release SDK, address migration issues, and one or two interesting new aspects of the API.

First however, a few words on yesterdays post touting the idea of a cloud-based restaurant seating arrangement and cleaning application. As you probably noticed, the main new ideas I discussed there were in honour of April fool's Day.

Many of my colleagues joined in with other similar hoax blog posts. Stephen Preston presents an April fool's Day blog post overview listing them all.

I hope you enjoy them. They might even provide you with a useful real-world idea or two :-)

As always, think outside the box!

Back to more serious business, the Revit API, and the Revit 2014 pre-release.

The Revit 2014 Pre-release SDK

As you can guess, ADN member have already been working with Revit 2014 and its API to get their products ready for the new release.

Here are a couple of questions and interesting observations that came up and are still coming in:

• Where is the Revit 2014 SDK?
• Do we need to rewrite our apps?
• Add to an existing command
• Full circle creation

Where is the Revit 2014 SDK?

Question: Is there an SDK available for Revit MEP 2014?

The Revit Developer Center still only lists the 2013 SDK...

Answer: ADN members can obtain the Revit 2014 SDK from the ADN web site. It is included in the preview version of Revit:

• Autodesk Developer Network > Login
• Downloads by Product Autodesk Revit
• Autodesk Revit Architecture 2014 available in English
• Autodesk Revit Architecture 2014 English Win 32-64bit (exe - 2.59 Gb)

The installer extracts its content to a temporary installation folder, which by default is located in C:\Autodesk.

Within this folder, you can navigate to the Utilities\SDK subfolder, which contains the installer:

• C:\Autodesk
•  \Autodesk_Revit_Architecture_2014_English_Win_32-64bit_dlm
•  \Utilities
•  \SDK
•  > 03/09/2013 12:27 AM 201,066,482 RevitSDK.exe

This executable extracts and installs the Revit SDK, which is identical for all flavours of Revit including MEP.

Please note that this is a pre-release version of the SDK. There definitely will be changes and additions made before the final release, so plan on updating it as soon as we get there. As always, the final version will obviously be posted to the Revit Developer Center as soon as possible.

Do we need to rewrite our apps?

Question: Sorry if my question is stupid, I am not a programmer and it is hard for me by myself to get to the problem details.

Our programmer reports that our apps do not function under the Revit 2014. I understand it happens because many methods were replaced with new calls. Does it mean that we should rewrite our apps and replace old methods with new ones? Is there a way to upgrade apps automatically?

Answer: Thanks for posting this question. Revit does not provide any tools to automatically upgrade lower version code to higher version. However, Revit does provide plenty of information on how to upgrade the code yourself. Here is the procedure:

• Open the lower version code in Visual Studio.
• Add the Revit 2014 API references.
• In the output window, each error includes a detailed instruction on how to change the code to the higher version.
• Follow these steps one by one.
• Compile the project.

That is easy to follow. Actually, the migration of an add-in from Revit 2013 to 2014 is much easier and faster than in the past few releases.

For more information, please look at the numerous examples in The Building Coder migration category.

Good luck!

Add to an Existing Command

Question: I read your post about disabling commands through the API and it’s sort of along the lines of what I’m trying to do. I’m looking to capture a specific CommandId ID_SETTINGS_REVISIONS, run it, and, when the command finishes, run a custom add-in. I don’t want to replace the command, just add some custom background content at the end of it.

Is that possible?

Answer: In 2013, all you can do is replace the existing command completely with your own implementation.

In 2014, you can also launch an existing Revit command.

Combining these two functionalities should enable what you wish.

Full Circle Creation

The Revit 2014 API enables the creation of a real full circle. That was is not possible in Revit 2013. There, we had to resort to creating two separate 180-degree arcs.

That was just a starter. Lots more to come!

Revit 2014 API and Plan View Room Boundary Loops

I am continuing the research and development for my cloud-based round-trip 2D Revit model editing project.

At the same time, Revit 2014 has been announced, and I am sure you are eager to hear more about that, especially from the API point of view, so let's have a look at that first.

The Revit 2014 API

It is impossible to cover everything, and I have to start somewhere.

Here are a couple of highlights:

• API access to the project browser and selected elements; API commands and macros are enabled.
• Copy and paste API supports copy within or between documents including view-specific elements.
• Full API support for the new non-rectangular crop regions.
• Schedule API now provides formatting control and read-write access to individual data items.
• Command API enables programmatic command launch including built-in Revit, external add-in and macro.
• Add-in API supports mid-session loading and execution.
• Displaced elements API enables exploded views.
• Join geometry API to create or remove a Boolean join and control join order.
• FreeForm element API enables modification of solid geometry imported from e.g. DWG or SAT.
• Site API enables editing of topography surface points and supports sub-regions.
• MEP calculations are moved to external services and can be replaced by add-ins.
• Structural reinforcement and rebar enhancements.
• Enhanced document open, save and worksharing API.
• Linked model API supports loading, unloading, path manipulation, link identification and creation.
• Linked model interaction enables tag creation for linked rooms, linked element selection, geometric reference conversion, etc.
• Import DXF markup, import and link SAT and SketchUp.
• Export to NavisWorks via add-in, access DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables.
• Direct API access to rendering output pipeline including all geometry and material properties.
• Macro API provides support for Python and Ruby development plus List, create, delete and execute modules, macros and security settings.

How does that sound?

Rather a lot of new stuff, isn't there?

Rather a lot of really exciting new stuff, isn't there?

Joe Ye describes a few of these API features in a little more detail on the AEC DevBlog.

To round this off, here are the complete materials from the Revit 2014 DevDays presentations:

• Presentation
• Recording
• Sample code

We will have all the time in the world to explore this in more detail anon.

The material provided above should keep you occupied over the Easter weekend, however :-)

Enjoy!

Retrieving Plan View Room Boundary Polygon Loops

Returning to the cloud-based 2D model editing project, one of the first required components is an add-in that determines and uploads the room, furniture and equipment family instance boundary polygons to some globally accessible data repository for a simplified 2D plan view rendering on a mobile device.

As a first step in that direction, I revamped my code to retrieve and graphically display area boundary loops and combined it with the integer-based point class that I implemented for the OBJ model exporter.

The task I want to achieve for the first part of this first step is to retrieve the room boundary and store the 2D loops in a cloud-based data repository.

Since Revit does not support precision below one sixteenth of an inch, I might as well approximate all my data to something in that region.

For performance and efficiency reasons, it is also useful to move my calculations from floating point double numbers to integers.

Since I want to display my model on a mobile device with a limited resolution using SVG, integers also seem pretty appropriate.

Very handily, a millimetre is just a little bit less than a sixteenth of an inch.

That leads me to define the following integer-based 2D point class:

/// <summary>
/// An integer-based 2D point class.
/// </summary>
class Point2dInt : IComparable<Point2dInt>
{
  public int X { get; set; }
  public int Y { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
  }
 
  public int CompareTo( Point2dInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
    }
    return d;
  }
 
  public override string ToString()
  {
    return string.Format( "({0},{1})", X, Y );
  }
}

A room boundary may include several loops, for instance if a room surrounds some other space such as an elevator, i.e. its outer boundary loop contains some interior loops representing 'holes'.

Therefore, the room GetBoundarySegments method returns a list of loops, and each loop as a list of boundary segments:

  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );

I therefore define my own integer-based 2D loop and list of loops classes like this:

  class JtLoop : List<Point2dInt>
  {
    public JtLoop( int capacity )
      : base( capacity )
    {
    }
 
    public override string ToString()
    {
      return string.Join( ", ", this );
    }
  }
 
  class JtLoops : List<JtLoop>
  {
    public JtLoops( int capacity )
      : base( capacity )
    {
    }
  }

The code to retrieve the boundary segments and convert them to my own representation can be implemented as follows:

/// <summary>
/// Retrieve the room plan view boundary 
/// polygon loops and convert to 2D integer-based.
/// For optimisation and consistency reasons, 
/// convert all coordinates to integer values in
/// millimetres. Revit precision is limited to 
/// 1/16 of an inch, which is abaut 1.2 mm, anyway.
/// </summary>
JtLoops GetRoomLoops( Room room )
{
  SpatialElementBoundaryOptions opt
    = new SpatialElementBoundaryOptions();
 
  opt.SpatialElementBoundaryLocation =
    SpatialElementBoundaryLocation.Center; // loops closed
    //SpatialElementBoundaryLocation.Finish; // loops not closed
 
  IList<IList<BoundarySegment>> loops = room.
    GetBoundarySegments( opt );
 
  int nLoops = loops.Count;
 
  JtLoops jtloops = new JtLoops( nLoops );
 
  foreach( IList<BoundarySegment> loop in loops )
  {
    int nSegments = loop.Count;
 
    JtLoop jtloop = new JtLoop( nSegments );
 
    XYZ p0 = null; // loop start point
    XYZ p; // segment start point
    XYZ q = null; // segment end point
 
    foreach( BoundarySegment seg in loop )
    {
      p = seg.Curve.get_EndPoint( 0 );
 
      jtloop.Add( new Point2dInt( p ) );
 
      Debug.Assert( null == q || q.IsAlmostEqualTo( p ),
        "expected last endpoint to equal current start point" );
 
      q = seg.Curve.get_EndPoint( 1 );
 
      Debug.Print( "{0} --> {1}",
        Util.PointString( p.ToUv() ),
        Util.PointString( q.ToUv() ) );
 
      if( null == p0 )
      {
        p0 = p; // save loop start point
      }
    }
    Debug.Assert( q.IsAlmostEqualTo( p0 ),
      "expected last endpoint to equal loop start point" );
 
    jtloops.Add( jtloop );
  }
  return jtloops;
}

My external command mainline Execute method driving this method also implements some fancy pre- and post-selection support and reporting code listing the contents of my 2D integer-based loops in the Visual Studio debug output window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Application app = uiapp.Application;
  Document doc = uidoc.Document;
 
  if( null == doc )
  {
    ErrorMsg( "Please run this command in a valid"
      + " Revit project document." );
    return Result.Failed;
  }
 
  // Iterate over all pre-selected rooms
 
  List<ElementId> ids = null;
 
  Selection sel = uidoc.Selection;
 
  if( 0 < sel.Elements.Size )
  {
    foreach( Element e in sel.Elements )
    {
      if( !( e is Room ) )
      {
        ErrorMsg( "Please pre-select only room"
          + " elements before running this command." );
        return Result.Failed;
      }
 
      if( null == ids )
      {
        ids = new List<ElementId>( 1 );
      }
 
      ids.Add( e.Id );
    }
  }
 
  // If no rooms were pre-selected, 
  // prompt for post-selection
 
  if( null == ids )
  {
    IList<Reference> refs = null;
 
    try
    {
      refs = sel.PickObjects( ObjectType.Element,
        new RoomSelectionFilter(),
        "Please select rooms." );
    }
    catch( Autodesk.Revit.Exceptions
      .OperationCanceledException )
    {
      return Result.Cancelled;
    }
    ids = new List<ElementId>(
      refs.Select<Reference, ElementId>(
        r => r.ElementId ) );
  }
 
  foreach( ElementId id in ids )
  {
    Element e = doc.GetElement( id );
 
    Debug.Assert( e is Room,
      "expected parts only" );
 
    JtLoops roomLoops = GetRoomLoops( e as Room );
 
    int nLoops = roomLoops.Count;
 
    Debug.Print( "{0} has {1} loop{2}{3}",
      Util.ElementDescription( e ), nLoops,
      Util.PluralSuffix( nLoops ),
      Util.DotOrColon( nLoops ) );
 
    int i = 0;
 
    foreach( JtLoop loop in roomLoops )
    {
      Debug.Print( "  {0}: {1}", i++, loop.ToString() );
    }
  }
  return Result.Succeeded;
}

I tested this on a simple sample room with one hole:

The original start and end points of the boundary segments for this room are reported as follows:

  (9.03,10.13,0) --> (-14.59,10.13,0)
  (-14.59,10.13,0) --> (-14.59,1.93,0)
  (-14.59,1.93,0) --> (-2.45,1.93,0)
  (-2.45,1.93,0) --> (-2.45,-3.98,0)
  (-2.45,-3.98,0) --> (9.03,-3.98,0)
  (9.03,-3.98,0) --> (9.03,10.13,0)
  (0.98,-0.37,0) --> (0.98,1.93,0)
  (0.98,1.93,0) --> (5.57,1.93,0)
  (5.57,1.93,0) --> (5.57,-0.37,0)
  (5.57,-0.37,0) --> (0.98,-0.37,0)

Converting these to my 2D integer-based loop classes and listing those generates the following debug output:

  Room Rooms <212639 Room 1> has 2 loops:
    0: (2753,3087), (-4446,3087), (-4446,587),
      (-746,587), (-746,-1212), (2753,-1212)
    1: (298,-112), (298,587), (1698,587), (1698,-112)

So far, so good.

As far as I can tell, all systems go.

My next step for this add-in is to implement code to determine 2D plan view boundary polygons for the furniture and equipment family instances contained within the selected room.

I am hoping to be able to make use of the ExtrusionAnalyzer class for this. As I mentioned, it is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction.

At the same time, I am continuing to explore options for a cloud-based data repository.

And I have my day-to-day support tasks to attend to too...

Anyway, here is GetRoomLoops.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Point Cloud Request Batching

Here is some important information for point cloud engine developers, who may be confused by the SDK samples provided.

Question: We have taken the Revit point cloud engine example provided and modified it to create three cells, each loading its points from an ASCII file. The cell boundary is then drawn as blue random points.

We noticed that the maximum number of points ever requested is 512 * 512 and decreases as you zoom out. This number is applied to all cells, so the third and second cells disappear rather that fewer points being drawn in each cell.

This of course prompts some questions:

1. What sets the size of the buffer that is to be filled with points?
2. How does the point engine pass the buffer to each cell such that a closer cell would be requesting more points than one in the distance?

Answer: An instance of the IPointCloudAccess class will be requested by Revit when drawing the point cloud in the view. For performance reasons, when rendering every frame, Revit asks the engine to fetch the necessary points split into multiple batches. The number of batches requested depends on the view: the smaller the projection of the cloud bounding box on the screen the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud ('visible' as defined by the filter). Thus, the points supplied by the engine should not be geometrically distinct, e.g. divided into multiple independent volumes, because otherwise, at distant zoom levels, Revit will only request a few batches and only part of the cloud will be displayed.

In other words, on every frame, Revit asks the engine to fetch some number of points in a few batches. Each batch is 256K points. The number of batches requested depends on the frame: the smaller the projection of the cloud bounding box on the screen, e.g. when you zoom out or orbit, the fewer batches Revit requests. Revit assumes that each batch contains points uniformly distributed over the visible part of the cloud, where 'visible' is defined by the filter.

In the sample code, the plug-in does the complete opposite: it groups points in a few cubes, 256K each, and returns one cube per requested batch. So if Revit requests 3*256K points, it gets three cubes, but if you zoom out and Revit requests only 2*256K points, it receives only 2 cubes. In this example Revit expects to get 2*256K points uniformly distributed over the 3 cubes.

This assumption is currently not reflected adequately in the documentation. Sorry! It should say something like:

The main purpose of the engine is to quickly fetch points from one point cloud file satisfying certain conditions described in the client query. Typical request would be to get specified number of representative points within specified volume, e.g. a view frustum. By representative we mean that it is responsibility of the engine to make sure that the points being returned give a good idea of the distribution of all points satisfying the query rather than, e.g. concentrating all in one area.

This simply shows how a contrived SDK engine sample may not provide the best example for real-world usage, not having a database of points which can be queried representatively.

Programmatically Flip Work Plane

Saikat Bhattacharya provided a very clear and succinct explanation on flipping the the work plane for a family instance, and a code sample using the IsWorkPlaneFlipped property to achieve this programmatically.

UIView, Windows Coordinates, ReferenceIntersector and My Own Tooltip

Here is my well-meant contribution to making this the most exciting Wednesday of your entire week.

For the first time in history, the Revit 2013 UIView class provides a possibility to convert back and forth between Revit model coordinates and Windows device screen points.

I imagined making use of that right away when I read about the UIView class, and mentioned it when discussing UIView and Windows device coordinates.

I am still a bit surprised that I have not yet received any questions about these exciting possibilities. Well, anyway, that gives me a chance to finally dive into this exploration free of preconceptions.

Another Revit 2013 topic that I wanted to talk about for a long time is the new ReferenceIntersector class. My previous attempts at publishing anything on it were thwarted by running into some unintended features which have meanwhile been attended to.

Now I can combine both of these topics into a single nice example, presenting my very own tooltips displaying any information I like based on the cursor location in the Revit BIM.

Does that sound cool, or what?

To give you an idea of what I am talking about, here is a two-minute video depicting a sample run demonstrating the final result, with the normal Revit tooltips and my own specialised ones displayed side by side.

To run the demo, I open up the basic architectural sample project, switch away from the perspective view, since add-ins are disabled there, select Level 2, turn on my own tooltips, hover around different elements to compare the Revit tooltip with my own one, and turn off my tooltips again:

Table of Contents

To display a useful tooltip, the user needs to be free to play around in the model.

Simultaneously, my add-in needs to be able to access the Windows cursor location, determine the corresponding Revit model coordinates from it, and query the Revit BIM to determine the information I would like to display.

This calls for an Idling event handler, adding a third topic to the two already mentioned above.

We thus end up with the following list, including hints on the respective approaches, solutions, and helper methods:

• Top-level form and Idling event management: ModelessForm_IdlingEvent.
• Helper methods: GetActiveUiView, GetView3d, ElementDescription.
• Idling event handler:
  • Access Windows cursor location: System.Windows.Forms.Cursor.Position.
  • Determine Revit model coordinates: UIView.
  • Query Revit BIM for information: ReferenceIntersector.
  • Display tooltip: JtTooltipForm.
  • Entire implementation.
• Toggle tooltip on and off commands.
• Conclusion and download.

Before closing, I also mention Saikat's new posts on multi-image naming conventions and text file TaskDialog command links, DesignScript availability on Autodesk Labs, and a nice video of my friend Falk on the Schafberg.

Top-level Form and Idling Event Management

As you hopefully know by now, the implementation to handle the Idling event needs to be really clean and clear and is a little bit tricky.

I strongly suggest basing anything you do on the ModelessForm_IdlingEvent SDK sample.

If you implemented your Idling event handler in any other way in the past, it might be a good idea revisiting it now and comparing notes with that sample.

I based my WinTooltip external application on it, anyway.

It handles all the modeless form interaction in the external application implementation.

In my case, the modeless form is either a Visual Studio designer generated JtTooltipForm or a hand-built JtTooltipForm2.

The external application is instantiated as a singleton instance, and provides public access to that instance so that external commands can access it and use its functionality to show and hide the modeless form.

It implements an internal CloseForm method, public methods ShowForm and HideForm, called by the external commands, and the standard interface methods OnStartup and OnShutdown, like this:

  /// <summary>
  /// Singleton external application class instance.
  /// </summary>
  internal static App _app = null;
 
  /// <summary>
  /// Provide access to singleton class instance.
  /// </summary>
  public static App Instance
  {
    get { return _app; }
  }
 
  /// <summary>
  /// The tooltip form to display.
  /// </summary>
  internal static JtTooltipForm2 _form = null;
 
  /// <summary>
  /// Dispose and null out form.
  /// Return true if it was previously not disposed.
  /// </summary>
  static bool CloseForm()
  {
    bool rc = _form != null;
 
    if( rc )
    {
      if( !_form.IsDisposed )
      {
        _form.Dispose();
      }
      _form = null;
    }
    return rc;
  }
 
  /// <summary>
  /// Create and show the form, 
  /// unless it already exists.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void ShowForm( UIApplication uiapp )
  {
    // If we do not have a form yet, create and show it
 
    if( _form == null || _form.IsDisposed )
    {
      // Instantiate JtTooltipForm to use 
      // the designer generated form.
 
      _form = new JtTooltipForm2();
 
      _form.Show();
 
      // If we have a form, we need Idling too
 
      uiapp.Idling += IdlingHandler;
    }
  }
 
  /// <summary>
  /// Hide the form.
  /// </summary>
  /// <remarks>
  /// The external command invokes 
  /// this on end-user request.
  /// </remarks>
  public void HideForm( UIApplication uiapp )
  {
    if( CloseForm() )
    {
      // If the form was showing, we had subscribed
 
      uiapp.Idling -= IdlingHandler;
    }
  }
 
  public Result OnStartup( UIControlledApplication a )
  {
    _app = this;
    _form = null;
 
    return Result.Succeeded;
  }
 
  public Result OnShutdown( UIControlledApplication a )
  {
    if( CloseForm() )
    {
      a.Idling -= IdlingHandler;
    }
    return Result.Succeeded;
  }

Helper Methods

Apart from the top-level management, the Idling event handler does all the rest of the work.

Before we get to the event handler itself, I'll present the three helper methods it uses:

• GetActiveUiView: retrieve the active UIView.
• GetView3d: retrieve the 3D view named "{3D}".
• ElementDescription: return a descriptive text for a given Revit element.

We can get the active document view directly, but need some additional coding to determine the associated UIView, for example like this:

/// <summary>
/// Return currently active UIView or null.
/// </summary>
static UIView GetActiveUiView( 
  UIDocument uidoc )
{
  Document doc = uidoc.Document;
  View view = doc.ActiveView;
  IList<UIView> uiviews = uidoc.GetOpenUIViews();
  UIView uiview = null;
 
  foreach( UIView uv in uiviews )
  {
    if( uv.ViewId.Equals( view.Id ) )
    {
      uiview = uv;
      break;
    }
  }
  return uiview;
}

The ReferenceIntersector constructor requires a 3D view argument in which the ray tracing takes place. In this sample, I assume that a suitable 3D view named "{3D}" is available and retrieve that using one single line of filtered element and LINQ driven code:

/// <summary>
/// Return the 3D view named "{3D}".
/// </summary>
View3D GetView3d( Document doc )
{
  return new FilteredElementCollector( doc )
    .OfClass( typeof( View3D ) )
    .Cast<View3D>()
    .FirstOrDefault<View3D>( 
      v => v.Name.Equals( "{3D}" ) );
}

You can obviously modify this in any way you like and set up a suitable 3D view to suit your specific view setting, sectioning and filtering needs.

The location dependent BIM information displayed in the tooltip can be determined completely freely. In my case, I simply detect what element the cursor is hovering over and use the ElementDescription method to put together a descriptive text for it:

/// <summary>
/// Return a string describing the given element:
/// .NET type name,
/// category name,
/// family and symbol name for a family instance,
/// element id and element name.
/// </summary>
static string ElementDescription(
  Element e )
{
  if( null == e )
  {
    return "<null>";
  }
 
  // For a wall, the element name equals the
  // wall type name, which is equivalent to the
  // family name ...
 
  FamilyInstance fi = e as FamilyInstance;
 
  string typeName = e.GetType().Name;
 
  string categoryName = ( null == e.Category )
    ? string.Empty
    : e.Category.Name + " ";
 
  string familyName = ( null == fi )
    ? string.Empty
    : fi.Symbol.Family.Name + " ";
 
  string symbolName = ( null == fi
    || e.Name.Equals( fi.Symbol.Name ) )
      ? string.Empty
      : fi.Symbol.Name + " ";
 
  return string.Format( "{0} {1}{2}{3}<{4} {5}>",
    typeName, categoryName, familyName,
    symbolName, e.Id.IntegerValue, e.Name );
}

This is somewhat similar to and yet does not exactly match the information displayed by the standard Revit tooltip and other parts of the user interface, as you might have noticed in the video recording.

Idling Event Handler

The Idling event handler implements the following steps, which we first discuss one by one before presenting the entire code in context:

• Access Windows cursor location: System.Windows.Forms.Cursor.Position.
• Determine Revit model coordinates: UIView.
• Query Revit BIM for information: ReferenceIntersector.
• Display tooltip: JtTooltipForm.
• Entire implementation.

Access Windows Cursor Location

Converting from the cursor position retrieved in Windows device coordinates to Revit model coordinates is possible by calculating the relative position in the UIView.

Here is an illustration assuming a screen resolution of 1600 x 1200 with a Revit view located at the rectangle 800,150 to 1500,650, displaying a plan view of part of the Revit model, with model coordinates ranging from 10,40,0 to 220,120,0. The current cursor location is represented by the green spot:

The Windows device coordinate origin 0,0 is at the upper left, and Y values increase downwards, whereas the Revit model coordinate Y values increase upwards.

You can easily query the cursor position in device coordinates on the Windows screen from .NET framework at any time using the System.Windows.Forms.Cursor.Position property:

  Point p = System.Windows.Forms.Cursor.Position;

Determine Revit Model Coordinates

The cursor location is obviously returned in Windows device coordinates, stored in the point (or vector) variable 'p'.

The aim is to determine the location indicated by this point in Revit model coordinates, for example by determining the vector v from the lower left corner of the Revit view to that location.

We can easily determine the relative position of p between the two corners of the UIView in Windows device coordinates by subtracting the lower left hand corner and dividing by the total width and height to obtain the relative width and height location values dx and dy like this:

  UIView uiview = GetActiveUiView( uidoc );
 
  Rectangle rect = uiview.GetWindowRectangle();
 
  Point p = System.Windows.Forms.Cursor.Position;
 
  double dx = (double) ( p.X - rect.Left )
    / ( rect.Right - rect.Left );
 
  double dy = (double) ( p.Y - rect.Bottom )
    / ( rect.Top - rect.Bottom );

From the UIView, we can also determine model coordinates of the view corners. They are stored in a and b, respectively.

Now it is easy to calculate the cursor point 'q' in model coordinates from the two relative values like this:

  IList<XYZ> corners = uiview.GetZoomCorners();
  XYZ a = corners[0];
  XYZ b = corners[1];
  XYZ v = b - a;
 
  XYZ q = a
    + dx * v.X * XYZ.BasisX
    + dy * v.Y * XYZ.BasisY;

Query Revit BIM for Information using ReferenceIntersector Ray Casting

Once we have the model space cursor location 'q', we can calculate a point beyond the model extents (hopefully) from which one can picture the user looking into the model.

The first element intersected by a ray cast from that point in the view direction should be the one we are interested in displaying information about.

Initially, the sample run was a bit boring, because the only element encountered when looking from straight above was always the roof.

I tweaked that to make the example more interesting, not by modifying the model itself – I use the standard architectural basic sample project rac_basic_sample_project.rvt – but by adding a filter to remove all roof category elements from the reference intersector results instead. The exact elements of interest and information to display are entirely up to you and your needs to determine, of course.

The ray casting requires a 3D view to operate in. In this case, I simply pick the one named "{3D}" returned by the GetView3d helper method. You can set up your own view with specific graphics properties, section cuts, and only certain elements visible, if that better suits your requirements.

Here is the code determining the view, view direction and ray origin, setting up the intersector, determining the target element, and defining the tooltip text to display in the variable 's':

  View3D view3d = GetView3d( doc );
 
  XYZ viewdir = view.ViewDirection;
 
  XYZ origin = q + 1000 * viewdir;
 
  // Find all elements:
 
  //ReferenceIntersector ri
  //  = new ReferenceIntersector( view3d );
 
  // Find all elements except roofs:
 
  ElementFilter f = new ElementCategoryFilter( 
    BuiltInCategory.OST_Roofs, true );
 
  ReferenceIntersector ri 
    = new ReferenceIntersector( f, 
      FindReferenceTarget.Element, view3d );
 
  ReferenceWithContext rc
    = ri.FindNearest( origin, -viewdir );
 
  string s = "Element not found";
 
  if( null != rc )
  {
    Reference r = rc.GetReference();
 
    Element e = doc.GetElement( r );
 
    s = ElementDescription( e );
  }

Display Tooltip and the JtTooltipForm class

I originally used the Visual Studio designer to create a simple tooltip form named JtTooltipForm for me, then tweaked that auto-generated code to create one named JtTooltipForm2 myself programmatically from scratch.

Besides the constructor setting up the form and the Label object to display the tooltip text, it also manages an offset from the cursor position at which to display itself, provides a method to set the tooltip text, and overrides the OnShown and OnVisibleChanged methods to react appropriately to position changes:

/// <summary>
/// A tooltip window designed to move 
/// around with the cursor position.
/// </summary>
class JtTooltipForm2 : Form
{
  /// <summary>
  /// The offset from the mouse pointer 
  /// at which to show the form.
  /// </summary>
  public Point Offset { get; set; }
 
  /// <summary>
  /// Tooltip text.
  /// </summary>
  Label _label;
 
  /// <summary>
  /// Set the tooltip text.
  /// </summary>
  public void SetText( string s )
  {
    _label.Text = s;
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnShown( EventArgs e )
  {
    base.OnShown( e );
 
    Location = new Point(
      MousePosition.X + Offset.X,
      MousePosition.Y + Offset.Y );
  }
 
  /// <summary>
  /// Move the window to an offset of mouse pointer.
  /// </summary>
  protected override void OnVisibleChanged(
    EventArgs e )
  {
    base.OnVisibleChanged( e );
 
    if( Visible )
    {
      Location = new Point(
        MousePosition.X + Offset.X,
        MousePosition.Y + Offset.Y );
    }
  }
 
  public JtTooltipForm2()
  {
    Size = new Size( 200, 20 );
 
    _label = new Label();
 
    SuspendLayout();
 
    _label.AutoSize = false; // the label will not change its height automatically, only width, so switch off AutoSize to wrap text
    _label.CausesValidation = false;
    _label.Dock = DockStyle.Fill;
    _label.Location = new Point( 0, 0 );
    _label.Size = new Size( 35, 13 );
    _label.Parent = this;
 
    AutoScaleDimensions = new SizeF( 6F, 13F );
    AutoScaleMode = AutoScaleMode.Font;
    BackColor = SystemColors.Info;
    ClientSize = new Size( 200, 12 );
    Controls.Add( _label );
    FormBorderStyle = FormBorderStyle.None;
    Name = "JtTooltipForm";
    Opacity = 0.8D;
    ShowInTaskbar = false;
    TopMost = true;
    TransparencyKey = Color.White;
 
    ResumeLayout( false );
    PerformLayout();
 
    Offset = new Point( 10, 0 );
  }
}

You may note that I switched off the AutoSize property. Setting it to true enables the label to automatically expand, and that just means getting wider to fit the text length. The label will not change its height automatically, only width.

A neat trick to wrap text before putting it into the label that I spotted and did not make use of employs a regular expression to do the job:

  WrappedMessage := RegExReplace( 
    LongMessage, "(.{50}\s)", "$1`n" );

Controlling the text and position from the Idling event handler is a trivial two-liner:

  // Move tooltip to current cursor 
  // location and set tooltip text.
 
  _form.Location = p + new Size( _form.Offset );
  _form.SetText( s );

Entire Idling Event Handler Implementation

For better readability, here is the entire Idling event handler implementation in all its glory.

It even includes one slight improvement that is not demonstrated by the ModelessForm_IdlingEvent SDK sample implementation:

If the Revit project is closed while the Idling event is still subscribed to, the UI document may be null. One needs to add a check for that situation as well in the Idling handler, in case the hander relies on an open document.

/// <summary>
/// Idling event handler.
/// </summary>
/// <remarks>
/// We keep the handler very simple. First check
/// if we still have the form. If not, unsubscribe 
/// from Idling, for we no longer need it and it 
/// makes Revit speedier. If the form is around, 
/// check if it has a request ready and process 
/// it accordingly.
/// </remarks>
public void IdlingHandler( 
  object sender, 
  IdlingEventArgs args )
{
  UIApplication uiapp = sender as UIApplication;
  UIDocument uidoc = uiapp.ActiveUIDocument;
 
  if( null == uidoc || _form.IsDisposed )
  {
    uiapp.Idling -= IdlingHandler;
  }
  else // form still exists
  {
    Document doc = uidoc.Document;
    View view = doc.ActiveView;
 
    UIView uiview = GetActiveUiView( uidoc );
 
    Rectangle rect = uiview.GetWindowRectangle();
 
    Point p = System.Windows.Forms.Cursor.Position;
 
    double dx = (double) ( p.X - rect.Left )
      / ( rect.Right - rect.Left );
 
    double dy = (double) ( p.Y - rect.Bottom )
      / ( rect.Top - rect.Bottom );
 
    IList<XYZ> corners = uiview.GetZoomCorners();
    XYZ a = corners[0];
    XYZ b = corners[1];
    XYZ v = b - a;
 
    XYZ q = a
      + dx * v.X * XYZ.BasisX
      + dy * v.Y * XYZ.BasisY;
 
    // If the current view happens to be a 3D view, 
    // we could simply use it right away. In 
    // general we have to find a different one to 
    // run the ReferenceIntersector in.
 
    View3D view3d = GetView3d( doc );
 
    XYZ viewdir = view.ViewDirection;
 
    XYZ origin = q + 1000 * viewdir;
 
    // Find all elements:
 
    //ReferenceIntersector ri
    //  = new ReferenceIntersector( view3d );
 
    // Find all elements except roofs:
 
    ElementFilter f = new ElementCategoryFilter( 
      BuiltInCategory.OST_Roofs, true );
 
    ReferenceIntersector ri 
      = new ReferenceIntersector( f, 
        FindReferenceTarget.Element, view3d );
 
    ReferenceWithContext rc
      = ri.FindNearest( origin, -viewdir );
 
    string s = "Element not found";
 
    if( null != rc )
    {
      Reference r = rc.GetReference();
 
      Element e = doc.GetElement( r );
 
      s = ElementDescription( e );
    }
 
    // Move tooltip to current cursor 
    // location and set tooltip text.
 
    _form.Location = p + new Size( _form.Offset );
    _form.SetText( s );
  }
}

Toggle Tooltip On and Off Commands

To simplify the usage and cooperation with other add-ins, I implemented two trivial read-only external commands calling the external application ShowForm and HideForm methods to toggle my personal tooltips on and off:

[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOn : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.ShowForm( 
      commandData.Application );
 
    return Result.Succeeded;
  }
}
 
[Transaction( TransactionMode.ReadOnly )]
public class CmdTooltipOff : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    App.Instance.HideForm(
      commandData.Application );
 
    return Result.Succeeded;
  }
}

Conclusion and Download

I hope you find this as useful as I imagine it might become, and look forward to your feedback.

By the way, I will be talking about this sample and the possibilities it demonstrates along with many other topics in my Autodesk University presentation CP4107 on the new Revit 2013 UI API functionality, probably making this the most exciting one of my three AU sessions.

Here is a current snapshot of the entire source code, Visual Studio solution and add-in manifest of the WinTooltip sample application, together the rest of my CP4107 sample material. The latter is based on my DevCamp Revit 2013 UI API samples.

Here are a couple of other items of interest before I wrap up, related to the Revit API, technology and purely human interst.

DWG and Image Export Naming Convention

Saikat Bhattacharya points out that the naming convention for exporting multiple images follows the one used for DWG export: [FileName]-[ViewType]-[ViewName].[image format].

Displaying a Text File from a TaskDialog Command Link

I recently mentioned the order of TaskDialog command links.

Now Saikat Bhattacharya picked up a related issue, on how to define a TaskDialog command link to open up a text file in the local system.

URLs and local system HTML links work fine out of the box. A text file, however, needs special processing. One way to launch it is by using the Process.Start method in the .NET System.Diagnostics namespace. Saikat provides the source.

DesignScript

A very exciting new technology is now publicly available on Autodesk Labs: DesignScript:

• A powerful scripting language for exploratory programming.
• Managing and distinguishing between a generative description of a design (as a script) and the resulting generated model.
• A language to help designers build and analyze complex geometric models that would be difficult to model with interactive techniques.
• Integrated into a host geometry application (currently AutoCAD).

The designer no longer directly models the resulting design: instead she develops a script whose execution generates the model. This enables a completely different kind of design model to be created. The design process is also different. An apparently minor edit to the script can have a profound effect on the generated model, enabling the exploration of a vast array of alternatives, with much less effort than manual interactive modeling. Here is a five-minute video explanation of Design Computation by Robert Aish for Autodesk University last year:

Kean Walmsley provides a very nice explanation and description of the DesignScript sample he implemented for it together with Robert in 2008 for the Design Computation Symposium and AU mainstage presentation.

Now you can try it for yourself. Unfortunately, DesignScript is not yet available for Revit...

Falk on Schafberg

For something completely unrelated to any technology at all, here is a nice little video of my friend Falk recently when we hiked over the Wildhauser Schafberg (sheep mountain) together, clearly illustrating some basic and sympathetic human and ovine commonalities :-)

Element Intersection

A common question when analysing a BIM is determining whether any of its elements intersect.

This was actually surprisingly difficult to answer programmatically in Revit a few releases back, as some of the interesting uses of the FindReferencesByDirection method show, for example the FindColumns SDK sample. Later, that method was enhanced to lead to FindReferencesWithContextByDirection.

The FindColumns sample searches for intersections between walls and columns by shooting a ray along the wall centre line, raised above the bottom level by a foot or so, and detecting any columns hit by it. One obvious problem with this approach is its inaccuracy – any column just partially intersecting the wall may easily be missed by the ray.

A few years ago, that was the best an add-in developer could hope for, and things looked even worse before the advent of these methods.

So what is the situation today? In short:

Question: How can I programmatically detect whether two Revit elements intersect?

Answer: You can now perform a Boolean operation on Revit element solids and determine whether they intersect using the BooleanOperationsUtils class ExecuteBooleanOperation method.

Please note that the resulting intersection solid is transient, in-memory only. It can be used for calculation and short-term visualisation using the analysis visualisation framework AVF, but it cannot be added to the Revit database or made persistent.

This class was introduced in the Revit 2012 API, and the associated webcast showed it being used impressively in a much improved version of the FindColumns SDK sample. This version determines the exact intersection solids between all columns and walls instead of roughly approximating the intersection detection by casting a single ray, and displays them to the user through AVF.

The Boolean intersection demo is described in detail and the source can be downloaded from the discussion of a simpler derived sample using AVF to highlight rooms.

Another example of making use of this class is given by the GeometryCreation_BooleanOperation SDK sample.

Finally, here are two discussions on element intersection before the introduction of the BooleanOperationsUtils class, on intersection between elements in Revit 2011 and the InstanceVoidCutUtils class.

AEC Technology Update

If you are interested in a succinct summary of all the key developments in the AEC technology industry in the past couple of months, here is a potantial cancidate: the AEC Technology Updates, Fall 2012, including some snippets of Autodesk related news such as Revit LT and the Vela acquisition.

Create Dimension between Two Lines

Another one of those recurring questions: how to create dimensioning.

I took the opportunity to highlight how to search the samples, find a solution, and apply a correction to RevitLookup yourself.

You have the code.

May the Force be with you.

Question: I tried to create detail drawings programmatically using the ItemFactoryBase NewDimension method.

I am creating detail lines in the drafting view based the on the geometry wall elements and would like to use Revit dimensioning to insert measurements into the detail drawings.

How do I obtain the reference for the detail lines of a drafting view to be able to call the NewDimension method?

I am sure that this is possible, since I can create dimension lines in a drafting view using the dimension line commands on the Annotate ribbon.

Answer: Whenever you are faced with a question like this, please always begin by studying the three main official sources of information:

• The Revit API help file RevitAPI.chm.
• The online wikihelp Revit API Developer's Guide.
• The Revit SDK sample source code.

Normally, when researching an issue like this myself, I perform a global search across the entire project in the SDKSamples2013.sln solution.

This time, happily, I extended it to the entire samples directory instead, including RevitLookup. To tell the truth, I even searched my whole hard disk for all C# files containing NewDimension, because there were not that many in total.

This turned up the following hits in the Revit SDK folder (copy and paste to an editor to see the truncated lines):

C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1255):               //        m_revitApp.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References, dimension.DimensionType);
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1470):            m_revitApp.ActiveUIDocument.Document.Create.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Test\TestElements.cs(1475):            m_revitApp.ActiveUIDocument.Document.FamilyCreate.NewDimension(m_revitApp.ActiveUIDocument.Document.ActiveView,
C:\...\SDK\RevitLookup\CS\Utils\Elements.cs(272):            Dimension dimensionClone = app.ActiveUIDocument.Document.Create.NewDimension(dimension.View, line, dimension.References);
C:\...\SDK\Samples\CreateDimensions\CS\Command.cs(213):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\CreateDimensions\CS\Command1.cs(219):                    Dimension newDimension = doc.Create.NewDimension(
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(31):    /// The class allows users to create dimension using Document.FamilyCreate.NewDimension() function
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(91):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(125):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);
C:\...\SDK\Samples\FamilyCreation\WindowWizard\CS\CreateDimension.cs(160):            dim = m_document.FamilyCreate.NewDimension(view, line, refArray);

The very first of those, in the RevitLookup test framework, looks like it should answer your question right away:

  XYZ location1 = GeomUtils.kOrigin;
  XYZ location2 = new XYZ( 20.0, 0.0, 0.0 );
  XYZ location3 = new XYZ( 0.0, 20.0, 0.0 );
  XYZ location4 = new XYZ( 20.0, 20.0, 0.0 );
 
  Curve curve1 = m_revitApp.Application.Create
    .NewLine( location1, location2, true );
 
  Curve curve2 = m_revitApp.Application.Create
    .NewLine( location3, location4, true );
 
  DetailCurve dCurve1 = null;
  DetailCurve dCurve2 = null;
 
  if( !doc.IsFamilyDocument )
  {
    dCurve1 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.Create.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
  else
  {
    if( null != doc.OwnerFamily
      && null != doc.OwnerFamily.FamilyCategory )
    {
      if( !doc.OwnerFamily.FamilyCategory.Name
        .Contains( "Detail" ) )
      {
        MessageBox.Show(
          "Please make sure you open a detail based family template.",
          "RevitLookup", MessageBoxButtons.OK,
          MessageBoxIcon.Information );
 
        return;
      }
    }
    dCurve1 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve1 );
 
    dCurve2 = doc.FamilyCreate.NewDetailCurve(
      doc.ActiveView, curve2 );
  }
 
  Line line = m_revitApp.Application.Create.NewLine(
    location2, location4, true );
 
  ReferenceArray refArray = new ReferenceArray();
 
  refArray.Append( dCurve1.GeometryCurve.Reference );
  refArray.Append( dCurve2.GeometryCurve.Reference );
 
  if( !doc.IsFamilyDocument )
  {
    doc.Create.NewDimension( 
      doc.ActiveView, line, refArray );
  }
  else
  {
    doc.FamilyCreate.NewDimension( 
      doc.ActiveView, line, refArray );
  }

I tried running this sample command by selecting the ribbon tab Add-Ins > Revit Lookup > Test Framework... > Object Hierarchy > APIObject > Element > Dimension > OK.

That calls the DimensionHardWired method to do the job.

Unfortunately, it throws an exception saying "Attempt to modify the model outside of transaction".

I fixed it by adding the following lines right at the beginning of the method:

  using( Transaction tx = new Transaction( doc ) )
  {
    tx.Start( "DimensionHardWired" );

Obviously, I need to commit the transaction and close the using statement at the end again:

    tx.Commit();
  }

Now is successfully completes with the following result:

You can also look at two The Building Coder samples creating wall dimensioning, either by iterating over the wall faces to pick the two suitable ones, or using FindReferencesByDirection to shoot a ray and find them directly.

They both retrieve the geometry references from the wall faces, and not from a simple detail line, though.

All together, this should provide more than enough to solve your issue.

Accessing the Path of a Family Document from the Family Instance

Before closing, here is pointer to a cool discovery by Saikat Bhattacharya: if you try to find the family document of a family instance and go through the path family instance > family symbol > family > document, you end up at the document containing the family instance. If you are actually after the family document defining the instance, you need to go through the EditFamily method instead. More details on accessing the path of a family document from an instance.

Exporting Parameter Data to Excel, and Re-importing

Did you observe the international talk like a pirate holiday yesterday?

I did not, I'm sorry to say. I only became aware of it this morning trying to find some reason why it was so quiet yesterday. Aaarrr!

Anyway, here is an update of an age-old sample application, originally created by Miroslav Schonauer for the very first Revit API training classes after the first introduction of the Revit API back in the Revit 2008 timeframe.

Miro put together a whole collection of useful samples, which survived time and changes extraordinarily well and made it through to become the Xtra Revit API training labs.

I received several queries lately on how to export data to Excel, with various follow-up options such as later including data from linked files as well, and enabling a re-import of modified data.

The FireRating SDK Sample

Actually, talking about re-importing the exported data, a simple example of this has been around all along as well. The FireRating SDK sample demonstrates:

• Creating and populating a new shared parameter in the model.
• Exporting all its values to Excel.
• Importing modified data back in from Excel to update the Revit model.

I mentioned this important sample a number of times, ever since the early beginnings of the blog, often to demonstrate how to add a shared parameter to various element types in the model:

• Adding a shared parameter to a DWG file.
• Defining a new parameter.
• Adding a shared parameter to an RFA file.
• Model group shared parameter.
• Parameter access and scheduling.

One very special use of this sample was in the special 100^th anniversary description of utilizing Revit API resources to get a beginner up to speed and running.

Because of its importance, this sample also made its way into the Revit API Xtra training labs in the shape of three commands corresponding to the steps listed above:

• Lab4_3_1_CreateAndBindSharedParam
• Lab4_3_2_ExportSharedParamToExcel
• Lab4_3_3_ImportSharedParamFromExcel

Of course, the importance of shared parameters for add-in was greatly diminished by the introduction of extensible storage.

Parameter Export to Excel Considerations

Anyway, back to the subject at hand.

The external command Lab4_2_ExportParametersToExcel in the ADN Xtra labs implements exporting all parameter data of all Revit elements to Excel. 'All' is relative, though...

It bases the selection of parameters on the standard Revit API Element.Parameters property. An attempt is made to export the values of the parameters returned in this collection, and others are ignored. Many elements do have other parameters associated with them as well, as demonstrated by BipChecker, the built-in parameter explorer. They could easily be added to the export as well, of course.

Furthermore, there are of course a multitude of other important data items not stored in parameters that might be interesting to export and potentially modify and re-import as well. It might be worthwhile checking whether RDBLink does anything like that... RDBLink was originally part of the Revit 2008, 2009 and 2010 SDKs, then matured into a subscription pack product.

The choice of Excel as an export target is not mine, nor would it normally be so. Due to popular demand, though, this command makes use of the Excel COM interface and .NET Interop to access that. It launches or attaches to a running instance of Excel and makes it visible, so you can see the work sheets and parameters being added one by one. It might be faster to make Excel invisible, and faster still to use some other library to generate the XLS file without direct access to Excel, and faster still choosing some completely different file format such as SLK, CSV, or, heaven forbid, TXT.

The command selects all elements in the entire model, both types (e.g. family symbols) and non-type elements. Each element is identified in the export by its element id, and a flag is added to tell whether it is a type or not.

The original implementation exported only model elements. Support for all elements was implemented by creating a union of two complementary filtered element collectors, which is easily possible and normally not recommended.

The elements are sorted by category, and elements with no valid category are ignored. The elements are sorted into a dictionary of separate containers for each category.

The category names are used to create individual work sheets in a new Excel work book.

The category names need some massaging to confirm with the Excel work sheet naming conventions; the name must:

• Not be blank.
• Not exceed 31 characters.
• Not contain any of the following characters:   :   \   /   ?   *   [   or   ].

In the original implementation, the entire parameter access was encapsulated in a try-catch exception handler. Many elements returned null, though, triggering and exception and slowing down the process enormously. Every exception handler is resource intensive and will significantly slow down execution and consume resources. An exception handler should be designed to handle unexpected, exceptional cases only; exceptions should be exceptional. Adding a preceding check for a null parameter before actually trying to access it speeded things up significantly. Maybe the exception handler can be removed completely?

As said, the elements are identified in the resulting Excel data by their element id. This is not a very safe method of identifying elements, because the element id may change, e.g. by work sharing operations. It would be safer to use the UniqueId instead.

When the new work book is set up, Excel automatically adds a couple of work sheets to it. The number of default work sheets added can be defined in the Excel application settings. I initially implemented code to remove the unneeded work sheets, but later commented it out to simply let them be. They don't really hurt.

For each category, all the elements are examined to determine what parameters they contain. A column is added to the work sheet for each parameter, and a header is set up listing the parameter name. We iterate over the elements in that category and add a row listing their element id, type flag, and parameter values for each.

Parameter Export to Excel Implementation

Let's summarise the steps:

• Collect all elements and sort them by category.
• Attach to or launch Excel and create a new work book.
• Loop through all the categories and set up a work sheet for each.
• Determine all parameters for the given category and create the work sheet header listing them.
• Iterate over each elements of the category and export its element id, type flag and parameter values.
• Report the results.

Here is the code implementing this as a read-only external command:

/// <summary>
/// Export all parameters for each model 
/// element to Excel, one sheet per category.
/// </summary>
[Transaction( TransactionMode.ReadOnly )]
public class Lab4_2_ExportParametersToExcel 
  : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication app = commandData.Application;
    Document doc = app.ActiveUIDocument.Document;
 
    // Extract and group the data from Revit in a 
    // dictionary, where the key is the category 
    // name and the value is a list of elements.
 
    Stopwatch sw = Stopwatch.StartNew();
 
    Dictionary<string, List<Element>> sortedElements 
      = new Dictionary<string, List<Element>>();
 
    // Iterate over all elements, both symbols and 
    // model elements, and them in the dictionary.
 
    ElementFilter f = new LogicalOrFilter(
      new ElementIsElementTypeFilter( false ), 
      new ElementIsElementTypeFilter( true ) );
 
    FilteredElementCollector collector
      = new FilteredElementCollector( doc )
        .WherePasses( f );
 
    string name;
 
    foreach( Element e in collector )
    {
      Category category = e.Category;
 
      if( null != category )
      {
        name = category.Name;
 
        // If this category was not yet encountered,
        // add it and create a new container for its
        // elements.
 
        if( !sortedElements.ContainsKey( name ) )
        {
          sortedElements.Add( name, 
            new List<Element>() );
        }
        sortedElements[name].Add( e );
      }
    }
 
    // Launch or access Excel via COM Interop:
 
    X.Application excel = new X.Application();
 
    if( null == excel )
    {
      LabUtils.ErrorMsg( 
        "Failed to get or start Excel." );
 
      return Result.Failed;
    }
    excel.Visible = true;
 
    X.Workbook workbook = excel.Workbooks.Add( 
      Missing.Value );
 
    X.Worksheet worksheet;
 
    // We cannot delete all work sheets, 
    // Excel requires at least one.
    //
    //while( 1 < workbook.Sheets.Count ) 
    //{
    //  worksheet = workbook.Sheets.get_Item(1) as X.Worksheet;
    //  worksheet.Delete();
    //}
 
    // Loop through all collected categories and 
    // create a worksheet for each except the first.
    // We sort the categories and work trough them 
    // from the end, since the worksheet added last 
    // shows up first in the Excel tab.
 
    List<string> keys = new List<string>( 
      sortedElements.Keys );
 
    keys.Sort();
    keys.Reverse();
 
    bool first = true;
 
    int nElements = 0;
    int nCategories = keys.Count;
 
    foreach( string categoryName in keys )
    {
      List<Element> elementSet 
        = sortedElements[categoryName];
 
      // Create and name the worksheet
 
      if( first )
      {
        worksheet = workbook.Sheets.get_Item( 1 ) 
          as X.Worksheet;
 
        first = false;
      }
      else
      {
        worksheet = excel.Worksheets.Add( 
          Missing.Value, Missing.Value, 
          Missing.Value, Missing.Value ) 
          as X.Worksheet;
      }
 
      name = ( 31 < categoryName.Length )
        ? categoryName.Substring( 0, 31 )
        : categoryName;
 
      name = name
        .Replace( ':', '_' )
        .Replace( '/', '_' );
 
      worksheet.Name = name;
 
      // Determine the names of all parameters 
      // defined for the elements in this set.
 
      List<string> paramNames = new List<string>();
 
      foreach( Element e in elementSet )
      {
        ParameterSet parameters = e.Parameters;
 
        foreach( Parameter parameter in parameters )
        {
          name = parameter.Definition.Name;
 
          if( !paramNames.Contains( name ) )
          {
            paramNames.Add( name );
          }
        }
      }
      paramNames.Sort();
 
      // Add the header row in bold.
 
      worksheet.Cells[1, 1] = "ID";
      worksheet.Cells[1, 2] = "IsType";
 
      int column = 3;
 
      foreach( string paramName in paramNames )
      {
        worksheet.Cells[1, column] = paramName;
        ++column;
      }
      var range = worksheet.get_Range( "A1", "Z1" );
 
      range.Font.Bold = true;
      range.EntireColumn.AutoFit();
 
      int row = 2;
 
      foreach( Element e in elementSet )
      {
        // First column is the element id,
        // second a flag indicating type (symbol)
        // or not, both displayed as an integer.
 
        worksheet.Cells[row, 1] = e.Id.IntegerValue;
 
        worksheet.Cells[row, 2] = (e is ElementType) 
          ? 1 
          : 0;
 
        column = 3;
 
        string paramValue;
 
        foreach( string paramName in paramNames )
        {
          paramValue = "*NA*";
 
          Parameter p = e.get_Parameter( paramName );
 
          if( null != p )
          {
            //try
            //{
              paramValue 
                = LabUtils.GetParameterValue( p );
            //}
            //catch( Exception ex )
            //{
            //  Debug.Print( ex.Message );
            //}
          }
 
          worksheet.Cells[row, column++] 
            = paramValue;
        } // column
 
        ++nElements;
        ++row;
 
      } // row
 
    } // category == worksheet
 
 
    sw.Stop();
 
    TaskDialog.Show( "Parameter Export",
      string.Format(
        "{0} categories and a total "
        + "of {1} elements exported "
        + "in {2:F2} seconds.",
        nCategories, nElements,
        sw.Elapsed.TotalSeconds ) );
 
    return Result.Succeeded;
  }
}

I ran the command on the basic architectural sample model rac_basic_sample_project.rvt. It takes about two minutes to complete, produces this XLS file output containing 124 work sheets, and displays the following message on terminating:

The timing is not very relevant, since I was doing other things at the same time on the machine.

Here is adn_labs_2013_2012-09-19.zip containing the complete source code, Visual Studio solution and RvtSamples include file of the ADN training labs with the updated Lab4_2_ExportParametersToExcel external command.

Elbow Fitting Selection and Dimensioning

Vacation time is approaching fast for me and lots of things need finishing off beforehand.

Meanwhile, one thing that had a number of developers champing at their bits for a while now finally came to fruition:

Autodesk Exchange

The Autodesk Exchange store is now open for application submissions. Stephen Preston already published several articles exaplaining the full details:

• Summary information
• Information for Revit developers
• Publishing an app

Here is another topic that recently kept me busy, with some helpful input from Martin Schmid and Steve Mycynek:

Selecting a Pipe Elbow Fitting

Question: I need to set the diameter of a pipe elbow fitting programmatically. The elbow diameter obviously needs to be adapted to the pipe diameter. The two pipes may also have different diameters.

I tried using the NewElbowFitting method to insert the elbow and simply pass in the two pipe connectors to it like this:

  doc.Create.NewElbowFitting( con1, con2 );

This does successfully create an elbow fitting instance. However, I don't see how to control which elbow symbol is inserted by this method. Is there any way to influence this?

Answer: Calling the NewElbowFitting method is similar to using the Trim tool in the user interface. When this method is called, Revit automatically chooses the appropriate elbow for you.

In Revit 2013, you can control the selection process through the routing preferences, whereas previous versions only enabled you to define one single default elbow, tee, etc. The routing preferences support multiple settings for different materials and sizes.

The routing preferences API is demonstrated by the RoutingPreferenceTools SDK sample. It implements three commands, one for analysis and reporting purposes, two for importing and exporting routing preferences to XML:

• Routing Preference Analysis: Analyze the routing preferences of a given pipe type to check for common problems, using the routing preferences API to look at all rules and criteria for a given PipeType.
• Routing Preference Builder with its two commands CommandReadPreferences and CommandWritePreferences: Set pipe type, fitting, and routing preferences in a project from data in an XML file and export these preferences to XML for archival, documentation, and collaboration purposes, allowing a user to work with routing preference data in a shareable XML format suitable for reuse in a wide variety of BIM management environments.

When you call NewElbowFitting, it inspects the pipe type and finds the first elbow in the appropriate routing preferences.

If the elbow inlet and outlet sizes differ, you need a reducing elbow.

How to Use the Routing Preferences API to Set the Elbow Symbol

The NewElbowFitting method will insert the elbow symbol specified in the routing preferences. Please note that while RP will choose the first symbol in the rule list that matches its criteria, you can always programmatically either set size criteria to ensure a later symbol is chosen for a given scenario, or re-order the rules using RoutingPreferenceManager RemoveRule and AddRule methods, at least temporarily, to force RP to choose a different elbow symbol than normal.

For example, if you have defined routing preference for 'Elbow Reducing - Threaded - MI - Class 150.rfa' and call this method, you will get an elbow that has different connection sizes as shown below on the left. If you don't have a transitioning elbow, but you do have a reducer defined, you will get a result as below right. Note that the reducer is quite odd in this particular model file :-)

In this case, both the Reducing Elbow and the Elbow + Reducer 'work'; which is used depends on their order in the definition of the RP.

The RP is the only way to influence this selection, both in the UI and in the API.

I Beg to Differ

In some cases, the outer diameter of the fitting and the pipes may differ. This is a content issue. Pipes and fittings are selected and connected based on the pipe 'Nominal Diameter' and the 'Nominal Diameter' of the fitting connector. In the Pipe Settings, a user can make the 'outer diameter' of a pipe bigger or smaller than its nominal diameter.

Here is an example with the following pipe type properties:

• Diameter 18 mm
• Outer Diameter 18 mm
• Inner Diameter 16 mm
• Size 18 mm

The generic pipe elbow fitting connected to the pipes by calling the NewElbowFitting method has the following properties:

• Nominal Diameter 18 mm
• Size 18 mm - 18 mm

For a fitting, the geometry of the elbow is completely arbitrary.

If you would like the elbow and pipe to have the same outer diameter, there are two ways to achieve this:

1. Make the outer diameter of the pipes bigger.
2. Modify the geometry of the elbow to be smaller.

Welded pipe fittings, for example, would have the same outer diameter, whereas threaded fittings, PVC, and others, typically have a larger outer diameter than the pipe itself, because the pipe engages into the fitting.

Change Elbow Dimension

Saikat handled an independent but related case that also happened to catch my attention:

Question: How can I change the diameter of an elbow pipe fitting, depending on the pipe diameter?

Answer by Saikat Bhattacharya: To test this, I created a pipe with an elbow fitting attached at one end. In the user interface, you can see that the nominal diameter parameter of the pipe is disabled, i.e. greyed out. The only thing I can do interactively in the user interface is modify the Nominal Radius of the pipe.

Based on this observation, I wrote the following few lines of code to modify the Nominal Radius of the selected elbow fitting using the API and it worked well:

  UIApplication uiApp = commandData.Application;
  UIDocument uiDoc = uiApp.ActiveUIDocument;
  Document doc = uiDoc.Document;
 
  Transaction trans = new Transaction( doc );
  trans.Start( "Change Diameter" );
  foreach( Element e in uiDoc.Selection.Elements )
  {
    FamilyInstance i = e as FamilyInstance;
 
    Parameter p = i.get_Parameter( 
      "Nominal Radius" );
 
    p.Set( 10 * 0.08333 );
  }
  trans.Commit();

For the complete solution and additional background information, please refer to Saikat's article on changing the diameter of an elbow fitting.

Invoke External Command on Start-up

Finally, to wrap this up, a little note on another issue that also cropped up and really is completely unrelated :-)

Question: I would like to call my Revit add-in in a batch operation in order to process multiple Revit files. The process would involve starting Revit, loading a model, invoking my add-in, and shutting down the application afterwards. I don't see any obvious command line option to achieve this. Is it possible at all?

Answer: Yes. This can be easily addressed by creating an external application, implementing appropriate OnStartup and DocumentOpened events, and driving the whole thing through a journal file or even directly from the command line.

Creating an Opening

Here is a question that we have looked at in the distant past, brought up again and reinforced by Jon Mirtschin of Geometry Gym, working on BIM and model exchange with Rhino, Grasshopper et al:

Question: Sorry to bother you, but trying to get a quick answer to this problem. If you happen to have 5 minutes to help, it will be greatly appreciated.

I've attached a sample Revit project. It simply creates a polyline curve array and slab outline, and then attempts to add an internal opening. This is a simplification from my IFC importer. When I run it, I get an error message about a circular reference.

Can you please advise what is wrong and how to fix? I've tried searching samples and online help to no avail.

Answer: Okey-doke, five minutes.

• Countdown starting at 9:45:34.70.
• I read the mail and stored your attachment: 9:47:09.20;
• Created a repository for your issue and unzipped: 9:48:12.65;
• Started up Visual Studio to look at your project: 9:49:02.60;
• Updated references to be able to compile: 9:49:55.64;
• Bumped .NET framework version to 4.0: 9:50:33.15;
• Fixed post-build event... or no, I'll just ignore that error: 9:51:21.87;

Sorry for being so literal, I just can't help it, and I even think it is fun :-)

Well, this looks like an interesting issue.

Before I dig any further, have you looked at the suggestions on creating a hole in a floor? They include exploring the NewOpenings and ShaftHolePuncher SDK samples.

Do those SDK samples work for you?

In additional to that very old post, here is another half-old one which raises another interesting and important point for you to explore: an extra transaction may be required after creating the slab and before punching a hole through it.

Please try that out as well.

I expect a full report including answers to every single one of the questions above, ok?

Thank you!

P.S.: 9:57:42.51 :-)

Response:

Well, at least you have a great stop watch. Most the time I'm too scared to even glance at the clock on the wall. I actually should also ask you to report your Revit start up time; I can probably allow a minute reduction for your great computers vs. my poor laptop ;-)

Ok, good news. You are correct about the transaction. It was one of the things I had in the back of my mind but hadn't checked yet. Thanks for pointing it out.

Adding the manual transactions and setting a commit and start before adding the opening profile worked. Note that when I went back to my real project, it has tiers of commands, so I was getting an exception to start a new transaction within the outer program command transaction. I added a call to the doc.Regenerate method instead, and that resolved this issue, so problem solved.

I did look at the examples you mention, and will be using them. In this case, the IFC data is presenting an outer and inner profile curves, so the nominated method is the best for this situation.

I don't know if I've answered every single one of your questions, but I'm close.

Here is my amended source code. Now I'm off to implement the change in my real project.

Please feel free to blog about this, I have read through most of your blog several times now and to me it is an invaluable resource. I would like to contribute in any small way.

Here is a sample image of a basic test:

This is an IFC generated from an Archicad model and now opened in Revit. I already had the wall openings working, and now slabs are there too. There are some more impressive and real world projects behind this.

Answer: For the stopwatch, I use the Windows command console time command, i.e. an old MS-DOS command :-)

C:\a\doc\revit\blog\ > time
The current time is: 10:43:48.29
Enter the new time:

My computer is pretty old and decrepit, actually. I am up for renewal soon :-)

Thank you for the appreciation and nice example!

The Revit 2013 Structure API

I migrated the ADN Revit Structure API training material to Revit 2013, which led me to put together the following summary of the structural API enhancements and some details of the migration steps:

• API enhancements
• RstLabs migration
• NewRstLab migration
• RstAvfDmu migration
• Materials

Revit Structure 2013 API Enhancements

I mentioned a few structure specific enhancements in the Revit 2013 API. They are discussed in somewhat more detail in the DevDays Online presentation on What's New in Revit 2013 and the complementary Revit 2013 API webcast, of which the first half provides an introduction to the Revit API in general, and the second covers some new 2013 specific features in more depth.

Actually, it was the webcast preparation that prompted me to start performing the migration described below, which in turn prompted me to publish the result and summarise the changes.

To recap, the structural enhancements include:

Structural Product Related Enhancements

Before we get to the detailed API changes, here are some notes on the main product goals and features:

Reinforcement detailing to help extend the BIM lifecycle from design to construction through detailing and fabrication:

• Area/path reinforcement to host real rebar and set
• Welded wire mesh
• Reinforcement fillets and hooks
• Additional reinforcement units
• Rebar cover

Structural analysis in BIM moving towards delivering structural analysis in the cloud and supporting partner ecosystem growth by

• Results storage, visualization and exploration in RST
• Improved analytical models for surface elements
• Seamless workflow between RST/RSA
• Improved rigid links

Structural analysis web service and visualisation to democratize analysis and make it more accessible, easy to both use and provide. Long term, we would like to deliver structural analysis in the cloud and thus support partner ecosystem growth. Support for modal and deformation analysis, enhanced results visualization.

Enhanced physical properties to centralize analysis workflows around BIM data and improve the efficiency of BIM-based analysis workflows.

• Extended thermal and structural properties of building envelope
• Material authoring and library management workflows
• Foundation for material ecosystem
• Data flow with key Building Performance and Structural Analysis applications

Now let's look at how these changes affect the API:

Reinforcement

The Rebar class provides a number of new methods and properties:

• CreateFromCurvesAndShape
• GetBarPositionTransform
• GetBarExistsAtPosition
• GetHookTypeId/SetHookTypeId
• RebarShapeMatchesCurvesAndHooks
• ScheduleMark
• TotalLength
• Volume

The Rebar.GetCenterlineCurves method takes new arguments to control

• Adjustment for self-intersection
• Inclusion of hooks
• Inclusion of bend radius curves (fillets)

The BarDescription class is now obsolete and replaced by the new RebarInSystem class representing a bar in an AreaReinforcement or PathReinforcement system, providing access to individual rebars in a system and the ability to switch back and forth between system and individual elements.

A new class ReinforcementSettings is provided. When ReinforcementSettings.HostStructuralRebar is true, area and path reinforcement elements create individual rebar elements that participate in views and schedules. The individual RebarInSystem elements have the same graphical representation and parameters as Rebar elements, and have the same API methods for inquiry. Since the RebarInSystem elements are almost entirely controlled by their area or path system element, they lack most of the modification methods of the Rebar class.

These two system classes now have types, and provide new members to retrieve system members, curve boundaries, remove an element and convert its bars into standard rebar via the new methods GetRebarInSystemIds, RemoveAreaReinforcementSystem, and RemovePathReinforcementSystem.

Welded Wire Mesh

• FabricSheet
  • Planar sheet of welded wire mesh
  • Created and cut by FabricArea
  • Option to automatically add symbols and tags
• FabricArea
  • Creates and manages a distribution of FabricSheets
  • Allows sketched welded wire mesh objects
  • Planar hosts only, identical criteria to Area and Path Reinforcement
• Related type classes
  • FabricAreaType provides identity data
  • FabricSheetType includes uncut dimensions, wire sizes and layouts
  • FabricWireType defines wire diameter

Physical Properties

• Structural family instances support additional structural material element
• Structural and thermal material assets can be shared and set on materials

Structural Analytical Model

• New element type AnalyticalLink
• Created between two analytical elements, e.g. a beam and a column
• Two kinds of links: user-defined and automatically generated
• Access link properties like "fixity state"

Analysis Visualization Framework

• Support for deformed shapes as part of AVF display
• AnalysisDisplayStyleDeformedShapeTextLabelType
• AnalysisDisplayDeformedShapeSettings input argument to new CreateAnalysisDisplayStyle override

Revit Structure Labs RstLabs Migration

As said, I migrated the Revit Structure API material from 2012 to 2013, starting with the labs RstLabs. The standard steps are getting to be a habit, after already completing the The Building Coder samples, ADN Revit API training labs, AdnRme Revit MEP API and extensible storage samples:

• Updated the Revit API assembly references.
• Set the target .NET framework version to 4.
• Removed the warnings caused by calls to the Element property in VB, represented as a call to the get_Element method n C#, replacing them by the new Revit 2013 GetElement method, which has the advantage of looking identical in both languages.

After that, no warnings remain.

There are four errors, though, which all are caused by the removal of the LOAD_USE_LOCAL_COORDINATE_SYSTEM_HOSTED built-in parameter.

Since the parameter value retrieved is not used anywhere and the call is just to demonstrate the retrieval of a parameter value in general, I simply commented out the offending statements.

New Revit Structure Labs NewRstLab Migration

Standard stuff, same as before: change the Revit API assembly references, .NET framework version, and replace the use of the Element property by calls to GetElement.

I also replaced the test for a concrete column by new code, since the MaterialConcrete class no longer exists in Revit 2013. Here is the old code I replaced:

  MaterialSet materials = column.Materials;
 
  MaterialConcrete matConcrete = null;
 
  foreach( Material mat in materials )
  {
    // cast it to concrete material
    matConcrete = mat as MaterialConcrete; 
    break;
  }
  if( null == matConcrete )
  {
    messages = "The selected column is not concrete";
    trans.RollBack();
    return Result.Failed;
  }

The new code is much clearer and simpler:

  if( StructuralMaterialType.Concrete 
    != column.StructuralMaterialType )
  {
    messages = "The selected column is not concrete";
    trans.RollBack();
    return Result.Failed;
  }

Revit Structure AVF and DMU Sample RstAvfDmu Migration

RstAvfDmu is a dual sample by Saikat Bhattacharya on using the analysis visualisation framework AVF and the dynamic model update DMU in the context of Revit Structure.

The only significant change required is due to the GetCenterlineCurves method taking some additional arguments in Revit 2013:

  // For this we first access 
  // the rebar line geometry
 
  //Line rebarLine = rebar.Curves.get_Item( 
  //  0 ) as Line; // 2011
 
  //Line rebarLine = rebar.GetCenterlineCurves( 
  //  false )[0] as Line; // 2012
 
  Line rebarLine = rebar.GetCenterlineCurves(
    false, true, true )[0] as Line; // 2013

Materials

Here is rst_2013_2012-06-12.zip containing the result of my efforts so far, the Revit Structure 2013 versions of RstLabs, NewRstLab and RstAvfDmu.

The Revit Structure link sample RstLink is not yet completed, nor have I yet updated the Revit Structure API slide deck.

DevCamp Day Two

This morning I presented my second session, on some of the Revit 2013 UI API enhancements, in the Revit API beginner track. After that, I returned back to the Revit API expert one to attend the presentations on modeless interaction and IFC before presenting my final session on the Revit MEP API. Here then are my sessions of today, in chronological order:

• 1-4 Revit 2013 UI API enhancements
• 2-3 Asynchronous interactions
• 2-2 IFC export open source
• 2-7 Revit MEP API

Revit 2013 UI API Enhancements

Enhanced add-in integration is an important topic in the Revit 2013 API. This session discusses four of the add-in integration topics in more depth, building on a preceding presentation by Saikat Bhattacharya presenting a snapshot of the entire Revit UI API functionality:

• Revit progress bar notifications
• Options dialogue WPF custom extensions
• Embed and control a Revit view
• Drag and drop

All four of these are covered by existing SDK samples, the first by ProgressNotifier (Events), the others by the comprehensive UIAPI sample.

For someone like me, feeling a strong affinity to Winnie the Pooh, the "bear of very little brain", the existing SDK samples are way beyond simple comprehension and reuse, so I ended up creating four own extremely simple and minimal ones exercising these features in just a few lines of code each instead, to reduce the code and required audience comprehension power to an absolute minimum.

Revit progress bar notifications

To receive information about the current Revit progress bar status, you can subscribe to the ProgressChanged event.

The event handler will receive a ProgressChangedEventArgs instance providing the following properties:

• Caption – progress bar caption describing operation in progress
• Stage – current stage of the progress bar, one of Started, CaptionChanged, RangeChanged, PositionChanged, UserCancelled, Finished
• LowerRange – lower limit of range, always zero
• UpperRange – upper limit of range, any non-zero number
• Position – Value between zero and UpperRange incremented with "PositionChanged" stage

The ProgressNotifier SDK sample displays a WPF-based dialogue box. It provides a button to open and load a Revit model. Loading the selected file will cause a number of progress bar actions to execute. These actions are monitored and presented in a stack structure, since occasionally more than one progress bar event may be active simultaneously:

My new ProgressWatcher sample in much simpler and tracks all progress bar events by just printing the event argument data to the Visual Studio debug output window. This can be achieved in a very few lines of code, basically only one each to subscribe to the event and to access and print the progress bar event data:

[Transaction( TransactionMode.ReadOnly )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    UIApplication uiapp = commandData.Application;
    Application app = uiapp.Application;
 
    app.ProgressChanged 
      += new EventHandler<ProgressChangedEventArgs>( 
        OnProgressChanged );
 
    return Result.Succeeded;
  }
 
  void OnProgressChanged( 
    object sender, 
    ProgressChangedEventArgs e )
  {
    double percent = 100.0 * e.Position / e.UpperRange;
 
    Debug.Print( 
      "'{0}' stage {1} position {2} [{3}, {4}] ({5}%)",
      e.Caption, e.Stage, e.Position, e.LowerRange, 
      e.UpperRange, percent.ToString( "0.##" ) );
  }
}

Saving the output to a text file will allow you to analyse in detail the progress bar event sequence and nesting.

Options dialogue WPF custom extensions

In Revit 2013, an add-in can add its own custom tabs to the standard Revit Options dialogue.

This is achieved by defining a WPF control to display and subscribing to the UIApplication DisplayingOptionsDialog event.

The event handler receives an DisplayingOptionsDialogEventArgs instance. It has a PagesCount property providing the number of Options dialogue tabs including default Revit ones. It also sports the AddTab method that can be used to add a tab, providing a name and a handler for it. The handler information is encapsulated in the TabbedDialogExtension class.

The TabbedDialogExtension class provides a constructor taking two arguments, a WPF user control instance and an OK handler. These cannot be changed later. It provides methods to get and set contextual help, and properties to read the WPF control and OK handler. It also provides properties to both get and set the cancel and 'restore defaults' handlers:

• Control – the control
• OnOKAction – the ok handler
• OnCancelAction – the cancel handler
• OnRestoreDefaultsAction – the restore defaults handler

The UIAPI SDK sample adds several custom tabs demonstrating most available features.

I created a minimal sample named AddOptionsTab which defines the simplest possible WPF control with one single button to click:

If you click the button, the corresponding event handler on the form is called, which simply displays a task dialog:

If this tab has ever been activated after the Options dialogue was opened, its OK, cancel and 'restore defaults' handlers are called, depending on the user actions.

Here is the entire user control source code defining its handlers:

public partial class UserControl1 : UserControl
{
  string _name;
 
  public UserControl1( string name )
  {
    _name = name;
 
    InitializeComponent();
  }
 
  private void button1_Click( 
    object sender, 
    RoutedEventArgs e )
  {
    TaskDialog.Show( _name, "I was clicked..." );
  }
 
  public void OnOK()
  {
    TaskDialog.Show( _name, "OK" );
  }
 
  public void OnCancel()
  {
    TaskDialog.Show( _name, "OnCancel" );
  }
 
  public void OnRestoreDefaults()
  {
    TaskDialog.Show( _name, "OnRestoreDefaults" );
  }
}

The event handler code reacting to the Options dialogue displaying simply instantiates the user control, calls the TabbedDialogExtension constructor with it, and feeds that to the event handler arguments AddTab method:

void OnDisplayingOptionsDialog( 
  object sender, 
  DisplayingOptionsDialogEventArgs e )
{
  UserControl1 c = new UserControl1( 
    "DevCamp User Control" );
 
  e.AddTab( "DevCamp Custom Tab", 
    new TabbedDialogExtension( 
      c, c.OnOK ) );
}

The event handler is called each time the Options dialogue is invoked once the event has been subscribed to, which is achieved in a single line of code like this in the AddOptionsTab external command:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  UIApplication uiapp = commandData.Application;
 
  uiapp.DisplayingOptionsDialog 
    += new EventHandler<DisplayingOptionsDialogEventArgs>( 
      OnDisplayingOptionsDialog );
 
  return Result.Succeeded;
}

Embed and control a Revit view

Another of the add-in integration enhancements enables you to embed and control a Revit view in your own form, dialogue or window.

The new PreviewControl class presents a preview control to browse the Revit model. It takes two input arguments, a document and a view id. The hosting form or window must be modal. The View can be any graphical view, i.e. must be printable. Perspective views are also supported, and all 3D Views can be manipulated by view cube. The visibility and graphical settings of the view are effective and respected by the control.

The UIAPI SDK sample proves a demonstration of this as well, which allows you to interactively select any of the open documents to view, or even open a new one, and secondly presents a list of all the documents views for you to switch between. Each time you change any of these two selections, the current preview control is discarded and a new one is instantiated with the updated input arguments. These input arguments are the only way in which the add-in affects the view, all further interaction happens between the control and the user.

To use a Revit preview control, you simply create a standard .NET form and insert a WPF host in it. A suitable host is the System.Windows.Forms.Integration.ElementHost. You populate this with a new Revit preview control instance, e.g. like this

  elementHost.Child = new PreviewControl( 
    doc, view.Id );

The PreviewControl instance needs to be disposed of after use:

  PreviewControl vc = elementHost.Child
    as PreviewControl;

  if( vc != null ) { vc.Dispose(); }

Here is a code snippet showing how all the printable views can be retrieved using a filtered element collector:

  IEnumerable<View> views
    = new FilteredElementCollector( doc )
      .OfClass( typeof( View ) )
      .Cast<View>()
      .Where<View>( v => v.CanBePrinted );

I created a minimal sample application PreviewControlSimple for this DevCamp class with much less code (and functionality than the UIAPI one, since it just displays the current view of a document with no further ado.

It does add one interesting twist, though: to show exactly how the hosting form is set up, I implemented that twice over, first using the Visual Studio designer as usual, and then converting the form to be completely programmatically generated. Here is the DisplayRevitView method taking the document and view input arguments for the preview control. It also takes a third argument for the main Revit window, so that the generated control can be hooked up to that as a parent window. This defines an appropriate relationship between the two as far as the Windows OS is concerned, ensuring correct minimisation and restoration behaviour:

const string _caption_prefix
  = "Simple Revit Preview - ";
 
void DisplayRevitView( 
  Document doc,
  View view,
  IWin32Window owner )
{
 
  using( PreviewControl pc
    = new PreviewControl( doc, view.Id ) )
  {
 
#if CREATE_FORM_BY_CODE
 
    using( System.Windows.Forms.Form form
      = new System.Windows.Forms.Form() )
    {
      ElementHost elementHost = new ElementHost();
 
      elementHost.Location
        = new System.Drawing.Point( 0, 0 );
 
      elementHost.Dock = DockStyle.Fill;
      elementHost.TabIndex = 0;
      elementHost.Parent = form;
      elementHost.Child = pc;
 
      form.Text = _caption_prefix + view.Name;
      form.Controls.Add( elementHost );
      form.Size = new Size( 400, 400 );
      form.ShowDialog( owner );
    }
 
#else // if not CREATE_FORM_BY_CODE
 
    Form1 form = new Form1( pc );
    form.ShowDialog( owner );
 
#endif // CREATE_FORM_BY_CODE
 
  }
}

Please note that correct disposal of the preview control is ensured by the 'using' statement. This is similar to Arnošt's strong recommendation to always encapsulate Revit Transactions in a 'using' statement.

Calling this method from the external command mainline with the current document view is trivial. I add one line of code to access the Revit main window:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  IWin32Window revit_window
    = new JtWindowHandle(
      ComponentManager.ApplicationWindow );
 
  UIApplication uiapp = commandData.Application;
  UIDocument uidoc = uiapp.ActiveUIDocument;
  Document doc = uidoc.Document;
 
  View view = doc.ActiveView;
 
  DisplayRevitView( doc, view, revit_window );
 
  return Result.Succeeded;
}

Drag and Drop API

I recently discussed the new drag and drop functionality and the UIAPI sample command demonstrating it.

The UIApplication provides the new static DoDragDrop method, with two overloads:

• DoDragDrop( ICollection<string> ) – initiate a standard built-in Revit drag and drop operation taking a collection of file names.
• DoDragDrop( object, IDropHandler ) – initiate a drag and drop operation with a custom drop implementation.

This method is designed for use in a modeless form.

Please note that this is currently the one and only Revit API method not requiring a valid Revit API context.

This method can be called from your modeless form at any time, even without Revit giving you explicit permission to interact with the API via some form of callback or notification, as required for all other Revit API calls.

The behaviour of drag and drop given a list of filenames depends on the type of files, as I already recently pointed out:

• One AutoCAD format or image file dragged onto Revit – A new import placement editor is started to import the file.
• More than one AutoCAD format or image files dragged – A new import placement editor is started for the first file.
• One family file dragged onto Revit – The family is loaded, and an editor started to place an instance.
• More than one family file dragged onto Revit – All the families are loaded.
• More than one family file including other format files dragged – Revit tries to open all the files.
• Valid file or list of files is passed – Revit does its best to use them appropriately.
• Any files are not usable – Failure is signalled to user, no exception is thrown, add-in is not notified.

Here again, I implemented a new DevCamp sample add-in DragDropApi to be able to show the necessary steps in a simpler context than the corresponding UIAPI example.

Here are my four new Revit 2013 UI API samples AddOptionsTab, DragDropApi, PreviewControlSimple, ProgressWatcher and the slides I used.

Asynchronous Interactions

Arnošt Löbel already presented on this topic at Autodesk University 2011 in his class CP5381 'Asynchronous Interactions and Managing Modeless UI with the Autodesk Revit API', as mentioned in the overview of the AU 2011 Revit and AEC API sessions.

In this class, Arnošt also covered the new external events and demonstrated his ModelessForm_ExternalEvent, ModelessForm_IdlingEvent (ModelessDialog) and WorkThread (MultiThreading) SDK samples.

The conclusion of the presentation is the following pledge that we are all strongly recommended to take:

• I shall not call the API unless invoked by it
• I shall not call the API from anywhere but the main thread
• I shall call the API only, not directly the Revits UI
• I shall use the Idling event cautiously and considerably

Here is a snapshot of the entire slide deck. This is not the final version, which will be posted soon after the end of DevCamp.

IFC Export Open Source

Angel Velez is senior principal engineer in the Revit development team and presented on the IFC exporter open source project, covering the following main topics:

• Introduction
  • History of IFC in Revit
  • Why open source?
• How the code Works
  • Overall structure of code
  • Key points of interest, e.g. element traversal, property sets
  • Look at alternate UI

Here is the snapshot of his slides.

Revit MEP API

The Revit MEP API is a recurring topic of mine at Autodesk University, and I presented on this once again last year in my session CP4453 'Everything in Place with Autodesk Revit MEP Programming', as mentioned in the overview of the AU 2011 Revit and AEC API sessions. The AU materials and the sample code that I use there was already published and discussed.

In preparation for the sessions here in Waltham, I also discussed the Revit 2013 MEP API and completed the migration of the ADN MEP sample code to Revit 2013.

Here is the slide deck I used today, based on the AU one and updated for Revit MEP 2013.

Please note again that all the materials provided above are just snapshots. Soon after the conference completes, the complete and final materials will be published.

Winding Down and Winding Up Again

In the evening we went out for a DevTech dinner, Japanese and Chinese cuisine. It was great to hang out with the guys for a while and wind down a bit:

Next stop is the DevLab tomorrow with a record number of almost fifty registered participants, so we will be way busy! Time to wind up again. No rest for the wicked! These events are always great, and I'm looking forward to it a lot.

Revit 2013 API Webcast Recording

The recording of the Revit 2013 API webcast that we held on May 17 is now available from the ADN DevTech Webcast Recordings Archive, entering "Revit API" as the course topic, or directly from here.

The 34 MB zip file includes:

• ReadMe.txt
• Slide deck
• Recording
• Code Samples

The webcast addresses two main areas: an introduction to Revit programming for beginners, including a quick walkthrough of basic concepts, and a discussion of some of the new functionality provided by the Revit 2013 API, which will be of interest to both beginners and experienced developers. The two parts are roughly equal in length.

The new API topics discussed have been selected to avoid too much overlap with the DevDays Online presentation on What's New in Revit 2013, from which a recording is also available, so these two complement each other and should do quite a good job together to cover all important aspects of the Revit 2013 API. This is the agenda of the second half of the webcast:

• New feature overview and DevDays Online recording
• Add-in integration features in depth, Idling and external events
• Analysis, simulation, MEP and Structure
• New SDK samples
• More News

For your convenience, here is the content of the readme file describing the sample code provided:

Webcast on Revit 2013 API

This folder includes the following materials:

• Recording – recording of the webcast and the Q&A collection. Click on the WMV file to view the recording. Answers to questions asked using the Q&A Console can be found in document file.
• Webcast – powerpoint slides used in the recording.
• Code Samples – code samples used for the demo. Please see below for notes on each sample.

About Code Samples Folder

This folder includes samples demonstrated in the webcast presentation. Some samples that were not demonstrated during the webcast but used in the presentation slides are also included.

The sample code is available in both C# and VB in the directories SourceCS and SourceVB, respectively. Both of these contain a Visual Studio solution file WebcastDemo.sln to compile and run it.

A sample Revit model Demo.rvt containing a few simple elements that can be used to test the functionality demonstrated by the sample code is also included. If you prefer, you may use any other Revit file.

Functionality Demonstrated by the Solutions

1. HelloWorldCmd – a bare-bones example of an external command.
2. HelloWorldApp – a bare-bones example of an external application.
3. CommandData – parameters of the execute method of the IExternalCommand interface.
4. SelectedElements – method to retrieve selected elements.
5. FilteredElements – use of FilteredElementCollector to identify all Walls that exceed a certain length.
6. AllElements – use of FilteredElementCollector to retrieve all elements in the model.
7. ElementIdentification – method to identify the type of an element.
8. AllWalls – use of FilteredElementCollector to retrieve all walls in the model.
9. AllDoors – use of FilteredElementCollector to retrieve all doors in the model.
10. ElementCreation – use of the Creation namespace and the static creation method to create a wall.
11. ElementModification – use of ElementTransformUtils to rotate a wall.
12. BuiltInParameters – method to retrieve built-in parameters.
13. SharedParameter – creation of a shared parameter and binding it to the Doors category.

The ADN MEP Sample AdnRme for Revit MEP 2013

Yesterday I discussed the Revit 2013 MEP API and the external services framework.

In preparation for my Revit MEP API presentation at the upcoming AEC DevCamp in Boston in June, I also migrated the ADN MEP API sample AdnRme to Revit MEP 2013.

The initial flat migration was extremely straightforward with zero code changes required.

I obviously had to change the Revit API assembly references, which forces an update of the .NET framework version to 4.0. After bumping the framework version, the whole solution immediately compiled with zero errors and warnings. I must admit I was a bit surprised.

New One-box Product Type

On loading it, though, I was surprised again, because the add-in ribbon panel was simply not displayed.

Debugging the external application OnStartup method revealed that since I was running and testing it in a one-box flavour of Revit, the product type was not 'MEP' but simply 'Revit'. To fix this, I had to add support for both of those enumeration values to my product type test:

public Result OnStartup( UIControlledApplication a )
{
  // only create a new ribbon panel in Revit MEP:
 
  ProductType pt = a.ControlledApplication.Product;
 
  //if( ProductType.MEP == pt ) // 2012
 
  if( ProductType.MEP == pt 
    || ProductType.Revit == pt ) // 2013
  {
    AddRibbonPanel( a );
    return Result.Succeeded;
  }
  return Result.Cancelled;
}

With that little change in place, everything works fine and my ribbon panel shows up as expected:

Actually, for full-fledged support of the new runtime discipline switching, I could add more flexible enabling and disabling of my buttons, if I wanted to, for instance by dynamically hiding this application when the MEP discipline is not enabled.

Here is the 'About' box, automatically populated with properties harvested from the .NET assembly company, copyright, description, product, title and version and attributes, explaining briefly what this sample is about:

History and Functionality

By the way, although I have been demonstrating and using this sample for many years now, I have still not described its functionality in detail here in the blog, so maybe that is something I should do right now.

Several descriptions have been made publicly available in the past, though, for instance in the materials for my Autodesk University 2011 virtual class CP4453 Everything in Place with Autodesk Revit MEP Programming, covering both the Revit MEP 2012 API features and the Revit MEP API in general.

Before that, I already published the code here on the blog for Revit MEP 2012 and previous versions, and at previous Autodesk University and AEC DevCamp events.

The AdnRme sample demonstrates several Revit MEP API aspects, in two separate main areas:

• HVAC air terminal analysis and sizing.
• Hierarchical display of an electrical system.

It also demonstrates some Revit and .NET API aspects not directly related to the MEP API, such as:

• External application implementation.
• About box, automatically populated using .NET assembly properties.
• Progress bar.

AdnRme implements an external application to define a custom user interface to access the sample commands, as you can see from the ribbon panel shown above. The about box is also shown above.

The progress bar may be useful in a large project, since the processing of a large number of elements may take a noticeable amount of time, and is implemented using a standard .NET modeless form:

HVAC Air Terminal Analysis and Sizing Sample

The HVAC part of the MEP sample was originally implemented based on Revit 2008, before the advent of any MEP-specific API at all, using pure generic Revit element and parameter access to analyse and modify the HVAC duct system.

It supports a typical HVAC engineering workflow including the following tasks:

• Placement and sizing of air distribution ducts and terminals.
• Analysis and verification of results.

In a little more detail, the workflow might look like this:

• Manually lay out air terminals.
• Run heating and cooling load analysis.
• Based on load analysis, assign flow to terminals.
• Based on terminal flow, size air terminals.
• Validate design; a common check figure uses air flow per surface area.

The MEP HVAC sample was originally implemented for Revit 2008 and based on room elements, since spaces had not yet been introduced back then. It was modified for RME 2009 to use spaces.

It implements the following four commands to support the HVAC engineering workflow described above. The first three support the actual workflow itself, the fourth cleans up and resets the data manipulated by them:

• Assign flow to terminals.
• Change air terminal size.
• Calculate and display flow density as colour fill to verify design by air flow per surface area.
• Reset demo.

This workflow is exercised in the following simple office building sample model with a place holder duct system in place:

Here it is in plan view:

The progress of the steps is displayed by four schedules set up in the sample model:

Initially, all the 51 diffusers are the same:

The 33 spaces have calculated and specified supply air flows defined, but no actual flow:

The CFM per SF parameter in the right-hand column is defined to generate a colour schema at the end to verify the results visually at a glance, and is currently still set to zero.

The air terminals have not yet been properly analysed and sized:

Their flow and actual supply air flow is still zero:

Executing the commands in the proper sequence fixes all this:

• Assign flow to terminals: calculate the required flow per terminal by dividing the required flow for the space by the number of terminals, and assigning the resulting value to each terminal via its Flow parameter.
• Change air terminal size: for each diffuser type, determine its minimum and maximum flow. Select the type that ensures that the actual flow lies between these two.
• Calculate and display flow density as colour fill to verify design by air flow per surface area: calculate the CFM per SF using the built-in parameters ROOM_ACTUAL_SUPPLY_AIRFLOW_PARAM and ROOM_AREA and set the "CFM per SF" parameter accordingly.

The schedules are all updated, and the predefined colour fill displays and enables visual verification of the results:

Electrical Hierarchy Sample

Later during the lifetime of this sample, the electrical hierarchy functionality was added, initially based on non-MEP-specific analysis of parameter values to determine the system structure, later rewritten and significantly simplified by accessing the MEP connectors for this task instead.

In a way, the electrical hierarchy part is closely related to the TraverseSystem duct system SDK sample, which traverses a duct system by moving through its elements from predecessor to successor element through the connectors and storing the resulting tree data in an HTML file.

The AdnRme electrical sample does the same and displays the result in a tree view form instead:

It actually determines and displays the hierarchical structure of the electrical systems in the model in several different ways. Its focus is to:

• Traverse the electrical system
• Reproduce the system browser data structure in a tree view
• Determine and display the complete connection hierarchy in a tree view

The standard RME system browser displays electrical components in a three-level flat list, and the complete hierarchical structure of the connection tree is not immediately apparent. This sample inspects the electrical systems and reproduces the structure and information displayed by the system browser as well as the full connection hierarchy. It implements the following commands:

• CmdElectricalConnectors
• CmdElectricalSystemBrowser
• CmdUnhostedElements

The first two analyse the electrical system hierarchical structure and present it to the user in a tree view in a modeless dialogue, either in the full hierarchical structure, or in the three-tier structure used by the system browser; the third detects and lists un-hosted elements.

The form displaying the full electrical system hierarchical structure is shown above. Besides the hierarchical structure, it also presents a list of panels and devices on the left-hand side and highlights them in bold in the hierarchical tree display.

Clicking on a panel node in the left-hand list redisplays the tree on the right, with all the tree nodes except the selected panel or device collapsed. Here we select the panel H-2:

Here, transformer T1 is selected instead:

Being modeless, the form remains visible and can be navigated after the command has terminated. You can leave the form open and switch back and forth between it and Revit to explore the electrical system simultaneously from both points of view. Note, however, that updates to the model will not be reflected in the dialogue until the command is re-executed. A sample model elec_project.rvt is provided. Also note that this was originally implemented a long time ago and does not take all of Arnošt's recent advice on interaction with a modeless dialogue and avoiding too much use of the Idling event into account. On the other hand, the modeless form never attempts to make any use whatsoever of the Revit API, so there should be nothing to worry about in this case.

Besides the connection hierarchy tree, the electrical sample also implements these other commands:

• Obsolete pre-connector approach
• Three-tier system browser structure
• Find un-hosted elements

The obsolete pre-connector parameter-based approach is still included in the source code, in the C# module CmdElectricalHierarchy2.cs, but has been removed from the user interface.

The system browser three-tier structure is also displayed in a tree structure, like this:

The un-hosted element command simply displays a Windows message box listing all elements, which may well overflow the screen in a large untidy model:

As said, I documented some other aspects of this sample in the last few years' Revit MEP API classes at Autodesk University and the AEC DevCamp two years back, so if you really want to know still more, you might be lucky there. I think this just about covers it, though, actually more than enough.

Here is adn_rme_2013.zip containing the full Visual Studio solution, source code, add-in manifest and electrical and HVAC sample models to run this and play with. Enjoy.

Many thanks once again to Martin Schmid for motivating and helping me set up the HVAC sample back then, many years ago, and many other inspiring impulses since!

US Army Corps of Engineers Revit Templates

Here is a little piece of news that just happened to come past my way and might be of interest to you as well, even though it is not API related:

The US Army Corps of Engineers ASACE has released version 1 of their Revit Architecture, Structure, MEP templates.

These templates were developed to standardize MILCON production documentation and deliverables created by in-house USACE staff to reduce project start-up and configuration lead times, improve the quality and consistency of the contract deliverables and increase the adoption of BIM in general.

If you are interested in this fiscal year's opportunities with USACE, here are some interesting links:

• Federal Business Opportunities
• Federal procurement bidding opportunity search
• USACE FY12 Acquisition Forecast – Military Construction

The Revit 2013 MEP API and External Services

I mentioned a few MEP-specific enhancements in the Revit 2013 API. To recap, the enhancements include:

• Access to routing preferences, selection of pipe sizes, materials, fitting types, and the RoutingPreferenceTools SDK sample demonstrating its use
• Pipe and duct friction factors
• MEPSection base class for duct and pipe sections
• Viscosity and density at specified temperatures, new FluidType and enhanced FluidTemperature classes
• Read and write access to panel schedule spare circuit values
• Access to localized user-visible display strings for enumeration values via new LabelUtils.GetLabelFor overloads
• ConnectorProfileType and PartType enumeration changes
• ConnectorElement changes in the family environment, and new static creation methods replacing the obsolete ones on the FamilyItemFactory class.
• A new ThermalProperties class, thermal material assets, thermal information in gbXML
• New calculation functionality and the external services framework
• MEP piping, system routing and centre line functionality
• A new Light and Light Group API
• ReferenceIntersector class

For more information on these and many other Revit API enhancements, please refer to the What's New section of the Revit API help file RevitAPI.chm.

Here are some additional notes on the external services framework:

External Services Framework

The new External Services framework wraps external service functionality, enabling certain services such as analysis or calculations to be encapsulated and replaced, providing a basis for future MEP calculations and structural code checking. The following excerpt from the Revit API help file RevitAPI.chm description of the new ExternalService class provides a pretty good idea of its use:

This is a base class from which SingleServerService and MultiServerService classes are inherited. It implements all basic methods, and the inherited classes add more specific methods. Use this base class to get information about a service and its servers, and the inherited classes to set or get active servers. Functionality:

• Add and remove a server to and from a service
• Query information about a service
• Access servers currently registered for a service
• Get and set active server (or servers) for a service

Although the framework is in place and fully functional in Revit 2013, no in-house external services making use of external servers have yet been implemented. For this reason, no examples of this framework have yet been provided.

The next thing I intend to do regarding Revit MEP is migrate my trusty old AdnRme sample and MEP sample code for Revit 2012 to Revit 2013.