The Building Coder

CouchDB Implementation and GitHub Repository

I more or less completed the research for my cloud-based round-trip 2D Revit model editing project.

I'll describe some parts of that, and also address

• Three aspects of life and programming
• Room editor navigation
• Nested asynchronous database call-back functions
• Roomedit – my first GitHub project
• Debugging JavaScript with Firebug
• Open source components used by Autodesk
• Retrieve slabs above specific walls

Lazy, Simple and Perfect

You will like the first slide of my upcoming tech summit presentation.

I start off with a couple of quotes on three fundamental aspects of software engineering and life in general:

• Lazy
• ... develop the three great virtues of a programmer: laziness, impatience, and hubris – Larry Wall
• Simple
• Simplicity is the ultimate sophistication – Leonardo da Vinci
• There is no greatness where there is no simplicity – Leo Tolstoy
• KISS
• Perfect
• Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away – Antoine de Saint-Exupéry

Basically, I demonstrate how easy it is to implement simple model navigation and 2D graphical editing using server-side scripting so that it works on all mobile devices.

So it is all about keeping it simple and easy.

Room Editor Navigation

The last instalment on this topic included a two-minute minimal demo recording illustrating its use and started describing the simplest aspect of the implementation, the server-side generated index.html home page that lists all models and prompts to select one of them.

From there, one navigates through the hierarchy of model > level > room > furniture and equipment. The latter finally reference the symbol objects that determine their geometry.

Now lets move on to the more interesting parts where the inter-related objects need to execute more complex queries to establish their relationships. I still have not covered the juicy part of rendering the SVG model, and the even juicier part of interacting with it, editing it, and updating the database with the changes made, either.

As said, the navigation logic is pretty trivial:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

Basically, the entire implementation is all squeezed into one single overgrown index.html file.

Moving on from the home page to the second simplest part of it, we have selected a specific model and list all the levels it contains.

This navigation takes place by invoking the same index.html URL and adding a modelId parameter to it.

This parameter is picked up and used to query the database for all levels in the specified model.

To retrieve only the required ones, I use a CouchDB view mapping model id keys to level documents like this:

  map_model_to_level = {
    map: function (doc) {
      if( 'level' == doc.type ) {
        emit(doc.modelId, doc);
      }
    }
  };

I can specify a key to CouchDB when querying this view, i.e. make a REST API call with a parameter like this:

  .../roomedit/_design/roomedit/_views?key=12345

This will retrieve only those level documents from the database whose modelId value matches the given key.

Here is the part of index.html handling that interaction:

. . .

else if ( paramdict.hasOwnProperty( 'modelid' ) ) {

  //======================================================
  // display a menu of all levels in selected model
  //======================================================

  var mid = paramdict['modelid'];
  db.getDoc( mid,
    function(err,resp) {
      if (err) {
        return alert(JSON.stringify(err));
      }
      var modeldoc = resp;
      db.getView('roomedit',
        'map_model_to_level',
        { key: JSON.stringify(mid) },

        function (err, data) {
          if (err) {
            return alert(err);
          }
          var n = data.rows.length;
          for (var i = 0; i < n; ++i) {
            var doc = data.rows[i].value;
            if( doc.modelId != mid ) {
              alert( 'model ids differ: doc '
                + doc.modelId + ", url " + mid );
            }
            var s = url + '?levelid=' + doc._id;
            $('<li/>')
              .append($('<a>').attr('href',s).text(doc.name))
              .appendTo('#navigatorlist');
          }
          var p = $('<p/>').appendTo('#content');
          p.append( $('<a/>').text('Home').attr('href',url) );
          p.append( document.createTextNode( three_spaces ) );
          p.append( $('<a/>').text('Back').attr('href',url) );

          $('<p/>')
            .text( 'Please select a level in the list below.' )
            .appendTo('#content');

          var table = $('<table/>').appendTo('#content');
          table.append( '<tr><td>' + 'Model:'
            + '</td><td>' + modeldoc.name + '</td></tr>' );

          var prompt = n.toString() + ' level'
            + pluralSuffix( n ) + ' in model ';

          var p = $('<p/>').text( prompt ).appendTo('#content');
          p.append( $('<i/>').text( modeldoc.name ) );
          p.append( document.createTextNode( dotOrColon( n ) ) );
        }
      );
    }
  );
}

As I already mentioned, this is populating an super simple HTML skeleton containing the following nodes:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

Here is the result in a model named 'Roombook' containing a single level 'Fondations':

Nested Asynchronous Database Call-back Functions

One challenge for me in the room editor CouchDB implementation was understanding how the asynchronous database call-back functions work, and how I can nest them to retrieve all the results I need.

In the case above, the situation is still very simple: I need to perform two database queries:

• Query a specific document, the model, using the db.getDoc function.
• Query all the levels it contains, which are returned by the map_model_to_level view with the model id key, using the getView function.

Both the getDoc and getView functions take an asynchronous call-back function as an argument.

I found out the hard way that I can nest these within each other to ensure that I have all up-to-date results before I display my page.

This gets a bit more hairy as the number of queries and thus the number of nested functions grows...

Roomedit – My First GitHub Project

Anyway, I have it all happily running now, and published the roomedit CouchDB application implementing this as my first ever GitHub project.

Debugging JavaScript with FireFox FireBug

Everybody makes errors. In my HTML and JavaScript code, these sometimes caused my index.html not to display anything at all.

Often this was due to some trivial JavaScript typo that would have been really hard to chase down.

Enter Firebug, thank God.

This is a great tool that I have started to rely on greatly to help me out of tight corners.

The Firebug debugging console is integrated in FireFox and includes support for examining and debugging all kinds of aspects of a web page.

You can open the Firebug console on any web page through Tools > Web Developer > Firebug > Open Firebug. That displays a new panel at the bottom of the browser with tabs for

• Console
• HTML
• CSS
• Script
• DOM
• Net
• Cookies

I use Console and Script, mostly.

The former displays the location of a JavaScript error and jumps to it when loading the file. It also lists the URLs visited and stuff like that, which is very useful for analysing the REST API calls being made.

The script tab provides a JavaScript debugger allowing you to set breakpoints and analyse variable values etc.

There are lots of tutorials and documentation available on this feature, such as these ones on Firebug and JavaScript debugging, so I will not trouble you any further with my description.

To tell the truth, though, I never looked at any of them.

The thing just worked for me, is incredibly valuable, and I am grateful.

Screen Snapshot on Mobile Device

Here is a quick guide how to create a screen snapshot on various types of mobile devices:

• iPhone – Press the Sleep/Wake and Home buttons together; the screen will fade temporarily, signalling that the screen shot was saved in your Camera Roll:
  
• Android – Press the Power and Home buttons together, or hold down the Lock/Power and Volume Down buttons together:
  
• Windows 8 – Press the Lock/Power and Home/Windows buttons together:
  

Open Source Components used by Autodesk

A colleague pointed out this open source repository containing all open source components used in AutoCAD, Map 3D and other Autodesk products.

I was actually surprised how short the list is. Anyway, it might be useful to know about.

Retrieve Slabs Above Certain Walls

Let's wrap this up with a standard Revit API question:

Question: I want to determine the slab above the walls of a particular room.

How can retrieve those using the Revit API, please?

Answer: As so often in Revit, there are a number of different possibilities, and it depends in part upon how the building has been modelled.

In a structural model, you may be able to query the analytical support data. I have no idea whether this information is included there, but my naive assumption would be that this should be possible.

Much more generally, you can analyse and query the geometry in a number of different ways.

The two possibilities that immediately spring to mind are:

• Use the ray casting functionality provided by the Document FindReferencesWithContextByDirection method and the ReferenceIntersector wrapper class.
• Use the geometric proximity functionality provided by some element filters, e.g.

The discussion on determining the columns supporting a beam demonstrates several different variations of the latter. Earlier blog posts include examples of the former as well.

Response: I was able to use the functionality for finding the supporting columns for beams from your link to solve my issue as well.

In my case, beam.GetGeneratingElementIds returns the desired supported floors.

I also tested using an ElementIntersectsSolidFilter to retrieve all walls that intersect the floor using the floor solid geometry object:

  Solid solid = null;
  ElementFilter slabIntersectFilter
    = new ElementIntersectsSolidFilter( solid );
 
  FilteredElementCollector walls
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfClass( typeof( Wall ) )
      .WherePasses( slabIntersectFilter );

This also solved my issue. It can be the alternative when beams are not there.

DWG Issues and Various Other Updates

One of the highlights mentioned in the overview of the Revit 2014 API is the FreeForm element API that enables modification of solid geometry imported from DWG or SAT.

Several other new DWG and DXF related features include import of DXF markup, import and link of SAT and SketchUp, and access to the DWG, IFC and DGN layer, linetype, lineweight, font and pattern tables.

One result of these enhancements is the possibility to access 3D coordinates in DWG import for the first time.

Besides looking at that, I'll also point out a few other issues further down:

• Differentiate Label and Text in DWG export
• Element Ids in extensible storage
• All-zero language codes in the Revit product GUID
• Another dockable panel sample

Access to 3D Coordinates in DWG Import

One DWG import aspect that has often been requested by developers in the past is the ability to explode 3D DWG files and obtain the resulting coordinates in the Revit project.

Revit 2014 families now provide the ability to explode and retain such 3D geometry.

Daniel Gijsbers discusses making use of this functionality to correlate Civil 3D alignments with Revit Structure.

In Revit 2013, one alternative way to achieve this was to implement an AutoCAD add-in that analyses the geometry and exports the 3D coordinate data. A separate Revit add-in could read the coordinate data and correlate it with the Revit geometry.

Differentiate Label and Text in DWG Export

On a related topic, how can I differentiate between Revit text and label elements after they have been exported to DWG?

Revit Export to DWG results in Labels becoming Text rather than Attributes, as most users might prefer.

It would be interesting to have some flag or embedded information in the exported text that could be used in an AutoCAD application to post-process the information received from Revit and restore the attribute information.

Happily, the exported Labels have Extended Entity Data like this attached:

  TypedValue 0 - type: 1001, value: REVIT
  TypedValue 1 - type: 1002, value: {
  TypedValue 2 - type: 1070, value: 1
  TypedValue 3 - type: 1000, value: 245287
  TypedValue 4 - type: 1002, value: }
  TypedValue 5 - type: 1002, value: {
  TypedValue 6 - type: 1070, value: 5
  TypedValue 7 - type: 1000, value: 243658
  TypedValue 8 - type: 1002, value: }
  TypedValue 9 - type: 1002, value: {
  TypedValue 10 - type: 1070, value: 2
  TypedValue 11 - type: 1000, value: -2000280
  TypedValue 12 - type: 1002, value: }

The xdata on Text elements, on the other hand, look like this instead:

  TypedValue 0 - type: 1001, value: REVIT
  TypedValue 1 - type: 1002, value: {
  TypedValue 2 - type: 1070, value: 1
  TypedValue 3 - type: 1000, value: 261323
  TypedValue 4 - type: 1002, value: }
  TypedValue 5 - type: 1002, value: {
  TypedValue 6 - type: 1070, value: 5
  TypedValue 7 - type: 1000, value: 209618
  TypedValue 8 - type: 1002, value: }
  TypedValue 9 - type: 1002, value: {
  TypedValue 10 - type: 1070, value: 2
  TypedValue 11 - type: 1000, value: -2000300
  TypedValue 12 - type: 1002, value: }

The differing TypedValue 11 is consistently -2000300 for a text and -2000280 for a label element.

What does this mean?

Well, is actually quite easy.

On seeing these large negative numbers in this specific range, an experienced Revit developer will quickly suspect built-in category or parameter enumeration values.

You can check what they actually represent in the Visual Studio debugger, by jumping to the definition of these enumerations and searching for the specific values.

Looking back at an ancient blog post on the DWG and DXF export Xdata specification confirms that these numbers do indeed represent the built-in category of the source element and thus can be used to distinguish the two.

Many thanks to Dale Bartlett, CAD-BIM System Manager at Atkins (Oman), for suggesting this topic.

Dale adds:

It will be interesting to see if this generates any comments.

As far as the AutoCAD geometry export, the purpose was to build a 3D Space Frame from an engineer’s analysis drawing. I did in fact write an XML file from AutoCAD of the geometry and imported it into Revit to build the frame.

It took an hour to build 20,000 elements, which was about a year less than doing it manually!

I’ll revise it with 2014 to make it a one-step-inside-Revit process.

Element Ids in Extensible Storage

Question: I need to store ElementId data using schemas within my Revit add-in.

However, the API documentation states that "ids are subject to change during an Autodesk Revit session and as such should not be retained and used across repeated calls to external commands."

My add-in will be used in a worksharing environment. My testing shows that if I try to save the integer value of an element id, and it changes, my saved id value will be invalid. However, if I store the actual ElementId in a schema I do not have this problem.

Is saving the ElementId using a Schema safe? If not, do you have any suggestions or examples of how to safely store an identifier to elements in a schema?

Answer: Yes, it is completely safe to store ElementId data in extensible storage for the purposes you describe.

The statement you quote refers to the fact that the integer value of an element id will change between sessions. Basically, you can think of it as a pointer. When stored as an element id in extensible storage, the actual links between the associated elements are stored, and the resulting integer values are recalculated from scratch in every new session, maintaining the links intact. The integer value of an element id may be changed by worksharing updates as well, and these changes are also automatically handled for element ids stored in extensible storage, so it is perfectly safe to save them there.

All-zero Language Codes in the Revit Product GUID

Watch out for all-zero language code identifiers in the Revit Product GUID due to the new Multiple Language Interface, or MUI, used in Revit 2014.

For details, please refer to the Revit Product 2014 GUID addendum.

Another Dockable Panel Sample

Guy Robinson published another dockable dialogue sample which does not require a command to be registered.

For details, please refer to the simpler dockable panel addendum.

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.

Removing Unused Mac Architectures, Languages and Files

Nature abhors vacuum, and every disk fills up.

This Mac has a 500 GB SSD, which is great, but gradually getting cramped.

Looking around for some disk space management tools, I also happened to stumble across Monolingual and made immediate and effective spontaneous use of it.

Mac programs come with bundled resources for multiple PC architectures and languages.

Monolingual is a program for removing unnecessary resources in order to reclaim several hundred megabytes of disk space.

It does exactly what it promises fast and effectively with zero hassle.

I first removed unneeded architectures from my installed program resources:

That saves a modest 30 MB of disk space:

Then I went for the list of languages, which is significantly longer:

Monolingual is clever enough to automatically uncheck all the languages that I currently have in use in my personal language settings from the list.

That saves 1.7 GB of disk space:

This is a pretty worthwhile result for a two-minute installation and two-minute execution process.

Add ten minutes of documentation time to that, and this is what you get.

I wish you a pleasant Sunday!

The weather here is pretty dreary, cold and windy, in case you hadn't guessed... :-)

Lifehacker and Disk Inventory X

While I was at it anyway, I also looked for a disk analyser.

I chanced upon a very illuminating and well-written article by lifehacker recommending Disk Inventory X, which I downloaded and tested.

Lifehacker looks pretty useful and competent in general, by the way.

Disk Inventory X produces an extremely clear overview of the disk usage:

Highly recommended, judging from my first impression.

It will still take some time and effort to explore exactly where I can efficiently save space, though...

Shortly thereafter I can report that I found some quick candidates such as the GarageBand support libraries, accounting for 1.4 GB of space, and XCode. I was forced to install it to obtain some libraries and Unix development tools, but I don't really need XCode itself, and it takes up over 3 GB.

Those are some significant savings...

Source Code Formatting and Google Prettifier

As you know, I format my source code to pretty short lines in order to avoid having them truncated by the narrow blog post view column.

I also like to present the code colour coded, as it appears in Visual Studio and many other programmer editors, to make it more readable.

For .NET code, I use CopySourceAsHtml inside of Visual Studio for that.

I tried using other tools outside of Visual Studio instead in the past, including building my own, but they have one big disadvantage: unless they read and analyse all the referenced .NET assemblies to determine the classes they define, they cannot always tell whether a given word represents a variable or a class. Classes are highlighted in a different colour in Visual Studio, and I find that pretty helpful.

For other languages, though, it would be really nice to be able to colourise the source code independently.

My colleague Cyrille Fauvel now pointed to two online colourising tools that he has used: the syntax highlighter and Google prettify. Both of them are not really useful for C#, for the reasons explained above, but do a really good job on other languages.

I tested the Google prettifier on some JavaScript, HTML and JSON code in my recent post on my cloud-based editor home page implementation and am very happy with the results.

For instance, here is a screen snapshot of the main JavaScript snippet before integrating the prettifier:

Afterwards, it looks like this instead:

I only have to do two things to achieve that.

1. Add a reference to the Google Prettify loader:

<script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js">
</script>

2. Add the 'prettyprint' class to my HTML 'pre' tags:

<pre class="prettyprint">

That's not much :-)

It comes in really handy right now, since I will be publishing more JavaScript, HTML and JSON for the final stages of my cloud-based 2D room editor in the next few days.

Many thanks to Cyrille for pointing this out!

Think Global, Act Local, Control Freak

After mulling over the above during the night, I decide to take control myself rather than go off and ask Google for help to render every page I post (and pass them every snippet of code to render, by the way).

So I downloaded the minimised version of the Google prettifier and now serve it up locally from The Building Coder typepad page itself.

In other words, I include the following script load statement instead of the one listed above:

<script src="http://thebuildingcoder.typepad.com/google-code-prettify/run_prettify.js">
</script>

Beyond that, nothing changes.

More Magic

Oh yes, and another magical little thank you to Cyrille for pointing out the Apple Magic Mouse to me.

I have been using it for a few days and am enthused.

I first thought it was a bit too slim for my chunky hand, but that is not the case, and I really love the perfect smoothness and full control it gives, better than any other system I tried.

Thank you again, Cyrille :-)

Add-In Wizards for Revit 2014

I updated my Visual Studio Revit add-in wizards and am taking the time to publish them today, which is Ascension Day and a holiday in Neuchâtel.

That also gives me some extra time to prepare for the June 3-4 Tech Summit presentation of my cloud-based round-trip 2D Revit model editing project.

The presentation must be pre-submitted by May 20, and a full recording by May 27, so pressure is rising. I completed the implementation and still want to catch up on documenting it here on the blog as well. You will be happy to hear that the auto-updating functionality using the Idling event now works fine.

Old and New Wizardry

I am starting to create numerous Revit 2014 add-ins now for quick testing purposes. As soon as that stage is reached, I immediately update my Visual Studio Revit C# add-in wizard.

The 2014 version generates the same boiler-plate code as the Revit 2013 one did, which can be simply deleted if not needed.

Last time around, I egoistically did not implement the VB version until later.

This time though, better realising how much appreciated it is, I took care of that as well, right up front.

It is important to understand how easy it is to modify the wizards for your own needs, and make copies with variations to support different requirements.

Here is an overview of previous explanations of various aspects that also show how create your own flavours:

• Original introduction, benefits, and usage example for C# and VB.
• Personalised minimal C# version for Revit 2011.
• A short additional usage note.
• 64-bit versions for C# and VB.
• Support for the Revit 2012 API for C# and VB.
• Updated C# and VB versions placing assembly DLL alongside add-in manifest and including other changes.
• Revit 2013 C# version including more skeleton code.
• Revit 2013 VB version.

Installing to non-x86 Program Files

I had a new issue to struggle with this time around, mentioned in the list above as well, dealing with 64-bit systems.

My Windows 7 virtual machine is a 64-bit system.

The $(ProgramFiles) used in the Visual Studio project template file automatically resolves that to "C:\Program Files (x86)", which is the wrong location.

Revit 2014 is installed in "C:\Program Files" with no x86 suffix.

Researching this, I found a resolution described and explained in this discussion on MSBuild and $(ProgramFiles) issue with 32/64 bits.

Unfortunately, that did not work at all. MSBuildExtensionsPath64 is not recognised in the Visual Studio wizard, at least in my simple use of it.

In the end, I simply checked what system variables are actually set on my system and found ProgramW6432 instead. That works fine.

Now both the C# and the VB versions work perfectly for me.

Revit Add-in Wizard Usage

I can simply install the wizard zip files in the appropriate locations, start up Visual Studio, create a new C# or VB Revit add-in project using the wizard default settings, and immediately hit F5 to start up Revit.exe in the debugger.

Revit is started up, my add-in is automatically loaded, and I am able to click on my new external command in the External Tools menu to test it immediately without having entered even one single byte of code myself.

The new command even executes in zero document state, although the default external command skeleton implementation throws an exception trying to access a property on the current UI document, which is null. It shows you that everything is working correctly right away, though.

Revit 2014 C# and VB Add-in Wizard Download

So, what are the appropriate locations, then? And where are the zip files?

Right here!

To install, simply copy the zip file of your choice to the matching Visual Studio project template folder in your local file system:

• Revit2014AddinWizardCs.zip – copy to
  [My Documents]\Visual Studio 2010\Templates\ProjectTemplates\Visual C#
• Revit2014AddinWizardVb.zip – copy to
  [My Documents]\Visual Studio 2010\Templates\ProjectTemplates\Visual Basic

I hope you find this useful and look forward to your suggestions for improvement.

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.

My Cloud-Based 2D Editor Implementation and Status

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, here are some issues I tackled since my last report:

• Updated project description and status
• CouchDB SVG editor implementation
• Home page: list all models and select one

Updated Project Description

I originally thought I would be implementing three cooperating components: the Revit add-in, a cloud-based data repository, and a browser-based JavaScript SVG viewer and editor client for the mobile devices.

After struggles with and resolution of the same origin policy, I discover that I need to use server-side scripting instead, which moves all the JavaScript and SVG handling to the cloud-based data repository component as well.

I updated my proposal accordingly as follows:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device
using Server-side Scripting, CouchDB and SVG

I demonstrate round-trip editing a 2D rendering of a Revit model on any mobile device with no need for installation of any additional software whatsoever beyond a browser.

How can this be achieved?

A Revit add-in exports polygon renderings of room boundaries and other elements such as furniture and equipment to a cloud-based repository implemented using a CouchDB NoSQL database.

On the mobile device, the repository is queried and the data is rendered in a standard browser using server-side generated JavaScript and SVG.

The rendering supports graphical editing, specifically translation and rotation of the furniture and equipment.

Modified transformations are saved back to the cloud database.

The Revit add-in picks up these changes and updates the Revit model in real-time.

All of the components used except Revit are completely open source.

This round-trip editing workflow is based on the following main components:

• A Revit add-in that determines room boundary and furniture and equipment family instance polygons for a simplified 2D plan view rendering.
• A cloud-based database repository managing the models, levels, rooms, furniture, equipment meta- and polygon data.
• A server hosted JavaScript SVG editor running in the browser on any device, rendering the model and supporting simple geometric modification of the model.

The presentation outline, the final proof of the pudding, looks like this:

• Show a Revit model.
• Export the model to a cloud-based data repository.
• Query and display the repository contents as a 2D rendering on a mobile device.
• Edit the model in the browser on the mobile device, updating the data repository.
• Watch the BIM in Revit auto-update.

I have now completed the implementation of all these steps with the single minute exception of the prefix 'auto'.

In other words, I currently have two commands in my Revit add-in:

• CmdUpload uploads the room and equipment boundary data to the cloud repository, either from a manually selected set of rooms, or all rooms in the model.
• CmdUpdate retrieves the changes applied to furniture and equipment on the mobile device. This is currently a command triggered by the user.

The next step for me will be adding the 'auto' to the update, i.e. the implementation of an external event that subscribes to changes in the cloud database caused by the user editing the furniture and equipment transforms on the mobile device and automatically applies real-time updates to the BIM.

Before I get to that, though, I have a huge backlog of information to share about all that has already been achieved, and how.

Without further ado, here is a little two-minute film demonstrating the current functionality to give you the idea:

CouchDB SVG Editor Implementation

I described the room editor database structure consisting of the model, level and room hierarchy.

Furniture and equipment instances are placed within the room and refer to separate symbol objects that store their geometry.

Two of the main tasks listed in my last to-do list were:

• Implement the rendering and editing of the 2D plan view in SVG on the mobile device.
• Reflect the modifications made back to the cloud-based CouchDB data repository.

Let's look at how I achieved that.

First, I must admit that I struggled quite a bit and burnt a significant amount of night oil on this. Maybe it would have been more efficient to do some reading up on basics before starting. Instead, I found various tutorials that did "almost" what I wanted that I tried to reproduce and tweak. Each and every one finally turned into a dead end, and I was thrown back to square one, or sometimes square 1.15 or so.

One impressive little sample application that really did help was Opto3, a small CouchDB application entirely hosted within CouchDB. It uses JQuery Mobile to serve a single-page mobile application that presents a four-panel drill-down approach to find an optometrist in a desired US location.

All the information stems from one single CSV file of US optometrician addresses. Here is its description, GitHub project repository and CodeProject article that also provides a useful list of additional references.

As said, I can use Kanso to maintain and install the database, push the views and upload my documents in JSON format to the local CouchDB database 'roomedit' using commands such as these:

$ kanso install

$ kanso push http://localhost:5984/roomedit

$ kanso upload mydata.json http://localhost:5984/roomedit

I ended up implementing my totally own version of a CouchDB application, unlike anything I saw in any of the samples.

Basically, I only use a couple of CouchDB views and a rather heavy-weight index.html file that renders them for various contexts, guiding the user through the model and room selection process and finally displaying the SVG editor page.

The selection logic is simple:

• Home page: list all models and prompt to select one of them.
• Model selected: list all levels in model and prompt to select one of them.
• Level selected: list all rooms on the level and prompt to select one of them.
• Room selected: display the room boundary and the furniture and equipment instances graphically and enable editing their location and rotation.

The first three steps were not so hard once I understood about CouchDB views and discovered how to render them in index.htm.

Integrating the SVG editor posed some really tough problems, but ended up being really simple as well.

For a while I was unsure whether I would be able to use the Raphaël JavaScript SVG library as is, or whether it needed to be packaged as a Kanso package. As it turned out, that was not necessary. Until I discovered that the hard way, though, I tried to avoid the use of any non-Kanso libraries at all, and struggled with SVG editing issues instead.

So let's start by looking at the simplest step first, how to list all models and prompt the user to select one of them.

Home Page: List all Models and Select One

The initial home page of my application is very simple. It looks like this, listing the available models and prompting the user to select one of them:

I represent each Revit model as a separate CouchDB document. All the data it carries is inherited from the DbObj base class, which specifies its type "model", description and name. I populate the two latter with information from the Revit ProjectInfo singleton object, and I use the Revit UniqueId as the CouchDB document identifier as well.

The resulting CouchDB JSON representation of my sample model looks like this (copy to an editor or view the HTML source to see the truncated lines in full):

{
  "_id": "bf0552b6-b7f7-4331-96d5-b19843262895-00015084",
  "_rev": "14-4e1c947c3d3e354117a1f016f2e23f63",
  "type": "model",
  "description": "ProjectInfo Project Information <86148 Project Information>",
  "name": "room_with_hole.rvt"
}

CouchDB implements and extremely scalable architecture and can host millions of documents.

Views are used to efficiently extract the ones required. A view can implement a map and a reduce function. The map function identifies the documents of interest and maps them to a key-value pair. The optional reduce function can be applied to reduce the results by accumulation or other means. I have no use for reduce in my application.

To list all available models, I use an utterly trivial view function that does not even create real key-value pairs. All I need is to extract all model documents and list the model document information itself, so I just emit all model documents as keys directly:

exports.models = {
  map: function (doc) {
    if( 'model' == doc.type ) {
      emit(doc, null);
    }
  }
};

To render the results of the view into my HTML target file, I define the following scaffolding:

  <h1>Room Editor</h1>

  <div id="content"></div>

  <ul id="navigatorlist"></ul>

In the JavaScript section, I require the Kanso db and jquery packages:

  var db = require('db').current();
  var $ = require('jquery');

The db package provides access to the current CouchDB database, and jquery is a Kanso wrapper for the standard jquery library.

Oh, and what is Kanso itself? Kanso is a framework enabling me to maintain my CouchDB views and other bits and pieces in standard file system files on the hard disk and upload them easily to the CouchDB database.

With that in place, the following JavaScript code queries the 'models' view and populates the HTML placeholder tags:

// display a menu of all available models

db.getView('room_loops', 'models',
  function (err, data) {
    if (err) {
      return alert(err);
    }
    var n = data.rows.length;
    for (var i = 0; i < n; ++i) {
      var doc = data.rows[i].key;
      var s = url + '?modelid=' + doc._id;
      $('<li/>').append($('<a>')
        .attr('href',s)
        .text(doc.name))
      .appendTo('#navigatorlist');
    }
    var p = $('<p/>').appendTo('#content');
    p.append( $('<a/>').text('Home').attr('href',url) );
    p.append( document.createTextNode( three_spaces ) );
    p.append( $('<a/>').text('Back').attr('href',url) );

    $('<p/>')
      .text( 'Please select a model in the list below.' )
      .appendTo('#content');

    var prompt = n.toString() + ' model'
      + pluralSuffix( n ) + dotOrColon( n );

    $('<p/>').text( prompt ).appendTo('#content');
  }
);

As you can see, the db.getView method is provided with three arguments: the database name, the view name, and a call-back function.

Understanding how the call-back function works was another big stumbling block for me.

In this simple case, all is clear, of course.

We submit the query to get the view and return immediately.

CouchDB processes the request and invokes the call-back function when completed.

The call-back function processes the resulting data rows, extracting the model document data from the key provided with each row and populating the HTML scaffolding accordingly.

Again, here is the final result with two models listed, just as you can see in the video above:

Well, I am spending much too much time documenting this for you, and really need to get on with the implementation and my real day work, so I will call it wraps for today now.

Revit 2014 SDK and Visual Debugging Tools

Two hot topics for today, especially the first:

• Updated Revit 2014 SDK
• Visual debugging tools

Updated Revit 2014 SDK

An updated Revit 2014 SDK is live on the ADN Open Revit developer page now:

www.autodesk.com/developrevit

This version includes RevitLookup and the AddInManager!

Visual Debugging Tools

Rudolf Honke of Mensch und Maschine acadGraph GmbH discovered a glitch in the definition of the room solids in one of the standard sample RVT project files.

Rudi says: When testing VRML exporter with Revit 2014, I noticed that the brand new rac_sample_project.rvt has some inconsistencies.

I export the ClosedShells of the rooms into VRML format to display then in my browser. On the left side you see overlapping room volumes from 'Hall' and 'Entry Hall':

'Kitchen and dining' has an upper edge that needs to be cut off:

'Hall' has two ears protruding into the sky:

I noticed this when debugging the funny results my application was producing.

Since it is not the code, I concluded it must be the input that was corrupted…

Without a visual tool like this, it is quite hard to evaluate what's wrong.

Jeremy adds: You can also observe this using the Export > gbXML command:

'Kitchen and dining' has an upper edge that needs to be cut off:

'Hall' has two ears protruding into the sky:

Furthermore, the Revit 2014 program folder contains a utility named gbXML2dwfx.exe.

If you drag and drop a gbXML file onto this it will create a DWFx file that can be viewed in Autodesk Design Review, the free 2D and 3D DWF viewer, which provides more functionality than many VRML viewers.

Response: Interesting. GbXML2Dwfx.exe appears to be new in Revit 2014.

Regarding the geometry, it is important to note that you cannot rely on geometrical integrity of your Revit Elements.

I faced this problem previously, not only with rooms but also with walls.

Every cut-off and every Boolean operation makes the geometry more complex, and rounding errors may occur.

This totally confirms the GiGo principle of Garbage in, garbage out, slightly less helpful than FiFo...

Transactions, Sub-Transactions and Transaction Groups

Here is a recent query from a developer that led to a nice succinct overview of transactions, sub-transactions and transaction groups by Arnošt Löbel.

This makes a change from the recent rash of monster posts. The last ten posts were all rather overwhelming in size, and hopefully impressive in content as well. From Aril 16 until 29, I posted a total of 26228 words, 245504 bytes.

So let's keep this one short, sweet and to the point.

Question: When should I use a transaction group with transactions versus transaction with sub-transactions?

At first glance, it looks as if both can achieve the same result, but there must be some kind of difference, mustn't there?

Answer: This question is actually covered at large in the API documentation for the respective classes. Of course, you could write a whole book about the detailed usage of transaction phases (i.e. Transaction, Transaction groups, Sub-Transaction), if you wanted to, but the documentation already covers all the really necessary information.

Here is a brief summary:

• A transaction is a phase that is needed to make modifications to a model. A transaction is undoable. Once committed, it appears on the undo/redo menu, where the end user can make it undone or later redone. Transactions cannot be nested, for only one client can modify the model at any given time.
• A sub-transaction marks a phase within an open transaction. It is to control (if a control is needed) a set of modifications done in a transaction, meaning that the modification enclosed in a sub-transaction can be rolled back as if they have not happened. In a sense, it allows an application to go back to a certain point (the start of the sub-transaction) in a sequence of model changes. Sub-transactions can be nested. A sub-transaction cannot be undone/redone once committed.
• A transaction group can control a set of transactions in the sense that even transaction that have already been successfully submitted can be rolled back if they were committed while inside an open transaction group. This give an application a way of undoing past transaction if some other transactions later (but still within the group) do not go as well as expected. For example, if three transactions are required (for whatever reason) to achieve something, and it is necessary to commit all three for the changes to make sense, the transactions could be controlled by a group. If the second or the third transaction fails, the whole group can be rolled back. Transaction groups can be nested, but they cannot be undone/redone, i.e. there is no trace of them in the undo/redo menu for the end user to see.

The temporary transaction trick touch-up describes a scenario using a transaction group to enable a transaction to be committed, so the model is updated and the new state can be queried, and still enabling the whole action can be undone afterwards.

For more information on the transaction framework, please refer to Arnošt's Autodesk University presentation CP3426 Core Frameworks in the Revit API.

Response: Thank you! I use the temporary transaction trick quite a lot, so I'll definitely start using transaction groups now as well.

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

Room and Furniture Loops Using Symbols

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I now implemented the first of the next steps mentioned at the end:

• Separation of symbol and instance data in my add-in and database structure: currently, the furniture loops are placed absolutely, and multiple instances of a symbol duplicate the same loop over and over again at different locations. I will rewrite this to separate the furniture loop definition, defined by the family symbol, and its placement, defined by the instance. This needs to be done anyway to enable editing the placement data through the editor interaction on the mobile device.

The first implementation just uploaded the room and furniture instance 2D boundary polygon loops, absolutely placed.

Besides converting that to defining and reusing symbols, I also added support for exporting the model and level data to the cloud.

I discuss the implementation of that here now:

• Database structure
• Database upload
• Integer based 2D placement
• Populating symbols and instances
• Retrieving the boundary loops
• GeoSnoop loop display
• Caveats
• Download
• Next steps

Database Structure

I enhanced the database classes to include a new class DbSymbol. It defines the family symbol loop, which is reused by the family instances.

The DbFurniture class no longer has its own individual loop data. Instead, it has a reference to a symbol and placement data defining its 2D translation and rotation.

All the database classes are derived from the DbObj base class:

• DbObj
• Type
• Description
• Name

Some of the derived classes have no additional properties of their own at all. The data structure is this as simple as this:

• DbModel
• DbLevel
• ModelId
• DbRoom
• LevelId
• Loops
• ViewBox
• DbSymbol
• Loop
• DbFurniture
• RoomId
• SymbolId
• Transform

The source code does nothing but exactly reproduce this structure. Here is the complete implementation of these classes:

  /// <summary>
  /// Base class for all Jeremy Room Editor classes.
  /// </summary>
  class DbObj : CouchDocument
  {
    protected DbObj()
    {
      Type = "obj";
    }
    public string Type { get; protected set; }
    public string Description { get; set; }
    public string Name { get; set; }
  }
 
  /// <summary>
  /// Current model, i.e. Revit project.
  /// </summary>
  class DbModel : DbObj
  {
    public DbModel()
    {
      Type = "model";
    }
  }
 
  /// <summary>
  /// Level.
  /// </summary>
  class DbLevel : DbObj
  {
    public DbLevel()
    {
      Type = "level";
    }
    public string ModelId { get; set; }
  }
 
  /// <summary>
  /// Room
  /// </summary>
  class DbRoom : DbObj
  {
    public DbRoom()
    {
      Type = "room";
    }
    public string LevelId { get; set; }
    public string Loops { get; set; }
    public string ViewBox { get; set; }
  }
 
  /// <summary>
  /// Family symbol, i.e. element type defining 
  /// the geometry, i.e. the 2D boundary loop.
  /// </summary>
  class DbSymbol : DbObj
  {
    public DbSymbol()
    {
      Type = "symbol";
    }
    public string Loop { get; set; }
  }
 
  /// <summary>
  /// Family instance, defining placement, i.e.
  /// transform, i.e. translation and rotation,
  /// and referring to the symbol geometry.
  /// </summary>
  class DbFurniture : DbObj
  {
    public DbFurniture()
    {
      Type = "furniture";
    }
    public string RoomId { get; set; }
    public string SymbolId { get; set; }
    public string Transform { get; set; }
  }

Database Upload

The database upload has not changed very much from the previous version, except that the model, level and symbol data is now added, and the furniture and equipment instances store their symbol reference and transformation:

/// <summary>
/// Upload model, level, room and furniture data 
/// to an IrisCouch hosted CouchDB data repository.
/// </summary>
static public void DbUploadRoom(
  Room room,
  List<Element> furniture,
  JtLoops roomLoops,
  Dictionary<string, JtLoop> furnitureLoops,
  List<JtPlacement2dInt> furnitureInstances )
{
  CouchClient client = new CouchClient(
    _web_url,
    5984 );
 
  CouchDatabase db = client.GetDatabase(
    _database_name, true );
 
  Document doc = room.Document;
 
  Element projectInfo
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ProjectInfo ) )
      .FirstElement();
 
  string uid = projectInfo.UniqueId;
 
  DbModel dbModel;
 
  if( db.DocumentExists( uid ) )
  {
    dbModel = db.GetDocument<DbModel>( uid );
 
    Debug.Assert(
      dbModel.Id.Equals( projectInfo.UniqueId ),
      "expected equal ids" );
 
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Document.Title;
 
    dbModel = db.UpdateDocument<DbModel>(
      dbModel );
  }
  else
  {
    dbModel = new DbModel();
 
    dbModel.Id = uid;
    dbModel.Description = Util.ElementDescription(
      projectInfo );
 
    dbModel.Name = projectInfo.Name;
    dbModel = db.CreateDocument<DbModel>( dbModel );
  }
 
  Level level = room.Level;
 
  uid = level.UniqueId;
 
  DbLevel dbLevel;
 
  if( db.DocumentExists( uid ) )
  {
    dbLevel = db.GetDocument<DbLevel>( uid );
 
    Debug.Assert(
      dbLevel.Id.Equals( level.UniqueId ),
      "expected equal ids" );
 
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.UpdateDocument<DbLevel>(
      dbLevel );
  }
  else
  {
    dbLevel = new DbLevel();
 
    dbLevel.Id = uid;
    dbLevel.Description = Util.ElementDescription(
      level );
 
    dbLevel.Name = level.Name;
    dbLevel.ModelId = projectInfo.UniqueId;
 
    dbLevel = db.CreateDocument<DbLevel>(
      dbLevel );
  }
 
  uid = room.UniqueId;
 
  DbRoom dbRoom;
 
  if( db.DocumentExists( uid ) )
  {
    dbRoom = db.GetDocument<DbRoom>( uid );
 
    Debug.Assert(
      dbRoom.Id.Equals( room.UniqueId ),
      "expected equal ids" );
 
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.UpdateDocument<DbRoom>( dbRoom );
  }
  else
  {
    dbRoom = new DbRoom();
 
    dbRoom.Id = uid;
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom.ViewBox = roomLoops.BoundingBox.SvgViewBox;
 
    dbRoom = db.CreateDocument<DbRoom>( dbRoom );
  }
 
  foreach( KeyValuePair<string, JtLoop> p in furnitureLoops )
  {
    uid = p.Key;
    Element e = doc.GetElement( uid );
    if( db.DocumentExists( uid ) )
    {
      DbSymbol symbol = db.GetDocument<DbSymbol>(
        uid );
 
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.UpdateDocument<DbSymbol>( symbol );
    }
    else
    {
      DbSymbol symbol = new DbSymbol();
      symbol.Id = uid;
      symbol.Description = Util.ElementDescription( e );
      symbol.Name = e.Name;
      symbol.Loop = p.Value.SvgPath;
 
      symbol = db.CreateDocument<DbSymbol>( symbol );
    }
  }
 
  foreach( FamilyInstance f in furniture )
  {
    uid = f.UniqueId;
    if( db.DocumentExists( uid ) )
    {
      DbFurniture dbf = db.GetDocument<DbFurniture>(
        uid );
 
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.UpdateDocument<DbFurniture>( dbf );
    }
    else
    {
      DbFurniture dbf = new DbFurniture();
      dbf.Id = uid;
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.SymbolId = f.Symbol.UniqueId;
      dbf.Transform = new JtPlacement2dInt( f )
        .SvgTransform;
 
      dbf = db.CreateDocument<DbFurniture>( dbf );
    }
  }
}

Integer Based 2D Placement

I implemented the following simple class to manage the 2D placement.

It is based on the 2D point class, storing the coordinate data in integers, for various reasons:

• Revit precision is no smaller than one sixteenth of an inch, ca. 1.2 mm.
• The data is stored in the cloud and rendered on a mobile device: the use of integers
• eliminates rounding issues,
• lowers the data volume,
• enhances performance,
• simplifies storage,
• improves human reading and understanding.

Since I am already using millimetres for the length measurement, I find it fitting to store the rotation in degrees. The SVG rendering expects degrees as input, anyway.

Here is the class implementation:

/// <summary>
/// A 2D integer-based transformation, 
/// i.e. translation and rotation.
/// </summary>
class JtPlacement2dInt
{
  /// <summary>
  /// Translation.
  /// </summary>
  public Point2dInt Translation { get; set; }
 
  /// <summary>
  /// Rotation in degrees.
  /// </summary>
  public int Rotation { get; set; }
 
  /// <summary>
  /// The family symbol UniqueId.
  /// </summary>
  public string SymbolId { get; set; }
 
  public JtPlacement2dInt( FamilyInstance fi )
  {
    LocationPoint lp = fi.Location as LocationPoint;
 
    Debug.Assert( null != lp,
      "expected valid family instanace location point" );
 
    Translation = new Point2dInt( lp.Point );
 
    Rotation = (int) (
      ( ( 180 * lp.Rotation ) + 0.5 ) / Math.PI );
 
    SymbolId = fi.Symbol.UniqueId;
  }
 
  /// <summary>
  /// Return an SVG transform,
  /// either for native SVG or Raphael.
  /// </summary>
  public string SvgTransform
  {
    get
    {
      return string.Format(
        "R{2}T{0},{1}",
        //"translate({0},{1}) rotate({2})",
        Translation.X, Translation.Y, Rotation );
    }
  }
}

The placement is instantiated from a family instance, and returns a suitably formatted SVG transformation string, either for native SVG or the Raphaël JavaScript SVG library.

Populating Symbols and Instances

To populate the symbol and instance data, I loop over all the instances exactly like I did previously.

Now, instead of exporting the family instance boundary loop in situ, I transform it back to the symbol definition coordinate system instead, and save that in a dictionary mapping the family symbol UniqueId to its boundary loop.

The family instance exports a reference to that symbol and its placement data:

  List<Element> furniture
    = GetFurniture( room );
 
  // Map symbol UniqueId to symbol loop
 
  Dictionary<string, JtLoop> furnitureLoops
    = new Dictionary<string, JtLoop>();
 
  // List of instances referring to symbols
 
  List<JtPlacement2dInt> furnitureInstances
    = new List<JtPlacement2dInt>(
      furniture.Count );
 
  int nFailures;
 
  foreach( FamilyInstance f in furniture )
  {
    FamilySymbol s = f.Symbol;
 
    string uid = s.UniqueId;
 
    if( !furnitureLoops.ContainsKey( uid ) )
    {
      nFailures = 0;
 
      JtLoops loops = GetPlanViewBoundaryLoops(
        f, ref nFailures );
 
      if( 0 < nFailures )
      {
        Debug.Print( "{0}: {1} extrusion analyser failure{2}",
          Util.ElementDescription( f ), nFailures,
          Util.PluralSuffix( nFailures ) );
      }
      ListLoops( f, loops );
 
      if( 0 < loops.Count )
      {
        // Assume first loop is outer one
 
        furnitureLoops.Add( uid, loops[0] );
      }
    }
    furnitureInstances.Add(
      new JtPlacement2dInt( f ) );
  }

Retrieving the Boundary Loops

The boundary loop retrieval has not changed very much, although the following significant enhancements were made:

• Store the symbol loop in the original symbol definition coordinate system.
• Store the instance transformation data.
• Manage the dictionary of symbols and the instances referencing them.
• Save intermediate tessellated curve points, not just start and end point. This functionality can be toggled on and off by setting the Boolean _tessellate_curves switch.

The implementation is separated into two methods:

• AddLoops: add the plan view boundary loops from a given solid to the list of loops.
• GetPlanViewBoundaryLoops: Retrieve the plan view boundary loops from all solids of given element united together. If the element is a family instance, transform its loops from the instance placement coordinate system back to the symbol definition one.

Here is the implementation:

/// <summary>
/// Add all plan view boundary loops from 
/// given solid to the list of loops.
/// The creation application argument is used to
/// reverse the extrusion analyser output curves
/// in case they are badly oriented.
/// </summary>
/// <returns>Number of loops added</returns>
int AddLoops(
  Autodesk.Revit.Creation.Application creapp,
  JtLoops loops,
  GeometryObject obj,
  ref int nExtrusionAnalysisFailures )
{
  int nAdded = 0;
 
  Solid solid = obj as Solid;
 
  if( null != solid
    && 0 < solid.Faces.Size )
  {
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    ExtrusionAnalyzer extrusionAnalyzer = null;
 
    try
    {
      extrusionAnalyzer = ExtrusionAnalyzer.Create(
        solid, plane, XYZ.BasisZ );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
      ++nExtrusionAnalysisFailures;
      return nAdded;
    }
 
    Face face = extrusionAnalyzer
      .GetExtrusionBase();
 
    foreach( EdgeArray a in face.EdgeLoops )
    {
      int nEdges = a.Size;
 
      List<Curve> curves
        = new List<Curve>( nEdges );
 
      XYZ p0 = null; // loop start point
      XYZ p; // edge start point
      XYZ q = null; // edge end point
 
      foreach( Edge e in a )
      {
        // This returns the curves already
        // correctly oriented:
 
        curve = e.AsCurveFollowingFace(
          face );
 
        if( _debug_output )
        {
          p = curve.get_EndPoint( 0 );
          q = curve.get_EndPoint( 1 );
          Debug.Print( "{0} --> {1} following face",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        curves.Add( curve );
      }
 
      q = null;
 
      JtLoop loop = new JtLoop( nEdges );
 
      foreach( Curve curve in curves )
      {
        p = curve.get_EndPoint( 0 );
 
        Debug.Assert( null == q
          || q.IsAlmostEqualTo( p, 1e-05 ),
          string.Format(
            "expected last endpoint to equal current start point, not distance {0}",
            (null == q ? 0 : p.DistanceTo( q ))  ) );
 
        q = curve.get_EndPoint( 1 );
 
        if( _debug_output )
        {
          Debug.Print( "{0} --> {1}",
            Util.PointString( p ),
            Util.PointString( q ) );
        }
 
        if( null == p0 )
        {
          p0 = p; // save loop start point
        }
 
        int n = -1;
 
        if( _tessellate_curves
          && _min_tessellation_curve_length_in_feet
            < q.DistanceTo( p ) )
        {
          IList<XYZ> pts = curve.Tessellate();
          n = pts.Count;
 
          Debug.Assert( 1 < n, "expected at least two points" );
          Debug.Assert( p.IsAlmostEqualTo( pts[0] ), "expected tessellation start equal curve start point" );
          Debug.Assert( q.IsAlmostEqualTo( pts[n-1] ), "expected tessellation end equal curve end point" );
 
          if( 2 == n )
          {
            n = -1; // this is a straight line
          }
          else
          {
            --n; // skip last point
 
            for( int i = 0; i < n; ++i )
            {
              loop.Add( new Point2dInt( pts[i] ) );
            }
          }
        }
 
        // If tessellation is disabled,
        // or curve is too short to tessellate,
        // or has only two tessellation points,
        // just add the start point:
 
        if( -1 == n )
        {
          loop.Add( new Point2dInt( p ) );
        }
      }
      Debug.Assert( q.IsAlmostEqualTo( p0, 1e-05 ),
        string.Format(
          "expected last endpoint to equal current start point, not distance {0}",
          p0.DistanceTo( q ) ) );
 
      loops.Add( loop );
 
      ++nAdded;
    }
  }
  return nAdded;
}

/// <summary>
/// Retrieve all plan view boundary loops from 
/// all solids of given element united together.
/// If the element is a family instance, transform
/// its loops from the instance placement 
/// coordinate system back to the symbol 
/// definition one.
/// </summary>
JtLoops GetPlanViewBoundaryLoops(
  Element e,
  ref int nFailures )
{
  Autodesk.Revit.Creation.Application creapp
    = e.Document.Application.Create;
 
  JtLoops loops = new JtLoops( 1 );
 
  Options opt = new Options();
 
  GeometryElement geo = e.get_Geometry( opt );
 
  if( null != geo )
  {
    Document doc = e.Document;
 
    if( e is FamilyInstance )
    {
      // Retrieve family instance geometry 
      // transformed back to symbol definition
      // coordinate space by inverting the 
      // family instance placement transformation
 
      LocationPoint lp = e.Location
        as LocationPoint;
 
      Transform t = Transform.get_Translation(
        -lp.Point );
 
      Transform r = Transform.get_Rotation(
        lp.Point, XYZ.BasisZ, -lp.Rotation );
 
      geo = geo.GetTransformed( t * r );
    }
 
    Solid union = null;
 
    Plane plane = new Plane( XYZ.BasisX,
      XYZ.BasisY, XYZ.Zero );
 
    foreach( GeometryObject obj in geo )
    {
      Solid solid = obj as Solid;
 
      if( null != solid
        && 0 < solid.Faces.Size )
      {
        // Some solids, e.g. in the standard 
        // content 'Furniture Chair - Office' 
        // cause an extrusion analyser failure,
        // so skip adding those.
 
        try
        {
          ExtrusionAnalyzer extrusionAnalyzer
            = ExtrusionAnalyzer.Create(
              solid, plane, XYZ.BasisZ );
        }
        catch( Autodesk.Revit.Exceptions
          .InvalidOperationException )
        {
          solid = null;
          ++nFailures;
        }
 
        if( null != solid )
        {
          if( null == union )
          {
            union = solid;
          }
          else
          {
            union = BooleanOperationsUtils
              .ExecuteBooleanOperation( union, solid,
                BooleanOperationsType.Union );
          }
        }
      }
    }
    AddLoops( creapp, loops, union, ref nFailures );
  }
  return loops;
}

GeoSnoop Loop Display

I obviously had to update my GeoSnoop display to take the symbol loop dictionary lookup into account.

I invoke it passing in the room loops, symbol loops, and instance placements:

  GeoSnoop.DisplayLoops( revit_window,
    "Room and furniture", roomLoops,
    furnitureLoops, furnitureInstances );

The new implementation displays the instances at their respective location by transforming the referenced symbol geometry accordingly.

I make use of two transformations:

• Matrix transform: Transform from native loop coordinate system to target display coordinates.
• Matrix placement: Additional transformation from symbol definition to instance location for placing an individual instance.

It also takes the aspect ratio of the room to display into account and adjusts the window height to fit, based on the room bounding box aspect ratio:

/// <summary>
/// Display a collection of loops in a .NET form.
/// </summary>
class GeoSnoop
{
  /// <summary>
  /// Pen size.
  /// </summary>
  const int _pen_size = 1;
 
  /// <summary>
  /// Pen colour.
  /// </summary>
  static Color _pen_color = Color.Black;
 
  /// <summary>
  /// Margin around graphics.
  /// </summary>
  const int _margin = 10;
 
  /// <summary>
  /// Draw loops on graphics with the specified
  /// transform and graphics attributes.
  /// </summary>
  static void DrawLoopsOnGraphics(
    Graphics graphics,
    List<Point[]> loops,
    Matrix transform )
  {
    Pen pen = new Pen( _pen_color, _pen_size );
 
    foreach( Point[] loop in loops )
    {
      GraphicsPath path = new GraphicsPath();
 
      transform.TransformPoints( loop );
 
      path.AddLines( loop );
 
      graphics.DrawPath( pen, path );
    }
  }
 
  /// <summary>
  /// Display loops in a temporary form generated
  /// on the fly.
  /// </summary>
  /// <param name="owner">Owner window</param>
  /// <param name="caption">Form caption</param>
  /// <param name="loops">Boundary loops</param>
  public static void DisplayLoops(
    IWin32Window owner,
    string caption,
    JtLoops roomLoops,
    Dictionary<string, JtLoop> furnitureLoops,
    List<JtPlacement2dInt> furnitureInstances )
  {
    JtBoundingBox2dInt bb = roomLoops.BoundingBox;
 
    // Adjust target rectangle height to the 
    // displayee loop height.
 
    int width = 400;
    int height = (int) (width * bb.AspectRatio + 0.5);
 
    // Specify transformation target rectangle 
    // including a margin.
 
    int bottom = height - (_margin + _margin);
 
    Point[] parallelogramPoints = new Point[] {
      new Point( _margin, bottom ), // upper left
      new Point( width - _margin, bottom ), // upper right
      new Point( _margin, _margin ) // lower left
    };
 
    // Transform from native loop coordinate system
    // to target display coordinates.
 
    Matrix transform = new Matrix(
      bb.Rectangle, parallelogramPoints );
 
    Bitmap bmp = new Bitmap( width, height );
    Graphics graphics = Graphics.FromImage( bmp );
 
    graphics.Clear( System.Drawing.Color.White );
 
    DrawLoopsOnGraphics( graphics,
      roomLoops.GetGraphicsPathLines(), transform );
 
    List<Point[]> loops = new List<Point[]>( 1 );
    loops.Add( new Point[] { } );
 
    foreach( JtPlacement2dInt i in furnitureInstances )
    {
      Point2dInt v = i.Translation;
      Matrix placement = new Matrix();
      placement.Rotate(i.Rotation);
      placement.Translate(v.X, v.Y, MatrixOrder.Append);
      placement.Multiply( transform, MatrixOrder.Append );
      loops[0] = furnitureLoops[i.SymbolId]
        .GetGraphicsPathLines();
 
      DrawLoopsOnGraphics( graphics, loops, placement );
    }
 
    Form form = new Form();
    form.Text = caption;
    form.Size = new Size( width + 7, height + 13 );
    form.FormBorderStyle = FormBorderStyle
      .FixedToolWindow;
 
    PictureBox pb = new PictureBox();
    pb.Location = new System.Drawing.Point( 0, 0 );
    pb.Dock = System.Windows.Forms.DockStyle.Fill;
    pb.Size = bmp.Size;
    pb.Parent = form;
    pb.Image = bmp;
 
    form.ShowDialog( owner );
  }
}

Still very short and sweet, isn't it?

Here is the result of displaying a room from the advanced sample project provided with Revit:

Those eight straight lines in the corners are columns. I should eliminate those. We don't want to move those around indiscriminately on a mobile device anyway, or the whole house might come crashing down around us.

Caveats

Rudolf Honke wrote in a reaction to my plan described last time:

You say that you want to avoid redundant geometry data in your cloud project:

As you know, it is possible to modify the geometry of an individual family instance by cutting voids off it. The geometry of such an instance differs from other ones.

As far as I remember, modifying instance geometry this way has been possible since Revit 2012 or so; the API 2013 says:

"FamilyInstance.GetOriginalGeometry: Returns the original geometry of the instance, before the instance is modified by joins, cuts, coping, extensions, or other post-processing."

Thus, there are at least three groups of elements to be handled:

• Individual elements, such as walls – have individual geometry, cannot be reused
• Family instances which have not been modified – can be instantiated, geometry is reusable
• Family instances which are post-processed, resulting in individual geometry – not reusable

In this case, I am only handling furniture and equipment instances that I do not expect to be modified.

After all, the plan is to move them around in the room, so they have to be free of constraints for it to work.

Still, these considerations obviously have to be taken into account for other applications.

Download

To wrap this up for the moment, here is GeoSnoopSymbols.zip containing the complete source code, Visual Studio solution and add-in manifest of the current state of this external command.

Next Steps

My next steps will be:

• Migrate this add-in from Revit 2013 to 2014.
• Implement server-side generated SVG code to display the room and furniture plan in CouchDB using Kanso.
• Implement editing of SVG on the mobile device and reflect changes back to CouchDB (I know how now).
• Implement Idling event handler and polling of CouchDB in the desktop add-in to reflect the changes back to the BIM in real-time.
• Implement an external application wrapper for the add-in providing four commands:
• Upload to cloud
• Refresh from cloud
• Subscribe to cloud
• Unsubscribe from cloud

I know exactly how to address all these points now, no exceptions left. Yay!

I look forward to hearing your comments and suggestions.

Migrating a Built-in Category and Other Things

Here is a category related issue that appeared when migrating from the Revit 2013 to the Revit 2014 API, plus a several other typical simple little Revit API questions from the last day or two:

• Migrating the room separation lines built-in category
• Storage of RGB colour values for materials
• Updating a DXF link
• Retrieving truss family elements
• Retrieving stair stringer data
• Storing custom data

Migrating the Room Separation Lines Built-in Category

Question: I get the following error while migrating my C# code from Revit 2013 to Revit 2014:

• 'Autodesk.Revit.DB.BuiltInCategory' does not contain a definition for 'OST_AreaSeparationLines'

It is caused by the following line of code:

  ICollection<Element> collection
    = collector.OfCategory(
        BuiltInCategory.OST_AreaSeparationLines )
      .ToElements();

Do you have any solution to suggest?

Answer: The easiest way to fix this kind of issue is to look at an element that has this category using RevitLookup in Revit 2013, and then load the same model and see what category it has in Revit 2014.

Response: That worked!

It seems to be called OST_RoomSeparationLines now.

Problem solved.

Storage of RGB Colour Values for Materials

Question: I looked at a material element 'Color' parameter value today. This parameter values comes back as an integer.

It appears to me to have the red and blue values reversed.

When looking at the 'Site – Earth' material in the rac_advanced_sample_project included with Revit, the Color property on the material class returns material.Color.Red=97, material.Color.Green=75 and material.Color.Blue=62, which is also what the Revit GUI shows in 'Manage Materials'. I checked on an online colour generator web site and it looks the same as in the Revit GUI, a dirty brown colour.

However, the integer number that comes back from the 'Color' parameter on the material element is 4082529, which when converted to RGB values using online converters, comes back as Red=62, Green=75 and Blue=97, which is a bluish colour. The Red and Blue values appear to be reversed.

I would have expected the integer 6376254 to be returned for this colour instead.

Can you explain this, please?

Answer: Yes, easily.

This is actually working as expected.

Revit uses the Windows convention of storing colours as an RGB COLORREF value in a DWORD (32 bit integer) that specifies "The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green; and the third byte contains a value for blue".

In other words it is (A)BGR and not (A)RGB.

This corresponds to the value of the integer returned from a Color parameter.

Updating a DXF Link

Question: I have created a DXF link DXF using the following code:

  DWGImportOptions opt = new DWGImportOptions();
  ElementId linkId;
 
  if( doc.Link( "C:\\tmp\\test.dxf",
    opt, doc.ActiveView, out linkId ) )
  {
    Element e = doc.GetElement( linkId );
    ImportInstance i = e as ImportInstance;
  }

Later, the DXF is modified by an external application.

Is it possible to programmatically force Revit to reload the link?

I think I could also delete the ImportInstance and create a new one, but I don't how to get the proper DWGImportOptions and DXF file path from the existing ImportInstance.

Answer: Yes, this can easily be achieved. You can use the RevitLinkType.Unload method to unload it first, and then call RevitLinkType.Reload to reload the updated DXF file.

The imported DXF file has the type of CADLinkType. Just as you say, you could also delete the link and import it again.

You can find the imported DXF ImportInstance's original path by calling the ExternalFileReference.GetPath method, and the ExternalFileUtils.GetExternalRefernce method will return the ImportInstance's ExternalFileReference object.

Retrieving Truss Family Elements

Question: How can I retrieve a truss element family instance?

Answer: This is a very basic question, answered many times over in the Revit API getting started material.

I recommend that you take a look at that material, work through the 'My First Revit Plugin' and DevTV tutorials, install the Revit SDK, RevitLookup, RvtSamples, and then answer that question for yourself.

I'll just give you one little additional hint to help get you started:

Every access to a Revit database element is achieved using a filtered element collector.

To retrieve all truss family instances, you could use something like this:

  FilteredElementCollector collector
    = new FilteredElementCollector( doc )
      .OfClass( typeof( FamilyInstance ) )
      .OfCategory( BuiltInCategory.OST_Truss );
 
  foreach( Element e in collector )
  {
    // e is a truss family instance
  }

Retrieval of Stair Stringer Data

Question: I want to access the values of the stair stringer height and thickness properties on a stair element. How can I achieve this, please?

I tried using the built-in parameters STAIRS_ATTR_STRINGER_THICKNESS and STAIRS_ATTR_STRINGER_HEIGTH, but the value being returned is null. I am also unable to get the family symbol of the stair element.

Answer: The two parameters that you are trying to access are stored on the stair type, not the stair itself.

The stair type is represented by the ElementType class, not FamilySymbol.

You can access the stair type and the two desired paramaters like this:

  Document doc = stair.Document;
 
  ElementId id = stair.GetTypeId();
 
  ElementType type = doc.get_Element( id )
    as ElementType;
 
  Parameter pThick = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_THICKNESS );
 
  Parameter pHeight = type.get_Parameter(
    BuiltInParameter.STAIRS_ATTR_STRINGER_HEIGHT );
 
  double thick = pThick.AsDouble();
  double height = pHeight.AsDouble();

Storing Custom Data

Response: I need more than just the path. I would like to retrieve other DWGImportOptions parameters as well. Is it possible to get them somehow?

Answer: I don't think there is any way to retrieve all the ImportInstance's DWGImportOptions.

Since the DXF file was imported by your own code, you can easily work around that gap by storing the DWGImportOptions property values of interest in the ImportInstance object.

You can use extensible storage (wiki, category) to store custom data on Revit elements.

When you use this, you can later read back the settings from the extensible storage data.

Accessing and Filtering by Ramp Material

I had a chat with Ning Zhou, who was away from the Revit API for a while and is now happily back in the fold.

He explored how to access the material of a ramp element.

Access to Ramp Material

Question: Is there a way to get the ramp material information using API? I tried lots of paths and could not find anything.

Answer (by Ning himself): I searched again using RevitLookup snoop.

It turns out that basic material info is accessible after all. I found it us under 'Object type' instead of 'Parameters'. Apparently only the material name is stored there, in the built-in parameter 'RAMP_ATTR_MATERIAL':

I have not seen anything providing the material volume, so I guess I'll have to use the geometry access and calculate that myself instead.

At least I can now implement a filter selection using the material name!

  FilteredElementCollector concreteRamps
    = new FilteredElementCollector( doc )
      .WhereElementIsNotElementType()
      .OfCategory( BuiltInCategory.OST_Ramps )
      .Where( e =>
      {
        ElementId id = e.GetValidTypes().First(
          id2 => id2.Equals( e.GetTypeId() ) );
 
        Material m = doc.GetElement( doc.GetElement( id )
          .get_Parameter(
            BuiltInParameter.RAMP_ATTR_MATERIAL )
          .AsElementId() ) as Material;
 
        return m.Name.Contains( "Concrete" );
      } );

Many thanks to Ning for his research and sharing this helpful result.

Before closing, here is another useful pointer on family instance placement and rotation:

Rotate a Family in Three Different Axes

Here is a pretty neat article on family instance placement strategies from a user point of view, describing how to rotate a family in three different axes, which is certainly useful for developers as well.

As always in the Revit API, knowing the best practice from a user and product point of view is of paramount importance before putting any thoughts or efforts at all into API development issues.

Grouping Schedule Headers and How to Do Something

Here is my first real Revit 2014 post, sharing some code friendlily provided by David Robison of Design Master showing how to use the ViewSchedule.GroupHeaders method.

Using the ViewSchedule GroupHeaders Method

Question: I am trying to call ViewSchedule.GroupHeaders, and it keeps throwing an unhandled argument exception saying "Headers could not be grouped. Parameter name: right".

Answer: Yes, this issue has been raised in the past and a few solutions were suggested.

First case

The ViewSchedule.GroupHeaders produces the argument exception mentioned above.

After a schedule is created, however, calling it directly with the same parameters succeeds, so the issue is not related to the arguments provided.

I investigated this issue and found 2 workarounds:

1. Activate the new schedule view and then group the header.
2. Refresh the new schedule view and then group the header when the schedule is out of data.

It seems that the second workaround is the right way to 'fix' this issue. We have to manually refresh the schedule data if the view is out of data. This behaviour is by design.

Second case

The API cannot get the updated value in Body section if the schedule view is not opened.

Close the schedule view:

1. IsCellOverridden returns True;
2. ResetCellOverride;
3. IsCellOverridden also returns True;

Open the schedule view:

1. IsCellOverridden returns True;
2. ResetCellOverride;
3. IsCellOverridden returns False (as expected);

The workaround is to call viewSchedule.GetTableData again.

The API calls will not work in the body section if the schedule view is closed.

The root cause is that the schedule data (especially the body section) will not be updated if the schedule view is closed.

This is no problem for the user interface, and improves performance because the schedule data is not regenerated. It does cause a problem in the API, though.

Response: I got this to work using the suggestion in first case #1.

I created the schedule, closed the transaction, set the schedule to the ActiveView and then grouped the headers.

I also discovered that the column indexes ignore hidden columns.

Here is a sample external command demonstrating the ViewSchedule.GroupHeaders function. Please note the comments describing some of the steps in more detail:

public Result Execute(
  ExternalCommandData commandData,
  ref string message,
  ElementSet elements )
{
  try
  {
    UIDocument uidoc = commandData.Application
      .ActiveUIDocument;
 
    Document doc = uidoc.Document;
 
    // Create the schedule
 
    Transaction tran = new Transaction( doc );
    tran.Start( "Create schedule" );
 
    ViewSchedule sampleSchedule
      = ViewSchedule.CreateSchedule( doc, new
        ElementId( BuiltInCategory.OST_Windows ) );
 
    foreach( ElementId id in
      ViewSchedule.GetAvailableParameters( doc, new
        ElementId( BuiltInCategory.OST_Windows ) ) )
    {
      try
      {
        sampleSchedule.Definition.AddField(
          new SchedulableField(
            ScheduleFieldType.Instance, id ) );
      }
      catch( Exception )
      {
      }
    }
    ScheduleDefinition sampleDefinition
      = sampleSchedule.Definition;
 
    // Hide two columns in the schedule
 
    sampleDefinition.GetField( 0 ).IsHidden = true;
    sampleDefinition.GetField( 1 ).IsHidden = true;
 
    // Commit the schedule. This is important so 
    // you can set the active view.
 
    tran.Commit();
 
    // Change the active view to the schedule. 
    // This is required before the GroupHeaders 
    // function will work.
 
    uidoc.ActiveView = sampleSchedule;
 
    // Group the last three headers.
    // Hidden fields are not counted in the left 
    // and right values, so make sure to account 
    // for that.
 
    tran.Start( "Group headers" );
 
    int iFieldCount = sampleDefinition
      .GetFieldCount();
 
    sampleSchedule.GroupHeaders( 0,
      iFieldCount - 5, 0,
      iFieldCount - 3, "Group Header" );
 
    tran.Commit();
 
    return Result.Succeeded;
  }
  catch( Exception ex )
  {
    MessageBox.Show( ex.ToString(),
      "Group Headers Sample" );
 
    return Result.Failed;
  }
}

Here are two important pieces of information I learned:

1. You have to set the active view to the schedule before the GroupHeaders method will work.
2. The left and right indices do not include hidden columns, so you need to make sure to adjust for those.

For completeness' sake, here is GroupHeadersSampler.zip containing the complete source code, Visual Studio solution and add-in manifest for this command.

Many thanks to David for testing this and sharing the code. Hopefully you are able to make good use of this sample.

Before closing, here is are some thoughts on how to research automating something using the Revit API in general, the kind of suggestions I regularly provide orally and seldom wind up putting down clearly and separately in writing:

How to Research Automating Something

Question: I would like to create a dimension that differs from the normal linear dimension style within the template.

Here is an example of the normal dimension style and the modified variant I would like, with the dimension text sticking out on the side like this instead:

How can I realise this programmatically, please?

Answer: There is a simple standard procedure for exploring this kind of issue.

First of all, determine whether what you wish is possible manually in the user interface.

If not, then it is probably not possible programmatically either.

If yes, then the two models before and after can be compared using RevitLookup, included with the Revit SDK, to analyse the differences.

That might give a hint how to achieve it programmatically.

If no differences can be found, then it is maybe impossible.

In this case, you can apparently achieve your goal manually, so the first hurdle is already taken.

Looking at the NewDimension method and the Dimension class members, I see no obvious input arguments or properties that might affect the dimension in the desired way.

Therefore, the only remaining things to check are the parameters on the dimension object.

You can list those before and after using RevitLookup or the built-in parameter BipChecker and compare.

I hope this helps.

Response: Yes, as you say, I know that it is possible to create this manually.

And yes, the text position and leader information are not shown in the standard UI, nor visible in RevitLookup.

I guess that this specific task cannot be achieved programmatically at this moment, then.

Answer: Sorry about that.

I hope the standard exploration procedure described above will prove useful anyway.

Room Editor Project Overview and CouchDB Configuration

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, here are some issues I tackled since my last report:

• Project Overview
• Replicating a CouchDB with Python
• Same origin policy snag and resolution
• Learning and struggling with CouchApps
• Relief moving to Kanso
• Next steps

Project Overview

To recapitulate, the grand plan is to grab a 2D floor plan with furniture and equipment layout from the BIM, upload it to the cloud, and make it accessible for viewing on mobile devices:

Furthermore, I am enabling some simple editing operations on the mobile device, e.g. to move the furniture and equipment around in the room a bit, update the cloud-based data repository, and reflect these changes back into the desktop BIM:

All of this with absolutely nil installation on the mobile device, and thus totally ubiquitous, using SVG and server-side scripting.

I already addressed a number of issues in realising this project and am documenting my progress here on the blog, in the three categories desktop, cloud and mobile.

Here is an overview of the results presented so far, both for this project and some previous related topics, classified into those three categories:

• Project overview and Tech Summit proposal
• Desktop
• Room plan view boundary loops
• Sort and orient curves to form a contiguous loop
• Extrusion analyser and plan view boundaries
• Curve following face and bounding box implementation
• GeoSnoop boundary curve loop visualisation
• Desktop to cloud via DreamSeat CouchDB Client
• Cloud
• Getting Going with the Cloud
• Apollonian Sphere Packing Web Service and AVF
• The BIM 360 Glue Viewer and REST API
• BIM 360 Glue REST API Authentication Using Python
• Free Cloud Based Data Repository with NoSQL, CouchDB, and IrisCouch
• Mobile
• Testing my OBJ exporter on Android
• Mobile Device Room Location
• Room Polygon and Furniture Picker in SVG
• 2D SVG Editing on Mobile Device with Raphael

Replicating a CouchDB with Python

In my last step, I determined the room, furniture and equipment plan view boundary polygons and uploaded them to a CouchDB database in the cloud, hosted on IrisCouch.

To play around interactively with that data, I would prefer to store it locally instead of on the server.

The easiest way to achieve this is to replicate the database.

Replicating a CouchDB repository is trivial, since it has built-in support for that.

All you need to do is specify the source and target database name and URL.

Also, as you may know, I love Python for command-line scripting.

Happily, several CouchDB interfaces for Python are available. As you can see on that page, they can be pretty simple.

Couchdbkit seems well supported and does the job.

Here is a little Python script that replicates the database 'rooms' created by my Revit add-in in IrisCouch from the web to a new database 'rooms2' my local CouchDB installation:

#!/usr/bin/python
import couchdb

server = couchdb.Server()
server.create( 'rooms2' )
server.replicate(
  'http://jt.iriscouch.com/rooms',
  'rooms2' )

You cannot make it much shorter or simpler than that, can you?

Same Origin Policy Snag and Resolution

I was originally envisioning a simple architecture composed of three components on the desktop, in the cloud, and on the mobile device, respectively, as illustrated above.

I started looking at how to access the cloud-based data repository from the mobile device and closed my last foray into this area mentioning that I had a nasty surprise discovering that the strict same origin policy prevents my simple JavaScript application from accessing my IrisCouch domain, so I cannot easily read the data on the mobile device in the manner I had expected.

The discovery cost me a few grey hairs and some sleep, but I found a good and obvious solution for that which you are probably all aware of already: server-side scripting.

In fact, this even simplifies things, in the end, since I really have nothing at all to install or implement on the mobile device, and my list of components to implement is reduced from three to two. Ok, it adds some complication to the cloud stuff, of course... or actually just additional learning opportunities.

I had already decided that NoSQL and the CouchDB implementation look like good candidates for my data repository requirements, and that I can test and host them in the cloud for free using the IrisCouch server. Please refer to the link in the overview above for more info on these.

Happily, CouchDB offers full support for server-side scripting. The same-origin policy effectively requires that the HTML from which the JavaScript is loaded must be served up from CouchDB. This can be done by attaching an HTML document to a CouchDB document. You can do this manually, or through the use of CouchApps.

Learning and Struggling with CouchApps

CouchApps are CouchDB generation environments and tools for web application developers interested in creating database-driven applications using nothing but HTML, CSS, and JavaScript.

A CouchApp is simply a collection of files that completely defines a CouchDB database to simplify development, deployment and maintenance. Simple command-line tools are used to synchronise the file collection with the real live CouchDB implementation.

I dived into several of the numerous CouchApp tutorials and was so excited I ended up spending entire nights at it, once with no sleep at all.

Here are some of the things I looked at:

• Getting started
• Build a simple CouchApp
• Good IBM CouchApp tutorial
• A short and effective CouchApp and JavaScript tutorial
• A better introduction and some more modern alternatives
• Documentation for jquery.couch.js
• A very clear and impressive CouchApp video tutorial by Max Ogden
• Very impressive node CouchApp JavaScript library node.couchapp.js
• Using node.js for effective asynchronous processing
• node.js + CouchDB == Crazy Delicious video presentation

Unfortunately, I found it pretty confusing. I learned a huge amount and achieved very little, partly due to the fact that several different CouchApp implementations exist and are used in parallel, and the tutorials do not specify exactly which version they are based on.

Still, I learned enough to continue feeling very enthusiastic about this approach, and then found an easier solution.

Relief Moving to Kanso

After struggling with different CouchApp implementations, I discovered Kanso, toting itself "the best way to create and share apps on CouchDB".

With the little that I know so far, I fully agree with that. Apparently, kanso is the Japanese phrase for simplicity, or, more specifically, simplifying the complex.

So easy! Everything works! The documentation includes a short and succinct getting started tutorial that explains a lot.

Later I found another tutorial that goes further faster than the one included in the documentation pages.

Later still, I found this extremely well documented complete application that can be tested online and demonstrates numerous additional important new features.

After studying these samples and trying to reuse some of the powerful functionality they provide, I am returning more and more often to the Definite Guide for CouchDB and finally starting to understand the basics of view, show and list functions, etc.

Bit by bit, I am managing to get some SVG graphics to display in my server-side scripts. Making use of the Raphael library, as I was planning to do, may prove hard, since there is no ready-built Kanso package for it. I may therefore revert to implementing my room furniture placement editor in pure SVG instead.

Next Steps

My next steps will be:

• Separation of symbol and instance data in my add-in and database structure: currently, the furniture loops are placed absolutely, and multiple instances of a symbol duplicate the same loop over and over again at different locations. I will rewrite this to separate the furniture loop definition, defined by the family symbol, and its placement, defined by the instance. This needs to be done anyway to enable editing the placement data through the editor interaction on the mobile device.
• Learn how to use templates in Kanso.
• Implement server-side generated SVG code to display the room and furniture plan in CouchDB using Kanso.
• Implement editing of SVG on the mobile device and reflect changes back to CouchDB (I do not know how yet).
• Implement Idling event handler and polling of CouchDB in the desktop add-in to reflect the changes back to the BIM in real-time.
• Implement an external application wrapper for the add-in providing four commands:
• Upload to cloud
• Refresh from cloud
• Subscribe to cloud
• Unsubscribe from cloud

I know exactly how to address all these points now, except for reflecting back the SVG editor changes to the CouchDB.

I remain excited and optimistic and look forward to hearing your comments and suggestions.

Migrating The Building Coder Samples to Revit 2014

I started migrating The Building Coder samples to Revit 2014. Funnily enough, on the exact same date as last year for the previous version.

The changes are very small this time around.

Furthermore, I am well prepared, since I recently intentionally eliminated all compiler warnings and deprecated calls compiling the code for Revit 2013.

First, however, a picture or three from my ski tour last weekend over Il Chapütschin (3386 m) and La Sella (3584 m) in the Swiss Engadin. Here I am on the first summit:

The panorama is grandiose:

We arrive back at the hut tired and happy:

Migrating The Building Coder Samples to Revit 2014

Back at the desk and steeped in the Revit API, Here is what I have done so far to migrate The Building Coder samples from Revit 2013 to Revit 2014:

• Update the Revit API assembly references
• Remove obsolete Collections namespace and RoomCreationData class
• TopographySurface namespace changed
• Some unit API changes
• Initial Revit 2014 version

Update the Revit API Assembly References

Every Revit add-in needs to reference the API assemblies.

They now live in the main Revit installation folder, together with Revit.exe.

In my case, this folder is "C:\Program Files\Autodesk\Revit Architecture 2014", and I am referencing the three assemblies RevitAPI, RevitAPIUI and UIFrameworkServices.

Just updating the references and recompiling generated 5 errors and 3 warnings.

Remove Obsolete Collections Namespace and RoomCreationData Class

Four of the five errors say "The type or namespace name 'Collections' does not exist in the namespace 'Autodesk.Revit' (are you missing an assembly reference?)".

To my surprise, I did indeed have several obsolete statements like this left over from previous versions:

using Autodesk.Revit.Collections;

They were actually not required at all by the Revit 2013 compilation, just left over from still older versions.

The fifth warning is similar, saying "The type or namespace name 'RoomCreationData' does not exist in the namespace 'Autodesk.Revit.Creation' (are you missing an assembly reference?)", and could also be resolved simply by removing this obsolete using statement:

using RoomCreationData
  = Autodesk.Revit.Creation.RoomCreationData;

Removing these erroneous using statements enables the compilation proper to execute and raises the number of problems reported to 3 errors and 108 warnings.

Just three errors! Looking good...

TopographySurface Namespace Changed

Now we hit some real errors caused by slight shifts and redefinitions in the API.

The first error is in CmdLandXml.cs:

  TopographySurface surface
    = doc.Create.NewTopographySurface( pts );

It says "The type or namespace name 'TopographySurface' could not be found (are you missing a using directive or an assembly reference?)".

The TopographySurface class apparently moved from one namespace to another. In Revit 2013, it lived in Autodesk.Revit.DB.

This is easily remedied by placing the cursor over the offending class name and pressing Ctrl + '.', which brings up a menu listing the fully qualified class name and offering to automatically correct the error for you:

Some Unit API Changes

The other two errors refer to units, one of the few areas seriously modified in the Revit 2014 API, and say:

• 'Autodesk.Revit.DB.Document' does not contain a definition for 'ProjectUnit' and no extension method 'ProjectUnit' accepting a first argument of type 'Autodesk.Revit.DB.Document' could be found (are you missing a using directive or an assembly reference?)
• 'Autodesk.Revit.DB.FormatOptions' does not contain a definition for 'Units' and no extension method 'Units' accepting a first argument of type 'Autodesk.Revit.DB.FormatOptions' could be found (are you missing a using directive or an assembly reference?)

They are caused by the following lines in ParameterUnitConverter.cs:

  FormatOptions fo = document.ProjectUnit
    .get_FormatOptions( ut );
 
  DisplayUnitType dut = fo.Units;

They are easily fixed by using the following new methods and properties:

  FormatOptions fo = document.GetUnits()
    .GetFormatOptions( ut );
 
  DisplayUnitType dut = fo.DisplayUnits;

We are left with zero errors and 111 warnings, which we will leave to deal with another day.

Initial Revit 2014 Version

So here is the result, the very first version 2014.0.100.2 of The Building Coder samples for Revit 2014.

To compare with the last version for Revit 2013, look at the version 2013.0.100.2 that I provided after eliminating all compiler warnings and deprecated calls.

Perpetual GUID Algorithm and Revit 2014 Product GUIDs

Every year anew, people ask for the Revit product GUIDs used to identify the Revit installation and stored in the Windows registry under

• HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Uninstall

I already answered several queries from developers lately wishing to update their installers for the new version.

I discussed this topic on a yearly basis in the past for Revit 2010 and previous versions, Revit 2011, Revit 2012, when the 'perpetual GUID algorithm' was introduced, and Revit 2013.

The install path is less of an issue since the introduction of the add-in manifest to inform Revit how to load your add-in, and the add-in manifest path is well known.

It is actually recommended to install .NET add-ins for both AutoCAD and Revit in or under the same directory as acad.exe and revit.exe, respectively: "It's safest to place assemblies at a location beneath the calling executable."

The best way to determine the Revit install location is to use the RevitAddInUtility, which provides an API for an installer to query that and also to generate an add-in manifest file from the relevant properties you specify. The same RevitAddInUtility assembly DLL works transparently on both 32 and 64 bits.

Revit 2014 and Previous Product GUIDs

In spite of all this, the product GUID is still important, so here is a list of the Revit GUIDs up to and including Revit 2014:

2014	64 bit	RAC	7346B4A0-1400-0110-0409-705C0D862004
		RST	7346B4A0-1400-0210-0409-705C0D862004
		RME	7346B4A0-1400-0310-0409-705C0D862004
		LT	7346B4A0-1400-0410-0409-705C0D862004
		One-Box	7346B4A0-1400-0510-0409-705C0D862004
	32 bit	RAC	7346B4A0-1400-0100-0409-705C0D862004
		RST	7346B4A0-1400-0200-0409-705C0D862004
		RME	7346B4A0-1400-0300-0409-705C0D862004
		LT	7346B4A0-1400-0400-0409-705C0D862004
		One-Box	7346B4A0-1400-0500-0409-705C0D862004
2013	64 bit	RAC	7346B4A0-1300-0110-0409-705C0D862004
		RST	7346B4A0-1300-0210-0409-705C0D862004
		RME	7346B4A0-1300-0310-0409-705C0D862004
		One-Box	7346B4A0-1300-0510-0409-705C0D862004
	32 bit	RAC	7346B4A0-1300-0100-0409-705C0D862004
		RST	7346B4A0-1300-0200-0409-705C0D862004
		RME	7346B4A0-1300-0300-0409-705C0D862004
		One-Box	7346B4A0-1300-0500-0409-705C0D862004
2012	64 bit	RAC	7346B4A0-1200-0110-0409-705C0D862004
		RST	7346B4A0-1200-0210-0409-705C0D862004
		RME	7346B4A0-1200-0310-0409-705C0D862004
	32 bit	RAC	7346B4A0-1200-0100-0409-705C0D862004
		RST	7346B4A0-1200-0200-0409-705C0D862004
		RME	7346B4A0-1200-0300-0409-705C0D862004
2011	64 bit	RAC	94D463D0-2B13-4181-9512-B27004B1151A
		RST	23853368-22DD-4817-904B-DB04ADE9B0C8
		RME	C31F3560-0007-4955-9F65-75CB47F82DB5
	32 bit	RAC	4AF99FCA-1D0C-4D5A-9BFE-0D4376A52B23
		RST	0EE1FCA9-7474-4143-8F22-E7AD998FACBF
		RME	CCCB80C8-5CC5-4EB7-89D0-F18E405F18F9
2010	64 bit	RAC	2A8EEE2F-4A9E-43d8-AA07-EC8A316B2DEB
		RST	BC9C0A08-DEA4-4138-A7FB-8F68866DB0C1
		RME	A1BD042B-8A6F-4e37-92A3-78921BB45B05
	32 bit	RAC	572FBF5D-3BAA-42ff-A468-A54C2C0A17C3
		RST	939D29FC-B82D-42a7-BB1E-8E3F121505CC
		RME	5C8281B1-B927-495a-A0FF-AB4BDFAE505C
2009	64 bit	RAC	D2466208-7348-4214-B01E-7BC8729E2BD3
		RST	B354FCF5-CF64-4fa2-AA84-9D9B2A6FA649
		RME	4A98F976-01B5-40e8-A496-AEFD85C3A446
	32 bit	RAC	A3A37DA6-70C0-497C-BCB1-148E9EC1D32E
		RST	C4B3B3C3-2EE9-48D3-9BF5-4443F7ECF759
		RME	E3781DCB-A650-4E66-9B74-67A1B17F052C
2008		RAC	4A11206C-4377-49E8-911E-B11548658FF3
		RST	8D0AE0BB-4FE5-491D-A284-3B363F02E639
		RME	60A2743E-C881-4880-94ED-96445E38616F
9.0		Revit Building	D11DB6CB-0332-4735-B312-B919741D975E
3		RST	3F11CEE0-D30D-41ce-8522-922B5D8BB324
8.1		Revit Building	7EBC0489-5E47-498D-BE31-B094484612E9
2		RST	BE814F63-629D-4fd8-B628-1437AC10F9D4

Perpetual Revit Product GUID Algorithm

As you can see above, all the Revit GUIDs from Revit 2012 onwards have a strong similarity.

They are actually generated according to the following pattern:

    {7346B4At-uuvv-wwxy-zzzz-705C0D862004}

The alphabetical characters above stand for:

20. [0/1]: ProductCode/UpgradeCode
21. [12, 13, 14, ...]: Major release version [12, 13, 14]
22. [00, 01, ...]: Release subversion
23. [01/02/03/04/05/06/07]: RAC/RST/RME/LT/One-Box/Server/Vasari
24. [0/1]: Win32/x64
25. [0/1]: Global/Language Pack
26. [0409...]: Language

The 'ww' item corresponds to the ProductType enumeration provided by the Revit API, with the following members:

• Architecture
• Structure
• MEP
• Revit
• LT
• Unknown

The last item, represented by 'zzzz', identifies the language. It uses the hexadecimal LCID or language code identifier. The ones supported by Revit are listed in the following table:

lang	.NET code	HEX LCID	DEC LCID	Language	Codepage
chs	zh-CN	0804	2052	Chinese Simpl.	936
cht	zh-TW	0404	1028	Chinese Trad.	950
csy	cs-CZ	0405	1029	Czech	1250
deu	de-DE	0407	1031	German	1252
enu	en-US	0409	1033	English	1252
esp	es-ES	040A	1034	Spanish	1252
fra	fr-FR	040C	1036	French	1252
hun	hu-HU	040E	1038	Hungarian	1250
ita	it-IT	0410	1040	Italian	1252
jpn	ja-JP	0411	1041	Japanese	932
kor	ko-KR	0412	1042	Korean	949
plk	pl-PL	0415	1045	Polish	1250
ptb	pt-BR	0416	1046	Portuguese Brazil	1252
rus	ru-RU	0419	1049	Russian	1251

Applying this algorithm to the different flavours of Revit from Revit 2012 onwards produces the values listed in the table above.

Windows Registry Keys

The installer creates the following registry keys:

  HKEY_LOCAL_MACHINE\SOFTWARE\Autodesk\Revit
  \[RELEASEYEAR]\REVIT-[PRODID]:[LANGID]

  HKEY_LOCAL_MACHINE\SOFTWARE\Autodesk\Revit
  \Autodesk Revit [RELEASEYEAR]
  \ServicePack[SERVICEPACK#]

RELEASEYEAR is the major version number, i.e. 2013, 2014, etc., PRODID specifies the flavour, listed as 'ww' above, and LANGID the locale, 'zzzz' above, SERVICEPACK# would be 1 for Update Release 1, etc.

For Revit 2014, the Windows registry key is

  HKEY_LOCAL_MACHINE\SOFTWARE
  \Autodesk\Revit\2014\REVIT-05:0409

MUI: Multiple Language Interface Update

Addendum:

Revit 2014 is using a new Multiple Language Interface, MUI.

Therefore, you may encounter all-zero language codes besides the ones listed above.

For instance, the following GUID refers to the global MSI which is used for the base product in all locales:

• 7346B4A0-1400-0110-0000-705C0D862004

The corresponding ENU Language Pack MSI would be installed by either an ENU base install or installing the ENU Language Pack on top of a non-ENU base install and create this GUID instead:

• 7346B4A0-1400-0110-0409-705C0D862004

Appropriate keys are added as each additional language pack is installed.