The Building Coder

External Command Lister and Adding Ribbon Commands

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Where can this information be obtained?

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

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

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

Where can they be obtained from then?

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

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

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

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

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

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

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

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

The code is very simple.

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

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

The one single important line is really just

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

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

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

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

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

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

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

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

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

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

Addendum by Rudolf Honke of Mensch und Maschine acadGraph GmbH:

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

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

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

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

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

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

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

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

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.

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.

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.

Launching AutoCAD within a Revit Add-in

We looked at the topic of running AutoCAD inside a Revit add-in way back in 2008, in the grey and dusty beginnings of this blog.

Many developers have made use of that since then, and the topic is still important for all those who have significant functionality running inside an AutoCAD application and wish to make use of or enhance it by connecting it with their Revit add-in.

Therefore, it is about time to dig that out and have a fresh look at it. Actually, it is rather overdue. I have some more up-to-date information on this that has been sitting around on my to-do list for quite a while. In fact, it is high time to get it out there before it becomes obsolete, and should still prove useful to anyone interested in this topic.

Actually, here are two separate solutions, testole.zip and Acctrl_Interops.zip + EmbedAutoCAD.zip.

Testole.zip

I will simply provide the sample code as it is with no further comment:

// This could have been read-only, but then it 
// cannot be started in zero document state:
 
[Transaction( TransactionMode.Manual )]
public class Command : IExternalCommand
{
  public Result Execute(
    ExternalCommandData commandData,
    ref string message,
    ElementSet elements )
  {
    Autodesk.AutoCAD.Interop.AcadApplication a
      = new Autodesk.AutoCAD.Interop.AcadApplication();
 
    a.Visible = true;
 
    Autodesk.AutoCAD.Interop.AcadDocument doc
      = a.Documents.Application.ActiveDocument;
 
    double[] stpoint = new double[3];
    double[] enpoint = new double[3];
    stpoint[0] = 5;
    stpoint[1] = 5;
    stpoint[2] = 0;
    enpoint[0] = 12;
    enpoint[1] = 3;
    enpoint[2] = 0;
 
    doc.ModelSpace.AddLine( stpoint, enpoint );
 
    doc.SaveAs( "C:/tmp/testline.dwg" );
 
    a.Quit();
 
    return Result.Succeeded;
  }
}

That shows how simple this can be.

Here is testole.zip containing the complete Visual Studio solution.

This is up to you to explore further on your own, if you like :-)

2. Acctrl_Interops.zip + EmbedAutoCAD_2012.zip

The second solution is not directly related to the Revit API, but should work in an add-in as well. It was prompted by the following query:

Question: How can I view and manipulate DWG files in a Windows form?

I want to create an AutoCAD add-in that shows a preview of another DWG file (not the current one) in a VB.NET form and then switch some layers on and off.

I am using Visual Studio 2010.

Answer: You can use the AutoCAD control AcCtrl for this.

Kean's article on embedding AutoCAD in a standalone dialog explains everything in full detail.

Response: This control does not seem to work with VS 2010 on the .NET framework 4.

Answer: I have attached the sample project that uses the Acctrl.dll from AutoCAD 2012 and Visual Studio 2010 with the .NET 4 framework.

The code is identical to the one that you download from the blog and works fine.

Here are the only things I changed:

• I used aximp to generate the interop DLLs from Acctrl.dll and attached them below in Acctrl_Interops.zip. These interop DLLs need to be referenced in the project.
• Set the 'Embed Interop types' toggle to False in the properties of these references.

Here are the two attachments, Acctrl_Interops.zip containing the interop DLLs I generated and EmbedAutoCAD.zip containing the complete Visual Studio solution using them.

I hope you find this useful!

Desktop to Cloud via DreamSeat CouchDB Client

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I now started looking at storing the plan view room and furniture boundary loop data in the cloud.

I wound up the main Revit add-in functionality using the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances, sort and orient its output curves, determine their bounding box and visualise the results in a dynamically generated GeoSnoop .NET form for verification. The plan view boundary loop data is handily managed in integer-based 2D points packaged by the JtLoops class.

That wraps up the initial add-in implementation. We will certainly return to it and add more functionality when the time comes to update the model with the edits applied on the mobile device.

Moving to the Cloud

The next step is to implement a cloud-based data repository to make this information ubiquitously available for consumption on mobile devices and elsewhere.

I mentioned looking at the CouchDB database and the free IrisCouch hosting service as a candidate repository implementation.

My colleague Philippe Leefsma took that same thought and very quickly and easily implemented a simple and efficient restful database using those components to host and consume images of CAD model data.

Philippe used the DreamSeat .NET CouchDB wrapper library to easily access the functionality from within a .NET add-in.

He added his own asynchronous support, in addition to the asynchronous support already provided by DreamSeat itself, and attached the complete implementation of a .NET client and console allowing for upload and viewing of pictures.

I added DreamSeat support to feed a CouchDB database with my plan view room and equipment boundary loop data in just a very few simple steps:

• Implement SVG path properties
• Add references to the DreamSeat libraries
• Implement couch document wrappers
• Instantiate, populate and save to cloud
• Looking at the cloud-based data repository

Implement SVG Path Properties

First of all, I need to decide how to store the boundary loops in my data repository.

I initially thought I would save the integer values, and may still do so.

For the moment, though, I implemented a much simpler placeholder by adding methods to the point and loop classes to serialise the data to a single complete SVG path string representation.

A single string is easy to add to the database and can be reused directly for the SVG visualisation. I am not planning to modify the boundary loops in any way, so I might as well manage them in static strings. The only disadvantage would be if I wanted to scale the coordinates differently. If that need arises, I may switch to uploading the structured integer-based point and loop data instead. We'll cross that bridge when we come to it.

An SVG path element contains a path data attribute that can include moveto, line, curve, arc and closepath instructions.

For an individual point, I simply output its two coordinate values. For the first loop vertex, I prepend an 'M' for moveto. For the second one, I prepend an 'L' for line-to. For all following vertices, the 'L' can be omitted. At the end, a 'Z' is appended to close the path.

For an individual point, Point2dInt, the SvgPath property is therefore implemented like this:

  /// <summary>
  /// Return a string suitable for use in an SVG 
  /// path. For index i == 0, prefix with 'M', for
  /// i == 1 with 'L', and otherwise with nothing.
  /// </summary>
  public string SvgPath( int i )
  {
    return string.Format( "{0}{1} {2}",
      ( 0 == i ? "M" : ( 1 == i ? "L" : "" ) ),
      X, Y );
  }

For an individual boundary loop, JtLoop, the member vertices are converted to their SVG string representation using LINQ and concatenated using the string Join method:

  /// <summary>
  /// Return an SVG path specification, c.f.
  /// http://www.w3.org/TR/SVG/paths.html
  /// M [0] L [1] [2] ... [n-1] Z
  /// </summary>
  public string SvgPath
  {
    get
    {
      return string.Join( " ",
        this.Select<Point2dInt,string>(
          (p,i) => p.SvgPath( i ) ) )
        + "Z";
    }
  }

For a collection of loops, JtLoops, concatenate the individual loop paths:

  /// <summary>
  /// Return the concatenated SVG path 
  /// specifications for all the loops.
  /// </summary>
  public string SvgPath
  {
    get
    {
      return string.Join( " ",
        this.Select<JtLoop,string>(
          a => a.SvgPath ) );
    }
  }

With these properties in place, I can finally set about uploading the data to the cloud.

Add References to the DreamSeat Libraries

Just like Philippe, I use the DreamSeat wrapper to access the CouchDB functionality from my .NET Revit add-in.

I simply added this functionality to the existing GetLoops external command.

First, I need to reference the DreamSeat .NET assemblies to access it classes and methods.

I grabbed these from the DreamSeat sample solution on github.

For my initial minimal upload usage, all I need are DreamSeat.dll and mindtouch.dream.dll:

Implement Couch Document Wrappers for my Data

Data in CouchDB is stored in documents.

DreamSeat provides a CouchDocument base class for deriving your own document wrappers.

I implemented derived classes to store some minimal model, level, room and furniture data as follows:

class DbObj : CouchDocument
{
  protected DbObj()
  {
    Type = "obj";
  }
  public string Type { get; protected set; }
  //public string UniqueId { get; set; }
  public string Description { get; set; }
  public string Name { get; set; }
}
 
class DbModel : DbObj
{
  public DbModel()
  {
    Type = "model";
  }
}
 
class DbLevel : DbObj
{
  public DbLevel()
  {
    Type = "level";
  }
  public string ModelId { get; set; }
 
}
 
class DbRoom : DbObj
{
  public DbRoom()
  {
    Type = "room";
  }
  public string LevelId { get; set; }
  public string Loops { get; set; }
}
 
class DbFurniture : DbObj
{
  public DbFurniture()
  {
    Type = "furniture";
  }
  public string RoomId { get; set; }
  public string Loop { get; set; }
  public string Transform { get; set; }
}

I initially thought of identifying documents with the auto-generated CouchDB identifiers, but then chose to use the UniqueId already provided by Revit to identify the objects in CouchDB as well.

Type, description and name are fields added to all my objects.

Type identifies the object type and can be one of model, level, room or furniture.

The only information of interest to me is:

• Mutual relationships, i.e. which room belongs to what level, where does the furniture go, etc., handled by the ModelId, LevelId and RoomId properties.
• Boundary loop data for display purposes, currently stored as strings representing the SVG path information produced by the properties described above.
• The transform applied to the furniture, which can be moved and rotated in the mobile device room editor and then needs to be updated back to the model again.

Pretty minimal and readable, isn't it?

Instantiate, Populate and Save to Cloud

Here is the entire code to connect to the cloud database host, open the 'rooms' database, and populate the room and furniture data for a given room, either creating new records or updating existing ones:

void UploadRoom(
  Room room,
  List<Element> furniture,
  JtLoops roomLoops,
  JtLoops furnitureLoops )
{
  CouchClient client = new CouchClient(
    "jt.iriscouch.com", 5984 );
 
  CouchDatabase db = client.GetDatabase(
    "rooms", true );
 
  string 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 = room.Level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
 
    dbRoom = db.UpdateDocument<DbRoom>( dbRoom );
  }
  else
  {
    dbRoom = new DbRoom();
 
    dbRoom.Id = uid;
    dbRoom.Description = Util.ElementDescription(
      room );
 
    dbRoom.Name = room.Name;
    dbRoom.LevelId = room.Level.UniqueId;
    dbRoom.Loops = roomLoops.SvgPath;
    dbRoom = db.CreateDocument<DbRoom>( dbRoom );
  }
 
  int i = 0;
 
  foreach( Element 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.Loop = furnitureLoops[i++].SvgPath;
      dbf = db.UpdateDocument<DbFurniture>( dbf );
    }
    else
    {
      DbFurniture dbf = new DbFurniture();
      dbf.Id = f.UniqueId;
      dbf.Description = Util.ElementDescription( f );
      dbf.Name = f.Name;
      dbf.RoomId = room.UniqueId;
      dbf.Loop = furnitureLoops[i++].SvgPath;
      dbf = db.CreateDocument<DbFurniture>( dbf );
    }
  }
}

As you can see, I am storing the data in my IrisCouch hosted database in the cloud.

Looking at the Cloud-based Data Repository

After running this command, I can retrieve the top-level database information in JSON format:

{"db_name":"rooms", "doc_count":10, "doc_del_count":11,
"update_seq":54, "purge_seq":0, "compact_running":false,
"disk_size":102511, "data_size":6921,
"instance_start_time":"1365674085202773",
"disk_format_version":6, "committed_update_seq":54}

This is what an individual room looks like in futon, the CouchDB management console:

Here is the raw JSON representation of the same data:

{
  "_id": "4d2e6fd6-eb44-4e2a-98c5-271decaa9225-00033e9f",
  "_rev": "2-a863fbc7b2294ef4d8630bc961221b24",
  "levelId": "e3e052f9-0156-11d5-9301-0000863f27ad-00000137",
  "loops": "M2753 3087 L-4446 3087 -4446 587 -746 587 -746 -1212 2753 -1212Z M298 -112 L298 587 1698 587 1698 -112Z",
  "type": "room",
  "description": "Room Rooms <212639 Room 1>",
  "name": "Room 1"
}

So far, so good.

Once I got that far, I wanted to start working on the visualisation in SVG and had a very nasty surprise: the strict same origin policy prevents my simple JavaScript application from accessing my IrisCouch domain, so I cannot easily read the data.

The discovery robbed me of a full night's sleep, but I think I have found a good way out of that dilemma as well.

Wish me luck!

Setting up your ViewOrientation3D

Here is a contribution from Mario Guttman of CASE, who already made various contributions here in the past. He says:

I have been purging my 2013 code of deprecated functions in preparation for my 2014 upgrade. One group of statements I have needed to replace are the view creations. They were previously using the Document.Create.NewView3D method and needed converting to the View3D.CreateIsometric with a separate ViewOrientation3D object defining the view direction.

Typically, in these kind of cases, I just search your blog for the answer. In this case I found a few references, for example your March 04, 2013 item on What's New in the Revit 2013 API – View API – View Creation. This, together with the wikihelp entry on the View3D class, describe the new syntax, but they don't really explain how you would create the values.

After searching the inner reaches of my brain for some ancient math skills I figured out the following:

Assuming that your user interface has produced two angular values (in degrees):

  /// <summary>
  /// The angle in the XY plane (azimuth),
  /// typically 0 to 360.
  /// </summary>
  double angleHorizD;
 
  /// <summary>
  /// The vertical tilt (altitude),
  /// typically -90 to 90.
  /// </summary>
  double angleVertD;

Then this utility function returns a unit vector in the specified direction:

  /// <summary>
  /// Return a unit vector in the specified direction.
  /// </summary>
  /// <param name="angleHorizD">Angle in XY plane 
  /// in degrees</param>
  /// <param name="angleVertD">Vertical tilt between 
  /// -90 and +90 degrees</param>
  /// <returns>Unit vector in the specified 
  /// direction.</returns>
  private XYZ VectorFromHorizVertAngles(
    double angleHorizD,
    double angleVertD )
  {
    // Convert degreess to radians.
 
    double degToRadian = Math.PI * 2 / 360;
    double angleHorizR = angleHorizD * degToRadian;
    double angleVertR = angleVertD * degToRadian;
 
    // Return unit vector in 3D
 
    double a = Math.Cos( angleVertR );
    double b = Math.Cos( angleHorizR );
    double c = Math.Sin( angleHorizR );
    double d = Math.Sin( angleVertR );
 
    return new XYZ( a * b, a * c, d );
  }

From this it is easy to create the ViewOrientation3D object as follows:

  XYZ eye = new XYZ.Zero;
 
  XYZ forward = VectorFromHorizVertAngles(
    angleHorizD, angleVertD );
 
  XYZ up = VectorFromHorizVertAngles(
    angleHorizD, angleVertD + 90 );
 
  ViewOrientation3D viewOrientation3D
    = new ViewOrientation3D( eye, up, forward );

Although it is already explained in one of your other posts, just for completeness, here is the final step is to apply the orientation to the view:

  ViewFamilyType viewFamilyType3D
    = new FilteredElementCollector( doc )
      .OfClass( typeof( ViewFamilyType ) )
      .Cast<ViewFamilyType>()
      .FirstOrDefault<ViewFamilyType>(
        x => ViewFamily.ThreeDimensional
          == x.ViewFamily );
 
  View3D view3d = View3D.CreateIsometric(
    doc, viewFamilyType3D.Id );
 
  view3d.SetOrientation( viewOrientation3D );

I hope you find this useful.

Personally, I do indeed.

Many thanks to Mario for sharing!

GeoSnoop .NET Boundary Curve Loop Visualisation

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I explained how I use the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances, sort and orient its output curves, and determine their bounding box for visualisation.

Today let's look at a simple loop visualisation implementation in a dynamically generated .NET form.

The components of interest are:

• Point2dInt – an integer-based 2D point
• JtLoop – a closed polygon boundary loop
• JtLoops – a list of boundary loops
• JtBoundingBox2dInt – a bounding box for 2D integer points
• GeoSnoop – display a collection of curves in a .NET form
• Validation of results – reality check
• Next steps – where to go from here
• Download – try this yourself at home

Point2dInt – an Integer-based 2D Point

I introduced this class in the initial discussion on retrieving plan view room boundary polygon loops.

The main idea is to have a robust lightweight data container for passing 2D point information back and forth between my Revit add-in, the cloud and mobile devices.

The later development motivated the addition of a couple of convenience methods since the first publication:

/// <summary>
/// An integer-based 2D point class.
/// </summary>
class Point2dInt : IComparable<Point2dInt>
{
  public int X { get; set; }
  public int Y { get; set; }
 
  const double _feet_to_mm = 25.4 * 12;
 
  static int ConvertFeetToMillimetres( double d )
  {
    return (int) ( _feet_to_mm * d + 0.5 );
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( int x, int y )
  {
    X = x;
    Y = y;
  }
 
  /// <summary>
  /// Convert a 3D Revit XYZ to a 2D millimetre 
  /// integer point by discarding the Z coordinate
  /// and scaling from feet to mm.
  /// </summary>
  public Point2dInt( XYZ p )
  {
    X = ConvertFeetToMillimetres( p.X );
    Y = ConvertFeetToMillimetres( p.Y );
  }
 
  /// <summary>
  /// Comparison with another point, important
  /// for dictionary lookup support.
  /// </summary>
  public int CompareTo( Point2dInt a )
  {
    int d = X - a.X;
 
    if( 0 == d )
    {
      d = Y - a.Y;
    }
    return d;
  }
 
  /// <summary>
  /// Display as a string.
  /// </summary>
  public override string ToString()
  {
    return string.Format( "({0},{1})", X, Y );
  }
 
  /// <summary>
  /// Add two points, i.e. treat one of 
  /// them as a translation vector.
  /// </summary>
  public static Point2dInt operator+(
    Point2dInt a,
    Point2dInt b )
  {
    return new Point2dInt(
      a.X + b.X, a.Y + b.Y );
  }
}

JtLoop – a Closed Polygon Boundary Loop

This class consists of a simple list of 2D integer points representing a closed boundary loop.

When a new point is added to the collection, it is compared to the last and ignored if they evaluate equal. This automatically suppresses too small boundary segment fragments.

/// <summary>
/// A closed polygon boundary loop.
/// </summary>
class JtLoop : List<Point2dInt>
{
  public JtLoop( int capacity )
    : base( capacity )
  {
  }
 
  /// <summary>
  /// Display as a string.
  /// </summary>
  public override string ToString()
  {
    return string.Join( ", ", this );
  }
 
  /// <summary>
  /// Add another point to the collection.
  /// If the new point is identical to the last,
  /// ignore it. This will automatically suppress
  /// really small boundary segment fragments.
  /// </summary>
  public new void Add( Point2dInt p )
  {
    if( 0 == Count
      || 0 != p.CompareTo( this[Count - 1] ) )
    {
      base.Add( p );
    }
  }
}

JtLoops – a List of Boundary Loops

Each room produces a collection of loops, since it may include holes. For the furniture and equipment, I am expecting to manage just one external boundary contour loop each. On the other hand, for the furniture, this class enables me to easily collect all the individual furniture loops together into one single object.

The addition operator + is used to unite the room and furniture loops into a single container to pass to the visualisation method.

The conversion to a list of Point instances is used to feed the System.Drawing.Drawing2D.GraphicsPath class AddLines method to display the loops in a form.

/// <summary>
/// A list of boundary loops.
/// </summary>
class JtLoops : List<JtLoop>
{
  public JtLoops( int capacity )
    : base( capacity )
  {
  }
 
  /// <summary>
  /// Unite two collections of boundary 
  /// loops into one single one.
  /// </summary>
  public static JtLoops operator+( JtLoops a, JtLoops b )
  {
    int na = a.Count;
    int nb = b.Count;
    JtLoops sum = new JtLoops( na + nb );
    sum.AddRange( a );
    sum.AddRange( b );
    return sum;
  }
 
  /// <summary>
  /// Return suitable input for the .NET 
  /// GraphicsPath.AddLines method to display the 
  /// loops in a form. Note that a closing segment 
  /// to connect the last point back to the first
  /// is added.
  /// </summary>
  public List<Point[]> GetGraphicsPathLines()
  {
    int i, n;
 
    List<Point[]> loops
      = new List<Point[]>( Count );
 
    foreach( JtLoop jloop in this )
    {
      n = jloop.Count;
      Point[] loop = new Point[n + 1];
      i = 0;
      foreach( Point2dInt p in jloop )
      {
        loop[i++] = new Point( p.X, p.Y );
      }
      loop[i] = loop[0];
      loops.Add( loop );
    }
    return loops;
  }
}

JtBoundingBox2dInt – a Bounding Box for 2D Integer Points

I discussed the 2D integer-based bounding box implementation last week.

As you can see there, it already includes a handy constructor taking a collection of loops to return their entire bounding box.

I now added properties to return the aspect ratio and a System.Drawing.Rectangle to easily define the visualisation target rectangle and coordinate system transformation:

/// <summary>
/// A bounding box for a collection 
/// of 2D integer points.
/// </summary>
class JtBoundingBox2dInt
{
  /// <summary>
  /// Minimum and maximum X and Y values.
  /// </summary>
  int xmin, ymin, xmax, ymax;
 
  /// <summary>
  /// Initialise to infinite values.
  /// </summary>
  public JtBoundingBox2dInt()
  {
    xmin = ymin = int.MaxValue;
    xmax = ymax = int.MinValue;
  }
 
  /// <summary>
  /// Return current lower left corner.
  /// </summary>
  public Point2dInt Min
  {
    get { return new Point2dInt( xmin, ymin ); }
  }
 
  /// <summary>
  /// Return current upper right corner.
  /// </summary>
  public Point2dInt Max
  {
    get { return new Point2dInt( xmax, ymax ); }
  }
 
  /// <summary>
  /// Return current center point.
  /// </summary>
  public Point2dInt MidPoint
  {
    get
    {
      return new Point2dInt(
        (int)(0.5 * ( xmin + xmax )),
        (int)(0.5 * ( ymin + ymax )) );
    }
  }
 
  /// <summary>
  /// Return current width.
  /// </summary>
  public int Width
  {
    get { return xmax - xmin; }
  }
 
  /// <summary>
  /// Return current height.
  /// </summary>
  public int Height
  {
    get { return ymax - ymin; }
  }
 
  /// <summary>
  /// Return aspect ratio, i.e. Height/Width.
  /// </summary>
  public double AspectRatio
  {
    get
    {
      return (double) Height / (double) Width;
    }
  }
 
  /// <summary>
  /// Return a System.Drawing.Rectangle for this.
  /// </summary>
  public Rectangle Rectangle
  {
    get
    {
      return new Rectangle( xmin, ymin,
        Width, Height );
    }
  }
 
  /// <summary>
  /// Expand bounding box to contain 
  /// the given new point.
  /// </summary>
  public void ExpandToContain( Point2dInt p )
  {
    if( p.X < xmin ) { xmin = p.X; }
    if( p.Y < ymin ) { ymin = p.Y; }
    if( p.X > xmax ) { xmax = p.X; }
    if( p.Y > ymax ) { ymax = p.Y; }
  }
 
  /// <summary>
  /// Instantiate a new bounding box containing
  /// the given loops.
  /// </summary>
  public JtBoundingBox2dInt( JtLoops loops )
  {
    foreach( JtLoop loop in loops )
    {
      foreach( Point2dInt p in loop )
      {
        ExpandToContain( p );
      }
    }
  }
}

GeoSnoop – Display a Collection of Curves in a .NET Form

Now comes the exciting part: extracting the loop information from my own data structures, setting up an appropriate .NET form and infrastructure, and passing the information across with a minimum of fuss.

I had some fiddling to do to set this up optimally, I can tell you.

I am very satisfied with the end result, though:

/// <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 );
 
    graphics.Clear( System.Drawing.Color.White );
 
    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 loops )
  {
    JtBoundingBox2dInt bb
      = new JtBoundingBox2dInt( loops );
 
    // 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 gr = Graphics.FromImage( bmp );
 
    DrawLoopsOnGraphics( gr,
      loops.GetGraphicsPathLines(), transform );
 
    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 );
  }
}

I bet you expected more than this, didn't you?

To quote Antoine de Saint-Exupéry: Il semble que la perfection soit atteinte non quand il n'y a plus rien à ajouter, mais quand il n'y a plus rien à retrancher (Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away).

Validation of Results

Actually, this is the really exciting part.

I mentioned that I was worried for a moment about the large number of loop vertices in the plan view of the desk. I was initially hoping for only four vertices, to represent a simple rectangle. After all, the plan view of a desk and chair looks like this in Revit:

In my visualisation, the same desk and chair loops are displayed like this instead:

The good news is:

• We have indeed produced closed loops.
• Their shape and location is correct.

Where do all those bumps come from, though?

The answer is easy and completely reassuring: the bumps are the desk drawer handles that stick out a little bit beyond the desktop surface. Looking at a 3D view in Revit from the top, the desk looks like this:

My results reproduce this exactly.

Looking at the chairs, I mentioned that some of the chair solids cause extrusion analyser failures, and I skip those. To be precise, I have two failures on each chair.

Comparing the chair 3D view from the top in Revit with my results shows that the armrests are the components causing trouble:

The rest matches up perfectly, once again validifying my approach. The bumps on the sides of the chairs are the armrest supports.

I also cleaned up the form generation as much as possible. Resizing, zooming and panning are not supported. The form aspect ratio is adjusted up front to adapt to the loops to display:

Once again, here is the same view in Revit:

Next Steps

Actually, the next steps are the really, really exciting part.

Now I can turn to the implementation of my data repository and the task of hosting it in the cloud.

I already discussed my tentative plans and high hopes for this. Let's see if I can live up to them.

Adventure! Who knows what will come, and where this will lead?

Download

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

Curve Following Face and Bounding Box Implementation

Continuing the research and development for my cloud-based round-trip 2D Revit model editing project, I looked at using the ExtrusionAnalyzer to create a plan view boundary profile for the furniture and equipment family instances and implemented a utility method SortCurvesContiguous to sort and re-orient the curves it returns into a closed contiguous loop.

An alternative and more effective method is to use the Edge AsCurveFollowingFace call instead of AsCurve, as we shall see below.

In any case, we want to check the results, e.g. to ensure that we really have obtained the valid closed boundary loops we expect.

The easiest way to do so is to visualise them graphically. To visualise something, you mostly need to know how big it is first. You often need to scale it to fit into your visualisation space, e.g. a fixed-size window, i.e. transform from its given initial size and location to the target coordinate space. A useful way to determine the size of a boundary loop is to calculate the bounding box of its collection of vertices.

That leads to the following topics of today's post, including one additional unrelated issue that just came in:

• Using AsCurveFollowingFace
• XYZ point bounding box calculation
• 2D integer-based point bounding box calculation
• Overview of sweep sample code and issue resolutions

Use Curve Following Face

I already had one stab at using a built-in Revit API method instead of implementing my own SortCurvesContiguous solution: Rudolf Honke suggested testing the ExporterIFCUtils ValidateCurveLoops method instead, but that did not work.

Now Bettina Zimmermann provided another idea:

I don’t understand why you write your own code for direction sorting of the curves when Revit can provide it for you: Edge.AsCurveFollowingFace. Scott Conover's Geometry API document describes it a bit but not very detailed.

I have written some code using Revit API to find the curves sorted in the right direction for using GeometryCreationUtilities.CreateExtrusionGeometry, so I found out it is possible using this call.

I tested that, simply replacing the call to Edge.AsCurve by AsCurveFollowingFace:

  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 requires post-processing using
      // SortCurvesContiguous:
 
      Curve curve = e.AsCurve();
 
      if( _debug_output )
      {
        p = curve.get_EndPoint( 0 );
        q = curve.get_EndPoint( 1 );
        Debug.Print( "{0} --> {1}",
          Util.PointString( p ),
          Util.PointString( q ) );
      }
 
      // 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 );
    }
 
    CurveUtils.SortCurvesContiguous(
      creapp, curves, _debug_output );
 
    q = null;
 
    JtLoop loop = new JtLoop( nEdges );
 
    foreach( Curve curve in curves )
    {
      // Todo: handle non-linear curve.
      // Especially: if two long lines have a 
      // short arc in between them, skip the arc
      // and extend both lines.
 
      p = curve.get_EndPoint( 0 );
 
      loop.Add( new Point2dInt( p ) );
 
      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
      }
    }
    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;
  }

I also added new code to the SortCurvesContiguous method to report correctly sorted and oriented curves. A typical snippet of output looks like this now:

(2.18,8.4,0) --> (2.18,5.78,0)
(2.18,8.4,0) --> (2.18,5.78,0) following face
(2.18,5.78,0) --> (7.31,5.78,0)
(2.18,5.78,0) --> (7.31,5.78,0) following face
(7.31,5.78,0) --> (7.31,8.4,0)
(7.31,5.78,0) --> (7.31,8.4,0) following face
(7.31,8.4,0) --> (6.75,8.4,0)
(7.31,8.4,0) --> (6.75,8.4,0) following face
(6.75,8.4,0) --> (6.75,8.46,0)
(6.75,8.4,0) --> (6.75,8.46,0) following face
(6.75,8.46,0) --> (6.41,8.46,0)
(6.75,8.46,0) --> (6.41,8.46,0) following face
(6.41,8.46,0) --> (6.41,8.4,0)
(6.41,8.46,0) --> (6.41,8.4,0) following face
(6.41,8.4,0) --> (3.08,8.4,0)
(6.41,8.4,0) --> (3.08,8.4,0) following face
(3.08,8.46,0) --> (3.08,8.4,0)
(3.08,8.4,0) --> (3.08,8.46,0) following face
(2.74,8.46,0) --> (3.08,8.46,0)
(3.08,8.46,0) --> (2.74,8.46,0) following face
(2.74,8.4,0) --> (2.74,8.46,0)
(2.74,8.46,0) --> (2.74,8.4,0) following face
(2.74,8.4,0) --> (2.18,8.4,0)
(2.74,8.4,0) --> (2.18,8.4,0) following face
0 endPoint (2.18,5.78,0)
1 start point match, no need to swap
1 endPoint (7.31,5.78,0)
2 start point match, no need to swap
2 endPoint (7.31,8.4,0)
3 start point match, no need to swap
3 endPoint (6.75,8.4,0)
4 start point match, no need to swap
4 endPoint (6.75,8.46,0)
5 start point match, no need to swap
5 endPoint (6.41,8.46,0)
6 start point match, no need to swap
6 endPoint (6.41,8.4,0)
7 start point match, no need to swap
7 endPoint (3.08,8.4,0)
8 start point match, no need to swap
8 endPoint (3.08,8.46,0)
9 start point match, no need to swap
9 endPoint (2.74,8.46,0)
10 start point match, no need to swap
10 endPoint (2.74,8.4,0)
11 start point match, no need to swap
11 endPoint (2.18,8.4,0)
(2.18,8.4,0) --> (2.18,5.78,0)
(2.18,5.78,0) --> (7.31,5.78,0)
(7.31,5.78,0) --> (7.31,8.4,0)
(7.31,8.4,0) --> (6.75,8.4,0)
(6.75,8.4,0) --> (6.75,8.46,0)
(6.75,8.46,0) --> (6.41,8.46,0)
(6.41,8.46,0) --> (6.41,8.4,0)
(6.41,8.4,0) --> (3.08,8.4,0)
(3.08,8.4,0) --> (3.08,8.46,0)
(3.08,8.46,0) --> (2.74,8.46,0)
(2.74,8.46,0) --> (2.74,8.4,0)
(2.74,8.4,0) --> (2.18,8.4,0)
FamilyInstance Furniture Desk <212646 1525 x 762mm> has 1 loop:
  0: (664,2561), (664,1761), (2227,1761), (2227,2561),
    (2056,2561), (2056,2580), (1954,2580), (1954,2561),
    (937,2561), (937,2580), (836,2580), (836,2561)

As you can see, AsCurveFollowingFace does indeed return all the curves correctly oriented and sorted, and SortCurvesContiguous has nothing at all left to do.

Thank you very much Bettina for this valuable suggestion!

Also thanks to Scott Conover for his valuable Geometry API document from the Autodesk University 2011 class, which I already mentioned numerous times in the past but was not previously published in PDF format and therefore not included in web searches until now.

Bounding Box Determination for XYZ Points

As explained above, I would like to check the validity of the boundary loop listed above. The easiest way to do so is by displaying it visually. To do so, I need to transform it from its native coordinate space to my display space, for instance Windows device or HTML5 Canvas coordinates. This normally requires scaling and translation, and in turn knowledge of the size and location of the native coordinate space. The latter can be easily determined by calculating a bounding box.

I therefore set out to implement a bounding box determination for XYZ points.

I could use the existing Revit API BoundingBoxXyz class, because it does provide both read and write access to its Min and Max properties. However, it includes a number of additional features that are of no interest to me at this point, so I prefer to create my own lightweight class for this.

My first idea was to use a generic Tuple class, e.g.

  class JtBoundingBoxXyz : Tuple<XYZ, XYZ>

However, the components of such a tuple are read-only and cannot be changed after instantiation, so I cannot easily update the min and max values as I add new points using this approach.

My next idea was to implement my own class and manage Revit XYZ max and min member variables within it. However, the components of an XYZ are read-only and cannot be changed except by re-instantiation, so extending the bounding box to include new points would have sub-optimal performance in this case as well.

The simplest solution appears to be managing six individual doubles instead, and instantiating XYZ return values when needed, like this:

/// <summary>
/// A bounding box for a collection of XYZ instances.
/// The components of a tuple are read-only and cannot 
/// be changed after instantiation, so I cannot use 
/// that easily.
/// The components of an XYZ are read-only and cannot 
/// be changed except by re-instantiation, so I cannot 
/// use that easily either.
/// </summary>
class JtBoundingBoxXyz // : Tuple<XYZ, XYZ>
{
  /// <summary>
  /// Minimum and maximum X, Y and Z values.
  /// </summary>
  double xmin, ymin, zmin, xmax, ymax, zmax;
 
  /// <summary>
  /// Initialise to infinite values.
  /// </summary>
  public JtBoundingBoxXyz()
  {
    xmin = ymin = zmin = double.MaxValue;
    xmax = ymax = zmax = double.MinValue;
  }
 
  /// <summary>
  /// Return current lower left corner.
  /// </summary>
  public XYZ Min
  {
    get { return new XYZ( xmin, ymin, zmin ); }
  }
 
  /// <summary>
  /// Return current upper right corner.
  /// </summary>
  public XYZ Max
  {
    get { return new XYZ( xmax, ymax, zmax ); }
  }
 
  public XYZ MidPoint
  {
    get { return 0.5 * ( Min + Max ); }
  }
 
  /// <summary>
  /// Expand bounding box to contain 
  /// the given new point.
  /// </summary>
  public void ExpandToContain( XYZ p )
  {
    if( p.X < xmin ) { xmin = p.X; }
    if( p.Y < ymin ) { ymin = p.Y; }
    if( p.Z < zmin ) { zmin = p.Z; }
    if( p.X > xmax ) { xmax = p.X; }
    if( p.Y > ymax ) { ymax = p.Y; }
    if( p.Z > zmax ) { zmax = p.Z; }
  }
}

Bounding Box Determination for 2D Integer Points

Applying the same principles, here is a pretty optimal implemenetation of a bounding box for 2D integer-based points. It includes a constructor taking a collection of loops, which is the output I am generating from my furniture and equipment plan view calculation:

/// <summary>
/// A bounding box for a collection 
/// of 2D integer points.
/// </summary>
class JtBoundingBox2dInt
{
  /// <summary>
  /// Minimum and maximum X and Y values.
  /// </summary>
  int xmin, ymin, xmax, ymax;
 
  /// <summary>
  /// Initialise to infinite values.
  /// </summary>
  public JtBoundingBox2dInt()
  {
    xmin = ymin = int.MaxValue;
    xmax = ymax = int.MinValue;
  }
 
  /// <summary>
  /// Return current lower left corner.
  /// </summary>
  public Point2dInt Min
  {
    get { return new Point2dInt( xmin, ymin ); }
  }
 
  /// <summary>
  /// Return current upper right corner.
  /// </summary>
  public Point2dInt Max
  {
    get { return new Point2dInt( xmax, ymax ); }
  }
 
  /// <summary>
  /// Return current center point.
  /// </summary>
  public Point2dInt MidPoint
  {
    get
    {
      return new Point2dInt(
        (int)(0.5 * ( xmin + xmax )),
        (int)(0.5 * ( ymin + ymax )) );
    }
  }
 
  /// <summary>
  /// Expand bounding box to contain 
  /// the given new point.
  /// </summary>
  public void ExpandToContain( Point2dInt p )
  {
    if( p.X < xmin ) { xmin = p.X; }
    if( p.Y < ymin ) { ymin = p.Y; }
    if( p.X > xmax ) { xmax = p.X; }
    if( p.Y > ymax ) { ymax = p.Y; }
  }
 
  /// <summary>
  /// Instantiate a new bounding box containing
  /// the given loops.
  /// </summary>
  public JtBoundingBox2dInt( JtLoops loops )
  {
    foreach( JtLoop loop in loops )
    {
      foreach( Point2dInt p in loop )
      {
        ExpandToContain( p );
      }
    }
  }
}

Stay tuned to see how I use this to finally display and verify the extrusion analyser output and my integer-based boundary loop management implementation, coming next.

Overview of Sweep Sample Code and Issue Resolutions

Before closing, here is one last issue that just came up and I would like to mention here as well:

Question: I am trying to create a sweep in a new family using the Revit API, and am having some difficulties.

I found only one single example in the Revit SDK Samples, and can only get it working using your template. When I use my own, it fails.

Where can I find some more information on this, please?

Answer: I discussed some very advanced sweep issues with Bill Adkison, and we published the essence of his results on sweep path tolerance criteria. Normally, sweep issues are nowhere near as hard as the ones he encountered and mastered.

The most recent sample code demonstrating sweep generation was for the sweep family performance enhancement.

Furthermore, the AEC DevBlog discusses a number of sweep creation issues and provides several source code samples to generate them:

• Sweep creation
• Sweep paths and sketch planes
• NewSweptBlend code sample
• NewSweptBlend profile prerequisites

I hope this helps. Good luck!

Revit 2014 API and Plan View Room Boundary Loops

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

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

The Revit 2014 API

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

Here are a couple of highlights:

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

How does that sound?

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

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

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

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

• Presentation
• Recording
• Sample code

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

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

Enjoy!

Retrieving Plan View Room Boundary Polygon Loops

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

So far, so good.

As far as I can tell, all systems go.

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

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

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

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

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

Relax – Simple Free Cloud Based Data Repository with NoSQL, CouchDB, and IrisCouch

Last week, I mentioned my proposal for the Autodesk Technical Summit in June, to present a cloud-based round-trip 2D Revit model editing project.

That will obviously required a cloud-based data repository. Talking with my colleagues, all of their suggestions were oriented towards the Microsoft Azure and Amazon solutions discussed so far on the cloud and mobile DevBlog.

I was searching for something freer, more open source, and less proprietary, and was rather surprised to discover an utterly relaxing solution that so far looks absolutely perfect for me and my needs.

I first stumbled upon IrisCouch, which led me to CouchDB and NoSQL, which all make me very happy. For didactical purposes, I will discuss them in inverted order, though.

Before I get to that, I would also like to mention my first ski tour of the year:

• Ski Tour Season Opening
• NoSQL
• CouchDB
• IrisCouch
• ID and GUID in Revit Documents
• Visual Revit Programming with Dynamo

My Ski Tour Season Opening

I went on a ski crossing of the Glarner Alps last weekend.

We took the cable lift up to the Fisetenpass and climbed the Gemsfairenstock, Clariden and Piz Cazarauls. We were hoping to get on to the Schärhorn as well, but had to give that up due to bad weather conditions. Instead we headed over the glacier to the Chammlijoch und down the Iiswaendli back to the Klausenpass.

This was my second ascent of the Clariden Mountain, following the last one in September 2011, from the opposite direction and obviously under very different conditions.

A great way to get away from computers for a day or two and face the natural elements instead, at their wildest and fiercest.

Relax – with NoSQL

As said, researching a simple efficient cloud-based data repository for my SVG editing project, I discovered NoSQL, 'not only SQL', a whole new class of database model, hitherto unknown to me.

A NoSQL database provides a simple, lightweight mechanism for storage and retrieval of data that provides higher scalability and availability than traditional relational databases. The NoSQL data stores use looser consistency models to achieve horizontal scaling and higher availability. Some NoSQL systems do allow SQL-like query language to be used.

NoSQL database systems are often highly optimized for retrieval and appending operations and often offer little functionality beyond record storage, e.g. key–value stores. The reduced run-time flexibility compared to full SQL RDBM systems is compensated by marked gains in scalability and performance for certain data models.

Since my application will only require storage of simple key-value pairs and should in theory be massively scalable, this sounds like an optimal choice. In practice, I only expect it to be a toy, of course; the scalability is required only to make it a useful example toy.

Relax – with CouchDB

Apache CouchDB is a NoSQL implementation, one of a new breed of database management systems.

As stated by its official by-line, the one word to describe CouchDB is relax. When you start CouchDB, you see:

Apache CouchDB has started. Time to relax.

CouchDB is built not only for, but of the Web. Its design borrows heavily from web architecture and the concepts of resources, methods, and representations. Data is self-contained:

Replication and backup is extremely simple, basically requiring no more than a modification of the base URL.

CouchDB is implemented in the Erlang programming language, which is used to build massively scalable soft real-time systems with requirements on high availability with uses in telecommunication, banking, e-commerce, computer telephony and instant messaging. Erlang's runtime system has built-in support for concurrency, distribution and fault tolerance.

Here is a 'what is' Q&A, getting started tutorial and full 270-page O'Reilly textbook CouchDB – The Definite Guide.

The textbook samples make use of the cURL command line tool, e.g. the following two command line statements to create a new and list a database:

  curl -X PUT http://127.0.0.1:5984/baseball
  {"ok":true}

  curl -X GET http://127.0.0.1:5984/_all_dbs
  ["baseball"]

Relax – with IrisCouch

As I initially mentioned, the starting point of this exploration of mine was IrisCouch, which terms itself 'easy CouchDB'. It provides a free hosting service, 'a couch in the cloud'. You can sign up in minutes to have your own Apache CouchDB server.

For my purposes, I can install CouchDB on my local machine, develop my data repository locally, and push it all to the cloud by replicating my local database to IrisCouch and changing the base URL to use that for all interaction.

Relax – with DreamSeat

While I explored the theory, my colleague Philippe Leefsma went ahead and implemented a pair of .NET applications uploading and consuming cloud-based data from an IrisCouch-hosted CouchDB database using the DreamSeat CouchDB .NET wrapper library.

Although the DreamSeat documentation boasts support for both complete synchronous and asynchronous API, Philippe used Visual Studio 2012 and its .NET 4.5 async support that automatically and transparently implements the entire support for async call-back. 'Async' methods can use the 'await' keyword, so he wrote a couple of anync wrapper methods for standard synchronous DreamSeat calls.

Well, that provides lots of material to play with in the immediate future, and gives me hope of easily implementing my cloud-based data repository requirements.

Here are a couple of other more directly Revit API related notes:

ID and GUID in Revit Documents

Question: A short question about the way unique ID’s are managed in Revit. I want to export a large number of RVT models through DB link to a single database and I really need to have unique ID’s in my destination tables. So far what I’ve seen is that the records pushed to my database have a field ID which seems to be unique within each Revit file, but not with my set of files.

So is there a way to have really unique identifier like a GUID instead of simple ID in my RVT models? Or at least is there a way to rely on a kind of GUID when we push data through DB link?

Answer: Each Revit element has an ID property, its element id, which is unique within the RVT document, but not globally.

Each Revit element also has a UniqueId property, which is globally unique, unless you do something to sabotage that.

Under normal circumstances, the UniqueId should fulfil your needs.

Visual Revit Programming with Dynamo

One last, final note before closing: if you are interested in a visual programming environment for Revit which allows non-programmers to create workflows to automate Revit functionality and geometry creation, be sure to check out Dynamo, also featured at AutodeskVasari.com.

Cloud & Mobile, Extensible Storage Data Use in Schedules

My topics for today are:

• Cloud and mobile topics I covered so far
• Cloud-based round-trip 2D Revit model editing on any mobile device using SVG
• Extensible storage data use in schedules

I am still meeting with my European DevTech colleagues here in Konk Leon, 'anse du Lèon', the cove of the lion, aka Le Conquet, Brittany.

Yesterday, one of our topics was work we have done so far for cloud and mobile applications. It was very interesting to hear about my peers' rich and varied experiences.

Cloud and Mobile Topics Covered so Far

I documented all my own experiences so far here on the blog, and was able to reuse that for my presentation quite spontaneously with no further preparation:

• Accessing a REST API web service from a Revit .NET add-in – Apollonian sphere packing and AVF.
• Thoughts on mobile indoor positioning, representing room polygons in SVG, the Azure SDK, ASP.NET MVC 4, and implementing a web service.
• An overview of the BIM 360 Glue viewer and REST API.
• BIM 360 Glue REST API authentication using Python.
• A room polygon and furniture picker in SVG.
• 2D SVG editing on mobile devices using the Raphaël JavaScript SVG library.

As I explained at the time, all of the explorations involving SVG are part of a larger master plan.

This plan has now matured to a certain extent and is forcing me to move ahead quite fast in the immediate future.

The main outcome so far is a presentation proposal that I submitted for the internal Autodesk technical summit taking place in June, and the fact that it was accepted.

My cloud and mobile roadmap is thus now clearly focused on implementing that proposal:

Cloud-based Round-trip 2D Revit Model Editing on any Mobile Device using SVG

I described the roadmap I envision in the discussion of my simple SVG editor. The main components include:

• 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.
• The SVG editor running in a browser on any device, rendering the model and supporting some simple geometric modification.

Here is the actual wording of my technical summit proposal:

Proposal Abstract

This presentation demonstrates 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. On the mobile device, the repository is queried and the data is rendered in a standard browser using JavaScript and SVG. The rendering supports modification, such as translation and rotation of the furniture and equipment, which is saved back to the cloud database. The Revit add-in picks up these changes and updates the Revit model.

Intended Audience and Prerequisites

Intended audience is programmers with interest in cloud-based and mobile computing, specifically interest in round-trip editing of a Revit model using a cloud-based data repository and editing a 2D model on an arbitrary mobile device with no additional software beyond a browser installed on it. 
Knowledge of .NET, JavaScript and REST programming is helpful but not required. Revit add-in experience is not a prerequisite.

Presentation Outline

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

Two of the important components whose implementation I plan to explore next are the polygon generation and data model:

Plan View Polygon Determination

The generation of the room boundary polygons is obvious, since the room has a boundary property.

For the furniture and equipment family instance, the solution is a less immediate. My current idea is to explore making use of the ExtrusionAnalyzer class. It is supplied a solid geometry, a plane, and a direction. From those, it calculates the outer boundary of the shadow cast by the solid onto the input plane along the extrusion direction. As far as I can tell, that should be exactly what I need.

Scott Conover mentioned this class in his session on the Geometry API, a continuation of his AU 2011 presentation CP4011 'Geometric Progression: Further Analysis of Geometry Using the Autodesk Revit 2012 API', enhanced for the Revit 2013 API.

As soon as I have the polygons determined, I want to implement functionality to render them easily. This will involve extent calculation, canvas definition, and coordinate system transformation. I will probably implement a simple .NET geometry viewer before moving on to the SVG rendering. I've been wanting to do that for a long time...

Cloud-based Data Repository

So far, my colleagues have been focusing on using the Amazon and Azure cloud hosting services, and many discussions on the cloud and mobile DevBlog deal with them.

I searched the Internet for other cloud-based database alternatives, and right now CouchDB looks pretty promising, so I might try a completely different approach using that instead.

There is a lot to do here as well: define the data model, set up the web service, define a format for saving the polygon data, etc. At the very least, I will need to manage:

• Model > metadata, rooms.
• Room > metadata, model, furniture, level, polygon.
• Furniture > metadata, room, polygon, transformation (initially identity).

Round tripping the information will be interesting, especially if I want the Revit model to update automatically when furniture positions are modified on the mobile device, which I certainly do, if only for the wow effect :-)

Stay tuned...

... Oh, and, yeah, wish me luck!

Extensible Storage Data Use in Schedules

Returning to the desktop again, here is a recent question from a developer on using estorage data in a schedule that leads to some general observations on that topic:

Question: I would like to display my extensible storage information in a schedule. I searched high and low, though, and was unable to find any samples or documentation on the subject. Can you help?

Answer: There is a good reason why you have not found anything: there is no such support.

The usage of extensible storage data is utterly and completely up to the add-in itself. The Revit API offers no support whatsoever for making use of estorage data in any way. The only support provided is for storage and retrieval, nothing else.

Well, one tiny little detail more: if an element id value is stored, and the element id is later modified by some worksharing operation, its value will be automatically updated.

On the other hand, there is currently no direct support for putting data into a schedule either.

I am no user interface expert, but I think that you can set up a schedule to be populated from certain parameter values via the user interface. You would have to talk with an application engineer or product support or explore this topic on the Internet to find out how that can be done.

Of course, there is nothing stopping you from extracting your data from extensible storage and transferring it into parameters set up to populate a schedule yourself.

I hope that answers your question and helps you get started successfully.

Parameter DisplayUnitType, Bretagne and Decompilers

After looking at several performance enhancement possibilities last week, e.g. the sweep family performance enhancement and LoadFamily and collector iteration performance, here is another exciting and pretty sophisticated exploration of internal Revit API implementation details by Victor Chekalin that can be used to achieve a significant speed improvement when accessing large numbers of parameters and checking their DisplayUnitType property.

Brittany

Before getting to that, though, here is an update on my current whereabouts.

Yesterday I spent travelling to Brest and Le Conquet (Konk Leon in Breton) for a meeting with my European DevTech colleagues.

This is the western-most point of northern France, home of my boss Cyrille, and my first visit to the Bretagne.

The weather is exciting and challenging, and the views spectacular.

A quick rainfall in the east and simultaneous glorious evening sunlight from the west produced a beautiful double rainbow.

We have a meeting room in a converted chapel with a view straight out onto the Atlantic.

Parameter DisplayUnitType Enhancement and Research

Back to the DisplayUnitType enhancement, here is the description of the research leading up to it in Victor's own words:

Now I'm working with the element parameters again and I need to get all parameters of a lot of elements in the project including their DisplayUnitType.

The problem is that not all parameters have a display unit type. If I try to retrieve a display unit type for a parameter where it does not exist, an Autodesk.Revit.Exceptions.InvalidOperationException is thrown. Unfortunately, there is no direct way to determine beforehand whether a parameter has a DisplayUnitType defined or not, i.e. whether the call will succeed or fail.

The most obvious way would be to wrap the code where I retrieve the display unit type in a try... catch block. But throwing and catching an exception is a very expensive operation and greatly reduces the performance – exceptions should be exceptional.

I decided to go deeper and looked at the RevitAPI.dll using dotPeek – free .NET decompiler.

At first I went to the DisplayUnitType property of the Parameter class.

public DisplayUnitType DisplayUnitType
{
  get
  {
    Definition definition = this.Definition;
    ParamTypeSpec paramTypeSpec1;
    if ((ParamTypeEnum) *(int*)
      definition.getParamTypeSpec(&paramTypeSpec1)
      != (ParamTypeEnum) 15)
    {
      throw new Autodesk.Revit.Exceptions
        .InvalidOperationException(new FunctionId(
          "n:\\build\\2013_ship_x64_inst_20120221_2030\\source\\api\\revitapi\\objects\\parameters\\APIParameter.cpp",
          581, "Autodesk::Revit::DB::Parameter::DisplayUnitType::get"),
          string.Empty);
    }
    else
    {
      ParamTypeSpec paramTypeSpec2;
      return (DisplayUnitType)
        \u003CModule\u003E.FormatOptions\u002EgetDisplayUnits(
          \u003CModule\u003E.AUnits\u002EgetFormatOptions(
            \u003CModule\u003E.ADocument\u002EgetAUnits(
              (ADocument*) *(long*) this.m_pCDA),
                (UnitType.Enum) *(int*) ((IntPtr)
                definition.getParamTypeSpec(&paramTypeSpec2) + 8L)));
    }
  }
}

The most interesting thing here is 'if ((ParamTypeEnum) *(int*) definition.getParamTypeSpec(&paramTypeSpec1) != (ParamTypeEnum) 15)'. The first idea is to call this method via reflection. But getParamTypeSpec is an internal unsafe method. Unfortunately, I don't know how to use reflector with pointers and internal structures. So, I decided to go another way.

The next step is to look at the ParameterType property of the Definition class.

public override ParameterType ParameterType
{
  get
  {
    REVIT_MAINTAIN_STATE revitMaintainState;
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bctor\u007D(
      &revitMaintainState);
 
    ParameterType parameterType;
    try
    {
      ParamDef* paramDefPtr = this.m_pParamDef;
      ParamTypeSpec paramTypeSpec;
      \u003CModule\u003E.paramDefToParamType(
        &paramTypeSpec, paramDefPtr);
      switch (^(int&) @paramTypeSpec)
      {
      case 1:
        parameterType = ParameterType.Text;
        break;
      case 6:
        parameterType = ParameterType.URL;
        break;
      case 9:
        parameterType = ParameterType.YesNo;
        break;
      case 11:
        parameterType = ParameterType.Integer;
        break;
      case 13:
        parameterType = ParameterType.Material;
        break;
      case 14:
        parameterType = ParameterType.FamilyType;
        break;
      case 15:
        switch (^(int&) ((IntPtr) &paramTypeSpec + 8))
        {
        case 0:
          parameterType = ParameterType.Length;
          break;
        case 1:
          parameterType = ParameterType.Area;
          break;
        case 2:
          parameterType = ParameterType.Volume;
          break;
        case 3:
          parameterType = ParameterType.Angle;
          break;
        case 4:
          parameterType = ParameterType.Number;
          break;
        case 26:
          parameterType = ParameterType.Force;
          break;
        case 27:
          parameterType = ParameterType.LinearForce;
          break;
        case 28:
          parameterType = ParameterType.AreaForce;
          break;
        case 29:
          parameterType = ParameterType.Moment;
          break;
        default:
          parameterType = (ParameterType) (
            ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
          break;
        }
      case 16:
        parameterType = ParameterType.NumberOfPoles;
        break;
      case 24:
        parameterType = ParameterType.FixtureUnit;
        break;
      case 30:
        parameterType = ParameterType.LoadClassification;
        break;
      default:
        parameterType = ParameterType.Invalid;
        break;
      }
    }
    __fault
    {
      \u003CModule\u003E.___CxxCallUnwindDtor(
        (__FnPtr<void (void*)>) __methodptr(REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D),
          (void*) &revitMaintainState);
    }
    \u003CModule\u003E.REVIT_MAINTAIN_STATE\u002E\u007Bdtor\u007D(
      &revitMaintainState);
    return parameterType;
    }
  }
}

Here we can see that a parameter will have a DisplayUnitType only if the ParameterType is Length, Area, etc.. So we can just check if the ParameterType is one of the Length, Area, etc. ones. If so, its parameter has a DisplayUnitType, otherwise not.

It is necessary to pay attention to the line

  default:
    parameterType = (ParameterType) (
      ^(int&) ((IntPtr) &paramTypeSpec + 8) + 100);
    break;

Looking at the ParameterType enumeration suggests that every parameter type whose integer value is greater than 100 belongs to paramTypeSpec = 15.

As a result, I created the following extension method for the Parameter class:

public static class ParameterExtensions
{
  public static bool HasDisplayUnitType(
    this Parameter parameter )
  {
    var parameterType =
        parameter.Definition.ParameterType;
 
    switch( parameterType )
    {
      case ParameterType.Length:
      case ParameterType.Area:
      case ParameterType.Volume:
      case ParameterType.Angle:
      case ParameterType.Number:
      case ParameterType.Force:
      case ParameterType.LinearForce:
      case ParameterType.AreaForce:
      case ParameterType.Moment:
        return true;
    }
 
    /* At the reflector I can see the following code
          default:
            parameterType = (ParameterType) 
              (^(int&) ((IntPtr) &paramTypeSpec 
              + 8) + 100);
            break;
        looking at the ParameterType enumeration 
        suggests that every parameter type whose 
        integer value is greater than 100 belongs 
        to paramTypeSpec = 15
    */
    return 100 < (int) parameterType;
  }
}

Comparison Benchmarking

To wrap this up, here is a little benchmark comparing the two methods.

The first one exercises the try... catch block:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
    message = "Cancelled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    try
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
    catch( Autodesk.Revit.Exceptions
      .InvalidOperationException )
    {
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

Pick an element. The result is 0.41 seconds.

Second measurement, with my new method:

  Reference r;
 
  try
  {
    r = uidoc.Selection.PickObject(
      ObjectType.Element );
  }
  catch( OperationCanceledException )
  {
 
    message = "Canceled";
    return Result.Cancelled;
  }
 
  var e = doc.GetElement( r.ElementId );
 
  Stopwatch sw = Stopwatch.StartNew();
 
  foreach( Parameter parameter in e.Parameters )
  {
    if( parameter.HasDisplayUnitType() )
    {
      DisplayUnitType dut =
          parameter.DisplayUnitType;
 
      Debug.Print( dut.ToString() );
    }
  }
  sw.Stop();
 
  TaskDialog.Show( "Benchmark result",
    sw.Elapsed.ToString() );

The result is 0.029 seconds for the same element!

You may say that 0.41 seconds is not so much, and users will not notice the difference between 0.41 seconds and 0.028. Of course the difference is not huge if you work with only one element. But note that the exception handling code works 15 times slower, repeatedly, ever single time it is called!

If you retrieve parameters for 100 elements, it takes 41 seconds using try... catch instead of just 3 seconds with my new method.

I hope this enhancement will be useful for other developers as well.

Many thanks to Victor for his very professional analysis and valuable result!

The best of luck to you in your new job, Victor, and congratulations on that achievement!

IL Decompilation

I talked about Reflector way back in the early days of the blog. It since became commercial.

Victor mentions using dotPeek for his explorations above.

When I brought this up with my colleagues, Adam added that he uses the ILSpy .NET Decompiler and is perfectly happy with that as well.

LoadFamily and Collector Iteration Performance

Since we are into the topic of family loading performance anyway, after yesterdays discussion on efficient sweep creation, here is another interesting discussion with some useful family loading and symbol filtering benchmarking results and observations by Thomas Jarzyna and an in-depth analysis of the effects of converting a filtered element collector to a .NET collection by Scott Conover:

Question: I need to load some family symbols into my project. I have a lot of different families and even more symbols, so to keep the projects small and clean I would prefer to load family symbols on demand only.

Therefore, whenever an instance of a family is to be created, I need to check first whether the family symbol is already loaded.

I can see two possible approaches to achieve this:

• Check whether the family symbol already exist by iterating through the database using a filtered element collector searching for family name and family symbol name.
• Not checking anything, and just always calling LoadFamilySymbol. It runs fine even if the family symbol is already loaded. One negative side effect of this approach is the "one time conversion" dialogue popping up for older families every time.

Which approach is better from a performance centred point of view, please?

Is there any other possible approach?

Answer: Both of your two approaches sound feasible.

I also find the "one time conversion" dialogue rather irritating and would not want my users to see it, especially not repeatedly.

If that is a serious problem for you, you could implement a system to ensure that it never occurs more than once. For instance, you could create different sub-directories for the different Revit versions of the same family, and check whether an updated version has already been generated before loading an older one.

However, I would expect the use of the filtered element collector to be much (very much!) more efficient.

However^2, it really depends on so many factors that it is impossible to say for sure.

The only way to really answer this with certainty for your particular system, workflow needs, and installation situation is to benchmark the different options.

I described a simple benchmarking system that I would use in a Revit add-in in lack of anything more sophisticated.

I cannot think of any other approach offhand.

The thought of calling LoadFamily without even checking beforehand actually never occurred to me :-)

Here are two different implementation examples checking whether a family has already been loaded, and loading it otherwise, for

• Creating and inserting an extrusion family
• Structural concrete setout points

I hope they fulfil your needs.

Response: Thank you for the answer.

I was hoping for a simple standard best practice, but I see it's not as easy as that.

In the meantime, I've done a little bit of benchmarking myself. Just basic, using a stopwatch:

And you are right, depending on the quantity of different Types (FamilySymbols) these approaches differ significantly.

For a scenario of creating 2000 family instances from one family (see attached sheet), this is my conclusion:

• If you expect less than a dozen different family symbols to load, just load them once via "LoadFamilySymbol" and don't care about iterating the element collection for the already loaded family symbols.
• Otherwise, iterating and finding the loaded family symbols first is better.
• Of course, this depends on the complexity of the family types and the environment (hardware & current load).
• A large number of different families is not considered yet.

I also noted the following interesting fact while iterating for "known" family symbols:

  var collector = new FilteredElementCollector( doc );

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .ToElements()
    .OfType<FamilySymbol>();

The additional call to the ToElements method makes the search using the collector slightly less effective (some milliseconds slower) compared to:

  IEnumerable<FamilySymbol> familySymbols = collector
    .OfClass( typeof( FamilySymbol ) )
    .OfType<FamilySymbol>();

But in the long term, iterating over the family symbols is much faster when ToElements is called first.

For the 2000 instances it takes 14 seconds without ToElements vs. 9 seconds with.

I guess this has to do with the caching provided by possible multiple enumerations of IEnumerable.

What do you think?

Thank you, till next time.

Answer: Thank you for your very interesting results and observations, and congratulations on your first benchmarking results! They are already very interesting.

A call to ToElements definitely costs some performance, since it allocates an entirely new generic .NET collection and copies all the elements across from the Revit filtered element collector, as I mentioned discussing FindElement and collector optimisation.

I am surprised and interested (and was initially a little disappointed) to hear that the subsequent iteration over the .NET collection is measurably faster than the Revit collector, though.

Yes, the speed improvement is probably indeed related to the explanation you point to. In this case, the Revit element collector may be storing the elements in 'Revit memory' and eating cycles when marshalling them across to '.NET memory'. This marshalling effort may need to be performed anew on each repetition of the iteration.

Ah yes, with that explanation, I am perfectly happy with this observation, and not disappointed at all.

Thank you for these illuminating results.

Scott adds: I would expect the total time spent in FilteredElementCollector.ToElements and subsequent iteration to be longer than direct iteration of FilteredElementCollector, regardless of the number of elements that pass the filter.

Of course, once ToElements has run and you store the managed handles, iteration of this collection should be fast – you are not going back to the document to find the elements again or filter them or wrap them in managed handles.

If you are doing more than one iteration of a given filter criteria, the first one will always be faster than the second – because of the extra time taken to create the Elements collection. The other activities – traversing the database, applying and evaluating the filter, wrapping the elements that pass into managed code – happen on both.

If you know you need to have the same filtered set of elements more than once, saving them in the collection should be faster for the second and subsequent iterations. This assumes that you know the document hasn’t changed where there are new elements that pass the filter (or some of them are deleted). The second iteration over the managed collection should be faster than re-traversing the document. This is a pretty specialized approach. The other reasons for converting FilteredElementCollector to a collection (you want to store a list of elements or ids for later, you need such a list as input to another method, you want to delete anything you find, etc.) still apply.

If you are running multiple loops on the collector with no changes in between, the second will be consistently faster. Optimally, you might want to unroll the loop to just do everything in one shot.

The first might be faster than the second if the collector is returning a really large number of elements.

Mostly, you want to get a set of things once and just do things to it once. Normally, only certain specialized applications such as multiple data extractions or multiple permutations for design studies might require retrieval of the exact same data and then doing things to it repeatedly in the same code sequence.

Let’s use made up concrete numbers.

• It takes 100 ms to process the model and find elements that pass the filters, and to wrap each element into the API object.
• It takes 5 ms to build the .NET collection returned by ToElements.
• It takes 1 ms to traverse a .NET IEnumerable<Element>, which could be either the Revit collector or the .NET collection.

So with one group of elements processed once:

• With collection: 100 + 5 + 1 = 106 ms.
• Without collection: 100 + 1 = 101 ms.

With the same exact group of elements processed 10 times in the same code (where we know there is no chance new elements were added or elements deleted that we care about):

• With collection obtained once: 100 + 5 + 10 * 1 = 116 ms.
• Without collection: 100 * 10 + 10 * 1 = 1010 ms.

Make sense?

The key thing to understand is that FilteredElementCollector caches nothing (except the filters applied to it, of course). Caching data needed for multiple things will be better – always – but premature if there’s no need to have such a cache at all.

Note that the built-in collections on Document (.WallTypes, etc.) – which are becoming obsolete in future versions – use FilteredElementCollector as their base; there is no caching done there either, and no real advantage to them other than saving the coding effort of building the collector and filters.

Adding a Button to Existing Ribbon Panel

Here is an interesting user interface contribution from Eduardo Teixeira of Autodesk:

Question: I am building a Revit add-in using the Revit API.

I would like to add a button for it to an existing out-of-the-box Revit ribbon panel using the Revit API in C#.

I could not find any documentation that shows how to do that.

Is it possible at all?

Answer: Yes, this can be done. I am not certain whether it is officially supported, though. You will have to explore on your own a bit.

The official API is limited. You can however also use functionality from the .NET UI Automation library and from the AdWindows.dll .NET assembly included with Revit, similar to the one provided with AutoCAD.

Here are some previous discussion exploring related issues that might help:

• Pimp my ribbon
• Roll a toggle button
• Enable button in zero document state
• Add non-command button to the ribbon

Response: Thanks for the tip. The article that really helped me was the first one you list. I was able to add a button to the existing out-of-the-box Energy Analysis panel under the Analyze tab.

There are just two simple steps required achieve the desired result:

To add a custom button to the Analyze tab in the Revit Energy Analysis ribbon panel:

1. Add a reference to the AdWindows.dll .NET assembly provided with Revit.
2. Add the two snippets of source code listed below to the external application implementation:
   1. In OnStartup, create and add the button.
   2. Handle the UIElementActivated event.

Adding the References

Add a reference to the AdWindows.dll .NET assembly provided with Revit.

Don't forget to set the copy local flag to false on that.

This will also require references to the .NET WindowsBase and PresentationFramework assemblies, which in turn require PresentationCore and System.Xaml.

Creating and Adding the Button

In OnStartup, localise the existing tab and panel, instantiate a new ribbon button, add it to the tab, and subscribe to the UIElementActivated event.

Here is a simplified version of Eduardo's code set up to run on Jeremy's system and open the browser to display The Building Coder home page:

public Result OnStartup( UIControlledApplication a )
{
  adWin.RibbonControl ribbon
    = adWin.ComponentManager.Ribbon;
 
  foreach( adWin.RibbonTab tab in ribbon.Tabs )
  {
    if( tab.Id == "Analyze" )
    {
      foreach( adWin.RibbonPanel panel
        in tab.Panels )
      {
        if( panel.Source.Id == "cea_shr" )
        {
          adWin.RibbonButton button
            = new adWin.RibbonButton();
 
          button.Name = "TbcButtonName";
          //button.Image = image;
          //button.LargeImage = image;
          button.Id = "ID_TBC_BUTTON";
          button.AllowInStatusBar = true;
          button.AllowInToolBar = true;
          button.GroupLocation = Autodesk.Private
            .Windows.RibbonItemGroupLocation.Middle;
          button.IsEnabled = true;
          button.IsToolTipEnabled = true;
          button.IsVisible = true;
          button.ShowImage = false; //  true;
          button.ShowText = true;
          button.ShowToolTipOnDisabled = true;
          button.Text = "The Building Coder";
          button.ToolTip = "Open The Building "
            + "Coder blog on the Revit API";
          button.MinHeight = 0;
          button.MinWidth = 0;
          button.Size = adWin.RibbonItemSize.Large;
          button.ResizeStyle = adWin
            .RibbonItemResizeStyles.HideText;
          button.IsCheckable = true;
          button.Orientation = System.Windows
            .Controls.Orientation.Vertical;
          button.KeyTip = "TBC";
 
          adWin.ComponentManager.UIElementActivated
            += new EventHandler<
              adWin.UIElementActivatedEventArgs>(
              ComponentManager_UIElementActivated );
 
          panel.Source.Items.Add( button );
 
          return Result.Succeeded;
        }
      }
    }
  }
  return Result.Succeeded;
}

As you can see, I am triggering the reaction to the button click by subscribing to the UIElementActivated event. Not sure if this is the correct way of doing it, but it works.

Handling the Event

In the event handler, check that the custom button was actually clicked and act on that, e.g. opening the browser at a specified URL.

void ComponentManager_UIElementActivated(
  object sender,
  adWin.UIElementActivatedEventArgs e )
{
  if( e != null
    && e.Item != null
    && e.Item.Id != null
    && e.Item.Id == "ID_TBC_BUTTON" )
  {
    // Perform the button action
 
    // Local file
 
    string path = System.Reflection.Assembly
      .GetExecutingAssembly().Location;
 
    path = Path.Combine(
      Path.GetDirectoryName( path ),
      "test.html" );
 
    // Internet URL
 
    path = "http://thebuildingcoder.typepad.com";
 
    Process.Start( path );
  }
}

Note that this requires no interaction with the Revit database, so there is no need to worry about a valid API context or transactions or any of that stuff.

Many thanks to Eduardo for sharing this!

Sample Run

Jeremy adds: for your convenience, here is AddButton.zip containing the source code, Visual Studio solution and add-in manifest for my version of this external application.

On my system, however, the button appears in the expected location but is disabled, so no action is triggered:

I am not sure why that happens. Maybe Eduardo or somebody else can help resolve this.

Parameters versus Properties

In his comment on reading material asset data, Alexander Buschmann points out that this same information can be accessed without retrieving, reading and converting the data directly from the undocumented built-in parameters.

Instead and more comfortably, you can use the following official properties on the appropriate classes:

  Material material = null;
 
  foreach( Material mat in e.Materials )
  {
    material = mat;
    break;
  }
  PropertySetElement pse = doc.GetElement(
    material.StructuralAssetId )
      as PropertySetElement;
 
  StructuralAsset asset = pse.GetStructuralAsset();
 
  double a = asset.WoodBendingStrength;
  double b = asset.WoodParallelCompressionStrength;
  double c = asset.WoodParallelShearStrength;
  double d = asset.WoodPerpendicularCompressionStrength;
  double f = asset.WoodPerpendicularShearStrength;

  // ... and lots of other properties ...

Even though a large and growing number of properties are available through this approach, the "Tension Parallel to Grain" one is actually currently not included in these, so you will indeed still have to use the direct parameter access anyway in this particular case.

Going through parameters is more generic, and most properties available on the classes are also available via parameters.

Parameters can also be used to define a parameter filter for a filtered element collector, so it is always useful to know that they are there and what they mean.

To discover the existence and use of specific parameters, you can use RevitLookup and BipChecker to explore a simple model. Modify the model interactively through the user interface and observe the effect on the parameters to discover their use and meaning.

He also adds:

For convenience, we use extension methods in our code to do this kind of thing, e.g.

public static class ElementExtensions
{
  public static Material material( this Element e )
  {
    foreach( Material m in e.Materials )
    {
      return m;
    }
    return null;
  }
}

If this class part of an imported namespace, it can be called as:

  Material material2 = e.material();

The compiler will translate that to this:

  Material material3
    = ElementExtensions.material( e );

It is mostly just convenience, but it also improves the readability of the code, since the entire loop above collapses into just this one single property call.

Many thanks to Alexander for pointing this out!

Here are some pointers to other extension methods that we discussed in the past:

• Scale a curve
• GetPolygon extension methods
• C# and .NET little wonders
• Top faces of sloped wall
• Unit conversion and display string formatting
• Materials collection and filtering
• RevitRubyShell implementation and installer
• Room in area predicate via point in polygon test
• FamilyParameter IsShared property

Show Viewport Extension Line or Label

Alexander also pointed out some other useful parameter to be aware of on the ViewType class in his comment on changing the viewport type, and my colleague Joe Ye just ran into a case dealing with the very same issue:

Question: We can change the length of the view title line:

For that we have to go to edit type and check the show extension line toggle:

It is possible to achieve this using the API?

Answer: Yes, you can set that check box via the API as well. Here is the process:

1. Get the view type object.
2. Get the parameter that represents the "Show Extension Line".
3. Change the parameter value.

Here is an example of performing these three steps:

  ElementId typeId = viewport.GetTypeId();
 
  ViewType viewtype = doc.GetElement( typeId )
    as ViewType;
 
  Parameter withLine = viewtype.get_Parameter(
    BuiltInParameter
      .VIEWPORT_ATTR_SHOW_EXTENSION_LINE );
 
  withLine.Set( 0 ); // No Line
  withLine.Set( 1 ); // Has Line

Alexander also points out that the built-in parameter VIEWPORT_ATTR_SHOW_LABEL affects the view label in a similar manner.

Duplicate Built-in Parameter Values and BipChecker Update

BipChecker is a tool that I would recommend every Revit developer to install, just like RevitLookup. It simply lists the values of all parameter data stored on a selected element.

Similar access is also offered within RevitLookup by the option Parameters > Built-in Enums Snoop... BipChecker offers much more functionality, though, and is a really powerful Revit database exploration and debugging tool.

The built-in parameter checker has been part of the ADN sample labs for ages now, and the original version is still provided in the Xtra materials. The time has come to finally remove it from there, though.

First, since I find it useful on its own, I extracted it into a separate add-in and baptised it BipChecker.

Secondly, Victor Chekalin enhanced it by implementing grouping of the long list by parameter group, data type, built-in versus standard Parameters collection, read-write, or none.

This tool always suffered one serious problem, though, due to repetitions in the definitions and assignment of some of the built-in parameter enumeration integer values.

Victor now tracked down and fixed that issue as well.

Here is his explanation:

Now I work closely with Materials and use our BiP checker. I noticed two strange things when I check material parameters using BiP Checker. The first one, the material cost stored as BuiltInParameter.DOOR_COST. The second one – some parameters appear twice or even triple:

I researched this and found the reason.

To iterate all built-in parameters, we used the Enum.GetValues method:

  var allParameters = Enum.GetValues(
    typeof ( BuiltInParameter ) );

This makes use of the integer values of the Enum. If different Enum values have the same integer value the GetValues method doesn’t work properly.

For example, BuiltInParameter.ALL_MODEL_COST and BuiltInParameter.DOOR_COST both have the integer value -1001205:

• DOOR_FIRE_RATING = -1001206
• ALL_MODEL_COST = -1001205
• DOOR_COST = -1001205
• ALL_MODEL_MARK = -1001203

In this case, BiPChecker shows DOOR_COST twice and doesn’t show ALL_MODEL_COST parameter at all.

The Solution

Use Enum.GetValues and Enum.TryParse instead of Enum.GetValues to get the BuiltInParameter value, and use the BuiltInParameter name from Enum.GetValues. This requires the .NET framework 4.

Now it looks much better:

Here is BipChecker05.zip containing the full source code, Visual Studio solution and add-in manifest of the updated BipChecker version 2013.0.5.0.

С уважением from Чекалин Виктор.

Many thanks to Victor for his research and important enhancement!

To wrap it up, here is a snapshot listing all built-in parameters on a wall with no grouping enabled, so that the results can be sorted across all groups by any desired criterion:

Basic File Info and RVT File Version

I presented an initial solution in Python for determining the version of an RVT file on disk from outside Revit making use of its OLE document Structured Storage format back in 2008. David Echols later shared a more full-fledged C# Revit OLE Storage viewer listing more information and displaying the preview image.

Since then, the Revit API added support for reading basic RVT file info through the BasicFileInfo class.

Victor Chekalin now presents another C# console application showing how some of this data can be accessed independently of the Revit API.

Before looking at that, here are some other topics that also came up in the past day or two:

• Building Setout Points used commercially
• Screen recording with Camtasia on the Mac
• Sustainable Autodesk Offices
• Reading the RVT file version without using the Revit API

Building Setout Points Used in a Commercial Application

I am glad to say that one of the sample add-ins I am particularly happy with now made its way into a commercial application.

Here is an excerpt from the current Australian ARSoftwareSolutions newsletter:

A recent meander through the TheBuildingCoder website led me to a routine for marking the corners of structural concrete corners. Once marked the points could be scheduled and provided to the builder as a file of set out point coordinates. These can then be established on site using various surveying tools. This seemed like something a lot of companies could benefit from so I set about including it in my software. (Please refer to http://thebuildingcoder.typepad.com/blog/rst for more complete details. Thank you to both Paul Hellawell of GHD and Jeremy Tammik for the idea and some of the coding.)

Of course I couldn't just leave it the way it was so I expanded on the concept, added extra functionality, and this now forms a part of ARUtils - Leader.

The basic concept is to mark all structural concrete corners with a "SetoutPoint" family. Critical setout points can then use a "Major" type of that family to indicate they are a critical point. Alternatively other points can be automatically designated as minor, centre points of curves, control points of splines, or just intermediate points along curves. Points can be promoted to Major or demoted to Minor as required for construction or changing needs.

When automatically placed at a point, each marker has the X,Y, and Z coordinates assigned to the marker. Once this has been done, the families can be scheduled and the points exported for use by the builder. The routine also keeps track of the item that generated the points so points can be grouped on a generating object basis.

Points marked. Diagram shows Major, Minor, Centre, Control and Curve following points.

Tagged points

Scheduled Keypoints

Schedule - All points

The interface

Note: You can automatically mark all structural concrete items, or pick specific items of any type to have markers placed.

Note: Should the project location change the coordinates can be automatically synchronised using the "Renumber / Update" option.

I am happy to see my efforts helping people and making their way out into the world :-)

Screen Recording on the Mac

On a completely different topic, I have been struggling a bit the past few days to set up a proper screen recording environment for myself to create a canned presentation.

I want to show some Powerpoint slides, record my narration, and also make use of Revit and Visual Studio for add-in demonstrations.

I planned to use Camtasia for this, as I have past experience with it and it does a good job.

The Revit and Visual Studio requirements led me to believe that I had to install Camtasia in my Windows virtual machine.

When I did that, I discovered that the Windows version that I had installed was European and therefore lacked the Windows Media Player, which caused Camtasia to fail. It took a while to find out, though.

I went off and downloaded a US version of Windows, created a new virtual machine, installed Revit, Visual Studio, Camtasia, and some other bits and pieces on it.

After doing all that, I discovered that the Camtasia output quality from this setup is suboptimal, and there are often problems with the audio getting lost completely.

After struggling a bit more with that, a colleague told me that the easiest thing to do is just to use Camtasia in the native Mac system and record the full screen. I can display the Powerpoint slides in full screen, record my narration, and switch back and forth to a full-screen virtual Windows machine at any time. So I wasted a lot of time there. Now I can get going with my recording just as soon as I finish this post.

Sustainable Autodesk Offices

Back to the architectural realm, two new case studies on the green office design of the Autodesk offices in Milan and Farnborough are now live on the Autodesk Sustainable Design Center:

• Farnborough
• Milano

These projects were implemented by Morgan Lovell plc and Goring & Straja Architects, respectively. The case studies describe the projects, challenges, solutions, results and learning experiences made.

I hope you find this interesting, useful and feel inspired to pursue the same kind of greening efforts in your own company :-)

Determining the RVT File Version Without Revit

Back to the main topic that I started discussing above.

This came up again prompted by a comment by Victor Chekalin, or Виктор Чекалин, on the original post.

He points to a stackflow discussion thread: How can I get the Revit file version using the Revit API?

Question: In the Revit API I know that I can get the version of the Revit instance that is currently running:

• ControlledApplication.VersionBuild
• ControlledApplication.VersionName
• ControlledApplication.VersionNumber

However, I would like to get the version of a Revit file itself before I open it. This way I could stop the automatic upgrade dialog that shows when a user opens an older Revit file in a newer version of Revit. I'm using Revit 2013 and expecting files from 2011, 2012, and 2013.

Answer from skeletank: I took a closer look at the discussion group posting from my question and found that the version information is actually human readable among the other gibberish of the file. The ".rvt" file is stored in OLE format so you can see the content if you use a tool like Structured Storage Viewer. It will be located under BasicFileInfo.

If you wanted to then you could probably use an OLE library for .NET to read the data but I used a StreamReader and a Regex instead.

Here is the regular expression:

Revit\sArchitecture\s(?\d{4})\s(Build:\s(?\w*)\((?\w{3})\)\)

Here is the code:

private void ControlledApplication_DocumentOpening(
  object sender,
  DocumentOpeningEventArgs e )
{
  FileInfo revitFileToUpgrade
    = new FileInfo( e.PathName );
 
  Regex buildInfoRegex = new Regex(
    @"Revit\sArchitecture\s(?<Year>\d{4})\s"
    +@"\(Build:\s(?<Build>\w*)\((<Processor>\w{3})\)\)" );
 
  using( StreamReader streamReader =
    new StreamReader( e.PathName, Encoding.Unicode ) )
  {
    string fileContents = streamReader.ReadToEnd();
 
    Match buildInfo = buildInfoRegex.Match( fileContents );
    string year = buildInfo.Groups["Year"].Value;
    string build = buildInfo.Groups["Build"].Value;
    string processor = buildInfo.Groups["Processor"].Value;
  }
}

This will allow you to get the year, build number, and the type of processor. Notice, however, that my version checks specifically for Architecture so you will need to modify it for MEP or Structural.

Answer from Victor Chekalin:

As you said, Revit file format is a Structured Storage document and information you need is stored in the BasicFileInfo stream.

Within the Revit 2013 API you can use the SavedInVersion method of the BasicFileInfo class.

Here is the full console application demonstrating how to extract BasicFileInfo data without the Revit API.

Unfortunately I don't now the format of the BasicFileInfoStream. But if you read it as string you can get version in which file was created.

Reading only the BasicFileInfo is much better than reading the whole file. Imagine if the Revit project is over 500 MB. You will read the whole file into memory when you call

  string fileContents = streamReader.ReadToEnd();

Also, Regular expression on the huge file works slow.

I think you should use

  var rawString = System.Text.Encoding.Unicode
    .GetString( rawData );

from my sample and use Regex in the rawString instead the whole file.

For your convenience, here is the full source code of Victor's solution:

using System;
using System.IO;
using System.IO.Packaging;
using System.Reflection;
using System.Runtime.InteropServices;
 
namespace ConsoleApplication1
{
  class Program
  {
    private const string StreamName = "BasicFileInfo";
 
    static void Main( string[] args )
    {
      string pathToRevitFile = ( 1 == args.Length )
        ? args[0]
        : @"pathToRevitFile";
 
 
      if( !StructuredStorageUtils.IsFileStucturedStorage(
        pathToRevitFile ) )
      {
        throw new NotSupportedException(
          "File is not a structured storage file" );
      }
 
      var rawData = GetRawBasicFileInfo( pathToRevitFile );
 
      var rawString = System.Text.Encoding.Unicode.GetString(
        rawData );
 
      var fileInfoData = rawString.Split(
        new string[] { "\0", "\r\n" },
        StringSplitOptions.RemoveEmptyEntries );
 
      foreach( var info in fileInfoData )
      {
        Console.WriteLine( info );
      }
    }
 
    private static byte[] GetRawBasicFileInfo(
      string revitFileName )
    {
      if( !StructuredStorageUtils.IsFileStucturedStorage(
        revitFileName ) )
      {
        throw new NotSupportedException(
          "File is not a structured storage file" );
      }
 
      using( StructuredStorageRoot ssRoot =
          new StructuredStorageRoot( revitFileName ) )
      {
        if( !ssRoot.BaseRoot.StreamExists( StreamName ) )
          throw new NotSupportedException( string.Format(
            "File doesn't contain {0} stream", StreamName ) );
 
        StreamInfo imageStreamInfo =
            ssRoot.BaseRoot.GetStreamInfo( StreamName );
 
        using( Stream stream = imageStreamInfo.GetStream(
          FileMode.Open, FileAccess.Read ) )
        {
          byte[] buffer = new byte[stream.Length];
          stream.Read( buffer, 0, buffer.Length );
          return buffer;
        }
      }
    }
  }
 
  public static class StructuredStorageUtils
  {
    [DllImport( "ole32.dll" )]
    static extern int StgIsStorageFile(
      [MarshalAs( UnmanagedType.LPWStr )]
      string pwcsName );
 
    public static bool IsFileStucturedStorage(
      string fileName )
    {
      int res = StgIsStorageFile( fileName );
 
      if( res == 0 )
        return true;
 
      if( res == 1 )
        return false;
 
      throw new FileNotFoundException(
        "File not found", fileName );
    }
  }
 
  public class StructuredStorageException : Exception
  {
    public StructuredStorageException()
    {
    }
 
    public StructuredStorageException( string message )
      : base( message )
    {
    }
 
    public StructuredStorageException(
      string message,
      Exception innerException )
      : base( message, innerException )
    {
    }
  }
 
  public class StructuredStorageRoot : IDisposable
  {
    StorageInfo _storageRoot;
 
    public StructuredStorageRoot( Stream stream )
    {
      try
      {
        _storageRoot
          = (StorageInfo)InvokeStorageRootMethod(
            null, "CreateOnStream", stream );
      }
      catch( Exception ex )
      {
        throw new StructuredStorageException(
          "Cannot get StructuredStorageRoot", ex );
      }
    }
 
    public StructuredStorageRoot( string fileName )
    {
      try
      {
        _storageRoot
          = (StorageInfo)InvokeStorageRootMethod(
            null, "Open", fileName, FileMode.Open,
            FileAccess.Read, FileShare.Read );
      }
      catch( Exception ex )
      {
        throw new StructuredStorageException(
          "Cannot get StructuredStorageRoot", ex );
      }
    }
 
    private static object InvokeStorageRootMethod(
      StorageInfo storageRoot,
      string methodName,
      params object[] methodArgs )
    {
      Type storageRootType
        = typeof( StorageInfo ).Assembly.GetType(
          "System.IO.Packaging.StorageRoot",
          true, false );
 
      object result = storageRootType.InvokeMember(
        methodName,
        BindingFlags.Static | BindingFlags.Instance
        | BindingFlags.Public | BindingFlags.NonPublic
        | BindingFlags.InvokeMethod,
        null, storageRoot, methodArgs );
 
      return result;
    }
 
    private void CloseStorageRoot()
    {
      InvokeStorageRootMethod( _storageRoot, "Close" );
    }
 
    #region Implementation of IDisposable
 
    public void Dispose()
    {
      CloseStorageRoot();
    }
 
    #endregion
 
    public StorageInfo BaseRoot
    {
      get { return _storageRoot; }
    }
  }
}

For your even greater convenience, I am also providing RevitBasicFileInfo.zip containing the full Visual Studio solution that I created to test it.

Here is the result of running this on a sample model on my system:

Many thanks to Victor for his clear explanation and solution!

Addendum: To get access to the StreamInfo class you need reference the WindowsBase.dll assembly.

The question marks displayed in the result console above are due to the fact that one part of BasicFileInfo is encoded in Unicode and another in BigEndianUnicode.

The second part is rendered legible by accessing it like this instead:

  var rawString = System.Text.Encoding
    .BigEndianUnicode.GetString( rawData );

Here is the same file information presented twice, once in standard little endian and once in big endian decoding:

This is a summary of the resulting readable text fields:

• Little-endian:
• Autodesk Revit 2013 (Build: 20120716_1115)
• C:\j\tmp\rvt\floor_slab.rvt
• Big-endian:
• 00000000-0000-0000-0000-000000000000
• Worksharing: Not enabled
• Username:
• Central Model Path:
• Revit Build: Autodesk Revit 2013 (Build: 20120716_1115)
• Last Save Path: C:\j\tmp\rvt\floor_slab.rvt
• Open Workset Default: 3
• Project Spark File: 0
• Central Model Identity: 00000000-0000-0000-0000-000000000000
• Locale when saved: ENU

Implement a Progress Bar and Abort a Lengthy Process

The time has come to talk of many things: of shoes and ships, and sealing-wax, of cabbages and kings [^]... or no, let's continue sticking to the Revit API for now, more or less; today's topics are:

• A walk in the snow and a crystal covered baby tree
• Implementation of a Revit add-in progress bar
• Aborting a lengthy process from the progress bar
• Harry's image generation video competition

A Walk in the Snow

I went for a walk in snow and fog on a local hill and appreciated this wind-driven ice crystal covered baby tree that:

I thought I would like to share that with you. Sorry that it is so dark, but that's the way it was.

Implementing a Revit Add-in Progress Bar

I chatted with Harry Mattison on various topics during the winter break. One of them was the implementation of a Revit add-in progress bar:

Question: I am trying to make a simple progress dialog based on your post on modeless dialogues. It seems to work well basically but has a few problems:

1. The first time I run the command, the progress dialog flashes briefly on the screen and then disappears.
2. The text label does not display properly.
3. Sometimes the entire progress dialogue content turns white and the title bar says 'Not Responding'.

Could you help me figure out if my approach is flawed or if it just needs some small adjustments?

Answer: Thank you, but no thank you... :-)

Instead, I propose that you look at my existing modeless progress bar implementation in the ADN Revit MEP sample add-in, which has worked flawlessly for years now.

Response: Your progress bar is great! I wish I had found it earlier.

Aborting a Lengthy Process

Here's hopefully one last question about the progress bar:

How can the user cancel the operation from the progress bar?

Answer: You could implement some standard .NET stuff on the progress bar; maybe simply add a cancel button to it, and an event handler for that.

Response: After spending some time thinking about events and the like, I realized the progress bar cancel solution is almost trivial.

An idle event wouldn't work in my case, because Revit was never going idle. It was too busy doing hard work of exporting images for my Image-O-Matic application. Instead, all I needed to do is add the Abort button to the progress dialog, and put this little bit of code in the progress bar class:

  private void btnAbort_Click(
    object sender,
    EventArgs e )
  {
    btnAbort.Text = "Aborting...";
    abortFlag = true;
  }
 
  public bool getAbortFlag()
  {
    return abortFlag;
  }

Then, inside my foreach loops, I just need to check the status of the flag:

  foreach( string phaseName in phaseList )
  {
    if( progressForm.getAbortFlag() )
      break;
 
    // . . .
  }

Many thanks to Harry for the fruitful discussion and helpful hint!

Image Generation Video Competition

Yet another item from Harry, this time a rather shameless plug, but I guess he earned it :-)

Harry announced a competition in which you can win a free, custom-built Revit API add-in according to your own specifications for downloading his Image-O-Matic application, generating a video with it, and uploading that to YouTube.

Have fun, and good luck to you!